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.

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.

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]".

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

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

Workflow

Step 1 — Gather Visual Data

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.

Step 2 — Extract Tokens

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.

Step 3 — Document Components

For each component, document all CSS properties including states:

markdown

### 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.

Step 4 — Write Brand Voice

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

Step 5 — Write Do's / Don'ts

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

Step 6 — Generate Outputs

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.

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.

tokens.json → DESIGN.md

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

variables.css → DESIGN.md

Parse

:root {}

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

tokens.json ↔ variables.css ↔ theme.css

Direct mapping:

$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

rico-design-md

NPX Install

Tags

SKILL.md Content