# Design Agent Architecture Specification v2 ## Overview A multi-stage AI design partner that takes a product idea from concept through shipped React UI. The system operates as a persistent project that accumulates design assets over time, with human checkpoints at every stage where taste decisions outweigh constraint satisfaction. The core architectural principle: **each stage narrows the design space**, so that by the time the AI is generating pixels, the number of valid options is small enough for constraint-based generation to reliably produce good output. ### Foundational Decisions - **Output format:** React components with Tailwind CSS. Easily replaceable with another framework by a downstream tool. - **Responsive from day one:** Mobile and desktop are treated as paired designs from Stage 2 onward. They share constraints but are not forced into identical structures. - **Components promote, not abstract.** Components start as page-specific implementations. They're promoted to shared only when a second page needs them. This defers generalization until evidence demands it. - **Nothing is deleted.** All intermediate artifacts — blocked views, rejected variants, superseded IA options — are preserved for traceability, debugging, and team onboarding. Rejected work moves to `_rejected/` folders, not the trash. - **The agent has opinions.** At every interactive stage, the agent provides expert guidance and pushes back on decisions it believes will harm the product. It commits when the user insists, but it advocates first. --- ## Project Schema ``` project/ ├── brief/ │ ├── brief.json # Personas, constraints, priorities │ ├── features.json # Prioritized feature list with MoSCoW │ ├── flows/ # Critical user flows │ │ ├── onboarding.json # Screen sequence + transitions │ │ ├── core_task.json │ │ └── settings.json │ └── _rejected/ # Discarded flow variants │ ├── architecture/ │ ├── sitemap.json # Screen inventory + navigation graph │ ├── responsive_strategy.json # Breakpoints, adaptation rules, shared vs divergent screens │ ├── screens/ │ │ ├── home/ │ │ │ ├── home_desktop.json # Element map — desktop IA │ │ │ ├── home_mobile.json # Element map — mobile IA │ │ │ ├── home_desktop_blocked.png │ │ │ ├── home_mobile_blocked.png │ │ │ └── _rejected/ │ │ │ ├── home_variant_b.json │ │ │ └── home_variant_c.json │ │ ├── detail/ │ │ └── ... │ └── _rejected/ │ ├── tokens/ │ ├── selected.json # Approved token set │ ├── tailwind.config.js # Generated from tokens │ ├── responsive_overrides.json # Mobile-specific token adjustments │ ├── _rejected/ │ │ ├── candidate_a.json │ │ ├── candidate_b.json │ │ └── candidate_c.json │ └── previews/ # Rendered style direction previews │ ├── direction_a_home.png │ ├── direction_b_home.png │ └── direction_c_home.png │ ├── components/ │ ├── registry.json # Index of all components + metadata │ ├── shared/ # Promoted components (used by 2+ pages) │ │ ├── ProductCard/ │ │ │ ├── ProductCard.jsx │ │ │ ├── ProductCard.eval.json │ │ │ └── _rejected/ │ │ │ └── ProductCard_media_variant.jsx │ │ ├── NavBar/ │ │ └── ... │ └── _rejected/ │ ├── pages/ │ ├── home/ │ │ ├── Home.jsx # Page component (desktop) │ │ ├── Home.mobile.jsx # Mobile variant (if IA diverges) │ │ ├── Home.eval.json # Evaluation report │ │ ├── components/ # Page-specific components (not yet promoted) │ │ │ └── HeroBanner/ │ │ │ └── HeroBanner.jsx │ │ └── screenshots/ │ │ ├── desktop_raw.png │ │ ├── desktop_blocked.png │ │ ├── mobile_raw.png │ │ └── mobile_blocked.png │ ├── detail/ │ └── ... │ └── changelog/ # Decision log for traceability ├── 001_brief_approved.md ├── 002_ia_home_selected_variant_a.md ├── 003_style_direction_selected_bold.md └── ... ``` ### Component Lifecycle Components follow a promotion path that defers generalization until it's earned: **1. Page-specific.** Created inside `pages/{page}/components/`. Accepts props for content but is not abstracted for reuse. Named specifically: `HeroBanner`, not `GenericBanner`. **2. Promotion trigger.** A second page needs the same component pattern. The agent identifies the overlap and proposes a refactor. **3. Shared component.** Moved to `components/shared/`. The refactor may: - Create a more flexible base component with additional props - Leave the original page-specific version as a thin wrapper if it adds meaningful defaults - Replace the original entirely if the shared version covers all cases **4. Design system extraction (user-triggered).** When the user requests it, the accumulated shared components, tokens, and patterns are extracted into a standalone design system package. The project schema is already organized to make this extraction mechanical. --- ## Stage Definitions ### Stage 1: Discovery **Mode:** Interactive conversation **Agent role:** Design strategist with opinions **Output:** `brief/` directory **Approval:** User confirms the structured brief before proceeding The agent extracts structured requirements from an unstructured product idea by acting as an experienced product designer. **Conversation structure:** 1. **Problem framing** — "Who has this problem? When do they encounter it? How do they solve it today?" 2. **Feature extraction** — List every feature, then force-rank using MoSCoW. The agent challenges "Must" items: "If we shipped without X, would anyone use it?" 3. **Flow mapping** — For each Must feature, define the screen-by-screen user sequence. These flows become the acceptance criteria for the final design. 4. **Constraint capture** — Target devices and breakpoints, accessibility requirements, brand guidelines, technical constraints. 5. **Brief synthesis** — Structured brief for user confirmation. **Agent opinion examples:** - "You listed 8 Must-have features. That's a lot for an MVP — can we move notifications and settings to Should?" - "The flow you described has 7 steps to complete a purchase. Industry benchmark is 3-4. Can we collapse the address and payment steps?" - "You mentioned both iOS and Android. Are we designing mobile-web or native? That changes the navigation pattern significantly." **Outputs:** - `brief.json`: Product name, description, personas (with goals, pain points, context), success metrics, non-goals - `features.json`: Each feature with MoSCoW priority, complexity estimate, which persona it serves - `flows/*.json`: Ordered step sequences — screen name, user action, system response, next screen --- ### Stage 2: Information Architecture **Mode:** Interactive with mandatory approval — potentially highly collaborative **Agent role:** UX architect with opinions **Output:** `architecture/` directory **Approval:** User approves each screen's IA (desktop + mobile) before proceeding The agent proposes how information is structured across screens. This stage requires user approval because IA decisions are product decisions — what the user sees first, what's behind a tap, what's the primary action. **Responsive treatment starts here.** For each screen, the agent produces paired IA variants for desktop and mobile. Some screens may share identical structure across breakpoints. Others may diverge significantly: | Desktop pattern | Mobile adaptation | |---|---| | Multi-column grid | Single column stack or horizontal scroll | | Sidebar navigation | Bottom tab bar + hamburger drawer | | Data table | Stacked cards or accordion | | Comparison layout | Tabbed single-item view with swipe | | Persistent filters panel | Bottom sheet or modal filters | **Process per screen:** 1. Agent generates 2-3 IA variants as element maps (desktop + mobile pair per variant) 2. Each variant is rendered as a blocked view 3. Agent presents variants with its recommendation and reasoning: "Variant A uses progressive disclosure which keeps the initial view clean, but Variant B shows all options upfront which reduces taps for power users. Given your persona is primarily mobile commuters who want speed, I recommend B." 4. User selects, mixes, or requests changes 5. If the user requests something the agent disagrees with: the agent explains its concern ("A carousel here means 60% of products won't be seen — the average user swipes through 2.3 items. An alternative would be..."). If the user insists, the agent commits and documents the decision in the changelog. 6. Agent checks approved IA against brief flows: "Can the user complete the core task within the approved structure?" **Responsive strategy document:** ```json { "breakpoints": { "mobile": { "max": 767, "columns": 4, "gutter": 16, "margin": 16 }, "tablet": { "min": 768, "max": 1023, "columns": 8, "gutter": 24, "margin": 24 }, "desktop": { "min": 1024, "columns": 12, "gutter": 24, "margin": 32 } }, "screen_adaptations": { "home": { "strategy": "reflow", "notes": "Same IA, 2-col grid → single column" }, "dashboard": { "strategy": "divergent", "notes": "Desktop shows full table + chart side-by-side. Mobile shows summary cards with drill-down to table." }, "checkout": { "strategy": "split", "notes": "Desktop is single page with sections. Mobile splits into 3 steps with progress indicator." } } } ``` **Outputs:** - `sitemap.json`: Screen graph with navigation edges per breakpoint - `responsive_strategy.json`: Per-screen adaptation strategy - `screens/{name}/{name}_desktop.json` and `{name}_mobile.json`: Approved element maps - `_rejected/` variants preserved for reference - Changelog entry documenting the decision and reasoning --- ### Stage 3: Style Direction **Mode:** Highly interactive — biggest taste decision **Agent role:** Visual designer presenting options **Output:** `tokens/` directory **Approval:** User selects a direction (may mix and match) The agent generates 3-4 complete token sets and applies each to representative screens. **Token set structure:** ```json { "meta": { "name": "Bold & Expressive", "description": "Saturated primary color, generous spacing, rounded shapes, strong shadows" }, "color": { "primitive": { "blue-600": "#2563eb", "...": "..." }, "semantic": { "primary": "{blue-600}", "background": "{white}", "surface": "{gray-50}", "text-primary": "{gray-900}", "..." }, "component": { "button-primary-bg": "{primary}", "card-bg": "{surface}", "..." } }, "typography": { "scale_ratio": 1.25, "base_size": 16, "font_family": { "heading": "Inter", "body": "Inter", "mono": "JetBrains Mono" }, "sizes": { "xs": 12, "sm": 14, "base": 16, "lg": 20, "xl": 25, "2xl": 31, "3xl": 39 }, "line_heights": { "tight": 1.25, "normal": 1.5, "relaxed": 1.75 }, "weights": { "normal": 400, "medium": 500, "semibold": 600, "bold": 700 } }, "spacing": { "base_unit": 8, "scale": [0, 4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96] }, "responsive_overrides": { "mobile": { "typography": { "base_size": 15, "scale_ratio": 1.2 }, "spacing": { "scale": [0, 4, 8, 12, 16, 20, 24, 32, 40, 48] } } }, "borders": { "radius": { "none": 0, "sm": 4, "md": 8, "lg": 12, "xl": 16, "full": 9999 }, "width": { "default": 1, "thick": 2 } }, "shadows": { "sm": "0 1px 2px rgba(0,0,0,0.05)", "md": "0 4px 6px rgba(0,0,0,0.07)", "lg": "0 10px 15px rgba(0,0,0,0.1)" } } ``` Note `responsive_overrides` — the mobile token adjustments are part of the token set, not a separate concern. Tighter type scale on mobile, compressed spacing scale, potentially different radius defaults. **The agent generates a `tailwind.config.js` from the approved token set.** This is the bridge between design decisions and code generation. Every subsequent component is constrained to classes that resolve to approved values. --- ### Stage 4: Component Generation **Mode:** Medium interactivity — review and select **Agent role:** UI designer working within approved constraints **Output:** `components/` directory (page-specific initially) **Approval:** User approves component variants; all approved variants enter the library For each component type needed, the agent generates 2-3 React + Tailwind variants within the approved token set. **All variants use the same tokens.** They differ in layout approach, information density, and interaction pattern — not in colors, fonts, or spacing values. This is what makes the variant selection a structural decision rather than a taste decision. **Evaluation runs automatically before presentation.** Each variant is: 1. Rendered to screenshot at both mobile and desktop breakpoints 2. Element-mapped via Pass 1 extraction 3. Evaluated against the 8 defect categories (alignment, spacing, hierarchy, orphan, grouping, consistency, touch targets, balance) 4. Checked for WCAG AA contrast compliance 5. Checked for token compliance (no hardcoded values that bypass the token set) Variants that fail hard constraints are either auto-fixed or withheld. The user only sees variants that pass evaluation. **Component registry tracks everything:** ```json { "id": "card_standard", "type": "card", "path": "pages/home/components/ProductCard/ProductCard.jsx", "location": "page_specific", "status": "approved", "used_in": ["home"], "tokens_version": "selected_v1", "eval_scores": { "desktop": { "spacing": 1.0, "alignment": 1.0, "contrast": 1.0 }, "mobile": { "spacing": 1.0, "alignment": 0.95, "contrast": 1.0 } }, "tags": ["product", "vertical", "with-cta"], "created": "2025-03-08", "promoted_to_shared": null } ``` --- ### Stage 5: Page Assembly & Refinement **Mode:** Mostly autonomous with final review **Agent role:** Production designer assembling approved parts **Output:** `pages/` directory **Approval:** User reviews assembled pages, requests adjustments The agent composes approved components into full pages following the approved IA, rendering at both breakpoints. **Assembly process:** 1. Select components from registry matching each IA element type 2. Generate page-level React component with layout (CSS Grid/Flexbox) 3. Render at all breakpoints, run full evaluation 4. Present pages with evaluation report and screenshots **Page-level evaluation (beyond component checks):** - Flow completion — can the user complete the critical path? - Hierarchy validation — is the most important element the most prominent? - Scroll budget — how much content is above/below the fold? - Cross-breakpoint consistency — do mobile and desktop feel like the same product? - Navigation consistency — same patterns across all screens --- ## Handling Change When the product evolves after initial delivery, the scope of change determines the re-entry point: | Change scope | Re-entry stage | Example | |---|---|---| | Content swap | Stage 5 only | "Change the hero copy" | | New component variant | Stage 4 | "We need a compact card for search results" | | New screen, existing patterns | Stage 2 + 4 + 5 | "Add a user profile screen" | | New feature, new flows | Stage 1 + 2 + 4 + 5 | "Add a messaging feature" | | Visual rebrand | Stage 3 + 4 + 5 | "New color palette and typography" | | Major pivot | Stage 1 (full restart) | "We're targeting a different market" | **Impact assessment process:** 1. Agent evaluates the change request against the existing brief, IA, and component library 2. Agent identifies which artifacts are affected and at which stages 3. Agent proposes a plan: "This requires new IA for 2 screens, 1 new component type, and reassembly of 3 pages. The token set and existing components are unaffected." 4. User approves the plan, and the agent re-enters the pipeline at the appropriate stage **All superseded artifacts move to `_rejected/`, never deleted.** The changelog records what changed, why, and what was replaced. This creates a complete design history that serves traceability, debugging, and onboarding. --- ## Self-Critique Loop (SCGG Pattern) Every generation step (Stages 4-5) uses an automated critique loop: ``` Generate React/Tailwind → Render via Playwright → Screenshot at each breakpoint → Pass 1 element extraction → Blocked view rendering → Evaluation pipeline → Critique (identify issues) → Regenerate with fixes ``` The loop runs a maximum of 3 iterations. Artifacts that still fail after 3 passes are flagged for human review. **Evaluation checks per iteration:** - Token compliance: no hardcoded colors, spacing, or font sizes outside the token set - Spacing consistency: all gaps match the spacing scale - Alignment: elements that should share edges do so within 2px - WCAG AA contrast: all text meets 4.5:1, all interactive elements meet 3:1 - Touch targets: all interactive elements ≥44px on mobile - Hierarchy: heading elements are visually larger than body text - Grouping: related elements (same parent in IA) are closer together than unrelated elements --- ## Agent Personality: Designer with Opinions The agent is not a "yes-man." It behaves as a senior designer who: **Advocates with reasoning.** "I'd recommend against an auto-playing carousel here. Eye-tracking studies show users engage with 2.3 items on average, meaning 60% of your content won't be seen. A static grid with a 'see more' tap would give every item equal visibility." **Acknowledges tradeoffs.** "The hamburger nav saves screen space, which matters for your content-heavy layout. But it hides navigation, which increases the learning curve for new users. Given your persona is first-time visitors, a visible bottom tab bar with 4-5 items might be worth the space cost." **Commits when overruled.** "Understood — we'll go with the carousel. I'll make sure the first item is the highest-priority content and add a pagination indicator so users know there's more to swipe through." **Documents disagreements.** Every case where the agent advocated against the user's final decision is recorded in the changelog with the agent's reasoning and the user's rationale. This creates a decision audit trail. This behavior is implemented through the system prompt, not through tooling. The agent's role description at each stage explicitly includes the mandate to advocate.