rico-design-md

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Get Design MD

获取设计系统文档（Get Design MD）

Convert any website into design system documents, or convert between formats.

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

Do's

正确做法

Read the reference example first. Before generating any format, read the matching file in
```
references/themes-github/
```
to match structure exactly. This prevents format drift.
Use semantic token names. Name tokens by role (ink, surface-1, accent-blue) not by appearance (vapor-white, charcoal-canvas) — unless the descriptive name is the brand's own.
Capture full CSS syntax for shadows. Write
```
rgba(255,255,255,0.1) 0 0.5px 0 0.5px
```
, not "subtle shadow". Downstream consumers need parseable values.
Document every observed component state. Hover, focus, active, selected — each state changes CSS properties. Missing states mean incomplete implementation.
Verify color values against screenshots. CSS inspection can miss overlay effects, gradient blends, and browser-specific rendering. Cross-check with visual evidence.
Provide open-source font substitutes. Proprietary fonts (GT Walsheim, Söhne) need alternatives (Mona Sans, Inter, DM Sans) for anyone implementing the design.
Include
$description
in tokens.json. Each token needs a human-readable description explaining its intended use — this is the DTCG standard and prevents misuse.
Write brand voice as design critique. The overview paragraph should read like a designer describing the brand's visual personality, not a feature list.

先阅读参考示例：在生成任何格式之前，请先阅读
```
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
```
，而非“柔和阴影”。下游使用者需要可解析的具体值。
记录所有观察到的组件状态：悬停（hover）、聚焦（focus）、激活（active）、选中（selected）——每种状态都会改变CSS属性。遗漏状态会导致实现不完整。
对照截图验证颜色值：CSS检查可能会遗漏叠加效果、渐变混合和浏览器特定渲染效果。需结合视觉证据交叉验证。
提供开源字体替代方案：对于专有字体（如GT Walsheim、Söhne），需提供替代字体（如Mona Sans、Inter、DM Sans），以便任何人都能实现该设计。
在tokens.json中包含
$description
字段：每个令牌都需要一个易于理解的描述，说明其预期用途——这是DTCG标准，可避免误用。
以设计点评的口吻撰写品牌风格描述：概述段落应像设计师描述品牌视觉个性一样，而非简单罗列功能。

Don'ts

禁忌事项

Don't invent placeholder values. If a token category is missing from the source (e.g., no shadows observed), skip it and note the gap. Fabricated values break trust.
Don't mix tokens from multiple themes. If a site has light and dark modes, ask the user which to document. If the dark mode is visually distinct (e.g., Linear, Supabase), offer to generate a separate
```
dark/
```
subdirectory with its own 4 files. Never blend tokens from both themes into one document.
Don't use generic Do's/Don'ts in DESIGN.md. Every rule must reference a specific token or property. "Use good contrast" is useless; "Reserve accent-blue for hyperlinks and focus rings only" is actionable.
Don't omit letter-spacing and line-height. Typography tokens without these are incomplete — tracking and leading define the brand voice as much as font-size.
Don't flatten complex shadows into single values. Layered shadows (light-edge + drop) must be preserved as-is, not simplified to a single
```
box-shadow
```
.
Don't skip the brand voice paragraph. It's the design rationale that guides future decisions. Without it, the document is just a token dump.

不要编造占位符值：如果源网站中缺少某个令牌类别（如未观察到阴影），请跳过该部分并注明缺失。编造的值会破坏可信度。
不要混合多个主题的令牌：如果网站有浅色和深色模式，请询问用户要记录哪个主题。如果深色模式视觉差异明显（如Linear、Supabase），可提议生成单独的
```
dark/
```
子目录，包含独立的4个文件。切勿将两个主题的令牌混合到同一文档中。
不要在DESIGN.md中使用通用的规范/禁忌：每条规则都必须引用特定的令牌或属性。“使用良好对比度”毫无意义；“仅将accent-blue用于超链接和聚焦环”才具有可操作性。
不要省略字间距（letter-spacing）和行高（line-height）：缺少这些属性的排版令牌是不完整的——字距和行高与字号一样，定义了品牌风格。
不要将复杂阴影简化为单一值：分层阴影（如边缘光+投影）必须原样保留，不能简化为单个
```
box-shadow
```
值。
不要跳过品牌风格概述段落：这是指导未来决策的设计依据。没有它，文档只是一堆令牌的堆砌。

Trigger Behavior

触发行为

Command	Output
`rico DESIGN.md [url]`	DESIGN.md + preview.html (default)
`rico preview [url]`	preview.html only
`rico tokens [url]`	tokens.json only
`rico variables [url]`	variables.css only
`rico theme.css [url]`	theme.css only
`rico 全部输出 [brand]`	All 5 files (DESIGN.md + preview.html + tokens + variables + theme)
`rico 把 DESIGN.md 转为 tokens`	Format conversion

Natural language also triggers: "create a DESIGN.md for linear.app", "extract design tokens from stripe.com", "generate preview for [url]".

命令	输出
`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]生成预览页面”。

Output Structure

输出结构

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

Default output:

rico DESIGN.md [url]

generates both

DESIGN.md

and

preview.html

The

preview.html

is a self-contained, single-file design system reference page:

Linear top-to-bottom layout (no bento grid) — content-adaptive, works with any brand
Sections: Hero → Colors (with swatches) → Gradients → Typography (type scale + fonts) → Spacing & Shapes → Shadows → Depth & Surfaces → Components (with live previews) → Do's & Don'ts
Download links for all spec files (DESIGN.md, tokens.json, variables.css, theme.css)
Sticky nav with section anchors
Scroll-triggered entrance animations
Responsive (mobile-first)

Based on the GitHub preview template at

references/themes-github/github-preview.html

themes/{brand-slug}/
├── DESIGN.md         # 完整样式参考（默认输出）
├── preview.html      # 可视化设计系统预览（默认输出）
├── tokens.json       # DTCG格式令牌
├── variables.css     # CSS自定义属性
└── theme.css         # Tailwind v4 @theme格式

默认输出：

rico DESIGN.md [url]

会同时生成

DESIGN.md

和

preview.html

。

preview.html

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

采用Linear式的从上到下布局（无网格布局）——内容自适应，适用于任何品牌
包含以下板块：Hero → 颜色（含色板）→ 渐变 → 排版（字号体系+字体）→ 间距与形状 → 阴影 → 层次与表面 → 组件（含实时预览）→ 正确做法与禁忌事项
所有规范文件（DESIGN.md、tokens.json、variables.css、theme.css）的下载链接
带板块锚点的粘性导航栏
滚动触发的入场动画
响应式设计（移动端优先）

基于

references/themes-github/github-preview.html

中的GitHub预览模板

Reference Examples

参考示例

The

references/

directory contains template and example files. Read the matching file before generating — structure must be consistent:

DESIGN.md template →
```
references/DESIGN-TEMPLATE.md
```
— fill this template for new sites
DESIGN.md example →
```
references/themes-github/DESIGN.md
```
— GitHub's complete output
preview.html example →
```
references/themes-github/github-preview.html
```
— GitHub's visual preview
tokens.json →
```
references/themes-github/tokens.json
```
— DTCG format reference
variables.css →
```
references/themes-github/variables.css
```
— CSS custom properties reference
theme.css →
```
references/themes-github/theme.css
```
— Tailwind v4 @theme reference

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格式参考示例

Workflow

工作流程

Step 1 — Gather Visual Data

步骤1 — 收集视觉数据

Screenshot hero, nav, CTAs, cards, typography sections, footer. Inspect DevTools for CSS variables,

@font-face

, computed styles, box-shadow, border-radius, spacing.

Why: Screenshots capture decorative elements (gradients, glows, illustrations) that CSS inspection alone misses.

截取Hero、导航栏、CTA、卡片、排版板块、页脚的截图。使用DevTools检查CSS变量、

@font-face

、计算样式、box-shadow、border-radius、间距。

原因：截图可以捕捉到CSS检查无法发现的装饰元素（如渐变、发光效果、插图）。

Step 2 — Extract Tokens

步骤2 — 提取令牌

Colors — Map observed values to semantic tokens:

Observed	Token	Type
Page bg	`canvas`	color
Card bg	`surface-1`	color
Elevated bg	`surface-2`	color
Primary text	`ink`	color
Secondary text	`ink-muted`	color
Link/accent	`accent-blue`	color
Success	`semantic-success`	color
Error	`semantic-error`	color
Border	`hairline`	color
Gradient	`gradient-{name}`	gradient

Typography — Record fontFamily, fontSize, fontWeight, lineHeight, letterSpacing for each font. Map sizes to tokens: 110px→display-xxl, 85px→display-xl, 62px→display-lg, 32px→display-md, 22px→headline, 15px→body, 14px→body-sm, 13px→caption, 12px→micro.

Check

font-feature-settings

for OpenType: cv01-99 (character variants), ss01-20 (stylistic sets), tnum (tabular), dlig (discretionary ligatures).

Font substitutes: GT Walsheim → Mona Sans/Geist/Inter 600-700. Söhne → Inter/DM Sans.

Spacing — Base unit detection: multiples of 4 → base=4px. Multiples of 5/10/15/20 → base=5px.

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

Shadows — Full CSS syntax only.

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

观察值	令牌	类型
页面背景	`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。

检查OpenType的

font-feature-settings

：cv01-99（字符变体）、ss01-20（样式集）、tnum（表格数字）、dlig（ discretionary ligatures）。

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

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

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

阴影 —— 仅保留完整的CSS语法。

Step 3 — Document Components

步骤3 — 记录组件

For each component, document all CSS properties including states:

markdown

undefined

对于每个组件，记录所有CSS属性及状态：

markdown

undefined

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)


Components: Navigation, Buttons (primary/secondary/translucent/icon), Pricing tabs,
Inputs (default/focused), Cards (standard/featured/spotlight), Comparison rows, Footer.

作用：主要行动召唤按钮

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)


需记录的组件：导航栏、按钮（主按钮/次要按钮/半透明按钮/图标按钮）、定价标签、输入框（默认/聚焦状态）、卡片（标准/特色/焦点）、对比行、页脚。

Step 4 — Write Brand Voice

步骤4 — 撰写品牌风格描述

5-8 sentences as design critique: dominant surface → typeface personality → accent color behavior → depth approach → signature rhythm break → component language.

用5-8句话以设计点评的口吻撰写：主导表面风格 → 字体个性 → 强调色用法 → 层次处理方式 → 标志性节奏变化 → 组件语言。

Step 5 — Write Do's / Don'ts

步骤5 — 编写正确做法/禁忌事项

7-8 each. Every rule references a specific token with reasoning.

各写7-8条。每条规则都需引用特定令牌并说明理由。

Step 6 — Generate Outputs

步骤6 — 生成输出

Read the reference example, then generate requested file(s).

Default: Generate

DESIGN.md

preview.html

preview.html generation:

Read the template at

references/themes-github/github-preview.html

Replace all CSS custom properties (
```
:root
```
variables) with the brand's tokens
Replace color swatches, type scale samples, spacing bars, radius boxes, shadow demos, depth levels, surface cards, and component previews with the brand's actual values
Replace the hero text, tags, and download links with brand-specific content
Replace the nav GitHub icon link with the brand's repository URL (if applicable)
Keep the overall structure and section order — only the content/tokens change
Use the brand's actual font family in type samples (with Inter as fallback)
Adjust component cards to match the brand's actual components (buttons, inputs, cards, navigation)

Single-file principle: preview.html must be fully self-contained (inline CSS, no external dependencies except Google Fonts). Must work when opened directly via

file://

protocol.

阅读参考示例，然后生成请求的文件。

默认输出：生成

DESIGN.md

preview.html

。

preview.html生成流程：

读取

references/themes-github/github-preview.html

中的模板

将所有CSS自定义属性（
```
:root
```
变量）替换为品牌的令牌
将色板、字号体系示例、间距条、圆角盒子、阴影演示、层次级别、表面卡片、组件预览替换为品牌的实际值
将Hero文本、标签和下载链接替换为品牌特定内容
将导航栏中的GitHub图标链接替换为品牌的仓库URL（如有）
保留整体结构和板块顺序 —— 仅更改内容/令牌
在字体示例中使用品牌的实际字体（以Inter作为 fallback）
调整组件卡片以匹配品牌的实际组件（按钮、输入框、卡片、导航栏）

单文件原则：preview.html必须完全独立（内联CSS，除Google Fonts外无外部依赖）。直接通过

file://

协议打开时必须能正常工作。

Format Conversion

格式转换

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

Parse markdown tables → map to target format. Include

$description

from Role column. Group variables.css by: Colors, Font Families, Type Scale, Weights, Spacing, Layout, Border Radius, Shadows, Surfaces.

解析markdown表格 → 映射到目标格式。包含“作用”列中的

$description

。variables.css按以下分组：颜色、字体族、字号体系、字重、间距、布局、边框圆角、阴影、表面。

tokens.json → DESIGN.md

Parse DTCG groups → generate markdown tables → infer components from token relationships.

解析DTCG分组 → 生成markdown表格 → 从令牌关系推断组件。

variables.css → DESIGN.md

Parse

:root {}

→ group by prefix (--color-, --font-, --text-, --spacing-, --radius-) → generate tables.

解析

:root {}

→ 按前缀分组（--color-、--font-、--text-、--spacing-、--radius-）→ 生成表格。

tokens.json ↔ variables.css ↔ theme.css

Direct mapping:

$value

→

--{name}: {value}

→

@theme { --{name}: {value} }

直接映射：

$value

→

--{name}: {value}

→

@theme { --{name}: {value} }

Edge Cases

边缘情况

SPA / client-rendered: Use view-source + network tab for CSS files
Compressed CSS: Use DevTools computed styles panel
Multi-theme: Ask user which theme to document. If dark mode is visually distinct, offer a separate
```
themes/{brand}-dark/
```
subdirectory. Never mix tokens from both themes
Auth-gated: Focus on public marketing pages
Missing tokens: Skip sections rather than invent values

SPA / 客户端渲染：使用查看源代码+网络面板获取CSS文件
压缩后的CSS：使用DevTools的计算样式面板
多主题：询问用户要记录哪个主题。如果深色模式视觉差异明显，提议生成单独的
```
themes/{brand}-dark/
```
子目录。切勿混合两个主题的令牌
需授权访问：专注于公开的营销页面
缺失令牌：跳过对应板块，而非编造值