rico-design-md

获取设计 MD

将任意网站转换为设计系统文档，或在不同格式之间转换。

应做事项

• 先阅读参考示例。 生成任何格式之前，先阅读 references/themes-github/ 中对应的文件，以确保结构完全一致。这可以避免格式偏差。
• 使用语义化令牌名称。 按作用命名令牌（如 ink、surface-1、accent-blue），而不是按外观命名（如 vapor-white、charcoal-canvas）——除非描述性名称本身就是品牌名称。
• 完整记录阴影的 CSS 语法。 写成 rgba(255,255,255,0.1) 0 0.5px 0 0.5px，不要写“微妙阴影”。下游使用者需要可解析的值。
• 记录所有观察到的组件状态。 悬停、聚焦、激活、选中——每种状态都会改变 CSS 属性。遗漏状态会导致实现不完整。
• 根据截图核验颜色值。 CSS 检查可能无法发现叠加效果、渐变混合和特定浏览器的渲染差异。请结合视觉证据交叉核对。
• 提供开源字体替代方案。 专有字体（GT Walsheim、Söhne）需要提供替代字体（Mona Sans、Inter、DM Sans），以便任何人都能实现该设计。
• 在 tokens.json 中包含 $description。 每个令牌都需要有一段易于理解的描述，说明其预期用途——这是 DTCG 标准，也能避免误用。
• 以设计点评的方式撰写品牌调性。 概述段落应像设计师描述品牌的视觉个性，而不是功能列表。

不应做事项

• 不要编造占位值。 如果源内容中缺少某类令牌（例如，未观察到阴影），就跳过该类并注明缺失之处。编造的值会损害可信度。
• 不要混用多个主题的令牌。 如果网站有浅色和深色模式，请询问用户要记录哪一种。如果深色模式在视觉上截然不同（例如 Linear、Supabase），可以提议生成单独的 dark/ 子目录，其中包含自己的 4 个文件。绝不要将两种主题的令牌混入同一份文档。
• 不要在 DESIGN.md 中使用通用的应做／不应做事项。 每条规则都必须提及具体令牌或属性。“使用良好的对比度”没有用；“仅将 accent-blue 用于超链接和焦点环”则具有可操作性。
• 不要遗漏 letter-spacing 和 line-height。 缺少这两项的排版令牌是不完整的——字距和行距与 font-size 一样，共同塑造品牌调性。
• 不要将复杂阴影简化为单个值。 分层阴影（边缘高光 + 投影）必须原样保留，不得简化为单个 box-shadow。
• 不要跳过品牌调性段落。 它是指导未来决策的设计依据。缺少它，文档就只是一堆令牌。

触发行为

命令	输出
rico DESIGN.md [url]	DESIGN.md + preview.html（默认）
rico preview [url]	仅 preview.html
rico tokens [url]	仅 tokens.json
rico variables [url]	仅 variables.css
rico theme.css [url]	仅 theme.css
rico 全部输出 [brand]	全部 5 个文件（DESIGN.md + preview.html + tokens + variables + theme）
rico 把 DESIGN.md 转为 tokens	格式转换

自然语言也会触发操作：“为 linear.app 创建 DESIGN.md”、“从 stripe.com 提取设计令牌”、“为 [url] 生成预览”。

输出结构

themes/{brand-slug}/
├── DESIGN.md         # Full style reference (default)
├── preview.html      # Visual design system preview (default)
├── tokens.json       # DTCG format tokens
├── variables.css     # CSS custom properties
└── theme.css         # Tailwind v4 @theme

默认输出： rico DESIGN.md [url] 会同时生成 DESIGN.md 和 preview.html。

preview.html 是一个独立的单文件设计系统参考页面：

• Linear 式从上到下布局（无 Bento 网格）——内容自适应，适用于任何品牌
• 章节：主视觉区 → 颜色（含色块）→ 渐变 → 排版（字号阶梯 + 字体）→ 间距与形状 → 阴影 → 深度与表面 → 组件（含实时预览）→ 应做与不应做事项
• 提供所有规范文件的下载链接（DESIGN.md、tokens.json、variables.css、theme.css）
• 带有章节锚点的粘性导航
• 滚动触发的入场动画
• 响应式设计（移动端优先）
• 基于 references/themes-github/github-preview.html 中的 GitHub 预览模板

参考示例

references/ 目录包含模板和示例文件。 生成前请先阅读对应文件——结构必须保持一致：

• DESIGN.md 模板 → references/DESIGN-TEMPLATE.md — 为新网站填写此模板
• DESIGN.md 示例 → references/themes-github/DESIGN.md — GitHub 的完整输出
• preview.html 示例 → references/themes-github/github-preview.html — GitHub 的视觉预览
• tokens.json → references/themes-github/tokens.json — DTCG 格式参考
• variables.css → references/themes-github/variables.css — CSS 自定义属性参考
• theme.css → references/themes-github/theme.css — Tailwind v4 @theme 参考

工作流

第 1 步 — 收集视觉数据

截取 hero、导航、CTA、卡片、排版区块和页脚的屏幕截图。检查 DevTools 中的 CSS 变量、@font-face、计算样式、box-shadow、border-radius 和间距。

原因： 屏幕截图能捕捉到仅靠 CSS 检查无法发现的装饰元素（渐变、辉光、插图）。

第 2 步 — 提取令牌

颜色 — 将观察到的值映射到语义令牌：

观察值	令牌	类型
页面背景	canvas	颜色
卡片背景	surface-1	颜色
高层级背景	surface-2	颜色
主文本	ink	颜色
次要文本	ink-muted	颜色
链接/强调色	accent-blue	颜色
成功	semantic-success	颜色
错误	semantic-error	颜色
边框	hairline	颜色
渐变	gradient-{name}	渐变

排版 — 记录每种字体的 fontFamily、fontSize、fontWeight、lineHeight、letterSpacing。 将字号映射到令牌：110px→display-xxl、85px→display-xl、62px→display-lg、 32px→display-md、22px→headline、15px→body、14px→body-sm、13px→caption、12px→micro。

检查 font-feature-settings 中的 OpenType 特性：cv01-99（字符变体）、ss01-20 （风格集）、tnum（等宽数字）、dlig（自由连字）。

字体替代方案：GT Walsheim → Mona Sans/Geist/Inter 600-700。Söhne → Inter/DM Sans。

间距 — 检测基础单位：4 的倍数 → base=4px。5/10/15/20 的倍数 → base=5px。

圆角 — xs(4px)·sm(6px)·md(10px)·lg(15px)·xl(20px)·xxl(30px)·pill(100px)·full(9999px)

阴影 — 仅使用完整 CSS 语法。

第 3 步 — 记录组件

针对每个组件，记录所有 CSS 属性，包括各类状态：

### Primary Button
**Role:** Main CTA
- background: `{colors.ink}` (#ffffff)
- color: `{colors.canvas}` (#0a0a0a)
- border-radius: `{rounded.pill}` (100px)
- padding: 10px 15px
- font: 14px/500/1.0/-0.14px
- hover: opacity 0.85
- active: transform scale(0.97)

组件：导航、按钮（主要/次要/半透明/图标）、定价标签、输入框（默认/聚焦）、卡片（标准/精选/聚焦展示）、对比行、页脚。

第 4 步 — 撰写品牌语调

用 5-8 句话进行设计点评：主导表面 → 字体个性 → 强调色的使用方式 → 层次处理方式 → 标志性的节奏变化 → 组件语言。

第 5 步 — 编写该做与不该做的事

每类各写 7-8 条。每条规则都须引用具体令牌并说明理由。

第 6 步 — 生成输出

阅读参考示例，然后生成所需文件。

默认： 生成 DESIGN.md + preview.html。

生成 preview.html：

1. 阅读 references/themes-github/github-preview.html 中的模板
2. 将所有 CSS 自定义属性（:root 变量）替换为品牌令牌
3. 将颜色样本、字号比例示例、间距条、圆角方框、阴影示例、层级、表面卡片和组件预览替换为品牌的实际值
4. 将 hero 文本、标签和下载链接替换为品牌专属内容
5. 将导航中的 GitHub 图标链接替换为品牌的代码仓库 URL（如适用）
6. 保持整体结构和区块顺序不变——仅更改内容/令牌
7. 在字号示例中使用品牌的实际字体系列（以 Inter 为后备字体）
8. 调整组件卡片，使其符合品牌的实际组件（按钮、输入框、卡片、导航）

单文件原则： preview.html 必须完全自包含（CSS 内联，除 Google Fonts 外无外部依赖）。直接通过 file:// 协议打开时必须能正常工作。

格式转换

DESIGN.md → tokens.json / variables.css / theme.css

解析 Markdown 表格 → 映射到目标格式。包含来自 Role 列的 $description。 按以下类别对 variables.css 分组：颜色、字体系列、字号比例、字重、间距、布局、 圆角、阴影、表面。

tokens.json → DESIGN.md

解析 DTCG 分组 → 生成 Markdown 表格 → 根据 token 关系推断组件。

variables.css → DESIGN.md

解析 :root {} → 按前缀分组（--color-、--font-、--text-、--spacing-、--radius-） → 生成表格。

tokens.json ↔ variables.css ↔ theme.css

直接映射：$value → --{name}: {value} → @theme { --{name}: {value} }

边缘情况

• SPA / 客户端渲染： 使用 view-source 和网络选项卡查找 CSS 文件
• 压缩后的 CSS： 使用 DevTools 的计算样式面板
• 多主题： 询问用户要记录哪个主题。如果深色模式在视觉上差异明显， 可提供单独的 themes/{brand}-dark/ 子目录。切勿混合两个主题的 token
• 受身份验证保护： 聚焦于公开的营销页面
• 缺少 token： 跳过相关部分，不要臆造值