/design-system

name: design-system
description: Creates the Tamagui brand system for an Expo/React Native Power Apps mobile app, including design-system.md, tokens.ts, and an HTML gallery.
user-invocable: true
allowed-tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion, Task, WebFetch
model: opus

**Shared instructions: [shared-instructions.md](../../shared/shared-instructions.md)** — read first.

Design System

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 + `npx power-apps 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 `/tweak-screen` (deterministic, 0 tokens)
• 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 env var CODE_APPS_NATIVE_ORCHESTRATING=1
   → Mode A (folded into /create-mobile-app Step 6.5)

2. Check cwd 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 current directory? [y/N]"

For Mode A/B, set `working_dir` to cwd. For Mode C, confirm with user.

**Drift detection (Mode B only — 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)

---

Sub-step 1 — Brand inputs

**Telemetry checkpoint: `collect_brand_inputs`**

**Print:** > "→ [design-system] Checking for brand inputs…"

**MUST stop and wait for user response.** Do NOT skip this step.

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` (hig