Mstar Design Md

Load order

Before first Read of this skill: Read mstar-harness-core (SKILL.md). For Prepare phase integration and gate rules, read mstar-phase-gates. For plan directory paths ({HARNESS_DIR}, {SPECS_DIR}), read mstar-conventions. On conflict, mstar-harness-core wins.

Scope (DESIGN.md lifecycle)

YAML frontmatter is the SSOT for token values. Colors, typography, spacing, rounded, and components live in the frontmatter as structured, machine-readable data. The Markdown body is supplementary documentation (rules, intent, usage guidance). When reading DESIGN.md, always parse the YAML frontmatter first; when writing, keep frontmatter and body in sync.

Out of scope: rendered UI preview tooling outside the repo; frontend implementation that consumes DESIGN.md tokens (use @frontend-dev / @fullstack-dev); QC review verdict rules (→ mstar-review-qc).

Location

• 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.

Prototype vs document

When the repository also ships a prototype, this document is a summary of that prototype, not a second source:

• Authority. The prototype is the design; DESIGN.md states in prose what it establishes. On conflict the prototype wins — unless the prototype is silent, in which case the decision and its reason belong in DESIGN.md. An unrecorded silence becomes a guess in the next implementation.
• One-directional sync. baseline → fixture → document. Change the prototype, rerun the generator that derives the machine-readable fixture, then bring DESIGN.md in line. Hand-editing the fixture, or iterating in DESIGN.md and back-filling the prototype, is the reverse direction and a defect regardless of which side turns out to be right.
• The fixture must be a tracked file derived from a tracked source. A deriver or comparator that reads a gitignored working path at runtime has no baseline: on a clean checkout it fails, and in the degraded mode it warns and exits 0, which reads as a pass forever.
• A lagging document fails nothing. A fixture that lags the prototype fails its check; nothing fails when DESIGN.md lags both. That direction is a review obligation: the reviewer compares the document against the fixture, because no gate will.

Converging an implementation onto that baseline — baseline kinds, parity layers, defect / decision / phantom triage — → skill mstar-design-system.

Role lifecycle

Creator: @architect (primary) + @product-manager (requirements)

@architect owns DESIGN.md content — token selection, naming, completeness level decisions. @product-manager provides design intent: brand identity, target audience, must-have UI patterns, accessibility requirements.

Orchestrator: @project-manager

In Prepare phase, PM decides whether the project needs a DESIGN.md. If yes, dispatches to @architect with product requirements from @product-manager. PM checks DESIGN.md exists and meets the assigned completeness level before plan(locked).

Consumers

• @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

Phase gate integration

DESIGN.md is a Prepare-stage artifact (like spec). It must be created and reviewed before plan(locked) for any plan that includes UI work.

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

For hotfix or plans with no UI changes, DESIGN.md check may be skipped.

Completeness levels（Evidence）

DESIGN.md supports three levels, each with built-in upgrade path:

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

The template includes all levels; Level 2 and 3 sections are commented out with <!-- LEVEL2_PLACEHOLDER: ... --> markers that explain when to activate them. The audit workflow detects these placeholders and can recommend upgrade.

Full checklist → references/completeness-checklist.md.

Workflows

Workflow 1: Create DESIGN.md (Prepare phase)

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

Workflow 2: Audit DESIGN.md completeness

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

Workflow 3: Add dark theme

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

Workflow 4: Consume DESIGN.md (implementation roles)

Before writing styled UI code:

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

Light/Dark dual-theme rules

Dual theme uses same token names, different values across two files:

Copy code
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

• 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 (this skill):

• 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