# App Design Architect

> Design screens and navigation using Apple HIG patterns and components

- Skill: `pproenca/app-design-architect` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add pproenca/app-design-architect`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pproenca/app-design-architect/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: pproenca (https://skillmd.com/u/pproenca)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/pproenca/app-design-architect

---


# 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.g., "Centered message + optional CTA. Confident tone, not apologetic."]
**Copy style**: [e.g., "'No upcoming sessions.' not 'You don't have any sessions yet!'"]
**Apple guidance**: "[Quote from relevant HIG reference]"

## Success / Feedback
**Haptic grammar**:
| Haptic | When |
|--------|------|
| [type] | [trigger] |
**Visual confirmation**: [e.g., "Inline checkmark or brief highlight animation. Full success screens only for significant completions."]
```

### 3d: Define shared visual vocabulary

If the app has reusable card types or component compositions that appear across multiple screens, define them in `design/vocabulary.md`:

```markdown
# Design Vocabulary

## Card Types

### [Card Type Name]

[ASCII wireframe of the card]

- **Leading**: [element]
- **Content**: [element]
- **Trailing**: [element]
- **Identity signal**: [what makes it recognizable at a glance]
- **Used in**: [which screens]

### [Next Card Type]
...

## Usage Matrix

| Surface | [Card A] | [Card B] | [Card C] |
|---------|----------|----------|----------|
| [Screen] | [usage or —] | ... | ... |

## Presentation Rules

| Presentation | When | Examples |
|---|---|---|
| Push | [rule] | [examples] |
| Sheet | [rule] | [examples] |
| Full-screen cover | [rule] | [examples] |
| Action sheet | [rule] | [examples] |
| Alert | [rule] | [examples] |
```

### 3e: Sketch every screen

Create `design/screens/` directory. For EVERY screen, create a separate file `design/screens/<screen-name>.md`.

Each screen file is self-contained — everything needed to implement that screen is in this one file.

```markdown
# [Screen Name]

**Tab**: [which tab, or "None — reached via [path]"]
**Intention**: [One sentence starting with a verb]
**Density**: [Very low / Low / Medium / High] — [why, referencing design character]
**Anchor**: [The single visual element the eye goes to first]
**Hierarchy**:
- **Primary**: [main content element]
- **Secondary**: [supporting context]
- **Tertiary**: [metadata, navigation, actions]
**Components**: [every HIG component used on this screen]

## Wireframe

┌─────────────────────────────┐
│ ◀ Back    Screen Title   ⊕  │
├─────────────────────────────┤
│                             │
│  ┌───────────────────────┐  │
│  │ [Content with          │  │  ← [Component]: [purpose]
│  │  components labeled]   │  │
│  └───────────────────────┘  │
│                             │
├─────────────────────────────┤
│  Tab1   Tab2   Tab3   Tab4  │
└─────────────────────────────┘

## States

**Empty**: When: [specific trigger]. [Follows app pattern. Copy: "[exact message]" + "[CTA text]" → [action]]
**Loading**: When: [specific trigger]. [Follows app pattern — OR — deviation: "[describe what's different and why]"]
**Error**: When: [what can go wrong on THIS screen]. [Follows app pattern — OR — deviation: "[describe]"]
**Success**: When: [trigger — OR — "N/A"]. [Description of feedback]

## Navigation

- **From**: [Screen + action — e.g., "Schedule (tap session card)"]
- **To**: [Screen + action — e.g., "Form Detail (tap form row)"]
- **Back**: [behavior — e.g., "Pop, scroll position preserved"]
- **Modals**: [sheets/alerts launched, or "None"]
```

**Guidelines for screen files:**
- If a screen has multiple distinct variants (e.g., editable vs read-only, two tier views), add a `## Variants` section with a wireframe and description for each variant.
- If a screen has notable animation choreography, add a `## Animation` section.
- If a screen has a typography map (complex screens with many text styles), add a `## Typography` section.
- Keep screen files focused. If a design decision applies to multiple screens, it belongs in `vocabulary.md` or `foundations.md`, not duplicated in each screen file.

You MUST produce a separate file for EVERY screen. No shortcuts. No "same as [Screen X]."

### 3f: Navigation graph

Save to `design/navigation.md`:

```markdown
# Navigation

## Tab Bar

[Tab structure diagram]

- **[Tab 1]** — [purpose]
- **[Tab 2]** — [purpose]
...

HIG compliance:
- [Key rules applied]

## Navigation Map

[Tree diagram showing all screens and how they connect]

## Navigation Graph

### Tab: [Tab 1 Name]
[Screen A] --tap [element]--> [Screen B]
[Screen B] --back--> [Screen A] (state: scroll preserved)
[Screen B] --tap [element]--> [Sheet C] (modal)
...

### Tab: [Tab 2 Name]
...

### Cross-tab Flows
[Deep links, tab switches]

### Modal Flows
[Sheets, alerts, action sheets]

## Consistency Check

Verify all of the following. List each with pass/fail:

- **Data display**: Same data type displayed the same way everywhere
- **Navigation**: Tab bar, back buttons, toolbars follow the same pattern
- **Density**: Matches design character — no screen wildly deviates
- **Components**: Same component for same purpose everywhere
- **States**: Loading and error use the same approach (per `states.md`)
- **Copy**: Tone of voice consistent across all labels and messages
```

Walk through the graph and verify: every screen is reachable, every screen has a way back, no dead ends, modal dismissal is always clear, tab switches preserve state.

## Step 4: Apply Foundations

Read `skills/apple-hig/indexes/foundations-checklist.md`.

For EACH foundation, read its full reference from `skills/apple-hig/references/foundations/` BEFORE making recommendations.

Work through all 7 in order. For each, use this format:

```markdown
## [Foundation Name]

**Source**: `design-[foundation].md`
**Apple says**: "[Direct quote — the most important guidance]"
**Applied to [App Name]**:
- [Specific recommendation 1 — name exact styles, colors, values]
- [Specific recommendation 2]
- [Specific recommendation 3]
**Connects to screens**: [Which screens this most affects]
```

The 7 foundations, in order:

1. **Typography** — Read `design-typography.md`. Name SPECIFIC text styles: "Title 2 for section headers, Body for list content, Caption 1 for metadata, Footnote for timestamps." Do NOT say "use appropriate typography."
2. **Writing** — Read `design-writing.md`. Define voice, tone, label style, button language, error message style for THIS app. Give examples of actual copy: button labels, error messages, empty state text.
3. **Branding** — Read `design-branding.md`. Where the brand shows (icon, accent color, launch screen) and where it stays quiet.
4. **Color** — Read `design-color.md` + `design-dark-mode.md`. Name accent color and its role. Name semantic colors for success/warning/error with hex values. Describe the dark mode approach. Include contrast scorecard.
5. **Materials** — Read `design-materials.md`. Where translucency, vibrancy, and background materials are used — reference specific screens and components.
6. **Layout** — Read `design-layout.md`. Spacing system, corner radius scale, touch targets, density spectrum. How screens adapt across iPhone SE → iPhone 16 Pro Max → iPad.
7. **Motion** — Read `design-motion.md`. Motion grammar (what each animation communicates), haptic grammar, choreography rules. Name transitions between specific screens. Reference the loading and error states from `states.md`.

Save to `design/foundations.md`.

Update `.codex/app-design.codex/app-design.local.md` to set `current_phase: "complete"`.

## Completion

Present a summary:

> "Design complete for [App Name]. Here's what we defined:"

- **Patterns**: [count] HIG patterns applied
- **Components**: [count] selected, [count] excluded
- **Screens**: [count] screens in `design/screens/`, each self-contained
- **Navigation**: [describe tab structure and key flows]
- **Foundations**: All 7 defined with specific values

Files created:
- `design/patterns.md` — Pattern mapping (lean reference)
- `design/navigation.md` — Tab structure, nav graph, presentation rules
- `design/vocabulary.md` — Shared card types and visual patterns
- `design/states.md` — App-wide loading, error, empty, success patterns
- `design/foundations.md` — Typography, color, layout, motion with specific values
- `design/screens/*.md` — One file per screen with wireframe and spec