/rico-design-md

name: rico-design-md
description: >
  Create design system documents from any website URL.
  Use this skill for: DESIGN.md, preview.html, design tokens, CSS variables, style references,
  brand analysis, or format conversion between DESIGN.md/tokens.json/variables.css/theme.css.
  Trigger on: "create a DESIGN.md", "extract design tokens", "analyze [brand]'s design system",
  "reverse-engineer [url]'s visual style", "rico DESIGN.md", "rico tokens", "rico 全部输出".
  Covers: DESIGN.md, preview.html, tokens.json (DTCG), variables.css, theme.css (Tailwind v4).

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