ios-design-router

name	ios-design-router
description	Use as the entry point for iOS UI design work in IBR. Classifies apps into 6 archetypes (Utility, Content, Productivity, Consumer, Editorial, Tool/Pro) and routes to domain references.
version	0.1.0
user-invocable	false

iOS Design Router

Entry point for iOS UI design work in IBR. Classifies app archetype, applies defaults, routes to domain reference files for specific components.

Read this first on every new app or iteration session. Does NOT contain option catalogs — those live in domain reference files.

Principle Hierarchy

When rules conflict:

1. Per-app design-config.md decisions — highest authority
2. Explicit user instructions in current session
3. Archetype defaults from this router
4. Domain file options (prefer "preferred" options when archetype fits)
5. HIG fundamentals (ios-design skill)

---

1. Archetype Classifier

Every iOS app fits one (sometimes two) of six archetypes. Archetype drives ~70% of design choices.

The Six Archetypes

Archetype	Core Purpose	Defining Signal	Examples
Utility	Complete a specific task fast	User comes, does thing, leaves	Calculator, Timer, FloDoro
Content/Feed	Browse information	Scrollable, frequently refreshed content	News, Social, Atomize News
Productivity	Manage work/projects	Persistent user workspace, creation tools	Notion, Linear, Things
Consumer/Habit	Daily engagement loop	Retention-focused, streak/reward mechanics	Duolingo, Headspace
Editorial	Long-form reading/media	Typography-forward, reading experience	Medium, Arc
Tool/Pro	Complex workflows	Power-user controls, deep functionality	Figma, dev tools

Classification Questions

Ask in order. Stop at first strong match.

1. Is the core action completable in <60 seconds per visit?  → UTILITY
2. Is the primary screen a scrollable feed of items the user didn't create?  → CONTENT/FEED
3. Does the user CREATE persistent artifacts (docs, tasks, projects)?  → PRODUCTIVITY
4. Is daily return/retention a core success metric with streaks/rewards?  → CONSUMER/HABIT
5. Is long-form reading or media consumption the primary activity?  → EDITORIAL
6. Does the app target professionals with complex workflows?  → TOOL/PRO

Hybrid Archetypes

Some apps span two archetypes. Identify primary (dominant screen, main value) and secondary (supporting feature). Primary drives defaults; secondary applies to its specific feature area only.

Examples: Atomize News = Content/Feed (primary) + Tool/Pro (secondary). FloDoro = Utility (primary) + Productivity (secondary).

If archetype is unclear after the 6 questions, ask the user.

---

2. Archetype Defaults Table

Starting points before loading domain files. Narrows the option space.

Category	Utility	Content/Feed	Productivity	Consumer/Habit	Editorial	Tool/Pro
Primary action/screen	ONE clear, 1-step	ONE + scroll context	ONE primary + contextual secondary	ONE engagement action	ONE reading/nav action	ONE primary + power menu
Task step budget	1–2 steps	2–3 steps	2–3 steps	1–2 steps	1–2 steps	3–5 steps
Tab bar	Standard iOS or hidden	Floating pill + auto-hide	Standard iOS	Floating pill	Hidden/minimal	Standard iOS
Accent application	CTA-Only	Semantic System	Semantic System	Expressive Spread	CTA-Only	Semantic System
Dark mode base	Layered Near-Black	True Black	Layered Near-Black	True Black or Glass	Layered Near-Black	Layered Near-Black
List pattern	Inset Hairline	Card Per Row	Card Per Row or Grouped	Card Per Row	Full-Width Line	Inset Hairline
Primary button depth	Drop Shadow	Drop Shadow	Drop Shadow	Inner Rim	Flat or Drop Shadow	Flat
Tap feedback	BG Highlight + Opacity	BG Highlight	BG Highlight + Opacity	Ripple on CTAs	Opacity Dim	BG Highlight
Onboarding	Value-First or None	Value-First	Progressive Disclosure	Interactive Tutorial or Quiz	Value-First	Progressive Disclosure
Skeleton loading	Pulse Fade	Shimmer	Pulse Fade	Shimmer	Pulse Fade	Pulse Fade
Empty state	System Icon + Text	System Icon + Text	Text Only	Custom Illustration	Text Only	System Icon + Text
Toast routing	Bottom Pill	Bottom Pill + Top Banner	All three channels	Bottom Pill + Celebration	Bottom Pill	All three channels
Celebration	Checkmark Morph	Score Tick	Checkmark Morph	Full treatment	Minimal	Checkmark Morph
Motion density	Low (2/screen)	Medium (3/screen)	Low (2/screen)	High (4+/screen)	Low (1–2/screen)	Low (2/screen)
Haptic baseline	Key moments	Key moments	Key moments	Key moments + custom	Key moments	Key moments
Profile header	Compact card (if any)	Cover + overlap avatar	Compact card	Cover + overlap avatar	Large centered	Compact card

Reading the table:

• Use defaults when no per-app config exists and no explicit user preference overrides
• "or" between options: either is valid — match to secondary archetype
• "All three channels" / "Full treatment": Consumer/Habit apps earn the maximum option set
• Motion density numbers are a ceiling, not a floor

---

3. Domain Reference Files

When a design task requires detailed options beyond the defaults table, Read the relevant file from ${CLAUDE_PLUGIN_ROOT}/references/ios-design/.

Task Domain	Reference File	When to Load
Tab bars, back nav, transitions, sheets, page hierarchy, search	1_navigation_structure.md	Building navigation or screen structure
Lists, cards, feeds, swipe actions, content resilience, grouping	2_lists_cards_content.md	Building data display or content views
Buttons, tap feedback, haptics, toggles, form fields, placement	3_buttons_touch_interactions.md	Building interactive controls or forms
Accent color, gradients, dark mode, elevation, typography, spacing, icons	4_color_surface_typography.md	Defining visual identity or applying design tokens
Loading states, skeletons, empty states, errors, toasts, celebrations, onboarding, profiles	5_motion_states_identity.md	Adding state handling, animations, or onboarding
Step counting, task flow validation, primary action rules	6_task_economy.md	Designing any multi-step flow or validating task efficiency

---

4. Clarification Protocol

Default behavior: decide using archetype defaults, flag choices in output for review.

When to DECIDE (don't ask)

• Archetype is clear and default obviously fits
• Low-impact choice (skeleton style, toast channel, micro-interaction timing)
• User gave strong directional guidance earlier in the session

Flag the decision in output (see §5).

When to ASK (stop and clarify)

• Archetype is ambiguous or hybrid primary is unclear
• High-impact, disruptive-to-change-later decisions:
  • Tab bar style (affects every screen)
  • Accent application tier (affects entire visual language)
  • Dark mode treatment (affects every surface)
  • Primary navigation pattern
  • Onboarding structure (affects first-run funnel)
• Conflicting signals in the session
• About to ADD an optional element to a screen (Task Economy — see below)

Task Economy: Validate Before Adding

Before adding any of the following, validate with the user:

• A secondary action to a screen that has a clear primary
• A confirmation dialog (unless action is truly destructive)
• A settings toggle for a behavior
• An option that could be inferred from context
• A step to a flow that was previously one screen
• A "Welcome" screen before a feature is usable

Exception — just decide: The addition is required by the task, the user explicitly requested it, or it's a CP-required element (empty state, error handler, accessibility label).

Validation question format:

I'm about to add [element] to [screen].
Without it: [simpler version]
With it: [what it adds]
Cost: +[N] step(s) / +[N] decision(s) for the user
Should I add it?

Task Economy: Step Counting

For any task flow: define the outcome, count theoretical minimum steps, count current design steps, look for cuts if gap is wider than 1–2, report count in output.

When NOT to Ask

• Platform fundamentals (how SwiftUI works, HealthKit patterns)
• HIG principles (not preferences)
• Things already answered in earlier turns
• Minor timing/easing values

---

5. Output Flagging Format

Every design choice made without asking must be surfaced for audit:

## Design Choices Made

**Inferred archetype:** [type]
**Reason:** [one sentence]

**Primary action(s) per screen:**
- [Screen]: [action] — N step(s) to complete

**Step counts for key tasks:**
- [Task]: [N steps] — floor is [theoretical minimum]

**Choices (review before committing):**
- **[Category]:** [option chosen] — [why, one sentence]

**Flagged as tentative:**
- [Choice] — [what to validate]

**Elements NOT added (Task Economy validated):**
- [What was considered] — [why cut]

---

6. Ask-First Trigger List

Always ask on a new app:

1. Archetype (if unclear after classification questions)
2. Brand accent color
3. Tab bar presence and style
4. Dark mode behavior

Ask conditionally: 5. Onboarding flow existence 6. Login/auth pattern 7. Charts usage 8. Custom vs system design approach 9. Target iOS version 10. App-specific voice/tone 11. Any optional UI element addition (Task Economy — applies throughout)

---

Related Skills

• ios-design: HIG fundamentals — navigation rules, color, typography, SF Symbols, haptics, materials. What the platform requires.
• apple-platform: Architecture patterns, SwiftData, concurrency, CI/CD, TestFlight. How to build it.
• This skill (ios-design-router) routes design decisions to the right domain reference and applies archetype defaults.