Skills
skills/skill.new.ndhy.com/retro-industrial-design-system

retro-industrial-design-system

SKILL.md

复古工业 Design System (Retro-Industrial)

这是一套带有复古工业质感的设计系统。核心特征：思源宋体衬线字体 + 暖色调（橙/棕/金）+ 深色底 + 网点/墨泼/颗粒素材。

何时使用此 skill

必用：

  • 创建任何新的 UI 组件（按钮、卡片、对话框、Toast、列表等）
  • 构建符合该品牌的页面、原型、artifact
  • 用户明确提到 "复古工业"、"复古工业"、"retro-industrial" 或品牌关键词
  • 为现有代码套用该品牌风格

建议用：

  • 涉及前端样式、CSS 变量、Tailwind class 且上下文暗示是这个项目
  • Code review 检查颜色/间距/字体是否硬编码

不用：

  • 纯逻辑/后端/数据处理代码
  • 用户明确要求别的风格（如 "Material Design"）

🚀 Agent 快速上手导航

第一次使用该 skill 的 AI Agent，按任务类型查对应文件：

任务类型 先读这个
新项目从 0 开始 QUICKSTART.md
找一个组件（用 Button、做表单等） components/INDEX.md（场景→组件决策表）
纠结"用 X 还是 Y" docs/component-selection.md
开工前先确定布局类型（页面 / 弹窗 / 抽屉） docs/layout-contract.md（v0.14 新增）
审代码合规性 docs/code-review-checklist.md
做视觉对照 打开 patterns/component-gallery/index.html
学习完整页面示例 patterns/backpack/

重要原则（每次都要记得）：

  1. 所有颜色/字号/间距走 var(--ri-*) token，禁硬编码
  2. 列表项 selected 用底色（不是描边）
  3. 错误态用橙色（不是红色）
  4. 开工前先定布局类型（页面 / 弹窗 / 抽屉 / 非模态浮层 / 内联片段）
  5. 视觉层（伪元素、纹理、混合模式）必须完整实现，不能省略

详细规则见下方"核心规则"章节。

工作流程（严格按顺序）

Step 1 — 读取 tokens

任何 UI 工作开始前，先读这几个文件以了解可用值：

  • tokens/build/tokens.css — 最常用。所有 CSS 变量定义在这里，HTML/CSS 项目直接 @import 即可。
  • tokens/build/tokens.ts — TypeScript 项目使用，提供类型安全的 token 访问。
  • tokens/build/tailwind.preset.js — Tailwind 项目使用，导入即可获得 bg-ri-*、text-ri-*、p-16、font-serif 等 class。

如果需要理解 token 的"语义"（比如 border-line 只用于对话组件），查看：

  • tokens/semantic/retro-industrial.json — 语义层，含每个 token 的 description。

Step 2 — 找语义 token，而不是原子色

原则：永远优先使用语义 token (--ri-color-button-primary-bg)，而不是直接用原子色 (--ri-palette-orange-900)。

只有在语义层找不到合适 token 的极少数情况下（比如设计了一个全新的、未覆盖的组件），才允许从原子调色板里挑一个最接近的 --ri-palette-* 值，并在代码注释里标注 // TODO: need semantic token for ...。

Step 3 — 检查是否有组件规范

快速查找：

  • 📌 想快速找"某场景该用哪个组件" → 查 components/INDEX.md（场景→组件决策表 + 常见组合模式）
  • 📌 纠结"用 X 还是 Y"（Toast vs Modal、Select vs Radio 等）→ 查 docs/component-selection.md

在 components/ 下查找对应组件的 SPEC.md。已经整理好规范的组件：

组件 路径 用途
Button components/button/SPEC.md 主按钮 / 次按钮（带角落装饰）
PageBackground components/page-background/SPEC.md 全屏深色背景（5 层叠加：深底+橙光+装饰角+halftone）
Modal components/modal/SPEC.md 模态对话框容器（双角橙光 + 米色边框 + 环境光阴影）
ModalHeader components/modal-header/SPEC.md 模态标题栏 + 关闭按钮（含暗色拖影 + CSS 画的 X）
Divider components/divider/SPEC.md 横向/纵向分隔线（2px tan 色）
ItemCard components/item-card/SPEC.md 物品卡（default / selected / empty 三态）
ItemGrid components/item-grid/SPEC.md 4 列物品网格 + 自定义滚动条
ItemDetailPanel components/item-detail-panel/SPEC.md 右侧详情面板（hero 大图 + 名称 + 描述 + 操作）
Toast components/toast/SPEC.md 数值变化提示（with-icon / text-only 两模态，gain/loss/neutral 三色变体）
BranchChoice components/branch-choice/SPEC.md 互动视频剧情分支选择（题干+倒计时+选项卡，2-4 选项自适应，多语言支持）
Dialogue components/dialogue/SPEC.md NPC 对话系统（对话框 + 可选 1-5 个回应选项；含业务可控高亮、角色名截断、RTL 支持）
Slider components/slider/SPEC.md 数值滑块（支持左侧图标；基于原生 input[type=range]）
Switch components/switch/SPEC.md 布尔开关（开/关文字标签）
SettingsPanel components/settings-panel/SPEC.md 非模态设置面板（vs Modal 的关键区别：不阻塞背后交互）
ConfirmDialog components/confirm-dialog/SPEC.md 二选一确认弹窗（Modal 的定型化小变体）
MenuRow components/menu-row/SPEC.md 共享菜单行原子（Drawer + ListPanel 共用；compact/comfortable 两种密度）
Drawer components/drawer/SPEC.md 左侧抽屉（含标题 + 进度条 + 菜单列表；部分阻塞）
ListPanel components/list-panel/SPEC.md 列表型模态弹窗（含自定义滚动条 + EmptyState 兜底）
LoadingPage components/loading-page/SPEC.md 全屏加载页（顶部进度条 + 加载中/错误两态）
EmptyState components/empty-state/SPEC.md 空状态/错误状态（图标+标题+说明+按钮；empty/error variant）
Input components/input/SPEC.md 文本输入框（5 状态 + 前缀图标，v0.11）
Textarea components/textarea/SPEC.md 多行文本框（视觉同 Input + resize vertical，v0.11）
Select components/select/SPEC.md 下拉选择（trigger + panel + options，v0.11）
Checkbox components/checkbox/SPEC.md 复选框（default/checked/indeterminate/disabled，v0.11）
Radio components/radio/SPEC.md 单选按钮（同组互斥，v0.11）
FormField components/form-field/SPEC.md 表单字段布局器（label + 控件 + helper/error，v0.11）

完整页面级模板：

Pattern 路径 描述
Backpack 背包页 patterns/backpack/index.html 完整背包界面，组合上述全部组件

写新代码前先扫一遍 — 如果你要做的东西能用上面任意一个组件实现，直接复用，不要重新发明。

如果要做的组件不在列表里，参考 Step 4 自由构建，但务必：

  • 所有颜色用 semantic token
  • 所有间距用 --ri-space-*
  • 所有字号用 --ri-font-size-* 配套 --ri-line-height-*
  • 字体一律用 var(--ri-font-serif)

Step 4 — 是否需要 surface 素材

复古工业的灵魂是那些网点、墨泼、颗粒、金属纹理的 SVG 素材。当构建卡片、面板、Toast 等"表面"类组件时，优先考虑使用 assets/ 下的素材作为背景。素材对应关系：

组件/场景 资源文件 用途描述
物品卡 assets/surfaces/card-surface.svg 卡片表面的网点/颗粒纹理
详情区 / 图片底 assets/surfaces/item-image-bg.svg 蓝墨泼溅底（也用于 Toast 光晕）
列表行容器 assets/surfaces/list-surface.svg 列表行背景（待使用）
Toast 横条 assets/surfaces/toast-surface.svg Toast 横条暖黄网点（v0.4 投入使用）
面板装饰 assets/decorations/panel-vector.svg 全屏右下装饰角
按钮前装饰件 assets/decorations/ri-btn-before.svg 按钮左下角网点
按钮后装饰件 assets/decorations/ri-btn-after.svg 按钮右下角叶片

使用方式（CSS）：

.ri-card {
  background-image: url('../assets/surfaces/card-surface.svg');
  background-size: cover;
  background-color: var(--ri-color-bg-card); /* fallback color */
}

Step 5 — 是否需要 icon 图标

skill 内置 152 个图标（v0.7 起）。优先从 skill 图标库取，禁止自创图标。

查图标的方式：

  • 浏览器打开 assets/icons/preview.html 看所有图标 + 搜索 + 切换颜色
  • 程序化查找：assets/icons/icon-manifest.json
  • 详细文档：assets/icons/ICONS.md

两套版本：

  • assets/icons/general/themed/<name>.svg —— 默认用这个。#323232 → currentColor，靠 CSS color 控制
  • assets/icons/general/raw/<name>.svg —— 保留原色，仅在需要保留品牌色（如某些彩色装饰图标）时用

🚨 路径约定（必读，避免图标 404）

skill 内部所有 SPEC.md 中图标 URL 统一使用占位符 [ICON_BASE]、[ICON_RAW_BASE]、[SURFACE_BASE]、[DECORATION_BASE]。Agent 把 SPEC 代码复制到业务项目时，必须替换占位符为真实路径：

占位符 业务侧需要替换为
[ICON_BASE] 业务项目中 themed 图标的实际路径（如 ./assets/icons/general/themed、@/assets/icons、/icons）
[ICON_RAW_BASE] raw 图标的实际路径
[SURFACE_BASE] 质感纹理（card-surface.svg 等）的实际路径
[DECORATION_BASE] 装饰件（ri-btn-before.svg 等）的实际路径

详细映射规则见 assets/icons/ICONS.md 的"业务侧路径约定"章节。

核心使用模式（只有这三种是有效的）：

<!-- 模式 1: 内联 SVG（最强大，可动画）-->
<svg class="ri-icon" viewBox="0 0 80 80" style="color: var(--ri-color-text-cream)">
  <!-- 粘贴 themed/<n>.svg 内容 -->
</svg>

<!-- 模式 2: CSS mask（最干净，纯装饰）-->
<style>
  .ri-icon-close {
    width: 24px; height: 24px;
    background-color: var(--ri-color-text-cream);
    -webkit-mask: url("[ICON_BASE]/close.svg") center/contain no-repeat;
            mask: url("[ICON_BASE]/close.svg") center/contain no-repeat;
    /*               ^^^^^^^^^^^^ 业务侧把 [ICON_BASE] 替换为实际路径 */
  }
</style>
<span class="ri-icon-close" aria-hidden="true"></span>

<!-- 模式 3: <img> 配合 raw 版（颜色不需要变时）-->
<img src="[ICON_RAW_BASE]/action.svg" alt="" />

⚠️ 不要 用 <img src="themed/x.svg"> —— <img> 把 SVG 当位图，外部 CSS color 不生效。详见 assets/icons/ICONS.md。

⚠️ 不要双击 HTML 用 file:// 协议打开 —— Safari 等浏览器在 file:// 下会拒绝加载 SVG mask，必须用本地 HTTP 服务器（python3 -m http.server 8080）。详见 ICONS.md。

图标颜色 token 速查：

场景 Token
默认深底图标 --ri-color-text-cream
高亮/关闭 --ri-color-text-cream-hi
警示/错误 --ri-color-text-loss
成功/增益 --ri-color-text-gain
进度/强调 --ri-color-accent-progress
品牌主色 --ri-color-brand-primary

Step 6 — Light / Dark 主题

双主题开箱即用。只需在 <html> 或根容器加 data-theme="dark"：

<html data-theme="dark"> <!-- Dark 主题 -->
<html>                   <!-- 默认 Light 主题 -->

所有 var(--ri-color-*) 会自动切换。不要给同一个组件写两套 class——那是错的。

Step 7 — 响应式分辨率适配（v0.10 新增）

skill 从 v0.10 起已完成 rem 化响应式适配。你几乎不需要为此做任何事——只要继续用 token。

开箱即用的效果：

窗口宽度 1rem 效果
≤ 1920px（常规 PC 笔记本） 11.23px（70.2% 缩放） 按钮字号 28px、Modal 比例缩小
1920px-2730px（流体过渡） 11.23 → 16px 平滑缩放
≥ 2730px（Pad 原生） 16px（100%） 完全还原设计稿

核心机制：

html {
  font-size: clamp(11.23px, calc(100vw / 171), 16px);
}
/* 所有 rem 值都随根字号缩放 */

业务侧使用规则：

  1. 正常用 token——token 已经是 rem，自动缩放：

    .my-component {
  padding: var(--ri-space-32);       /* = 2rem, auto-scales */
  font-size: var(--ri-font-size-30); /* = 1.875rem, auto-scales */
}

  2. 不要硬编码 px（除例外情况，见"第一原则"）：

    /* ❌ 错：不响应式 */
.my-card { width: 300px; }

/* ✅ 对：用 token（如有对应值）*/
.my-card { width: var(--ri-width-card-lg); }

/* 🟡 可接受：独特尺寸，rem 化并注释 */
.my-card { width: 18.75rem; /* = 设计稿 300px */ }

  3. 阴影 / 1-2px 描边 / transform 几何保留 px——这些参数不应缩放（光影和工艺边界）。

完整的响应式策略文档：docs/responsive-strategy.md

两种响应式策略：

  • 🟢 rem + clamp（v0.10 默认）：适用于绝大多数组件和页面
  • 🟡 transform: scale 整舞台：适用于像背包页这种"沉浸式完整画布"的 pattern（见 patterns/backpack/index.html）

核心规则（禁止违反）

🔴 第一原则：Token 优先且唯一（强制纪律）

所有视觉属性必须通过 token 表达，禁止任何形式的硬编码。 这条规则不是"建议"——是 skill 的存在前提。违反这条规则就违反了"设计系统"本身。

适用范围（无例外）：

  • 颜色（color, background, border-color, box-shadow 颜色）→ var(--ri-color-*)
  • 字号 + 行高（必须配套使用）→ var(--ri-font-size-N) + var(--ri-line-height-N)
  • 字体 → var(--ri-font-serif)，禁止其他字体（普惠体保留给未来其他主题）
  • 字重 → var(--ri-weight-regular | medium | bold)
  • 间距（padding, margin, gap）→ var(--ri-space-N)
  • 圆角 → var(--ri-radius-*)
  • 描边粗细 → var(--ri-stroke-*)
  • 阴影 / drop-shadow → var(--ri-shadow-*) / var(--ri-drop-shadow-*)
  • 图标尺寸 → var(--ri-sizing-*)

严格禁止：

  • ❌ 任何形式的色值字面量：#XXXXXX、rgb(...)、rgba(...)、hsl(...)、white、black 等
  • ❌ 任何硬编码 px 数字（除了下方"例外"列出的几何/光影场景）
  • ❌ 任何 font-family 字面量
  • ❌ 复制粘贴 SPEC 里 token 注释中的 hex 值（注释里写 #EB6728 只是给人看的，代码里必须是 var(--ri-color-button-primary-bg)）

v0.10 关键规则：Token 已 rem 化

从 v0.10 起，所有尺寸类 token（字号 / 间距 / 圆角 / 描边 / 图标尺寸）都以 rem 为单位输出。配合响应式根字号 html { font-size: clamp(11.23px, calc(100vw / 171), 16px) }，整个系统自动适配 PC 到 Pad 的宽度范围。

对业务侧的影响：几乎没有——继续用 var(--ri-*) token 就行，不需要知道底层是 rem 还是 px。但不能再硬编码 width: 300px（不响应式），应改用 token 或至少改写成 18.75rem（附 /* = 设计稿 300px */ 注释）。

详见 docs/responsive-strategy.md。

遇到没有对应 token 的值怎么办：

如果某个视觉属性在现有 token 里找不到对应值，不要硬编码绕过去。正确流程：

  1. 优先：找最接近的 token 用上（即使略有偏差），并在代码注释标注 // TODO(design-system): need token for X, currently using Y as approximation
  2. 次选：如果偏差太大无法接受，新增 token 到 skill，而不是硬编码：
    • 在 tokens/semantic/retro-industrial.json 加新 entry
    • 跑 python3 scripts/build.py 重新编译
    • 提 PR 到 design-system 仓库
    • 等合并后再用新 token

例外（仅以下情况允许 px 字面量）：

  • 阴影参数：box-shadow: 0 4px 14px rgba(...) 里的 px 是光影效果参数，保留 px（不随缩放变化，避免糊/过大）
  • 1-2px 描边：border: 1px solid var(...)（工艺边界，保持精确像素）
  • Transform 几何：translateY(-2px), rotate(45deg) 等交互微反馈
  • Viewport 单位：max-width: 100%, height: 100vh
  • 响应式断点 @media 查询：@media (max-width: 768px)（断点本质是 viewport 查询，必须 px）
  • 透明度数值：opacity: 0.5（除非未来定义了 --ri-opacity-* token）
  • 注释中的示例 hex 值（仅供阅读，不能粘进代码）

🔴 第二原则：状态区分纪律（v0.12 新增，强制纪律）

组件的 hover / selected / focus / active 等激活态，不能凭直觉设计视觉手法，必须按 docs/state-differentiation.md 的三原则决定：

原则速查：

组件角色 激活态手法 典型组件
列表选择器（高密度） 半透明底色 + 文字变色 MenuRow, Select option, BranchChoice, Dialogue
独立可选卡片（低密度） 大幅描边 + 发光 ItemCard
开关类 底色切换 Switch, Checkbox, Radio
输入类 focus 边框变色 + 发光 Input, Textarea, Select trigger
按钮类 本体色 + transform Button

严禁：

  • ❌ 列表选择器用描边区分 selected（在高密度排列下会造成锯齿冲突）
  • ❌ 输入框 focus 用底色覆盖（会盖住用户内容）
  • ❌ 同一设计系统内同类组件用不同手法（如 MenuRow 用描边、Select 用底色—— v0.12 已统一到底色）

允许破例：

  • 有明确理由（如 ItemCard 低密度网格用描边）
  • 必须在组件 SPEC 中说明破例理由
  • 并加入 docs/state-differentiation.md 的"破例清单"

列表选择器统一的橙色 alpha 阶梯：

/* default     — 无橙色覆盖（组件自身 default 底） */
/* hover       — 橙 8%  半透覆盖 */
/* selected    — 橙 15% 半透覆盖 + 文字变 brand-primary + bold */
/* selected+hover — 橙 22% 半透覆盖 */
/* pressed     — 橙 28% 半透覆盖（press 瞬间）*/

🔴 第三原则：布局契约与完整实现纪律（v0.14 新增，强制纪律）

解决的问题：避免"中间态 UI"（既不是完整页面也不是弹窗的居中窄卡片）+ 避免"视觉层偷工减料"（伪元素/纹理/mask 等被省略）。

3.1 开工前必须声明布局类型

任何 UI 任务，编码前必须且只能确定一种布局类型：

代号 适用
FULL_PAGE_DESKTOP 桌面完整页面（背包、商店、设置中心）
MODAL_DIALOG 模态弹窗（ConfirmDialog、Modal）
DRAWER 侧边抽屉（系统菜单）
NON_MODAL_PANEL 非模态浮层（SettingsPanel、音量调节）
INLINE_FRAGMENT 内联片段（单组件、嵌入其他页面的区块）

禁止的"中间态"：

  • ❌ FULL_PAGE_DESKTOP 任务做成窄列居中竖版卡片（移动端形态）
  • ❌ MODAL_DIALOG 没有遮罩（变成伪弹窗）
  • ❌ 不明确是页面还是弹窗的"通用居中卡片"

每种布局类型的详细结构契约见 docs/layout-contract.md。

3.2 视觉层必须完整实现（禁止偷工减料）

SPEC 里定义的以下内容都是视觉语言的一部分，不能省略：

  • 🔴 伪元素装饰层（::before / ::after 画的网点、光晕、装饰件）
  • 🔴 素材资产（card-surface.svg 网点纹理、panel-vector.svg 装饰角）
  • 🔴 混合模式（mix-blend-mode: screen / multiply）
  • 🔴 渐变和覆盖层（background: linear-gradient(...) 多层叠加）
  • 🔴 阴影发光（shadow-card-selected 的暖黄光晕等）

Agent 容易省的地方：为了"先出原型"跳过纹理层、伪元素层。这等于降级视觉——必须全部实现。

3.3 阻塞与降级协议

当实际受限无法完全实现规范要求（如找不到素材文件、浏览器兼容性问题）：

  1. 先说明阻塞点——告诉用户哪里做不到、为什么
  2. 列出具体缺失项
  3. 征得用户明确同意再降级
  4. 代码里标注：
    • 普通降级：/* TEMPORARY DOWNGRADE: <原因> */
    • 布局降级：/* TEMPORARY LAYOUT DOWNGRADE: <原因> */

禁止静默降级——不能"默默把纹理层省掉然后说做好了"。

🟢 其他核心规则

  1. 思源宋体统一：Retro-Industrial 主题所有文本一律使用 var(--ri-font-serif)。普惠体是为未来其他主题预留的。
  2. 行高 = 字号 × 1.5：无论何时设置 fontSize，必须配套设置对应的 lineHeight。
  3. 按钮装饰件配套：主/次按钮共用 ri-btn-before.svg + ri-btn-after.svg，主按钮 mix-blend-mode screen，次按钮 multiply。disabled 时装饰件隐藏。详见 components/button/SPEC.md。
  4. 素材图不自创：需要质感纹理时只用 assets/ 里的 SVG，不让 Claude 自己生成"类似"的纹理——那会破坏品牌一致性。
  5. 优先用既有组件：写新代码前先扫一遍 components/ 下的 SPEC，能复用 ri-card、ri-button、ri-modal 等就直接用，不要重新发明。

反例（绝对不要）

// ❌ 硬编码颜色和像素
<button style={{ background: '#EB6728', padding: '12px', borderRadius: '8px' }}>

// ❌ 用了错的字体
<div style={{ fontFamily: 'Inter, sans-serif' }}>

// ❌ 行高不配套
<p style={{ fontSize: 30 }}>复古工业</p>

// ❌ 原子色当语义色用
<span style={{ color: 'var(--ri-palette-orange-900)' }}>

正例

// ✅ CSS 变量
<button className="ri-button ri-button--primary">提交</button>

// ✅ Tailwind preset
<button className="bg-ri-button-primary-bg text-ri-button-primary-fg px-24 py-12 rounded-button-base font-serif text-s30 font-medium">
  提交
</button>

// ✅ TS/React inline
import { riTokens } from './tokens/build/tokens';
<div style={{ color: riTokens.color['text-body'], padding: riTokens.space.s16 }}>

目录结构

retro-industrial-design-system/
├── SKILL.md                        ← 你正在读的文件
├── README.md                       ← 团队安装与贡献指南
├── CHANGELOG.md
│
├── tokens/
│   ├── primitives/                 ← 原子层（调色板、字号阶梯、间距阶梯）
│   │   ├── colors-light.json
│   │   ├── colors-dark.json
│   │   ├── typography.json
│   │   └── dimensions.json
│   ├── semantic/                   ← 语义层（component-oriented）
│   │   └── retro-industrial.json
│   └── build/                      ← 编译产物，代码直接消费
│       ├── tokens.css              ← CSS 变量（含 light/dark）
│       ├── tokens.ts               ← TS 类型安全访问
│       └── tailwind.preset.js      ← Tailwind preset
│
├── assets/
│   ├── surfaces/                   ← 表面背景纹理
│   │   ├── card-surface.svg
│   │   ├── item-image-bg.svg
│   │   ├── list-surface.svg
│   │   └── toast-surface.svg
│   ├── decorations/                ← 装饰元素
│   │   ├── panel-vector.svg
│   │   ├── ri-btn-before.svg
│   │   └── ri-btn-after.svg
│   └── icons/                      ← 152 个图标（v0.7 新增）
│       ├── general/
│       │   ├── raw/                ← 原始版（保留 #323232）
│       │   └── themed/             ← currentColor 版（推荐）
│       ├── icon-manifest.json      ← 清单 + 分类
│       ├── ICONS.md                ← 使用文档
│       └── preview.html            ← 浏览器预览（搜索 + 换色）
│
├── components/                     ← 组件规范
│   ├── button/SPEC.md              ← 主/次按钮
│   ├── page-background/SPEC.md     ← 全屏背景
│   ├── modal/SPEC.md               ← 模态容器
│   ├── modal-header/SPEC.md        ← 标题栏 + 关闭按钮
│   ├── divider/SPEC.md             ← 分隔线
│   ├── item-card/SPEC.md           ← 物品卡（3 态）
│   ├── item-grid/SPEC.md           ← 4 列网格 + 滚动条
│   ├── item-detail-panel/SPEC.md   ← 右侧详情面板
│   ├── toast/SPEC.md               ← 数值变化提示（with-icon / text-only）
│   ├── branch-choice/SPEC.md       ← 互动视频分支选择（含倒计时 + 多语言）
│   ├── dialogue/SPEC.md            ← NPC 对话系统（对话框 + 可选 1-5 个回应选项）
│   ├── slider/SPEC.md              ← 数值滑块（v0.8）
│   ├── switch/SPEC.md              ← 布尔开关（v0.8）
│   ├── settings-panel/SPEC.md      ← 非模态设置面板（v0.8）
│   ├── confirm-dialog/SPEC.md      ← 二选一确认弹窗（v0.8）
│   ├── menu-row/SPEC.md            ← 共享菜单行原子（v0.9）
│   ├── drawer/SPEC.md              ← 侧边抽屉（v0.9）
│   ├── list-panel/SPEC.md          ← 列表模态（v0.9）
│   ├── loading-page/SPEC.md        ← 全屏加载页（v0.9）
│   ├── empty-state/SPEC.md         ← 空状态/错误状态（v0.9）
│   ├── input/SPEC.md               ← 文本输入框（v0.11）
│   ├── textarea/SPEC.md            ← 多行文本框（v0.11）
│   ├── select/SPEC.md              ← 下拉选择（v0.11）
│   ├── checkbox/SPEC.md            ← 复选框（v0.11）
│   ├── radio/SPEC.md               ← 单选按钮（v0.11）
│   └── form-field/SPEC.md          ← 表单字段布局器（v0.11）
│
├── patterns/                       ← 页面级完整模板
│   └── backpack/
│       ├── index.html              ← 完整背包页参考实现
│       ├── assets/                 ← 配套素材
│   ├── backpack/                   ← 背包页 pattern（使用 transform: scale 整体缩放）
│   │   ├── index.html
│   │   ├── assets/
│   │   └── README.md               ← 使用与数据注入说明
│   └── component-gallery/          ← 组件看板（含响应式测试栏，v0.9 新增）
│       ├── index.html
│       ├── tokens.css              ← 拷贝自 tokens/build/
│       ├── assets/
│       └── README.md
│
├── QUICKSTART.md                   ← 新项目快速上手（v0.13 新增，Agent 第一站）
│
├── components/
│   ├── INDEX.md                    ← 组件索引 + 场景决策表（v0.13 新增）
│   ├── button/SPEC.md
│   ├── ...（省略其他组件 SPEC，完整列表在 INDEX.md）
│
├── docs/
│   ├── token-mapping.md            ← HTML→Token 映射表（参考用）
│   ├── responsive-strategy.md      ← 响应式策略文档（v0.10 新增）
│   ├── state-differentiation.md    ← 状态区分规则（v0.12 新增）
│   ├── component-selection.md      ← 组件选择决策集（v0.13 新增）
│   ├── code-review-checklist.md    ← Code review 对照清单（v0.13 新增）
│   └── layout-contract.md          ← 布局契约（5 种布局类型定义，v0.14 新增）
│
└── scripts/
    ├── build.py                    ← 重新编译 tokens 产物（v0.10 起输出 rem）
    ├── themify-icons.py            ← 处理新增图标（去 #323232 → currentColor）
    └── process_raw_figma.py        ← Figma 原始 JSON 清洗

当前版本 & 局限

当前版本：v0.14.1（图标路径占位符化 + drawer 坏文件名修复 + file:// 警告强化）

已覆盖：

  • ✅ 完整双主题原子层颜色（9 色系 × 12 阶）
  • ✅ 完整字号、字重、间距、描边阶梯（全部 rem 化）
  • ✅ 语义层 token：color、shadow (12 项)、radius (9 项)
  • ✅ 动画 token（duration + easing）+ 断点 token（bp-mobile/tablet/desktop/wide）
  • ✅ 7 个素材资源 + 152 个图标
  • ✅ 27 个组件规范（Button 3 变体）:
    • 基础：Button, PageBackground, Modal, ModalHeader, Divider
    • 内容：ItemCard, ItemGrid, ItemDetailPanel
    • 反馈：Toast, LoadingPage, EmptyState
    • 对话剧情：BranchChoice, Dialogue
    • 容器：ConfirmDialog, SettingsPanel
    • 导航：MenuRow, Drawer, ListPanel
    • 表单：Slider, Switch, Input, Textarea, Select, Checkbox, Radio, FormField
  • ✅ 1 个完整 pattern（背包页）+ 1 个组件看板（含响应式测试栏 + §11 状态区分规则章节）
  • ✅ Tokens 产物：CSS 变量（带 clamp 根字号）、TS 类型、Tailwind preset
  • ✅ 三大系统文档：token-mapping + responsive-strategy + state-differentiation（v0.12 新增）
  • ✅ 工程级规范：多语言适配、字符溢出策略、RTL 支持、业务可控高亮
  • ✅ 图标库系统：raw + themed 双版本、manifest、preview HTML、3 种使用模式
  • ✅ 响应式适配（v0.10）：rem + clamp 根字号，PC/Pad 自动缩放
  • ✅ 表单家族（v0.11）：基于已有设计语言推导，0 新 token
  • ✅ 状态区分规则（v0.12）：三原则 + 橙色 alpha 阶梯 + 破例清单

尚未覆盖（已知缺口）：

  • ⚠️ Dark 模式的语义层映射尚未验证
  • ⚠️ DatePicker / TimePicker / NumberInput 等复杂表单待补
  • ⚠️ Tabs / Breadcrumb / Pagination / Stepper 等导航辅助待补
  • ⚠️ Table / Badge / Tag / Avatar 等数据展示待补
  • ⚠️ 移动端 < 768px 的结构降级未定义
  • ⚠️ 背包 pattern 仍用 transform: scale（有意保留）
  • ⚠️ 表单家族视觉方案基于设计语言推导，待设计师最终 review

遇到上述缺口时：在代码中用最接近的 token，并在注释里标注 // TODO(design-system): ...，便于后续补齐。绝不通过硬编码绕过去（见上方"第一原则：Token 优先且唯一"）。

Installs
3
Source
skill.new.ndhy.…n-system
First Seen
Apr 24, 2026