mstar-design-md

Original：🇺🇸 English

Translated

DESIGN.md design system specification for Morning Star projects. Create, audit, and maintain project-level design tokens (Colors, Typography, Spacing, Elevation, Motion, Shapes, Components, Voice & Content) using Vercel Geist as reference template. Three-level completeness checklist (MVP/Standard/Production) with built-in upgrade placeholders. Supports light/dark dual-theme via DESIGN.md + DESIGN.dark.md sharing same token names with different values. Prepare 阶段由 @architect 主责创建，@product-manager 提供设计需求；@frontend-dev / @fullstack-dev 实现 UI 时消费；@qc-specialist / @qa-engineer 审查 UI 对齐 DESIGN.md。Read when PM assigns DESIGN.md creation in Prepare, initiating a new UI project, @architect defining a design system, implementing styled components, auditing UI against design spec, adding dark theme, or user mentions "DESIGN.md" / "design tokens" / "design system". Phase gate → **mstar-phase-gates**; paths → **mstar-plan-conventions**.

1installs

Sourcebtspoony/mstar-harness

Added on2026-08-16

NPX Install

npx skill4agent add btspoony/mstar-harness mstar-design-md

SKILL.md Content

View Translation Comparison →

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-plan-conventions

. On conflict, mstar-harness-core
wins.

你还可能要 Read	何时
`mstar-phase-gates`	Prepare 阶段判定 gate、何时 DESIGN.md 必须就绪
`mstar-plan-conventions`	`{HARNESS_DIR}` / `{SPECS_DIR}` 路径解析
`mstar-roles`	`@architect` / `@product-manager` / `@frontend-dev` / `@qc-specialist` / `@qa-engineer` 角色职责边界
`mstar-coding-behavior`	实现角色消费 DESIGN.md 前的通用编码约束

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

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.

PM includes "DESIGN.md creation/audit" in Prepare tracking checklist when the plan involves UI
```
@architect
```
creates or updates DESIGN.md;
```
@product-manager
```
reviews design intent alignment
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

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

Level 1 — MVP (minimal, prevents guesswork): palette, base typography, spacing scale
Level 2 — Standard (consistent components): full token scales, breakpoints, component tokens (Button, Input)
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)

Read
```
references/design-md-spec.md
```
for section definitions and YAML frontmatter structure
Copy
```
templates/DESIGN.md.template
```
to
```
{PROJECT_ROOT}/DESIGN.md
```
— the template includes the full YAML frontmatter skeleton
Interview
```
@product-manager
```
for brand colors, typography preferences, must-have patterns
Fill Level 1 frontmatter tokens (uncomment and replace
```
"[placeholder]"
```
values with concrete hex/px values)
If plan requires Level 2+ out of the gate, uncomment and fill those sections too
Update the body prose to match the frontmatter values (target audience, aesthetic principles, rhythm rules)
Run the completeness audit workflow below to confirm level
Report to PM: path created, level achieved, what's needed for next level

Workflow 2: Audit DESIGN.md completeness

Read
```
DESIGN.md
```
and
```
DESIGN.dark.md
```
(if exists) — parse the YAML frontmatter for structured token values
Load
```
references/completeness-checklist.md
```
Check each checklist item; note gaps in both frontmatter (missing/uncommented keys, placeholder values) and body (missing rules/documentation)
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

Update DESIGN.md level tag (e.g.,

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

) if changed

Workflow 3: Add dark theme

Read existing
```
DESIGN.md
```
to extract token names

Copy

templates/DESIGN.dark.md.template

to

{PROJECT_ROOT}/DESIGN.dark.md

For each token in DESIGN.md, define the dark-theme equivalent value
Preserve same token names; only values change (see
```
references/design-md-spec.md
```
§ Light/Dark rules)
Audit with Workflow 2 to confirm Level 3 completeness

Workflow 4: Consume DESIGN.md (implementation roles)

Before writing styled UI code:

Read
```
DESIGN.md
```
(and
```
DESIGN.dark.md
```
if exists)
Parse the YAML frontmatter for token values — this is the SSOT for colors, typography, spacing, rounded, and components
Resolve component
```
{colors.X}
```
,
```
{typography.X}
```
,
```
{rounded.X}
```
references by tracing back to the corresponding frontmatter keys
Extract tokens into implementation layer (CSS custom properties, Tailwind config, theme object, etc.)
Follow DESIGN.md body Voice & Content rules for copy text
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:

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