Cross-Device Recomposition Spec

Produce an implementation-ready responsive contract. Preserve the approved design language and meaning; change composition when the available space or input mode requires it.

Establish evidence and authority

1. Inspect the approved design frames, screenshots, implementation, structured content, variables, styles, components, and constraints.
2. When Figma nodes are supplied, inspect each named device root and the same semantic sections within them. Use structured context and screenshots; do not infer a system from a single frame.
3. Record source precedence. Prefer approved requirements and design-system variables/components over frame-local values, accepted device frames over implementation accidents, and implementation over unsupported guesses.
4. Record target width ranges, orientation, minimum supported width, input modes, and content/localization constraints. Treat 1440, 834, and 390 as comparison samples only when no product baselines exist. Endpoint frames prove states, not the exact width where one state changes into another.
5. Mark conflicting or missing evidence Open. Stop when the source direction, content priority, or authority cannot be resolved safely.

Read device-baselines.md before setting device or transition rules. Use migration-ledger.md for rule IDs, evidence, and output tables.

Separate the migration layers

Build one shared source model and classify every observed value:

• Invariant — approved fact, semantic order, token, component responsibility, state meaning, or brand rule that all devices must share.
• Fluid — a value that may interpolate within an evidenced range without changing structure.
• Reflow — a structural change in axis, order, grouping, columns, disclosure, alignment, or position.
• Interaction swap — an equivalent control model for another input mode, such as hover to tap/focus or spatial map to map plus list/detail.
• Media adaptation — an evidenced crop, focal anchor, aspect ratio, source swap, or art direction rule.
• Exception — an approved device-specific deviation with scope and reason.

Do not promote repeated raw pixels to tokens unless variables, styles, components, or repeated evidence support that conclusion. Do not maintain device-specific copies of the same fact.

Compare semantic peers

For every section or component that appears across devices:

1. Match it by semantic role and content identity, not layer name or canvas position alone.
2. Record what stays constant: purpose, facts, actions, component states, visual hierarchy, and media subject.
3. Record what changes: reading order, layout axis, columns, density, crop, visible context, navigation, motion, and fallback.
4. Distinguish intentional design changes from capture artifacts, hidden prototype states, overflow outside a frame, and one-off implementation fixes.
5. State the smallest reusable rule that explains the approved variants. Keep project-specific measurements as evidence, not universal defaults.

Specify responsive transitions

Define behavior for the full supported range, not only three screenshots.

For each structural change, specify:

• the failure signal that requires change, such as collision, unreadable measure, lost focal subject, undersized target, competing gestures, or hidden primary action;
• the evidenced transition condition, exact breakpoint, or still-open interval;
• the layout immediately before and after the transition;
• axis, order, columns, alignment, spacing, media, visibility, and interaction changes;
• behavior at intermediate widths and, after a breakpoint is implemented, one pixel on both sides of it;
• long-copy, localization, zoom, missing-media, and reduced-motion results.

When moving to a small screen, actively recompose. Convert multi-column or spatial layouts into the clearest reading sequence; preserve the primary task; keep secondary context reachable through a named disclosure or local scroll model. Never accept uniform scaling, clipped desktop overflow, smaller text alone, or silent content removal as responsive behavior.

Choose breakpoints from approved product ranges or a measured intrinsic-fit failure using the real components, tokens, and stress copy. When only endpoint frames are available, record the interval between the nearest approved states, the probing method, and the decision owner; keep the exact breakpoint Open. Never invent a precise coding threshold from device names, nominal Figma widths, midpoint arithmetic, or proportional ratios.

Specify interaction equivalence

• Give hover-only information a tap, focus, or always-visible equivalent.
• Keep controls at least as large as the approved system target; use 44 px mobile and 48 px Pad only as study defaults when no system target exists.
• Keep vertical page scrolling available. Use horizontal swipe for one clearly signaled local peer set and avoid nested gestures on the same axis.
• Preserve current position, total count, active state, next action, keyboard path where applicable, and focus restoration after disclosure.
• Map scroll-linked or cinematic motion to an information-equivalent reduced-motion state.

Check migration integrity

Do not mark the specification ready when:

• a claimed invariant has no authoritative evidence;
• a frame-local pixel value is presented as a global token without support;
• any small-screen result is only a scaled or clipped desktop layout;
• a structural change lacks a before/after transition rule;
• an exact breakpoint is claimed from endpoint frames without approved or measured evidence;
• intermediate and minimum widths are unaddressed;
• hover, spatial, drag, or scroll-driven behavior lacks an equivalent input model;
• essential content or state disappears without an approved exception;
• media crop can remove the subject needed to understand the section;
• acceptance criteria cannot distinguish pass from fail.

Return the handoff

Return:

1. Scope and source precedence — surfaces, ranges, input modes, authoritative evidence, and open conflicts.
2. Invariant ledger — shared facts, tokens, component responsibilities, states, and approved exceptions.
3. Semantic comparison matrix — the matched sections/components and evidence from each supplied device.
4. Migration map — each rule classified as invariant, fluid, reflow, interaction swap, media adaptation, or exception.
5. Breakpoint and reflow table — failure signal, evidence level, exact threshold or open interval, before/after composition, probing method, and intermediate-width behavior.
6. Device composition matrix — desktop, Pad, mobile, and minimum-width structure, density, media, navigation, and primary task.
7. Accessibility and fallback rules — touch, keyboard, focus, zoom, localization, missing media, and reduced motion.
8. Risks and open decisions — owner and affected rules for every unresolved dependency.
9. Acceptance matrix — observable checks with viewport/input, expected result, failure condition, and evidence method.

Stop after the specification. Do not edit implementation files, write to Figma, create a prototype, or claim that the resulting interfaces passed final QA.