designseeddocs

Editor

Validation & linting

1 min read

The validator is the safety net. It runs continuously in the editor and on every export, so you never publish a DESIGN.md that fails the schema or the contrast budget.

What it checks

Schema integrity

  • Every required role exists (primary, ink, bg, accent, muted).
  • Font family includes a sans stack with at least one entry.
  • Type ramp has a base size; sizes parse as valid CSS lengths.
  • Light theme is complete; dark theme either matches the light theme's keys or is intentionally empty.

Contrast

  • AA body text (4.5:1) for every text/background pair.
  • AA large text (3.0:1) for buttons + headings.
  • AAA body (7.0:1) — flagged as a soft warning, not a hard fail.

Round-trip integrity

  • Every value parses cleanly through the CSS export, the Tailwind preset emit, and the DTCG JSON emit. A token that survives one but not the others is a bug.

Theme parity

  • If light has 12 tokens, dark should have 12 (or be explicitly empty). Asymmetric themes confuse downstream consumers.

How issues are reported

Each issue carries:

  • A severity — error (fails the export) or warning (informational).
  • A location — the field in the editor, plus the line number in the rendered DESIGN.md.
  • A fix hint — concrete suggested value when the validator can compute one.

Click any issue in the right rail to jump to the responsible field. Fix it, save, and the issue clears immediately.

Running outside the editor

designdrop validate                 # validates ./DESIGN.md
designdrop validate apps/web/DESIGN.md

The CLI runs the same rules. Wire it into pre-commit:

# .husky/pre-commit
designdrop validate apps/web/DESIGN.md || exit 1

Or in CI:

# .github/workflows/ci.yml
- run: pnpm dlx designdrop validate apps/web/DESIGN.md