## 规则速览（L1 · 设计元素单源）

新增颜色/字号/间距：先登记 `tokens/*.css` → `node design-pipeline/export-tokens.mjs` 再生成各端 → 业务代码只引 token。
新增组件：先建 `components/<组>/X.jsx`（+ .d.ts）并在本页「组件登记」加卡，再到各端实现。
新增图标：先登记 `icons.js`（Lucide 24 网格 2px 圆头）+ `icon-map.json` 跨端映射，业务代码禁止内联 <path>。
违规谁拦：`design-pipeline/check-ds.mjs`（真相源自检）/ `check-code.mjs`（代码侧单源）/ `export-tokens.mjs --check`（产物零 diff），pre-commit 与 CI 双挂。

### 各端消费方式

端 | 消费方式 | 令牌文件
--- | --- | ---
桌面（Tauri web 层） | vite alias `@dudu/design` 直引 CSS 变量与组件 | `design/tokens/*.css`（源）
iOS（SwiftUI） | `DuduTheme.*` 常量（codegen 直写） | `ios/dudu/Shared/DuduTheme.swift`
Android（Compose） | `DuduTheme.Light/Dark` → `DuduPalette` 注入 | `android/.../design/DuduTheme.kt`
官网（web/） | `<link href="tokens.css">`，页面只允许 var(--*) | `web/tokens.css`（codegen，含 Outfit 内嵌）

## Tokens 色板

色块直接渲染 var(--token)，与 tokens/colors.css 永远同步；右上角切主题查看 dark 值。完整定义见 colors.css · typography.css · spacing.css · effects.css · fonts.css

### 品牌蓝阶梯

blue-50
blue-100
blue-200
blue-300
blue-400
blue-500 ★
blue-600
blue-700
blue-800
blue-900

### 中性阶梯（冷灰）

gray-0
gray-25
gray-50
gray-100
gray-200
gray-300
gray-400
gray-500
gray-600
gray-700
gray-800
gray-900
gray-950

### 语义与功能

accent
accent-hover
accent-press
accent-soft
positive
warning
danger
bg-app
surface-card
surface-2
surface-3
border-1

### 浮层与第三方品牌

overlay-bg
overlay-text
overlay-text-2
overlay-text-3
overlay-wave
brand-wechat
brand-wechat-press

## 组件登记

每个 `components/**/*.jsx` 组件必须在此有登记卡（check-ds 第④道）。演示卡：core · forms · voice

### core

Button
主/次/幽灵/危险按钮，三种尺寸
variant · size · block — components/core/Button.jsx
IconButton
方形图标按钮
size · label（无障碍必填）— components/core/IconButton.jsx
Badge
状态徽标
tone: green/blue/orange/red/neutral — components/core/Badge.jsx
Kbd / HotkeyCombo
键帽与快捷键组合（⌘ ⇧ Space）
keys=['⌘','⇧','Space'] — components/core/Kbd.jsx
Card
标准卡片容器
padding — components/core/Card.jsx
ProgressBar
用量进度条，超阈自动警告色
value/max · warnAt=0.9 — components/core/ProgressBar.jsx
Icon
icons.js 单源图标渲染器
name · size · sw — components/core/Icon.jsx

### forms

Input
文本输入框
size: md/lg — components/forms/Input.jsx
Switch
开关
checked · onChange — components/forms/Switch.jsx
SettingRow
设置行（标签 + 描述 + 右侧控件）
label · description — components/forms/SettingRow.jsx
Select
自绘下拉选择器：触发器同 Input，弹层同菜单（radius-md + shadow-menu），选中项前置对勾。全端下拉外观基准，禁用原生 select
value · onChange · options · placeholder — components/forms/Select.jsx

### voice

RecognitionOverlay
桌面识别浮层 · 聆听/流式两态
state · text — components/voice/RecognitionOverlay.jsx
MicBar
移动端按住说话 · 四种状态
state — components/voice/MicBar.jsx
Waveform
波形条（唯一循环动画，仅录音中）
active · bars · height · color — components/voice/Waveform.jsx

## 图标登记（icons.js + icon-map.json）

Lucide 线条 · 24 网格 · 2px 圆头 · currentColor。下方由 `icons.js` 实时渲染（需经 serve.mjs 访问；file:// 打开时仅显示映射表）。

## Guidelines 规范卡

Logo
圆形嘴巴 + 声波线条 · 线性风格
Wordmark
dudu 几何线条字标
品牌蓝阶梯
blue-50 → 900
中性阶梯
gray-0 → 950 冷灰
表面与文字
bg → surface → text，Light/Dark
功能色
绿=录音/成功 · 琥珀=警告 · 红=错误
识别浮层色
双模式深色玻璃
字体家族
Outfit（自托管）+ 系统中文栈
字号阶梯
12 → 44
识别文本规范
final 实色 · partial 弱色
间距网格
4px 基准
圆角阶梯
xs 4 → full 999
控件高度
桌面 28/36 · 移动 44/56
层级与阴影
card → menu → window → overlay
动效
快入慢出 · 120/200/320ms · 无弹跳

## UI Kits（屏级原型）

桌面端 UI Kit
识别浮层 · 托盘菜单 · 设置 · 登录购买（可交互，Light/Dark）
移动端 UI Kit
语音键盘（按住说话）+ 主 App 四屏（可交互，Light/Dark）

已知滞后：ui_kits 预览页仍经 unpkg CDN 加载 React/Babel，离线/无代理网络下不可用（治理项见 doc/frontend-overview.html）。