nex_design_system/docs/02-design-tokens-and-theme.md

1.8 KiB
Raw Permalink Blame History

02. Design Tokens & Theme

1. 单一事实来源

同一语义设计值只能有一个权威来源。权威源可以是 TS/JS Token 对象、CSS Variables、JSON/YAML、主题平台导出或 UI 框架主题配置。

允许从权威源单向派生到 CSS、组件库主题或样式框架。禁止多个层分别人工维护同一语义值。

2. Token 语义

按项目需要定义:

  • Color:brand、success、warning、danger、info;
  • Text:primary、secondary、muted、inverse;
  • Surface:canvas、surface、elevated、overlay;
  • Border/Focus:default、subtle、strong、focus;
  • Spacing、Typography、Radius、Elevation、Motion、Layout、Z-index。

不要求每个项目建立全部类别,不要求统一物理文件格式。

3. 命名和适配

  • 不强制 --nex-* 前缀。
  • 优先沿用项目现有变量、主题和命名。
  • 需要映射时,记录设计语义到项目 Token 的对应关系。
  • 不为追求统一建立第二套 Token 层。

4. 主题

  • 项目支持 Light/Dark 时,语义 Token 应覆盖两种主题。
  • 页面组件消费语义 Token,不在页面里分散维护主题颜色。
  • 第三方组件库主题应从项目权威 Token 派生。
  • Portal、图表、编辑器、选中态、禁用态和悬浮层应遵循同一主题语义。
  • 单主题项目不必为了规范形式增加另一套主题。

5. 设计值

  • 新页面避免散落重复的硬编码设计值。
  • 内容决定的颜色、一次性局部几何值、媒体/图表原始值可合理保留。
  • 例外应局部化,避免把所有数字字面量都当成违规。
  • 旧页面逐步治理,不进行没有语义判断的全局替换。

6. 尺度

字号、间距、圆角、阴影、控件高度、内容宽度和导航尺寸由项目按品牌与任务定义。NEX 不规定跨项目固定像素值。