/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, Skill
model: opus

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