design-system

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

**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` (highest — skips Sub-steps 3 AND 4)
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