如何在适配暗黑模式的CSS项目中高效使用KSS？

问题根因 #

KSS生成的组件预览区域默认使用自带的白色背景容器，你定义在业务页面body、:root上的暗黑模式样式默认不会作用于KSS的预览容器，就会出现白色文字叠白色背景的显示异常。

可行解决方案 #

方案1：扩展全局样式覆盖KSS容器 #

直接在你的全局CSS中，把暗黑基础样式同时作用于KSS的文档根和预览容器（如果类名和示例不同，可按F12检查自己所用KSS版本的容器类名替换即可）：

/* 原有基础样式扩展适配KSS */
:root,
.kss-styleguide, /* KSS文档全局根容器 */
.kss-example__rendered /* 单个组件示例的渲染容器 */ {
  --fg-color: white;
  --bg-color: black;
  color: var(--fg-color);
  background-color: var(--bg-color);
}

这个方案改动最小，全局一次修改所有组件预览都生效。

方案2：修改KSS构建配置引入全局样式 #

如果你使用的是kss-node等工具，直接在KSS的构建配置文件中，把包含暗黑基础样式的CSS文件添加到全局引入列表里，KSS生成文档时会自动把你的全局样式加载到整个文档页面：

// kss-config.json 配置示例
{
  "css": [
    "./src/styles/global.css" /* 替换为你的全局CSS文件路径 */
  ]
}

这个方案可以保证KSS文档的样式和你的业务页面完全一致，不需要额外修改CSS代码。

方案3：给单个组件示例套独立容器 #

如果不想改动KSS全局样式，只需要在每个组件的KSS注释的Markup部分外层套一个自定义的暗黑容器即可：

/* KSS注释示例 */
/*
Simple

Markup:
<div class="demo-dark-root">
  <h2 class="simple">some text</h2>
</div>

Styleguide Simple.simple
*/

然后在全局CSS中新增容器样式：

.demo-dark-root {
  --fg-color: white;
  --bg-color: black;
  color: var(--fg-color);
  background-color: var(--bg-color);
  padding: 12px;
}

这个方案适合只需要部分组件预览适配暗黑模式的场景。

内容的提问来源于stack exchange，提问作者Enlico