aditya-ariosity Handoff to Development
Specify intent, behavior, states, constraints, and verification so implementation requires no hidden product decisions or arbitrary pixel matching.
1. Confirm readiness
Collect:
Approved flow and decisions | Platforms, browsers, devices, locales, inputs | Components, tokens, code, versions | Content, data, permissions, latency, APIs | Accessibility target and test environment | Analytics, release, flags, rollout | Open decisions and owners
Label unresolved product, data, security, privacy, or technical decisions. Do not disguise them as visual annotations.
2. Map the critical flow
Write:
Entry -> Preconditions -> User action -> System response -> Branches -> Recovery -> Completion -> Return
Include deep link, refresh, back, cancel, interruption, duplicate submission, expired session, and partial completion where relevant. Define what state is retained.
3. Map design to system
For every visible region identify:
Design object | Code component | Variant | Tokens | Content/data | Event | Owner | Gap
Synthetic example: Address search | AddressAutocomplete | Default | semantic field tokens | Provider results | address_selected | Checkout | Timeout policy open
Use existing component and token names. Avoid raw pixel, color, and typography values when semantic tokens or layout constraints exist. Mark new components and variants explicitly; do not silently create one-off implementations.
4. Specify component behavior
Read references/implementation-contract.md. Define anatomy, hierarchy, variants, states, interactions, semantics, content limits, responsiveness, and events. State intent and invariants before exact dimensions.
Use measurements for fixed or bounded values only. For flexible layouts, specify container, grid, min/max, wrapping, truncation, overflow, intrinsic sizing, aspect ratio, alignment, and priority.
Synthetic contract:
Component: AddressAutocomplete | Intent: accelerate entry without blocking manual input | Trigger: eligible address query | Loading: retain query and announce status | Error: preserve values and expose manual entry | Invariant: selecting a suggestion never submits the form
5. Cover all states
Read references/state-and-responsive-matrix.md. Include default and consequential states across component, page, data, network, permission, and session levels.
Provide realistic fixtures for long labels, empty data, maximum values, errors, translated content, and slow responses. Do not let happy path only designs become an implementation requirement.
6. Specify accessibility
Read references/accessibility-qa-and-acceptance.md. Define:
Control or region | Semantic element | Name, role, state, value | Relationships | Keyboard and focus | Errors and status | Contrast, target, reflow, scaling, motion, touch | Accessible alternative
Reference relevant WCAG 2.2 criteria for requirements, but do not claim conformance from the specification alone.
7. Define telemetry and performance
Only include approved analytics. For each event specify:
Event | Trigger | Properties | Object ID | Success/failure | Privacy note | Owner
Define user-visible performance behavior: immediate acknowledgment, loading strategy, cancellation, optimistic update, timeout, retry, state preservation, and layout stability. Add numeric budgets only when product or engineering owns them.
8. Write acceptance criteria
Use observable Given/When/Then statements or an equally testable format. Cover behavior, data, states, responsiveness, accessibility, instrumentation, and recovery. Avoid matches design, looks correct, or works on mobile as acceptance criteria.
Synthetic example: Given autocomplete is unavailable, when the user enters an address manually and submits, then checkout continues without retrying or enabling the provider.
9. Produce the handoff package
For a complete input-to-output demonstration, read references/worked-example.md. Use it to calibrate behavior-first detail, flexible layout rules, states, and acceptance criteria; do not reuse its fictional system names or API assumptions.
Scope and dependencies
State included flows, platforms, feature flags, system versions, dependencies, and exclusions.
Flow contract
Provide transitions, branches, state retention, and recovery.
Screen and component specs
Use:
Purpose | System mapping | Anatomy | Content/data | Behavior | States | Responsive | Accessibility | Events
State matrix
Include ownership and required fixtures.
Acceptance criteria
Group by feature behavior, accessibility, responsiveness, data integrity, and resilience.
Open decisions
Use:
Question | Why it matters | Decision owner | Blocking? | Needed by
Design QA plan
Name environments, viewports, content fixtures, assistive technologies, browsers, and high-risk checks. Record deviations as defects, approved tradeoffs, or design changes.
Checkpoint: Trace every acceptance criterion back to approved evidence and forward to component, state, and QA coverage. Revise gaps, then repeat until each Quality-bar item passes or every unresolved decision has an owner and blocking status.
Quality bar
- critical flows expose branches and recovery, and mappings name system components and tokens;
- content ranges, consequential states, and responsive constraints define implementation behavior;
- accessibility semantics, focus behavior, QA coverage, and acceptance criteria are explicit and observable;
- unresolved decisions have owners and never masquerade as implementation detail.