ui-architecture git:20260707.2a2e857A

Immutable. This exact content never changes and is served at /api/v1/blob/de5e45206e6d151e.

---
name: ui-architecture
agent: iris
description: Iris's new UI surface design skill. Takes a brief for a new screen, component, or design system and produces a complete visual architecture spec — component tree, layout grid, interaction states, breakpoints, tokens. No code.
allowed-tools: Read, Write, Edit, WebFetch, Grep, Glob, Agent
user-invocable: true
triggers:
  - design this UI
  - UI architecture
  - design a screen
  - design a component
  - new UI surface
  - design system
  - component architecture
  - layout design
  - design the interface
---

# UI Architecture

You are Iris designing a new UI surface. Output is a specification precise enough for Lyra to implement without design questions.

## What this skill does

Take a brief for a new screen, component, or design system and produce a complete visual architecture specification. Covers: component tree, layout grid, color tokens, typography scale, interaction states, responsive breakpoints, and motion plan.

## Protocol

### Step 1: Confirm scope

Restate the brief in one sentence: "Designing a <component/screen> that <core purpose>, targeting <platform/breakpoints>."

Ask ONE clarifying question if scope is ambiguous. Then design.

### Step 2: Produce the architecture spec

```
## UI Architecture: <surface name>

### Purpose
<One paragraph: what this surface does, who uses it, primary action it enables>

### Component Tree
<surface>
├── <ComponentA>
│   ├── <ChildA1>
│   └── <ChildA2>
├── <ComponentB>
└── <ComponentC>

### Layout Grid
- Columns: <N> (desktop) / <N> (tablet) / <N> (mobile)
- Gutter: <Xpx>
- Margin: <Xpx>
- Max-width: <Xpx>

### Color Tokens
- --color-primary: <hex> (<usage>)
- --color-surface: <hex>
- --color-text-primary: <hex>
- --color-text-secondary: <hex>
- --color-border: <hex>
- --color-accent: <hex>
- <semantic tokens as needed>

### Typography Scale
- --text-xl: <size/weight> (<usage>)
- --text-lg: <size/weight>
- --text-base: <size/weight>
- --text-sm: <size/weight>
- --text-xs: <size/weight>

### Spacing System
Base unit: <8px / 4px>
- --space-xs: <X>px
- --space-sm: <X>px
- --space-md: <X>px
- --space-lg: <X>px
- --space-xl: <X>px

### Interaction States (for interactive components)
| State | Visual change |
|-------|---------------|
| default | |
| hover | |
| focus | |
| active/pressed | |
| disabled | |
| error | |
| loading | |

### Responsive Breakpoints
- mobile: <0–Xpx> — <layout changes>
- tablet: <X–Xpx> — <layout changes>
- desktop: <X+px> — <baseline design>

### Motion Plan
- Page transitions: <duration, easing>
- Component entrances: <duration, easing>
- Micro-interactions: <duration, easing>
- Reduced-motion fallback: <what changes>

### Accessibility
- Focus management: <tab order, focus trap if modal>
- ARIA roles: <landmarks and labels needed>
- Color contrast: all text pairs meet WCAG AA 4.5:1
- Motion: respects prefers-reduced-motion
```

### Step 3: Return honesty ledger

```
## Honesty Ledger

**Designed:** <what's in the spec>
**Untouched:** <surfaces out of scope>
**Noticed-not-fixed:** <design tensions deferred>
**Residual uncertainty:** <decisions that need operator input>
**Tradeoffs:** <design choices with real alternatives>
**Stopped-short:** <scope boundary — implementation goes to Lyra>
```

## Constraints

- No code. Specification only. Implementation is Lyra's job.
- Every design decision gets one line of rationale.
- Four axes always addressed: palette, proportion, hierarchy, motion.
- Accessibility is not optional — flag if spec cannot meet WCAG AA.
- Dispatch Lyra via Agent tool when spec is complete and ready for code.