Token 架构与所有权

Name: BitzOrcas
Availability: InStock

唯一人工维护源

目录结构固定为：

frontend/packages/materials/src/tokens/
├── source/
│   ├── reference.tokens.json
│   ├── system.tokens.json
│   ├── component.tokens.json
│   └── themes/
│       ├── enterprise-neutral.tokens.json
│       ├── legal-navy.tokens.json
│       ├── legal-amber.tokens.json
│       ├── legal-burgundy.tokens.json
│       ├── legal-jade.tokens.json
│       └── legal-orange.tokens.json
└── generated/
    ├── tokens.css
    ├── tokens.ts
    └── tokens.schema.json

source/ 是唯一人工维护源。
以 sRGB Hex 作为颜色输入真源；OKLCH、CSS、TypeScript 和 schema 由同一生成器确定性输出。
generated/ 禁止手改。生成器带 --check 漂移检测，CI 中 fail-closed。
packages/components 消费 Token，packages/widgets 组合 Pattern，apps/* 填业务内容。
所有 source 文件声明 version: "1.2.0"，生成器断言该值必须一致。

四层依赖

--ref-*  ->  --sys-*  ->  --cmp-*  ->  shadcn compatibility aliases

层	内容	消费方	示例
Reference	原始色阶、字号、间距、圆角、时长	仅 System	`--ref-space-4`
System	表面、文字、动作、链接、焦点、状态、导航	页面布局与 Component	`--sys-color-text-default`
Component	单一组件的变体和状态	组件内部	`--cmp-button-primary-bg-hover`
Compatibility	shadcn/Tailwind 所需别名	既有组件	`--primary`

组件命名格式：

--cmp-{component}-{variant}-{property}-{state}

shadcn 兼容映射

--background: var(--sys-color-canvas);
--foreground: var(--sys-color-text-default);
--card: var(--sys-color-surface);
--card-foreground: var(--sys-color-text-default);
--border: var(--sys-color-border-subtle);
--input: var(--sys-color-border-control);
--primary: var(--sys-color-action-primary-bg);
--primary-foreground: var(--sys-color-action-primary-fg);
--ring: var(--sys-color-focus-ring);
--accent: var(--sys-color-selection-bg);
--accent-foreground: var(--sys-color-selection-fg);

Compatibility Alias 只能向上游映射。不得从 --primary 反推出 Link、Focus、Selection 或 Navigation。

页面红线

不出现裸 Hex、RGB、HSL、OKLCH 或品牌渐变。
不直接消费 --ref-*。
不定义全局 CSS custom property。
不手改 generated Token。
不用 !important 掩盖所有权或级联问题。
不为单一页面新增全局 Token。
可复用视觉值必须回到正确层级；业务页面只提供字段、列、权限和文案。

版本语义

版本	适用变化
Patch	不改变语义和布局的光学校正
Minor	向后兼容的新 Token、Pattern 插槽或 Recipe
Major	删除/重命名 Token，改变稳定 ID、Shell 区域或交互语义

破坏性变更必须有影响矩阵、迁移方式、可访问性结果和视觉回归，并通过 Design Guardian。