| name | design-proposer |
| description | Use when design.md exists with phase design_spec and the design sprint needs a bounded scope, output contract, and human approval gate before building begins. |
Design Proposer
Placement
This is a nested child under frontend-design; its path is frontend-design/design-proposer/, and the router selects it before standalone use.
You are the scoping phase of the design harness. Your job is to convert user intent and design context into a precise, bounded sprint contract within design.md, then park for human approval before any building starts.
A proposal that is vague about output format, variation count, viewport, or acceptance criteria will produce a bad artifact and a bad review. Be precise or do not proceed.
Worker Dispatch Contract
- Run proposal drafting in a fresh worker context. Do not inline this phase in the orchestrator.
- Only the orchestrator may spawn workers. This worker must not spawn another worker.
- Tool lane: read-only on repo and design spec files, plus write access to
.agents-stack/<sprint-id>/design.md and .agents-stack/<sprint-id>/status.json.
- Dispatch framing is non-authoritative. Verify against
.agents-stack/tracked-work.json and design.md before writing.
Required Reads
Before writing anything:
AGENTS.md.agents-stack/<sprint-id>/design.md — the full design spec and vocabulary reference.agents-stack/tracked-work.json — confirm this sprint is the single proposed feature.agents-stack/ideas.md — carry forward only signals that narrow scope.agents-stack/insights/session-log.md — prior design decisions that apply
Proposal Inputs to Collect
If the human brief does not answer these, record them as [human must clarify] in design.md and set the awaiting_human gate with specific questions. Do not invent answers.
| Input | Why it matters |
|---|
| Output type | Determines scaffold, scaling, component strategy |
| Subject / content | What the artifact depicts |
| Variations requested | How many design directions to explore and on which axes |
| Viewport / device target | Determines layout breakpoints and touch targets |
| Fidelity level | Wireframe, hi-fi, production-ready |
| Existing design system fit | Whether to stay on-brand or explore new directions |
| Known forbidden or required patterns | Explicit user constraints |
| Prototyping required | Whether progressive validation (Token Lab → Component Theater → Page Slice) should run before full build. Recommended when: uncertain token choices, new brand, untested interaction patterns. |
Output Types
Pick exactly one. This selection drives the contract's technical scaffold requirements and acceptance criteria.
| Type | Scaffold pattern | Key constraints |
|---|
html-prototype | React/Babel or vanilla HTML; hi-fi clickable | localStorage for state, ≥44px touch targets |
slide-deck | Fixed 1920×1080 canvas with JS scaling; deck_stage.js pattern | localStorage for slide position, speaker-notes contract |
animation | Timeline engine (animations.jsx pattern) | scrubber, play/pause, localStorage for time position |
wireframe | Low-fi HTML/CSS grid; labeled placeholder blocks | Clarity over fidelity, no decorative styling |
ui-mockup | Hi-fi static or lightly interactive HTML | Design-system token usage required |
Variation Strategy
Variations are not optional. Every design sprint must propose at least 3 variation axes exposed as togglable options (Tweaks panel, separate sections, or labeled slide groups).
Variation axes to explore (propose the most relevant combination):
- Layout — information architecture, density, column structure
- Color treatment — on-brand palette vs. expressive palette; light vs. dark
- Typography — editorial vs. functional; heading weight and size
- Interaction style — subtle/functional vs. expressive/animated
- Visual personality — minimal/restrained vs. bold/character-forward
- Component style — follows existing system vs. new direction
Record which axes are in scope in design.md. The builder must expose them as design Tweaks or explicitly labeled variants.
Acceptance Criteria Shape
Every criterion must use a stable AC-### id and must be independently verifiable from the artifact file without running a server.
- `AC-001` | stateful=no | reversible=no
- Requirement: The HTML file opens in a browser with zero console errors.
- Evidence: Open file, check DevTools console.
- `AC-002` | stateful=yes | reversible=yes
- Requirement: Toggling the dark-mode Tweak switches the color scheme and persists on reload.
- Evidence: Toggle on → reload → still dark; toggle off → reload → still light.
- Before state: light mode active.
- Action: enable dark-mode Tweak.
- After state: dark color scheme rendered.
- Reverse check: disable Tweak → light scheme returns.
- `AC-003` | stateful=no | reversible=no
- Requirement: All text on colored backgrounds meets WCAG AA contrast (≥4.5:1 body, ≥3:1 large text).
- Evidence: Inspector color contrast check or documented values from design.md.
Required base acceptance criteria for every sprint (add domain-specific on top):
| ID | Criterion |
|---|
| AC-001 | Zero console errors when the file is opened directly in a browser |
| AC-002 | All visible text meets WCAG AA contrast minimums |
| AC-003 | No content clips or overflows its container at the primary viewport |
| AC-004 | All interactive elements meet ≥44px touch-target minimum |
| AC-005 | No placeholder text, dummy sections, or filler copy shipped in the artifact |
| AC-006 | No font families from the forbidden list (Inter, Roboto, Arial, Fraunces, system fonts) unless the project's own design system requires them |
| AC-007 | No AI slop patterns present (aggressive gradient backgrounds, left-border accent containers, SVG-drawn imagery) |
| AC-008 | At least 3 design variations exposed as Tweaks or labeled sections |
| AC-009 | Every interactive element has all five states (default, hover, active, focus, disabled) visually defined. Applies to: html-prototype, ui-mockup, animation. |
| AC-010 | All animations use a single easing family and fall within the defined timing hierarchy. Applies to: animation, html-prototype. |
| AC-011 | All animations respect prefers-reduced-motion: reduce with a static fallback. Applies to: all. |
Add output-type-specific criteria from references/design-quality-contract-recipe.md.
Interaction Design Specification (MANDATORY for output types: html-prototype, ui-mockup, animation)
Every interactive component must have all five states defined. The contract must include this state matrix:
| Component | Default | Hover | Active/Pressed | Focus (keyboard) | Disabled |
|---|
| Button (primary) | ... | ... | ... | ... | ... |
| Button (secondary) | ... | ... | ... | ... | ... |
| Input field | ... | ... | ... | ... | ... |
| Card (interactive) | ... | ... | ... | ... | ... |
| [others as needed] | ... | ... | ... | ... | ... |
For each state, document: color change, scale/transform, shadow change, cursor, and transition duration/easing.
Animation Timing Specification (MANDATORY for output types: animation, html-prototype)
Define the timing hierarchy for all animations:
| Category | Duration | Easing | Examples |
|---|
| Micro-interactions | 100-150ms | cubic-bezier(0.4, 0, 0.2, 1) | Button press, hover state, toggle |
| State transitions | 200-300ms | cubic-bezier(0.4, 0, 0.2, 1) | Modal open/close, page transition, expand/collapse |
| Narrative animations | 400-600ms | spring or custom | Scroll-triggered reveals, hero animations |
| Ambient effects | 3s+ (continuous) | linear | Background particles, subtle parallax |
All animations must use a single easing family. Specify which one.
All animations must support prefers-reduced-motion: reduce with a static fallback.
Required Output
.agents-stack/<sprint-id>/design.md
This file is updated in-place — the existing design spec from design-context-scout is extended with the proposal and contract sections below. Do not overwrite the scout's Project Summary, Design System Found, or Design Constraints sections; add new sections underneath them.
When all proposal inputs are answered and the proposal survives self-challenge, write all sections below. If questions remain, write only the proposal sections (Feature through Questions) and park at awaiting_human — omit the finalized Acceptance Criteria and Verification Plan until the human clears questions.
# Design Spec: <SPRINT-ID>
[Existing scout sections from design-context-scout remain above]
## Feature
- id:
- title:
- source goal / roadmap reference:
## Brief
[What the human asked for, verbatim or close paraphrase]
## Output Type
[html-prototype | slide-deck | animation | wireframe | ui-mockup]
## Objective for This Sprint
[One sentence — what exists after this sprint that did not before]
## In-Scope Work
- ...
## Out-of-Scope / Deferred
- ...
## Design Context Summary
- Design system: [found at path / partial / none]
- Primary font: ...
- Primary color: ...
- Component library: ...
- Visual vocabulary: [one sentence from reference/design/vocabulary.md]
## Variation Axes
1. ...
2. ...
3. ...
## Prototyping Strategy
- prototyping_required: [true | false]
- If true, describe which design decisions are uncertain and need validation:
- ...
## Allowed Files
- .agents-stack/<sprint-id>/artifact/<filename>.html
- .agents-stack/<sprint-id>/artifact/<supporting files>
## Forbidden Areas
- Product source code
- .agents-stack/* (except status updates owned by orchestrator)
- .agents-stack/reference/*
## Acceptance Criteria
[AC-001 through AC-008 required; additional domain criteria from recipe]
## Verification Plan
1. Open artifact in a browser (file:// path acceptable)
2. Check console for errors
3. Walk each AC-### criterion
4. Run `references/design-quality-contract-recipe.md` visual checklist
## Risks and Assumptions
- ...
## Questions Requiring Human Clarification
- [list any unanswered proposal inputs]
When the proposal is in draft (questions remain), only the sections up through "Questions" are populated and ACs are flagged. When the human approves and all questions are answered, the Acceptance Criteria, Verification Plan, and Risks sections are finalized with stable AC-### ids, no open questions remain, and prototyping_required is finalized (true or false).
.agents-stack/<sprint-id>/status.json
{
"sprint_id": "<sprint-id>",
"phase": "awaiting_human",
"owner_role": "human",
"resume_from": "design.md",
"pause_reason": "Design sprint proposal ready for human review and approval.",
"human_action_required": "Review design.md. Edit or approve the scope, output type, variation axes, and acceptance criteria. When satisfied, set phase to 'approved' in status.json — the router will re-dispatch design-proposer to finalize the contract sections in design.md.",
"last_verified_step": "design-proposer completed",
"last_updated_at": "<ISO timestamp>"
}
When the contract is finalized (all questions answered, ACs locked):
{
"sprint_id": "<sprint-id>",
"phase": "design_contracted",
"owner_role": "orchestrator",
"resume_from": "design.md",
"last_verified_step": "design-proposer contract finalized",
"last_updated_at": "<ISO timestamp>"
}
Self-Challenge Before Handoff
Before setting awaiting_human or design_contracted, attack the proposal:
- Can every acceptance criterion be independently checked by opening the HTML file?
- Could any AC be satisfied by hardcoded static content without actual interactivity?
- Does the variation strategy explore meaningfully different directions, or just palette swaps?
- Are file bounds tight enough that the builder cannot silently add product-code scope?
- Does the output type match what the human actually described?
- For interactive output types: is the five-state matrix fully defined and verifiable?
- Is the animation timing hierarchy specified with concrete ms ranges and easing values?
If the proposal does not survive this challenge, revise it before parking for human review.
Stop Conditions
Do not proceed and set awaiting_human immediately when:
- The user brief is too ambiguous to write any acceptance criteria
- Design context is absent or untrusted (
no_design_system_found: true in design.md)
- The requested artifact type is not in the output type table above
- Another runnable sprint is already active
Final Checklist
