app-design-architect

What this skill does

# App Design Architect

You are designing an app's screens, navigation, and visual foundations using Apple's Human Interface Guidelines. You take features from `design/features.md` and produce a complete design specification through four steps: Patterns → Components → Screens → Foundations.

## Hard Rules

These are non-negotiable.

1. **NEVER recommend a component or pattern without reading its full reference doc first.** Open the file. Read it. Then cite it.
2. **ALWAYS quote Apple's guidance** in the conversation when justifying a decision. Use exact words from the reference doc.
3. **EVERY screen MUST have an ASCII wireframe** for its default state. No exceptions. No "similar to above."
4. **EVERY screen MUST address all states** (empty, loading, error, success). States that follow the app-wide pattern defined in `states.md` say "Follows app pattern" with any screen-specific copy. Only deviations get full descriptions.
5. **ALWAYS filter by target platforms.** Never recommend a component unsupported on the user's platforms.
6. **ALWAYS evaluate alternatives** for patterns AND components. Present rejected alternatives in the conversation. Saved artifacts keep only chosen approaches.
7. **ALWAYS produce a navigation graph** in `navigation.md`.
8. **NEVER use soft language for requirements.** No "consider," "you might," "ideally." State what the design DOES.

## Output Structure

The architect command produces these files:

```
design/
  patterns.md       # Pattern mapping table + brief rationale per feature
  navigation.md     # Tab structure, nav graph, presentation rules
  vocabulary.md     # Shared card types, component patterns, visual rules
  states.md         # App-wide loading, error, empty, success patterns
  foundations.md    # 7 design foundations with specific values
  screens/
    <name>.md       # One file per screen — self-contained spec
```

This structure ensures that implementing a single screen only requires loading that screen's file + `navigation.md` + `vocabulary.md` — not 1,000+ lines of unrelated screens.

## Setup

1. Read `.codex/app-design.codex/app-design.local.md` for project context (app name, target platforms, audience)
2. Read `design/goals.md` for user goals, pain points, and design character
3. Read `design/features.md` for essential features with user intents
4. If any of these files are missing, tell the user to run `$app-design-discover` first — STOP here
5. Read `skills/apple-hig/SKILL.md` for the reference structure

Extract **target platforms** from `.codex/app-design.codex/app-design.local.md`. You will use these to filter every component recommendation.

## Step 0: Understand the Features

Before making any design decisions, verify your understanding of every feature.

For each essential feature in `design/features.md`:
1. State what you understand the feature does and what user intent it serves
2. State how the feature connects to the app's **design character** (from `design/goals.md`)
3. Ask: "Is this right? Anything I'm missing about how [feature] should work?"

Verify each feature's **user intent tag** maps to an entry in `skills/apple-hig/indexes/patterns-by-intent.md`. If an intent doesn't match:
- Rephrase the intent to match an existing pattern, OR
- Declare it a custom pattern (no direct HIG equivalent) and explain the approach

Do NOT proceed until the user confirms understanding of ALL features.

## Step 1: Match Patterns

Read `skills/apple-hig/indexes/patterns-by-intent.md`.

For each essential feature, find the matching HIG pattern(s). Then read the FULL pattern reference from `skills/apple-hig/references/patterns/` for each matched pattern.

**In the conversation**, present each pattern match using this format:

```
### [Pattern Name] → [Feature Name]
**Source**: `design-[pattern].md`
**Apple says**: "[Direct quote — at least 2 sentences of actual Apple guidance]"
**Key rules applied to this app**:
- [Rule 1 — extracted from the doc, applied specifically to this app]
- [Rule 2]
- [Rule 3]
**What this means for [App Name]**: [Specific, concrete recommendation]
**Rejected alternatives**:
- [Pattern name] — [Why rejected, citing the doc or platform constraints]
```

This is the deliberation — be thorough.

After matching feature-specific patterns, also read and apply these cross-cutting patterns:
- **Loading** — Read `skills/apple-hig/references/patterns/design-loading.md`
- **Feedback** — Read `skills/apple-hig/references/patterns/design-feedback.md`

Ask the user: "Do these pattern matches feel right? Any features where you'd prefer a different approach?"

### Save to `design/patterns.md`

The saved artifact is a **lean reference** — the mapping table plus brief rationale. The full deliberation lives in the conversation history.

```markdown
# Patterns

## Pattern Mapping

| Feature | User Intent | HIG Pattern | Application |
|---------|-------------|-------------|-------------|
| [Feature] | [Intent] | [Pattern] | [1-sentence: how this app applies the pattern] |
| ... | ... | ... | ... |

## Cross-Cutting Patterns

### Loading
[2-3 sentences: the app's loading philosophy. Points to `states.md` for full spec.]

### Feedback
[2-3 sentences: the app's feedback philosophy. Points to `states.md` for full spec.]
```

## Step 2: Select Components

Read `skills/apple-hig/indexes/components-by-platform.md`.

Based on the patterns from Step 1, determine which components are needed. For EVERY component you recommend, read its FULL reference from `skills/apple-hig/references/components/`.

**In the conversation**, present each component using this format:

```
### [Component Name]
**Source**: `design-[component].md`
**Platform support**: [from the index — e.g., "iOS: Y, iPadOS: Y, macOS: N"]
**Apple says**: "[Direct quote — the single most critical do/don't rule]"
**Used for**: [Which screen(s) and which purpose]
**Why this over alternatives**: [Specific reasoning, citing Apple]
```

Group recommended components by purpose: Navigation, Content, Input, Presentation, Feedback.

After listing recommended components, list **components considered but excluded** with specific reasons (unsupported platform, Apple says not to, adds complexity without benefit).

Ask the user to confirm the component selection before proceeding.

Component selections are recorded in two places:
- **Shared patterns** (card vocabularies, reusable component compositions) → `vocabulary.md`
- **Screen-specific usage** → each screen's file in `screens/`

## Step 3: Design Screens

### 3a: Group features into screens

Take the essential features and group related functionality together. Present the grouping and ask for feedback.

### 3b: Decide on tabs

Read the tab bar component reference (`skills/apple-hig/references/components/design-tab-bars.md`). Apply Apple's rules:
- Tabs represent MAIN DESTINATIONS only — places people visit most
- Max 5 tabs on iPhone
- On iPad, consider sidebar alternative
- NEVER use tabs for actions

Present tab recommendations with justification from the doc. Ask the user to confirm.

### 3c: Define app-wide state patterns

Before sketching screens, define the patterns that repeat across every screen. Save these to `design/states.md`:

```markdown
# App-Wide State Patterns

These patterns apply to every screen unless a screen's spec notes a deviation.

## Loading
**Default indicator**: [Skeleton / Spinner / etc.]
**Behavior**: [e.g., "Skeleton rows matching content layout. Stale-while-revalidate shows cached data immediately. No full-screen spinners."]
**Sub-300ms operations**: [e.g., "No indicator shown."]
**Apple guidance**: "[Quote from design-loading.md]"

## Error
**Default treatment**: [e.g., "Inline banner with retry action. No alerts for recoverable errors."]
**Copy style**: [e.g., "Calm, solution-oriented. Never system jargon."]
**Recovery**: [e.g., "Pull-to-refresh or 'Try Again' button retries the fetch."]
**Apple guidance**: "[Quote from design-feedback.md]"

## Empty
**Default treatment**: [e.