mstar-design-md

• Primary: project root

  DESIGN.md

  (human + agent visible, aligns with

  AGENTS.md

  )
• Dark theme: project root

  DESIGN.dark.md

  (same token names, different values)

• DESIGN.md

  is a project-level design contract, not a harness internal artifact. It lives beside

  README.md

  and

  AGENTS.md

  .

• @frontend-dev

  /

  @fullstack-dev

  — read DESIGN.md before implementing styled components; map tokens to CSS/theme variables

• @qc-specialist

  — verify UI implementation aligns with DESIGN.md tokens

• @qa-engineer

  — verify visual output matches design spec when

  QA gate: mandatory

plan(locked)

1. PM includes "DESIGN.md creation/audit" in Prepare tracking checklist when the plan involves UI

2. @architect

   creates or updates DESIGN.md;

   @product-manager

   reviews design intent alignment
3. PM gates on: DESIGN.md exists, meets completeness level declared in plan,

   @product-manager

   signed off

1. Level 1 — MVP (minimal, prevents guesswork): palette, base typography, spacing scale
2. Level 2 — Standard (consistent components): full token scales, breakpoints, component tokens (Button, Input)
3. Level 3 — Production (complete design system): dual theme, elevation, motion, shapes, component library, voice

<!-- LEVEL2_PLACEHOLDER: ... -->

references/completeness-checklist.md

1. Read

   references/design-md-spec.md

   for section definitions and YAML frontmatter structure
2. Copy

   templates/DESIGN.md.template

   to

   {PROJECT_ROOT}/DESIGN.md

   — the template includes the full YAML frontmatter skeleton
3. Interview

   @product-manager

   for brand colors, typography preferences, must-have patterns
4. Fill Level 1 frontmatter tokens (uncomment and replace

   "[placeholder]"

   values with concrete hex/px values)
5. If plan requires Level 2+ out of the gate, uncomment and fill those sections too
6. Update the body prose to match the frontmatter values (target audience, aesthetic principles, rhythm rules)
7. Run the completeness audit workflow below to confirm level
8. Report to PM: path created, level achieved, what's needed for next level

1. Read

   DESIGN.md

   and

   DESIGN.dark.md

   (if exists) — parse the YAML frontmatter for structured token values
2. Load

   references/completeness-checklist.md

3. Check each checklist item; note gaps in both frontmatter (missing/uncommented keys, placeholder values) and body (missing rules/documentation)
4. Report:
   • Current completeness level
   • Gaps preventing next level (frontmatter gaps vs. body gaps, tagged separately)
   • Presence of upgrade placeholders (

     LEVEL2_PLACEHOLDER

     ,

     LEVEL3_PLACEHOLDER

     in both frontmatter comments and body HTML comments)
   • Recommendation: whether to upgrade now or defer
5. Update DESIGN.md level tag (e.g.,

   <!-- COMPLETENESS_LEVEL: 1 — last audited YYYY-MM-DD -->

   ) if changed

1. Read existing

   DESIGN.md

   to extract token names
2. Copy

   templates/DESIGN.dark.md.template

   to

   {PROJECT_ROOT}/DESIGN.dark.md

3. For each token in DESIGN.md, define the dark-theme equivalent value
4. Preserve same token names; only values change (see

   references/design-md-spec.md

   § Light/Dark rules)
5. Audit with Workflow 2 to confirm Level 3 completeness

1. Read

   DESIGN.md

   (and

   DESIGN.dark.md

   if exists)
2. Parse the YAML frontmatter for token values — this is the SSOT for colors, typography, spacing, rounded, and components
3. Resolve component

   {colors.X}

   ,

   {typography.X}

   ,

   {rounded.X}

   references by tracing back to the corresponding frontmatter keys
4. Extract tokens into implementation layer (CSS custom properties, Tailwind config, theme object, etc.)
5. Follow DESIGN.md body Voice & Content rules for copy text
6. If DESIGN.md is missing, has no frontmatter, or is incomplete, report to PM — do not guess tokens

DESIGN.md         DESIGN.dark.md
-----------       --------------
gray-100: #fff    gray-100: #111
gray-1000: #000   gray-1000: #eee

• Token names are the SSOT interface — consumers reference tokens by name, not raw values

• references/design-md-spec.md

  § Light/Dark rules defines the contract

Engine check (when available): run

mstar design-md validate <dir>

(or

import { validateDesignTokenFrontmatter, assertLightDarkParity, completenessLevel } from "@mstar-harness/engine"

in a host hook) to validate the token frontmatter schema above, the light/dark parity of

DESIGN.dark.md

(same token names, different values), and the achieved completeness level. On

fail

-> do not proceed; fix and re-run. Skill text below remains authoritative when the runtime is absent.

• references/design-md-spec.md

  — normative spec: section definitions, token naming conventions, light/dark contract

• references/completeness-checklist.md

  — three-level audit checklist with detailed criteria per level

• references/vercel-example.md

  — Vercel Geist DESIGN.md as annotated reference (read when creating from scratch or needing design inspiration)

• templates/DESIGN.md.template

  — full template including all Level 1-3 sections with placeholder comments

• templates/DESIGN.dark.md.template

  — dark theme template with same token names, different values