design-system

> **Plugin check**: Run `node "${PLUGIN_ROOT}/scripts/check-version.js"` - if it outputs a message, show it to the user before proceeding. **Shared instructions: [shared-instructions.md](../../shared/shared-instructions.md)** — read first. # Design System **Entry routing:** use the shared [App feature entry points](../../shared/shared-instructions.md#app-feature-entry-points) preflight before the workflow below. Before reading brand state, bind `working_dir` through [app-working-directory.md](../../shared/references/app-working-directory.md). Use that root for every shell call and absolute file-tool path, including history, rollback, previews, and runtime wiring in the referenced workflows. Read-only `--history` / `--diff` and standalone brand generation without an app remain here. Source of truth for every screen built in a Power Apps mobile app. Produces three artifacts: 1. `brand/design-system.md` — full spec (palette, typography, spacing, components, negatives) 2. `brand/tokens.ts` — importable Tamagui token export 3. `brand/design-system.html` — deterministic visual gallery (zero LLM cost) Design-system and Tamagui integration are complementary, not alternatives. `/design-system` owns user-facing brand/design decisions and preview artifacts; `/create-mobile-app` Step 9b applies [`references/tamagui-integration.md`](./references/tamagui-integration.md) as internal implementation plumbing so those decisions become Tamagui tokens, aliases, and provider props. The old separate `tamagui-design-system` skill existed before this split was clear; keeping it separate made users choose implementation details and added prompt surface. Do not reintroduce it as a user-invocable skill. ## When to use - **Step 6.5** — auto-invoked from `/create-mobile-app` after scaffold + `pa app init`, before screen builders - **Standalone** — `/design-system` callable any time to create or refresh a brand system - **Refresh** — `/design-system --refresh <dimension>` to change one aspect - **Reskin** — `/design-system --reskin` for full visual layer swap - **Dark mode** — `/design-system --add-dark-mode` to derive + wire dark theme ## When NOT to use - Screen-level visual tweaks → use `/edit-app` - Plan-level screen changes → use `/edit-app screens` - Data model changes → use `/add-dataverse` or `/setup-datamodel` ## Inputs - `working_dir` — absolute path to project root (auto-detected or passed by orchestrator) - Optional flags: `--brand-doc`, `--logo`, `--from-url`, `--design-spec`, `--from-canvas-app`, `--from-code-app`, `--from-figma`, `--stylesheet`, `--power-pages-mode` - Optional: `--refresh <dimension>` — palette | typography | components | density | negatives | motion - Optional: `--reskin` — full theme swap - Optional: `--add-dark-mode` — derive + wire dark theme - Optional: `--add-theme <name>` — add named theme variant - Optional: `--history` / `--diff <ts>` / `--rollback <ts>` — version history ## References — read before executing - [`references/design-system-schema.md`](./references/design-system-schema.md) — schema for `brand/design-system.md` - [`references/preview-template.md`](./references/preview-template.md) — HTML template for gallery render - [`references/refresh-flow.md`](./references/refresh-flow.md) — single-dimension refresh logic - [`references/input-modes.md`](./references/input-modes.md) — how each input flag is processed - [`references/vibe/brand-examples.md`](./references/vibe/brand-examples.md) — real-world brand examples (Uber, Linear, Intercom, Sentry) - [`references/vibe/style-picker.md`](./references/vibe/style-picker.md) — internal folded style picker --- ## Sub-step 0 — Mode detection + setup **Print:** > "→ [design-system] Detecting project context…" Detect invocation mode: ``` 1. Check MOBILE_APP_ORCHESTRATING=1 AND matching explicit caller context → Mode A (folded into /create-mobile-app or approved /edit-app work) 2. Check the resolved working_dir for app.config.js + tamagui.config.ts + package.json with expo deps → Mode B (standalone in existing project) 3. Else → Mode C (standalone, no project) → Ask: "No native project detected. Write brand/ to <working_dir>? [y/N]" ``` All modes retain the already resolved `working_dir`; do not resolve another root from the launch directory. Mode C still requires user confirmation before writes. **Write boundary (all paths):** `--plan-only` or a planning-phase handoff returns only a proposal; do not write brand artifacts, previews, history, or memory-bank. Detect prior brand state before generating anything: an existing spec, light or dark token file, gallery, history, or record of a previously applied design makes this a rerun, not first-time generation. A new creation plan alone is not prior brand state; first-time drafts generated in this invocation remain drafts during edit/regeneration, not pre-existing approved designs. Keep proposed choices and memory-bank notes pending until approval. On reruns, do not overwrite live artifacts or existing previews during input/style selection; any comparison preview must be proposal-only. Every generation/reskin rerun uses **Sub-step 3.5** before its first live write, even if its cost path or input flag skips other sub-steps. Dedicated refresh, dark-mode, and rollback commands retain their own equivalent approval/backup flows; do not add a second gate to them. **Drift detection (Mode A/B — existing brand/ present):** If `brand/design-system.md` AND `brand/tokens.ts` both exist: 1. Parse current tokens.ts palette + typography tokens 2. Parse current design-system.md ## Palette and ## Typography 3. Compute diff 4. If divergent → surface drift, ask user to resolve before proceeding (see [refresh-flow.md](./references/refresh-flow.md) § Drift) Treat that resolution as a proposal until the concrete approval and backup boundary (Sub-step 3.5 for generation reruns); do not repair drift during detection. --- ## Sub-step 1 — Brand inputs **Telemetry checkpoint: `collect_brand_inputs`** **Print:** > "→ [design-system] Checking for brand inputs…" Reuse brand inputs and decisions in the approved caller scope. Ask only for missing inputs; return scope-changing choices to `/edit-app` rather than reopening an independent design flow. Fresh creation still owns the interactive brand selection below when those choices have not yet been made. Ask user for optional brand input. See [`references/input-modes.md`](./references/input-modes.md) for full processing details. ``` You're building {{app_name}} — a {{industry}} app. {{screen_count}} screens, {{entity_count}} entities. Do you have any brand input? (skip with Enter): (1) Skip — use Field/Ops industry defaults No brand assets. I'll pick a direction from 3 visual styles (or you can skip style-picking entirely). High contrast, large tap targets, safety-first colors. (2) Free-text notes > "Slate-blue accent, no orange. Must look at home next to ServiceTitan." (3) Logo PNG / JPG > --logo ~/Downloads/logo.png (4) Design doc (markdown, PDF, or text) > --brand-doc ~/projects/brand.md > --design-spec ~/work/design-system.md (5) More options… > --from-url https://contoso.com (extract palette from live site) > --from-canvas-app ~/exports/my-app.msapp (extract from canvas app) > --from-code-app ~/projects/sibling-web (extract from code app) > --from-figma <file-key> (extract from Figma) Skip? [Enter to skip — same as option 1] ``` If flag was passed on invocation, skip asking — process directly. **On input provided:** Extract palette/typography tokens immediately (~3-5k tokens). Print extracted summary: > "→ [design-system] Extracted from {{input}}: {{primary color}}, {{font family}}, {{N}} tokens." **On skip:** Continue with no brand context. **Priority order** when multiple inputs given: 1. `--design-spec` (highest — skips style/spec generation, not Sub-step 3.5 or confirmation) 2. `--brand-doc` (locks direction, skips Sub-step 3) 3. `--from-figma` (locks palette + typography + components) 4. `--from-code-app` (highest fidelity sibling) 5. `--from-canvas-app` (locks palette + typography + conventions) 6. `--logo` (extracts palette, applied as tint) 7. `--from-url` / `--stylesheet` (palette extractors) 8. Free-text notes (always applied as overrides on top) --- ## Sub-step 2 — Cost picker **Telemetry checkpoint: `select_design_depth`** **Print:** > "→ [design-system] How much design depth do you want?" Show the cost picker, adapting the intro and option set to brand input. **If brand input was provided, print:** `Brand input applied ✓ — {{primary color}}, {{font family}} extracted.` Default: **c**. | Option | Label | Behavior | Cost | |---|---|---|---| | a | Full design | See 3 browser styles, pick one, then get component reference; brand tints all options. | ~3 min, ~25k tokens | | b | Spec + reference | Pick a style in chat, write full design spec, see component reference sheet. | ~1 min, ~8k tokens | | c | Brand preview | Apply brand to List + Form + Detail mockups; skip style picker and component sheets. | ~30 sec, ~2k tokens | | d | Skip everything | Use palette with industry defaults; no previews. | <5 sec, ~0 tokens | **If NO brand input, print:** `No brand input — defaulting to polished-inspection (white surface + Power-Platform green accent + status-stripe cards + soft-tinted pills; source: references/vibe/direction-polished-inspection.md).` Default: **c**. | Option | Label | Behavior | Cost | |---|---|---|---| | a | Full design | See 3 browser styles, pick one, then get component reference; biggest visual quality gain. | ~3 min, ~30k tokens | | b | Spec + reference | Pick a style in chat, write full design spec, see component reference sheet. | ~1 min, ~12k tokens | | c | Apply defaults | Apply polished-inspection tokens and open a 3-screen preview. MVP-friendly zero-click default. | ~30 sec, ~3k tokens | **Default rationale:** `(c)` is the MVP-first-run default — Enter through every prompt and the app comes out styled with the **polished-inspection** direction (which fits ~70% of mobile-app traffic — inspection / field-ops / asset-tracking apps that demo to enterprise stakeholders). Users who want to compare 3 styles side-by-side opt INTO `(a)` explicitly. This trades "highest possible design quality on first run" (path a) for "zero clicks to a styled MVP" (path c) — the right tradeoff at MVP because the user can always re-run `/design-system` to upgrade later. **Outdoor-only opt-in:** for true field-utility apps (full sun, full shift, gloves), pass `--direction inspection` to use the dark slate + safety-orange preset instead. The MVP default is light + green because that demos better and remains usable; the outdoor-dark preset is a deliberate opt-in. **Note:** Option (c) "Brand preview" only appears when brand input was provided (there's nothing to preview without brand tokens). Keep `visual_companion: <yes|no|skip>` pending; persist it to `memory-bank.md` only after the applicable approval. **Branches:** - **(a)** → style picker (Sub-step 3), then Sub-step 3.5 before Sub-steps 4–7 (~3 min) - **(b)** → skip Sub-step 3 (style picker), run Sub-step 3.5 before Sub-steps 4–7 (spec + gallery + review) - **(c) Brand preview** → prepare the brand-token candidate, run Sub-step 3.5 before applying it, then render key screen mockups (List + Form + Detail), open browser on standalone runs only (otherwise print the path), and proceed to Sub-step 7. Skip style picking and full-spec generation, not the write boundary. No extra question about how many screens — always shows 3 key screens. - **(c) Apply defaults / (d) — no-brand path** → skip Sub-steps 3, 5. Run these in order: 1. **Minimal Sub-step 4** — prepare `brand/tokens.ts` from the industry's direction preset, then run Sub-step 3.5 before writing it. **Source-of-truth lookup order for the preset bundle:** 1. If the user passed `--direction <name>` (e.g. `inspection`, `saas`, `product`), load `${PLUGIN_ROOT}/skills/design-system/references/vibe/direction-<name>.md` and use its tokens. 2. **Airline / aviation / commercial-flight carve-out (HARD RULE).** If the brief contains any of `airline`, `aviation`, `flight`, `aircraft`, `carrier`, `pilot`, `cabin crew`, `boarding`, `departure`, `tarmac`, `turnaround`, `ground ops`, OR the app name contains those tokens, DO NOT load the `signature` preset (safety-orange would clash with airline brand expectations). Instead **load [`${PLUGIN_ROOT}/skills/design-system/references/vibe/direction-airline.md`](./references/vibe/direction-airline.md)** — deep aviation blue (`#0A4F8F`), white surfaces, hi-vis status pills, hairline borders. Token bundle is the canonical FlightCheck tokens (proven in production). After approval, record in `memory-bank.md` as `direction: airline`. 3. **Else (true "all defaults" path) → load [`${PLUGIN_ROOT}/skills/design-system/references/vibe/direction-polished-inspection.md`](./references/vibe/direction-polished-inspection.md) as the canonical `polished-inspection` preset** — white surface, Power-Platform green `#007d48` accent (Power Platform–aligned default), status-stripe cards, soft-tinted status pills, large tap targets. This is the polished MVP default that fits any inspection / field-ops / asset-tracking app (~70% of mobile-app traffic) AND demos cleanly to enterprise stakeholders. The previous `signature` preset (slate dark + safety orange, sourced from `uber-design.md`) is now opt-in via `--direction inspection` for true outdoor-only field apps. 4. As a last fallback, if the source file is unreadable, use the inspection direction inlined in [`references/design-system-schema.md`](./references/design-system-schema.md). For first-time defaults, skip the full `brand/design-system.md` write — only `brand/tokens.ts` is needed. If a prior full design exists, do not silently replace its tokens with defaults: Sub-step 3.5 must approve the concrete token delta and corresponding spec-section updates together, or preserve both unchanged. Record the chosen source in `memory-bank.md` only after approval under `## Design`: `direction: polished-inspection (default — white + Power-Platform green, demo-friendly enterprise polish)` so future runs know what was picked. 2. **Mini-preview (Sub-step 6.5 lite)** — render exactly 3 screens (List + Form + Detail archetypes from the plan's `## Screens`; if fewer exist, render whichever do) using the same HTML preview template + Tamagui-to-HTML mapping as `screen-planner`, with `brand/tokens.ts` values substituted. Write to `<working_dir>/_plan_preview.html` — the canonical filename. `/create-mobile-app` takes its screen carousel from that file and the build plan links it, so writing anything else leaves both empty on this path. Open it in the browser on standalone runs only; in orchestrator mode print the path, because the build plan already links it. Print: `"→ Polished-inspection preview ready at file://<working_dir>/_plan_preview.html — confirm the look (or re-run /design-system --direction <inspection|saas|product> to switch)."`