The initial app is no longer generated by a separate command. /plan-milestones
now always makes milestone 01 'App Shell Generation' (target platform asked in
the single question round): theme from design tokens, one screen per blueprint
entry, routes, reusable components — no feature logic — plus Playwright setup
and the e2e/app-shell.spec.ts smoke spec. It is executed like any other
milestone via /execute-milestones (which loads platform-ui-generation for it)
or /add-feature. Milestone 02 becomes the MVP core. All workflow diagrams,
skills, docs READMEs, CLAUDE.md, and README updated; docs/design README also
gains the screen-inventory.md entry.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
1.**MVP first**: Phase 1 delivers the MVP; milestone 1 is its core — the smallest coherent, end-to-end usable product. Not a layer (e.g. "all the models"), but a vertical slice a user could actually use.
2.**Vertical slices**: Each feature cuts through UI → logic → data. Avoid horizontal milestones like "backend milestone" / "frontend milestone".
3.**One feature = one `/add-feature` run**: If a feature needs more than one steering directory to implement, split it. If it is a one-line change, merge it into a neighbor.
4.**One phase file = one `/execute-milestones` run**: A phase groups 1–3 milestones that together form a meaningful release.
5.**Dependency order**: A feature never lands in an earlier milestone than something it depends on, and a milestone never lands in an earlier phase than its dependencies.
6.**Exactly-once assignment**: Every feature belongs to exactly one milestone; every milestone to exactly one phase file. Deliberately deferred items go to the roadmap's "Later / Icebox" — nothing silently disappears.
7.**Living documents**: Phase files track status. `/add-feature` and `/execute-milestones` check off features (`[ ]` → `[x]`) as they complete, and milestone/phase statuses are updated in both the phase file and `roadmap.md`.
1.**App shell first**: Milestone 01 is always **App Shell Generation** — there is no separate generate-app command; the initial app is built as the first milestone (see "Milestone 01" below).
2.**MVP first**: Phase 1 delivers the MVP; milestone 02 is its core — the smallest coherent, end-to-end usable product on top of the shell. Not a layer (e.g. "all the models"), but a vertical slice a user could actually use.
3.**Vertical slices**: Each feature cuts through UI → logic → data. Avoid horizontal milestones like "backend milestone" / "frontend milestone".
4.**One feature = one `/add-feature` run**: If a feature needs more than one steering directory to implement, split it. If it is a one-line change, merge it into a neighbor.
5.**One phase file = one `/execute-milestones` run**: A phase groups 1–3 milestones that together form a meaningful release.
6.**Dependency order**: A feature never lands in an earlier milestone than something it depends on, and a milestone never lands in an earlier phase than its dependencies.
7.**Exactly-once assignment**: Every feature belongs to exactly one milestone; every milestone to exactly onephase file. Deliberately deferred items go to the roadmap's "Later / Icebox" — nothing silently disappears.
8.**Living documents**: Phase files track status. `/add-feature` and `/execute-milestones` check off features (`[ ]` → `[x]`) as they complete, and milestone/phase statuses are updated in both the phase file and `roadmap.md`.
## Inputs
@ -51,6 +52,20 @@ File naming: `phase[N]-milestones.md` with `N` starting at 1 (e.g. `phase1-miles
Use the structure in `template.md` for each phase file and for the roadmap.
## Milestone 01: App Shell Generation (always the first milestone)
The initial app is not created by a separate command — it is **milestone 01**, the first milestone of phase 1, executed like any other milestone (via `/execute-milestones phase1-milestones.md` or feature by feature with `/add-feature`). Implementation follows the **platform-ui-generation skill** for the design→code mapping.
Record the **target platform** (`web` | `flutter` | `winui3`) in the milestone's Scope. Its features are:
- [ ] Generate the app shell and theme from the design tokens — entry point, layout shell, and the platform's styling system converted from `design-tokens.json`
- [ ] Generate routes, screens, and reusable components from the UI blueprint — one screen per `ui-blueprint.json` entry, navigation wired, shared components extracted, **no feature logic**
- [ ] Set up Playwright and the app-shell smoke spec — `playwright.config.ts`, `test:e2e` script, and `e2e/app-shell.spec.ts` verifying the shell renders and every blueprint route navigates (see the e2e-testing skill; platform equivalents for flutter/winui3)
Definition of done (in addition to the standard one): the app runs, every blueprint screen is reachable, tokens are the only styling source (no hard-coded values), and no feature logic exists beyond what the documents describe.
**Dependency**: milestone 01 requires the design spec (`docs/design/`). Every later milestone depends on milestone 01.
## How to Slice Features
A well-sized feature:
@ -67,10 +82,11 @@ Too small (merge it): "Change button color" → fold into the feature that owns
## How to Group Milestones and Phases
1. Tag every feature with its PRD priority and its dependencies.
2. Milestone 1 (MVP core): the minimal dependency-closed set of P0 features that forms a usable product walk-through (a user can start, do the core job, and finish).
3.Following milestones: group remaining features by theme and priority, keeping each milestone a meaningful step on its own ("after milestone N, the user can additionally …"). Prefer 3–8 features per milestone.
4.**Phase 1** contains milestone 1 plus any milestone required to make the MVP releasable. **Following phases** group the remaining milestones into meaningful releases — prefer 2–3 phases with 1–3 milestones each.
5.A phase should be independently valuable: after `/execute-milestones phase[N]-milestones.md` finishes, the product is in a releasable state.
2. Milestone 01 (App Shell): always first — see "Milestone 01" above.
3.Milestone 02 (MVP core): the minimal dependency-closed set of P0 features that forms a usable product walk-through (a user can start, do the core job, and finish).
4.Following milestones: group remaining features by theme and priority, keeping each milestone a meaningful step on its own ("after milestone N, the user can additionally …"). Prefer 3–8 features per milestone.
5.**Phase 1** contains milestones 01 and 02 plus any milestone required to make the MVP releasable. **Following phases** group the remaining milestones into meaningful releases — prefer 2–3 phases with 1–3 milestones each.
6. A phase should be independently valuable: after `/execute-milestones phase[N]-milestones.md` finishes, the product is in a releasable state.
## Status Tracking Rules
@ -84,6 +100,7 @@ Too small (merge it): "Change button color" → fold into the feature that owns
Before finishing:
- [ ] Milestone 01 is the App Shell milestone, with its target platform recorded and the three shell features listed.
- [ ] Every P0/P1 PRD requirement maps to a feature in some milestone (or is explicitly in the icebox).
- [ ] Every feature appears in exactly one milestone; every milestone in exactly one phase file.
- [ ] Milestone numbering is global and consecutive across phase files.
Use this structure for each `docs/milestones/phase[N]-milestones.md`. A phase file contains one or more milestones; milestone numbers are global across all phase files.
**Milestone 01 is always "App Shell Generation"** (first milestone of phase 1): its In Scope records the target platform (`web` | `flutter` | `winui3`), its features are the three shell features defined in SKILL.md (theme from tokens, screens/routes from the blueprint, Playwright + app-shell smoke spec), and its Definition of Done additionally requires that every blueprint screen is reachable and no feature logic was implemented.
description: Guide for converting the design files (design-tokens.json + ui-blueprint.json) into application code for Web, Flutter, or WinUI 3. Use when running /generate-app or implementing UI against the design spec.
description: Guide for converting the design files (design-tokens.json + ui-blueprint.json) into application code for Web, Flutter, or WinUI 3. Use when executing the App Shell milestone (milestone 01) or implementing UI against the design spec.
allowed-tools: Read, Write, Edit, Bash
---
# Platform UI Generation Skill
This skill explains how to convert the design files under `docs/design/` into application code. It is used by `/generate-app` and by `/add-feature` when implementing UI.
This skill explains how to convert the design files under `docs/design/` into application code. It is used by the **App Shell milestone** (milestone 01 — planned by `/plan-milestones`, executed by `/execute-milestones` or `/add-feature`) and by `/add-feature` when implementing UI.
## Core Principles
1.**Source of truth**: `docs/design/ui-blueprint.json` defines structure; `docs/design/design-tokens.json` defines values.
2.**No hard-coded values**: every color, size, spacing, radius, and duration in generated code must come from a token.
3.**Reusable components first**: extract reusable components; do not inline the entire tree into screens.
4.**No feature logic during scaffolding**: `/generate-app` creates the shell, theme, routes, screens, and shared components only. Features come from `/add-feature`.
4.**No feature logic during scaffolding**: the App Shell milestone creates the shell, theme, routes, screens, and shared components only. Features come from the later milestones.
5.**Respect the platform mapping**: `docs/design/platform-mapping.md` documents how each artifact maps to each platform.
## Inputs
@ -85,7 +85,7 @@ Each generated reusable component must:
- Reference tokens for all visual values — no hard-coded literals.
## Scaffolding Scope (what the App Shell milestone creates)
- App entry point and shell
- Theme/styling system from tokens
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
