design-md-planner

A skill that interviews you about your product and visual taste, commits to a specific referenced aesthetic direction, and writes a DESIGN.md design system file in Google's DESIGN.md format then audits it with the official @google/design.md CLI until it lints clean.

Why this exists

AI-generated design systems tend to converge on the same look: indigo-violet primary, Inter, rounded-2xl with a soft shadow, a centered hero, a three-column feature grid. Every individual choice is defensible. Together they read as unauthored, because nobody actually decided anything, they just landed on the statistical center of everything a model has seen.

This skill exists to prevent that. Its core rule: every value in the resulting file must trace back to a source or an argument. Not "a nice blue," but this blue, because it's the oxide on weathered copper, or the exact ink of a 1968 Braun manual. If a token can't be defended, it wasn't a decision, and it will look like it wasn't.

What it does

The skill has two jobs:

1. Mechanical — produce a valid DESIGN.md (YAML token frontmatter + markdown rationale) that passes npx @google/design.md lint with zero errors.
2. Taste — produce a system with an actual point of view: a named, referenced aesthetic direction with a real tradeoff, not a blend of adjectives.

Two modes

• Codify-existing — point it at a repo, URL, screenshots, or existing brand. It extracts what's actually there (config files, CSS variables, hardcoded hex values), reports what's consistent, what's drifted, and what's slop, then proposes a direction that's already implied by the good parts.
• Greenfield — no visual language yet. It asks a short set of high-leverage questions (what the product is, who uses it and under what conditions, what someone should feel in the first second, light/dark, hard constraints, and reference products you'd defend), then proposes 3-4 concrete named directions to choose from rather than accepting vague adjectives like "modern and clean."

The workflow

1. Pick the mode — codify-existing or greenfield, and gather the right inputs for each.
2. Propose concrete directions — 3-4 real, named aesthetics (e.g. "Swiss Editorial," "Terminal Precision," "Warm Analog"), each with an honest one-line tradeoff. The user picks or asks Claude to pick and commit.
3. Derive the system — palette (built in OKLCH, anchored to a real referent, tinted neutrals), typography (two typefaces by classification, a modular scale, deliberate tracking and weight spacing), shape/elevation/layout/motion (hierarchical radius, borders over shadows, a fixed spacing base).
4. Write DESIGN.md — sections in order: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts. Prose carries the argument, tokens carry the values. Components wire tokens to real usable states and are what the linter checks contrast against.
5. Audit with the CLI — run npx @google/design.md lint and iterate until zero errors and zero unexplained warnings.
6. Read it back with fresh eyes — a self-check pass against a slop checklist before handoff, since the linter validates structure but not taste.

Repo structure

design-md-planner/
├── SKILL.md                      # entry point: when to trigger, the full workflow
├── references/
│   ├── designmd-spec.md          # the DESIGN.md format spec
│   ├── cli.md                    # CLI command reference + fix for every lint rule
│   ├── anti-slop.md              # catalog of AI-design tells and what to do instead
│   ├── color-craft.md            # building palettes that don't look stock
│   ├── typography.md             # typeface pairing, scale derivation, type library
│   └── style-directions.md       # the named aesthetic directions and their rules
└── assets/
    ├── DESIGN.template.md        # commented skeleton to start from
    └── DESIGN.example.md         # a complete worked system, lints clean

When it triggers

Use whenever the user wants a design system, design tokens, a DESIGN.md, a style guide, a brand or visual identity, a color palette or type scale for a product, wants something to "look good" or "not look AI-generated," wants to codify the design of an existing app or site, or is starting a UI/frontend project without a pinned-down visual language, even if they never say "design system" or "DESIGN.md" explicitly.

Requirements

• Node.js (for the @google/design.md CLI, run via npx)
• On Windows PowerShell, use npx -y -p @google/design.md designmd lint since design.md collides with a file association

Output

A DESIGN.md file at the project root, chosen deliberately over docs/design.md or similar since agents look for it there by convention. Delivered alongside: the direction chosen and what it trades away, the lint audit before/after counts, and anything flagged but left for the user to decide.