mstar-design-md

Files (6)

• SKILL.md
• completeness-checklist.md · references/
• design-md-spec.md · references/
• vercel-example.md · references/
• DESIGN.dark.md.template · templates/
• DESIGN.md.template · templates/

SKILL.md (first lines)

## 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**.

| 你还可能要 Read | 何时 |
|-----------------|------|
| `mstar-phase-gates` | Prepare 阶段判定 gate、何时 DESIGN.md 必须就绪 |
| `mstar-conventions` | `{HARNESS_DIR}` / `{SPECS_DIR}` 路径解析 |
| `mstar-roles` | `@architect` / `@product-manager` / `@frontend-dev` / `@qc-specialist` / `@qa-engineer` 角色职责边界 |
| `mstar-coding-behavior` | 实现角色消费 DESIGN.md 前的通用编码约束 |
| `mstar-design-system` | 一个实现需要收敛到既有 baseline（原型 / 设计导出 / 既有产品标记 / 书面契约）时：baseline 定位与机器化、三层 parity、defect/decision/phantom 分诊、coverage 证据 |

## Scope (DESIGN.md lifecycle)

| Topic | See |
|-------|-----|
| Normative spec: section definitions, token naming, light/dark rules, **YAML frontmatter structure** | `references/design-md-spec.md` |
| Three-level completeness checklist (MVP / Standard / Production) | `references/completeness-checklist.md` |
| Vercel Geist DESIGN.md as annotated reference | `references/vercel-example.md` |
| Full template with YAML frontmatter and Level 2/3 placeholders | `templates/DESIGN.md.template` |
| Dark theme template (same token names, different values) | `templates/DESIGN.dark.md.template` |

**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

From btspoony/mstar-harness, MIT.

More from btspoony/mstar-harness