design-system-showcase

name: design-system-showcase description: 'Build a full design-system skill package with showcase site for a real project or brand. Produces: SKILL.md, CHEATSHEET.md, token CSS, reference docs (tokens, anti-patterns, components, mockup-to-react), HTML templates with snippets, a React+Vite showcase SPA, demo HTML→PDF pipeline, and TypeScript verification scripts. Triggers on "create a design system / extract visual language / build design tokens / make a showcase site / 做设计系统 / 提取视觉语言 / 生成 token".'

Design System Showcase Skill

Create a portable design-system skill package and its showcase site from a real project, product, or brand. The output is an npm package: researched visual language, CSS tokens, a one-page cheatsheet, reference docs, HTML mockup templates, a React showcase SPA, demo HTML files with PDF exports, and TypeScript verification.

Core Principles

• Start from real artifacts, not generic taste. Use official product pages, docs, repositories, screenshots, logos, decks, or user-provided materials.
• Keep SKILL.md procedural and lean — a task routing table, not a brochure. Put detailed design rules in references/.
• CHEATSHEET.md is the daily driver. Agents read it before every mockup or component task. Full rationale lives in references/tokens.md.
• Use progressive disclosure. Tell the agent exactly when to read each reference file.
• Generate assets only after the design language is documented. The showcase, templates, and demos must all consume the same src/tokens.css.
• Never invent brand facts, logos, screenshots, product UI, metrics, dates, or partnerships. Mark gaps or ask once.

Target Repository Shape

.
├── CHEATSHEET.md              # One-page quick reference (invariants, color table, typography, spacing, quick decisions)
├── LICENSE
├── README.md                  # Install + usage + verify
├── SKILL.md                   # Lean execution guide with task routing
├── package.json               # npm package: exports, scripts, devDependencies
├── references
│   ├── anti-patterns.md       # "What NOT to do" with code examples
│   ├── components.md          # Component catalog + selection rules
│   ├── mockup-to-react.md    # HTML→React translation table
│   └── tokens.md             # Full token spec with rationale and edge cases
├── scripts
│   ├── check.ts              # TypeScript lint: token drift, banned classes, raw hex
│   ├── check.test.ts         # Unit tests for check.ts
│   └── generate-pdfs.sh      # Headless Chrome PDF generation
├── showcase
│   ├── index.html            # Entry point (Google Fonts preconnect, mount React)
│   ├── public
│   │   ├── demos
│   │   │   ├── _shared.css          # Shared demo stylesheet
│   │   │   ├── demo-post.html       # Long-form post demo (zh)
│   │   │   ├── demo-post.en.html    # Long-form post demo (en)
│   │   │   ├── demo-post.pdf
│   │   │   ├── demo-post.en.pdf
│   │   │   ├── demo-resume.html     # Resume demo (zh)
│   │   │   ├── demo-resume.en.html
│   │   │   ├── demo-resume.pdf
│   │   │   ├── demo-resume.en.pdf
│   │   │   ├── demo-report.html     # One-page report demo (zh)
│   │   │   ├── demo-report.en.html
│   │   │   ├── demo-report.pdf
│   │   │   └── demo-report.en.pdf
│   │   └── favicon.svg
│   ├── src
│   │   ├── App.tsx                   # Root: Toolbar + sections
│   │   ├── i18n.ts                   # Bilingual support (zh/en)
│   │   ├── main.tsx                  # React entry
│   │   ├── styles.css                # Tailwind v4 entry + showcase CSS
│   │   ├── theme.ts                  # Theme toggle (light/dark, URL param + localStorage)
│   │   ├── sections
│   │   │   ├── Hero.tsx              # Project name, positioning, core token preview
│   │   │   ├── OutputSamples.tsx     # Demo cards with iframe preview + PDF download
│   │   │   ├── Manifesto.tsx         # Numbered invariants grid
│   │   │   ├── Color.tsx             # Neutral + accent + semantic swatches
│   │   │   ├── Typography.tsx        # Font roles + size scale
│   │   │   ├── Spacing.tsx           # Spacing + radius tiers
│   │   │   ├── Components.tsx        # Component catalog reference
│   │   │   ├── Snippets.tsx          # Live snippet demos
│   │   │   ├── AntiPatterns.tsx      # What NOT to do (visual)
│   │   │   ├── Decision.tsx          # Quick decision table
│   │   │   ├── Background.tsx        # Background / texture reference
│   │   │   └── Footer.tsx
│   │   └── snippets
│   │       ├── CodeBlock.tsx
│   │       ├── CommentThread.tsx
│   │       ├── Form.tsx
│   │       ├── Modal.tsx
│   │       └── Sheet.tsx
│   ├── tsconfig.json
│   └── vite.config.ts
├── src
│   └── tokens.css                    # Canonical Tailwind v4 @theme tokens
└── templates
    ├── scaffold.html                 # HTML scaffold with dark mode toggle + all tokens
    └── snippets
        ├── code-block.html
        ├── comment-thread.html
        ├── form.html
        ├── hero.html
        ├── list-card.html
        ├── logo.html
        ├── modal.html
        ├── sheet.html
        └── stat-grid.html

Add only the files that serve the skill or the showcase. Do not add installation guides, quickstart docs, or process notes unless explicitly asked.

Bundled Assets

This skill includes ready-to-use files. Copy or adapt them into the target project instead of generating equivalents from scratch.

Read references/cheatsheet-format.md before writing the project's CHEATSHEET.md. Read references/design.spec.md for the DESIGN.md token format specification when writing references/design.md.

Workflow

Step 1 · Scope the System

Identify the subject and intended outputs.

Record:

• Project name and one-line positioning
• Primary audience
• Supported languages (default: Chinese-first with English)
• Color system: palette source, naming convention (e.g., Japanese 和色)
• Typography: font roles (sans/serif/mono), CJK fallback requirement
• Distribution: monorepo package, standalone repo, or both

If scope is ambiguous, choose a minimal default:

• SKILL.md + CHEATSHEET.md
• src/tokens.css
• references/tokens.md + references/anti-patterns.md
• templates/scaffold.html + 3 snippets
• scripts/check.ts
• showcase/ (Hero + Color + OutputSamples sections minimum)
• One demo: showcase/public/demos/demo-post.html + PDF
• package.json + README.md

Step 2 · Gather Source Material

Use primary sources first:

• Official website and docs
• Product screenshots or user-provided captures
• Existing logo, icons, fonts, and brand files
• Repository source code (especially existing CSS/Tailwind config)
• Real output samples from the product

Create a short source ledger in working notes before writing design rules:

| Source | Type | Date checked | Useful facts | Gaps |
|---|---|---:|---|---|
| [Name](URL) | Official site | YYYY-MM-DD | Logo, tone, color palette | No typography specs |

Source rules:

• Current facts such as versions, prices, funding, metrics, launches, and market claims must be checked.
• If sources conflict, use the most official source or ask the user once.
• If a logo, UI screenshot, or product image is missing, mark it as a gap. Do not draw an approximate logo.

Step 3 · Extract the Design Language

Convert the research into a constraint system. Produce three outputs:

3a. src/tokens.css — Canonical Tailwind v4 tokens

@theme {
  --color-accent: #...;
  --color-neutral-1: #...;
  /* ... through --color-neutral-10 */
  --color-info: #...;
  --color-success: #...;
  --color-warning: #...;
  --color-error: #...;
  --color-border: rgba(...);
  --font-sans: ...;
  --font-serif: ...;
  --font-mono: ...;
}

3b. CHEATSHEET.md — One-page quick reference

Read references/cheatsheet-format.md for the exact structure, section order, and parser-critical formatting rules before writing this file.

1. Invariants — 8–12 numbered rules (the core contract)
2. Color — Neutral table (var, hex, tier, use) + accent + semantic
3. Typography — Font stack vars + size/use table
4. Spacing & radius — Gap tier table + radius table
5. Backdrop blur (if applicable) — Level table
6. Quick decisions — "Need X → use Y" lookup table
7. Verification — the check command and what it validates

Every hex in the cheatsheet must match src/tokens.css. The verify script enforces this.

3c. references/tokens.md — Full spec with rationale

Deep dive on every token group: the WHY behind each value, dark mode behavior, edge cases, and the reasoning the cheatsheet condenses away.

Step 4 · Write Reference Docs

Read references/design.spec.md for the DESIGN.md token format specification.

references/anti-patterns.md

Structure by category (Color, Typography, Layout, Components, Process). Each anti-pattern shows:

1. Wrong code example
2. Right code example
3. Why it matters

Cover at minimum:

• Banned Tailwind default classes (e.g., neutral-50…950)
• N-5 misuse as text color
• Raw hex outside the contract
• Accent overuse
• Synthetic bold on CJK
• Hardcoded font-family
• Hard drop shadows
• Skipping the cheatsheet

references/components.md

• Inventory of existing UI primitives (file tree)
• Selection rules: Modal vs Dialog vs Sheet, Button vs Link vs Tag
• Rules for adding a new UI entry
• Import conventions

references/mockup-to-react.md

• General rules (structure first, no new tokens during handoff)
• Mapping table: HTML mockup pattern → React component
• Handoff steps (1–5)
• What to do when the mapping table is silent

Step 5 · Define the Output SKILL.md

The generated project's SKILL.md is an execution guide with a task routing table:

## Step 1 · Identify the task

| User says | Task tier | Read |
|---|---|---|
| "make a mockup for X" | **New mockup** | `CHEATSHEET.md` + `references/tokens.md` + `references/anti-patterns.md` |
| "build component X" | **New React component** | `CHEATSHEET.md` + `references/components.md` + `references/anti-patterns.md` |
| "convert this mockup to React" | **Handoff** | `references/mockup-to-react.md` + `references/components.md` |
| "audit this file for token compliance" | **Token audit** | `references/anti-patterns.md` + `references/tokens.md` |

Follow with Step 2 (Produce) and Step 3 (Verify) — procedural, not descriptive.

End with a "When NOT to use this skill" section and a "Languages" note.

Step 6 · Build Templates

templates/scaffold.html

Copy templates/scaffold.html from this skill to the target project, then replace every hex value in :root with your project's actual token values (from src/tokens.css). The structure, dark mode block, and toolbar are complete and need no other changes.

templates/snippets/

Reusable HTML sections that use only token vars. Minimum set:

• hero.html — hero section with title, tagline, CTA
• list-card.html — card grid or list
• form.html — form with input, label, button
• modal.html — dialog overlay
• sheet.html — bottom/side sheet
• code-block.html — syntax-highlighted code
• stat-grid.html — metrics/stats layout
• comment-thread.html — comment UI
• logo.html — brand mark (if applicable)

Each snippet must:

• Use only var(--color-...), var(--font-...) — no raw hex
• Work inside scaffold.html without modification
• Be self-contained (no external dependencies beyond the scaffold's <style>)

Step 7 · Build the Showcase

The showcase is a React + Vite SPA that proves the system by displaying real outputs.

package.json

{
  "name": "@[scope]/design-system",
  "type": "module",
  "exports": {
    "./tokens.css": "./src/tokens.css",
    "./skill": "./SKILL.md",
    "./cheatsheet": "./CHEATSHEET.md"
  },
  "scripts": {
    "check": "tsx scripts/check.ts",
    "test": "tsx --test scripts/check.test.ts",
    "showcase:dev": "vite --config showcase/vite.config.ts",
    "showcase:build": "vite build --config showcase/vite.config.ts",
    "showcase:preview": "vite preview --config showcase/vite.config.ts",
    "demo:pdf": "bash scripts/generate-pdfs.sh"
  },
  "devDependencies": {
    "@tailwindcss/vite": "^4.1.0",
    "@types/react": "^19.0.0",
    "@types/react-dom": "^19.0.0",
    "@vitejs/plugin-react": "^6.0.0",
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "tailwindcss": "^4.1.0",
    "tsx": "^4.19.0",
    "typescript": "^6.0.0",
    "vite": "^8.0.0"
  }
}

Showcase sections (in order)

Showcase infrastructure

Copy these files from the bundled templates/showcase/ directory:

• vite.config.ts → showcase/vite.config.ts (verbatim)
• main.tsx → showcase/src/main.tsx (verbatim)
• theme.ts → showcase/src/theme.ts (verbatim)
• i18n.ts → showcase/src/i18n.ts, then replace all dict entries with project-specific copy
• styles.css → showcase/src/styles.css, then fill in all /* CUSTOMIZE */ blocks
• package.json → package.json, then fill in @SCOPE and DESCRIPTION

Add showcase/index.html (not bundled — must be written per project):

<!doctype html>
<html lang="zh-CN" data-theme="light">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
    <title>[Project] · Design System</title>
    <meta name="description" content="[One-line description]" />
    <!-- Add Google Fonts preconnect + stylesheet links here -->
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>

Demo files

At minimum 3 demo types in showcase/public/demos/:

Each demo has 4 variants: {name}.html, {name}.en.html, {name}.pdf, {name}.en.pdf.

All demo HTML files import _shared.css which sources tokens from src/tokens.css.

Step 8 · Write Verification Scripts

Copy scripts/check.ts, scripts/check.test.ts, and scripts/generate-pdfs.sh from this skill to the target project's scripts/ directory.

scripts/check.ts — copy verbatim. It reads src/tokens.css, CHEATSHEET.md, and templates/ from the project root, so no path changes are needed.

scripts/check.test.ts — copy verbatim.

scripts/generate-pdfs.sh — copy, then update the DEMOS array at the top to list your demo base names:

DEMOS=(
  "demo-post"
  "demo-resume"
  "demo-report"
)

All three scripts are self-contained and require no other modifications.

Step 9 · Verify and Iterate

Run validation before shipping:

# Lint token drift + template compliance
pnpm check         # or: tsx scripts/check.ts

# Unit tests for the check script
pnpm test          # or: tsx --test scripts/check.test.ts

# Generate PDFs from demo HTML
pnpm demo:pdf      # or: bash scripts/generate-pdfs.sh

# Build showcase for deployment
pnpm showcase:build

Checks to enforce:

• Token drift: every hex in CHEATSHEET.md matches src/tokens.css
• Banned classes: no text-neutral-50…950 in templates
• Raw hex: no literal hex (except #fff/#000) in inline styles
• Font contract: no hardcoded font-family — use var(--font-*)
• CJK fallback: every font stack includes CJK families
• PDF generation: all demo HTML produces valid PDF

If a check fails, fix the source (token CSS or template), not the exported artifact.

Gotchas

• A showcase without real demo assets is not convincing. Create at least one complete demo flow (HTML → PDF).
• A skill with only design adjectives is weak. Convert taste into tokens, invariants, code examples, and automated checks.
• The CHEATSHEET.md and src/tokens.css are the two sources of truth. Everything else derives from them. If they disagree, the verify script must catch it.
• CJK typography needs special attention: no synthetic bold, mandatory fallback chains, font-medium (500) cap.
• Demo PDFs expose small CSS mistakes. Avoid alpha badge backgrounds, hard shadows, unsupported browser-only layout tricks, and missing font fallbacks.
• Logo fonts (--font-logo-*) are separate from body fonts (--font-sans/serif/mono). Never mix them.
• The showcase SPA must consume the same src/tokens.css as the templates. One contract, one source.
• Do not use Python for verification — use TypeScript (tsx) to stay in one toolchain.
• Large or licensed fonts may belong in the repository for local preview but not in the distributable package.

Delivery Checklist

• SKILL.md has accurate frontmatter and task routing table
• CHEATSHEET.md captures invariants, color/type/spacing tables, quick decisions, verify command
• src/tokens.css declares all tokens as Tailwind v4 @theme
• references/tokens.md provides full rationale for every token group
• references/anti-patterns.md lists wrong/right code pairs by category
• references/components.md catalogs UI primitives with selection rules
• references/mockup-to-react.md provides a complete mapping table
• templates/scaffold.html contains all token vars + dark mode + toolbar
• templates/snippets/ has at least 5 reusable HTML sections
• scripts/check.ts validates token drift + template compliance
• scripts/check.test.ts has passing unit tests
• scripts/generate-pdfs.sh produces PDFs from demo HTML
• showcase/ builds successfully with Vite and renders all sections
• showcase/public/demos/ has at least 1 demo type (zh + en + PDF)
• package.json has correct exports, scripts, and devDependencies
• README.md explains install, usage (CSS import), package structure, and verify command