Design System From Reference — Skill (v0.2)

What you (Claude) actually do

You are a multimodal model running inside Claude Code. When you Read a PNG file, you see the image. This skill exploits that: the harvest script dumps a dozen small focused screenshots (rest+hover buttons, individual headings, individual cards, hero crop, nav strip) instead of one giant full-page PNG. You read those small images one at a time, describe what you see in design-token terms, and use the JSON files alongside only for exact numeric values.

This is the whole point of v0.2: the previous version tried to grep compiled CSS, which only works on Tier 1 sites. Looking at pixels works on any site whose buttons are made of pixels.

When invoked

User typed /design-system-from <url> or asked you to follow this skill with a reference URL. They expect:

1. A tier classification with honest expectations.
2. A design.md populated with REAL values from the harvest.
3. A minimal ds/ folder + /design-test sandbox.
4. A "Frontend Design System" section appended to CLAUDE.md.
5. A summary of what was harvested, what's high-confidence vs guessed.

If no URL — ask for one. Without calibration the output is generic AI aesthetic, which defeats the point.

Workflow

Step 0 — Locate the bundle

This SKILL.md ships next to capture.mjs and templates/. Find the bundle absolute path. Common locations: ~/tools/design-system-starter/, ~/.claude/skills/design-system-starter/, ~/dev/design-system-starter/, /tmp/dss/ (one-prompt zero-install path).

If not found in defaults — ask the user.

Step 1 — Run the harvest

cd "$BUNDLE_DIR"
[ ! -d node_modules ] && npm install
[ ! -d ~/.cache/ms-playwright ] && npx playwright install chromium

TARGET=<user-url> node capture.mjs

Output lands in /tmp/<sitename>-extract/. Manifest:

Step 2 — Tier classification (do this before extraction)

Read tier-hints.json. Apply this rubric to classify the site:

canvas_area_ratio > 0.5                        → Tier 4 (Canvas-heavy)
hashed_classes > total_classes * 0.5           → Tier 3 (CSS-in-JS)
tailwind_like_classes > total_classes * 0.3
  AND custom_props_in_html < 20                → Tier 2 (Tailwind utility)
custom_props_in_html > 30
  OR semantic_classes > 20                     → Tier 1 (Semantic CSS / design tokens)
otherwise                                       → Tier 2 (default)

Report the tier to the user with honest expectations:

For Tier 4/5: stop here. Tell the user what you found and offer alternatives (e.g. "share a screenshot of the page section you want and I'll extract from that").

Step 3 — Vision-first extraction

This is the heart of the skill. You are a multimodal model. Read the small focused PNGs, describe what you see, then use JSON for exact numbers. Don't try to grep tokens out of compiled CSS — that approach falls apart on Tailwind, CSS-in-JS, and canvas-driven sites. Looking at pixels works on anything visible.

3a — First impression (sets the vibe)

Read 02-fold-desktop.png. In your head, answer:

• Is the canvas dark or light?
• Are there ambient gradients/auras on the background, or flat?
• Typography weight — heavy or thin?
• Density — generous whitespace or compact?
• Mood — editorial, technical, playful, brutalist?

These adjectives drive token defaults for everything below.

3b — Buttons (run for every btn-*-rest.png you have)

For each named button:

1. Read btn-<name>-rest.png AND btn-<name>-hover.png (both, side by side mentally).
2. Describe the hover delta in plain English: "background lightens", "shadow shifts down 2px", "border brightens by ~30%", "no visible change" — whatever you actually see.
3. Read btn-<name>.json for the exact numeric values backing your observation.
4. Categorize: is this a primary CTA (filled / accented), an outline secondary, or a header/ghost tertiary? Use both size and prominence signals.

Pick the single most prominent button as accent-cta in your design.md. Pick the next as outline. Pick the smallest/quietest as ghost.

3c — Typography (run for every heading-*.png)

For each heading screenshot:

1. Read heading-<tag>-N.png.
2. Visually: is the text plain colored or gradient-painted? (Gradient-painted = different colors blending within letterforms, often pastel halos.)
3. Read big-text-styles.json entry N. If webkitTextFillColor === 'rgba(0, 0, 0, 0)' AND backgroundImage contains radial-gradient or linear-gradient — yes, painted. Extract the gradient stops verbatim into design.md.
4. Note tracking sign: letterSpacing numeric — positive or negative? Display-font tracking is editorial signal.

3d — Cards (run for card-0.png, card-1.png, card-2.png)

For each card screenshot:

1. Read card-N.png.
2. Describe: solid surface, gradient surface, border-only, glassmorphism? Hover affordance?
3. Read cards-inventory.json for exact bg/border/radius/shadow values.
4. If multiple cards share the same recipe — write ONE card recipe in design.md, not three.

3e — Color extraction discipline

By the time you've read 8-12 PNGs, you've seen the palette. Compile the canonical token list:

• 2-3 canvas/surface levels (background, raised surface, nested surface)
• 3 text levels (primary, secondary, muted)
• 1 brand accent (the color of the primary CTA you identified)
• 0-3 secondary accents (only if you saw clearly distinct accent uses)
• 4 status colors — if the site doesn't use status states obviously, use generic green/blue/amber/red-300 from Tailwind (this is fine, status is generic)

Do not invent accents you didn't see. Do not copy every color the site happens to use into a token (e.g. a s