b2c-app-builder 0.221.39

package/catalog/generated/firstparty/knowledge/design/editorial-scrollytelling.md

@@ -0,0 +1,239 @@
+# Evidence-Led Editorial Scrollytelling
+
+Use this reference when a public web surface needs a scroll-led story. It defines the story, state, controller, and proof contracts.
+
+Do not add scrollytelling because the component exists. First prove that a sequence makes the subject easier to understand.
+
+## Transfer Rule
+
+Transfer mechanics from reference work. Never transfer its palette, typefaces, metaphors, claims, copy, layout identity, or assets.
+
+Derive each visual decision from the current audience, evidence, brand, product, and conversion goal. Record that derivation in `DESIGN.md`.
+
+## Audited Reference Lessons
+
+A first-party audit of a production brand site contributed four mechanics:
+
+- evidence-first situation-to-mechanism-to-outcome-to-proof stories;
+- semantic `StoryScene`, `StoryAnchor`, and `StoryVisual` roles;
+- a narrow IntersectionObserver reading line;
+- code-native evidence artifacts.
+
+Its current mobile layout can let later states move beyond the inline visual. Large scroll jumps do not always sample each intermediate state deterministically.
+
+A first-party audit of a production portfolio site contributed these mechanics:
+
+- typed bilingual scene data;
+- measured step centers and one shared progress protocol;
+- responsive reader-line guide ratios;
+- restoration, resize, and font-load measurement;
+- separate no-JavaScript, reduced-motion, and Save-Data behavior.
+
+B2C App Builder combines the story grammar and evidence discipline with the deterministic controller. It transfers no identity from either site.
+
+## When Scrollytelling Applies
+
+Use scrollytelling only when the reader must understand a change across two or more linked states. Good subjects include a process, system response, transformation, or evidence trail.
+
+Do not use it for a list of unrelated benefits. Use a normal section, table, diagram, or static sequence instead.
+
+Optional sections stay optional. Do not add a default stack of hero animation, marquee, bento grid, scrollytelling, stats, testimonials, and pricing.
+
+## Optional Cinematic Layer Method
+
+When depth helps explain the selected story, plan layered composition before generating assets. For each layer record its semantic role, source and rights, dimensions, alpha requirement, alignment or anchor, depth relationship, critical content and mobile treatment. Add camera and lighting constraints only where the scene needs them. Identity and claims remain owned by the accepted brand kit.
+
+Declare entry, hold and exit checkpoints for the scene using the existing shared progress controller. Inspect those checkpoints forward, reverse, after a large jump and after restoration. Essential labels remain semantic text. A prerecorded sequence must not pretend to be an interactive three-dimensional object.
+
+Select ordinary HTML/SVG, layered 2.5D, actual 3D or media according to the task, available support, performance and meaningful fallback. A sticky stage, portal, serif face, card rail or a prescribed scroll distance is never required by this method. Real 3D requires actual geometry, picking and renderer proof on selected targets; declaring a technique does not install an implementation.
+
+This section adapts selected asset-planning and checkpoint ideas from Amir Mushich's [Cinematic Scroll Prompt Kit](https://github.com/amirmushichge/cinematic-scroll-prompt-kit), reviewed at commit `39ac222e385061c1eeab7f063b869950ee7cca1b` under MIT. The adaptation removes the example's fixed visual treatment and uses this reference's existing semantic controller and fallback contracts. No scene assets or executable demo are imported.
+
+## Build Order
+
+Use this order:
+
+1. Lock the audience, positioning, and claim ledger.
+2. Write the situation-to-mechanism-to-outcome-to-proof map.
+3. Render the complete semantic page without animation.
+4. Author concrete HTML and SVG visual states.
+5. Connect the measured state controller.
+6. Recompose the page for mobile layouts and Tier 1 locales.
+7. Harden accessibility, performance, browser proof, and deployment proof.
+
+## Story Map
+
+Write the story map before component work. Each scene must follow this semantic chain:
+
+1. **Situation:** Show the condition, constraint, or uncertainty that existed.
+2. **Decision or mechanism:** Show what the person or system did.
+3. **Outcome:** Show the change that resulted.
+4. **Proof:** Show the artifact, observation, or sourced result that supports the outcome.
+
+Each beat has one semantic role and one visual state. A scene can cover multiple roles through multiple beats. Do not omit the mechanism and jump from a problem to a claim.
+
+Use stable IDs. Copy edits and locale changes must not change an ID.
+
+```ts
+type StoryRole = "situation" | "need" | "decision" | "intervention" | "mechanism" | "outcome" | "proof";
+
+type StoryBeat = {
+  id: string;
+  role: StoryRole;
+  evidenceRef: string;
+  visualJob: string;
+  typographyJob: string;
+};
+```
+
+Use `StoryBeat.id` for both the semantic anchor and its corresponding visual state. The supplied scaffold publishes the same ID through `data-scene-state` and `data-scene-beat`.
+
+Use HTML for the reading sequence. Use HTML, SVG, and CSS for diagrams, interfaces, maps, records, and data states when possible.
+
+## Visual Meaning Contract
+
+Each scene visual must depict at least one of these items:
+
+- the situation;
+- the decision or mechanism;
+- the change or outcome;
+- the proof.
+
+Do not use a repeated slogan, giant word, random object, decorative dashboard, or abstract glow as the main evidence visual.
+
+Typography must have a semantic job. It can mark a source, quote, status, count, place, time, actor, or change in state. It must not repeat nearby prose only to fill space.
+
+Keep labels, values, and relationships as real DOM or SVG text. Do not bake necessary text into an image.
+
+## State And Controller Contract
+
+The anchor is the source of narrative state. The visual never runs on a separate narrative clock.
+
+Measure each step center after layout. Measure again after resize, orientation change, font load, locale change, or document-direction change.
+
+After a host changes the locale or the document `dir`, call `remeasureScrollScenes()` after the new DOM and fonts are ready.
+
+Choose a reader line for each responsive layout. The reader line is the viewport position where a step becomes active.
+
+Use this formula with reader position `r` and adjacent centers `c0` and `c1`.
+
+```text
+t = clamp((r - c0) / (c1 - c0), 0, 1)
+```
+
+Use one controller to publish the state to the scene root. Use this protocol exactly:
+
+```text
+data-scene-state stable active visual state ID
+data-scene-beat  stable active beat or state ID
+data-scene-direction forward or reverse
+--scene-p        normalized scene progress from 0 to 1
+--beat-t         normalized progress between the current and next anchor
+--beat-index     zero-based active beat index
+```
+
+Components can read this protocol through CSS or typed state. Do not create a second progress value for a child animation.
+
+Use direct state changes when the story has clear discrete states. Use interpolation only for a relationship that changes continuously between two anchors.
+
+Scroll down and scroll up must produce the same states in reverse order. Scroll-linked interpolation stops when scrolling stops.
+
+A discrete state can use a short tokenized settle. The active state changes immediately and never lags behind the prose.
+
+An ambient loop can use its own clock only when it carries no narrative meaning. Pause the loop when the scene is off screen.
+
+## Portable Host Contract
+
+`Scrollytelling.tsx` is a React adapter. It is not the capability boundary.
+
+An Astro, server-template, or static SSR host starts from [`scrollytelling.portable.example.html`](../../examples/workspace/business/growth/landing/scrollytelling.portable.example.html). Treat that file as the exact markup contract. Preserve its root static/final state, progress variables, direction and lifecycle attributes, semantic figure and ordered list, matching step/visual IDs, and final ARIA state. Replace its copy and visual contents.
+
+Every `[data-scene-step-state]` must have exactly one `[data-scene-visual-state]` with the same stable ID. Missing, duplicate, invalid, or mismatched IDs make `registerScrollScene()` warn and skip enhancement. The server-rendered final state remains the fallback.
+
+Do not require a React island when the host can use the framework-light controller directly. Register each `[data-scene-track]` from a client module after SSR.
+
+For a non-React host, serialize the request-derived Save-Data Boolean into `data-scene-save-data` and pass the same value to `registerScrollScene(element, { saveData })`. When true, never emit the heavy image/video source. Emit either:
+
+- a lightweight poster wrapper with `data-scene-poster-asset-id`; or
+- an empty wrapper with `data-scene-visual-omitted="true"` and no `img`, `video`, or `source` element.
+
+The portable example contains both modes. CSS hiding is not network prevention.
+
+## Sticky And Responsive Composition
+
+The sticky stage and its text anchors must share one scene container. The real anchor layout creates the scroll runway.
+
+On wide screens, use an asymmetric stage and reading rail when the story supports that composition. Keep the active copy within a stable reading band.
+
+Do not shrink a desktop scene to make the mobile version. Author a mobile composition.
+
+The mobile composition must include a clear guide. The guide can show the scene title, current beat, and progress. Keep it near the compact stage and out of the text path.
+
+Test short and tall mobile viewports. The sticky stage must not cover the active copy, controls, browser chrome, or safe areas.
+
+## Progressive Enhancement
+
+JavaScript, reduced motion, and data saving are different conditions.
+
+- **No JavaScript:** Render every heading, step, claim, and proof in semantic document order. A final-only visual is valid only when prose or captions contain every claim and proof. Otherwise, render static visual panels in document flow.
+- **Reduced motion:** Remove travel, parallax, smooth interpolation, and delayed reveals. A final-only visual follows the same claim-and-proof rule. Otherwise, render static visual panels in document flow.
+- **Save-Data:** Pass the request-derived `saveData?: boolean` prop to the SSR component. The runtime ORs this value with `navigator.connection.saveData`. When the prop is true, render a poster or omit the heavy source on the server. CSS hiding does not stop an image request. The prop supplies SSR state and controller policy. It does not intercept the network.
+
+Provide a poster and a static evidence state for each video. Never require video playback to understand the claim.
+
+Do not move focus, change the URL, or send screen-reader announcements on scroll. Decorative duplicates must use `aria-hidden="true"`.
+
+## Generated Media
+
+Use generated media only through the approved `growth/content-assets/CONTENT_ASSETS.md` route. Record its narrative job, source inputs, model, date, rights, locale scope, and fallback.
+
+Generated media can provide atmosphere or a bounded evidence plate. It must not invent proof or hide a weak state model.
+
+Reject generated media that adds illegible text, false product UI, unsupported people, false locations, or untraceable claims.
+
+## Surface Contract
+
+Record the decision in `growth/landing/surface-contract.json`. Use the shape in `knowledge/process/artifact-contracts.md`.
+
+When scrollytelling applies, the contract must include:
+
+- `applicable`, `evidence`, and `locales`;
+- ordered `scenes` with narrative roles, stable states, visual jobs, and evidence IDs;
+- source kind and content-asset IDs for heavy media and its Save-Data poster;
+- `localizations` with exact locale-specific beat text, captions, accessible descriptions, copy keys, and SHA-256 digests;
+- numeric desktop, mobile, and short-mobile activation guides;
+- mobile, reduced-motion, no-JavaScript, and Save-Data modes;
+- a `forward_reverse` proof flag for each scene;
+- `qa` rows with browser, platform, viewport, locale, direction, mode, scene, expected state, result, and evidence.
+
+Do not put localized `text`, `copy_key`, `copy_sha256`, `caption`, or `accessible_description` on the scene root. Put them in each locale row.
+
+When it does not apply, record `applicable: false`, the evidence-based reason, and empty `scenes` and `qa` lists.
+
+## QA Matrix
+
+Record evidence for every applicable row.
+
+| Test                       | Required proof                                                                                |
+| -------------------------- | --------------------------------------------------------------------------------------------- |
+| Forward and reverse scroll | Each stable state activates once in order and in reverse order.                               |
+| Jump and restored position | The controller selects the correct state without sampling each earlier state.                 |
+| Scroll stop and scrub      | Narrative motion stops and tracks the same anchor-derived progress.                           |
+| Desktop                    | Current Chrome, Safari, and Firefox at short and tall desktop viewports.                      |
+| Mobile                     | Current iOS Safari and Android Chrome at short and tall mobile viewports.                     |
+| Resize and rotation        | Centers are measured again. The active state stays correct.                                   |
+| Tier 1 locales             | Each state, direction, and fallback mode is proved against the localized layout.              |
+| No JavaScript              | The complete reading sequence and proof remain available.                                     |
+| Reduced motion             | No travel, parallax, autoplay, or delayed reveal remains.                                     |
+| Save-Data                  | Heavy media stops. Code-native evidence remains usable.                                       |
+| Keyboard and screen reader | DOM order, headings, links, focus, names, and decorative hiding are correct.                  |
+| Slow device and network    | First text paint is not animation-gated. No scene causes harmful input delay or layout shift. |
+
+Run these gates before handoff:
+
+```bash
+npm run check:design-room -- --root .
+npm run check:vibecoded-tells -- --root .
+npm run check:scrollytelling -- --root .
+npm run check:landing-funnel -- --root .
+```

package/catalog/generated/firstparty/knowledge/design/landing-motion-craft.md

@@ -0,0 +1,67 @@
+# Landing Motion Craft
+
+Use this reference before you build or animate a landing page, funnel page, or public web surface. Use `docs/prototypes/landing-motion-lab.html` as the local motion proof. Use motionsites.ai (`https://motionsites.ai`) only as an inspiration benchmark.
+
+When the page needs a scroll-led story, also load [`editorial-scrollytelling.md`](./editorial-scrollytelling.md). That reference owns story maps, stable state anchors, measured progress, responsive composition, and scrollytelling proof.
+
+## The two-lane content model
+
+One brand timing system, two delivery lanes. Both read the same promoted `--motion-*` tokens (`design/system/tokens.css`, generated from `DESIGN.md` by `npm run promote:design-tokens`):
+
+| Lane      | Tool                                                                       | Owns                                                                                      | Never does                        |
+| --------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | --------------------------------- |
+| **Baked** | Remotion (`remotion-content-assets.md`)                                    | hero loop `.webm`/`.mp4` + poster, section media tiles, ad/store art — render once, embed | live scroll/hover/cursor behavior |
+| **Live**  | DOM, CSS, and `motion/react` when needed (`https://motion.dev/docs/react`) | measured story state, in-view reveals, parallax, count-up, cursor response, and marquee   | frame-exact video output          |
+
+Remotion renders frames. It does not own live DOM behavior. Record each baked-video choice in `strategy/TOOL_DECISIONS.md`. The choice uses the license gate in [`paid-tool-routing.md`](../operations/paid-tool-routing.md).
+
+## The section library
+
+`business/growth/landing/` ships reusable section code, `lib/motion-tokens.ts`, and `motion.css`. Treat this set as an inventory, not a page recipe. Select a section only when audience, story, proof, and conversion evidence require it.
+
+Do not fill every slot. Do not apply a source site's palette, fonts, metaphors, claims, copy, layout identity, or assets. Transfer the useful mechanism and express it through the current design contract.
+
+For scrollytelling, write the situation-to-mechanism-to-outcome-to-proof map before component work. The story anchors must drive the visual state. Do not use a separate narrative timer.
+
+Two web-lane recipes live in the in-app benchmark file [`motion-craft-benchmarks.md`](./motion-craft-benchmarks.md): R9, the contained edge-warp scroll transition (margin, channel-split, and edge-proximity rules), and R1, asynchronous-grid hero liveness. Load it when a landing hero or scroll moment calls for either.
+
+When the 60fps.design MCP is connected, the landing lane can ground a hero, scroll moment, or micro-interaction in a live exemplar the same way the in-app lane does — `60fps_search_shots` to find the pattern, `60fps_get_motion_breakdown` for its trigger/start→transition→end anatomy (tools and ground rules in `motion-craft-benchmarks.md` §Live Catalog Access). The shots are iOS in-app clips: adopt the mechanic, re-express it in `motion/react` on the `--motion-*` scale, and skip `60fps_get_motion_code` on this lane — its SwiftUI starter has no web target. motionsites.ai stays the landing benchmark; when the MCP is not connected, the section library plus R9/R1 remain the contract and searching is not required.
+
+Before you draft section copy, load `knowledge/words/no-slop-writing.md`. Use the voice in `strategy/BRAND.md` and `11_STAR_EXPERIENCE.md`.
+
+Host the supplied React adapters in Next.js App Router or another React SSR site. An Astro or static SSR host can render the semantic scrollytelling markup and register the framework-light controller directly. Scrollytelling does not require a React island. Use `motion/react` only for sections that need its choreography. Never import it in the mobile binary. `check:template-safety` enforces this boundary.
+
+## The progressive-enhancement contract (enforceable)
+
+Rules 1, 2, and 4 are mechanically enforced by `check:landing-funnel` when landing sources animate. Deploy gates and browser proof verify rule 3.
+
+1. **Real text, always.** Above-the-fold copy exists in static HTML and is never animation-gated. Reveal states apply only under `html.js`. A final-only no-JavaScript visual is valid only when semantic prose or captions contain every claim and proof. Otherwise, render static visual panels in document flow.
+2. **Reduced motion preserves proof.** Animated sources must include a `prefers-reduced-motion` rule. A final-only visual is valid only when semantic prose or captions contain every claim and proof. Otherwise, render static visual panels in document flow.
+3. **Motion never gates LCP/INP.** Server-render or statically render content; hydrate choreography after. Entrance animation must not delay first paint or hide text from crawlers.
+4. **Tokens, not magic numbers.** Durations/easings read the `--motion-*` scale. Raw millisecond literals in landing motion styles are flagged — retime the brand by re-promoting tokens, not by editing sections.
+5. **Save-Data is separate.** Pass the request-derived `saveData?: boolean` prop during SSR. The runtime ORs it with `navigator.connection.saveData`. When the prop is true, render a poster or omit the heavy source on the server. CSS hiding does not stop an image request.
+6. **Layout changes trigger measurement.** Call `remeasureScrollScenes()` after a locale or document-direction change.
+
+## The landing motion token scale
+
+The in-app micro-motion band (120–360ms) is deliberately too short for cinematic web work; the landing lane adds:
+
+| Token                         | Default           | Use                                                                 |
+| ----------------------------- | ----------------- | ------------------------------------------------------------------- |
+| `--motion-duration-reveal`    | 600ms             | in-view reveals, word stagger                                       |
+| `--motion-duration-cinematic` | 1200ms            | mesh drift, scrollytelling cross-fades, count-up, marquee base unit |
+| `--motion-easing-emphasis`    | expo-out          | entrances that should feel decisive                                 |
+| `--motion-easing-spring`      | springy overshoot | playful accents (toggle re-price, badges)                           |
+| `--motion-stagger`            | 60ms              | per-item stagger step                                               |
+
+These live in `DESIGN.md` → promoted into `design/system/tokens.css`, `tokens.json`, and `DesignTokens.swift` (`check:token-promotion` gates the hash). Remotion compositions read the same values so baked and live motion share one feel.
+
+## Production floor (beyond the proof)
+
+- **Type:** self-host the real display webfont (subset, `font-display: swap`, preload). The token fallback stack is for dependency-free proofs only.
+- **Baked hero video:** opt-in per launch through the Remotion lane; always ship a poster and keep the mesh fallback.
+- **Smooth scroll (Lenis):** optional; if adopted it must degrade cleanly, respect reduced motion, and be registered in `source-registry.yaml` before use.
+- **Copy:** section copy passes the `no-slop-writing.md` self-check (§6) before `check:landing-funnel` runs — brand voice from `strategy/BRAND.md` wins over generic landing-page register.
+- **Scrollytelling:** show the situation, mechanism, change, and proof. Do not use repeated slogans or giant words as evidence visuals.
+- **Generated media:** use the approved content-asset route. Record its narrative job and provenance. Do not use it to hide weak state design.
+- **Verification:** record Chrome, Safari, and Firefox proof for short and tall desktop viewports. Record iOS Safari and Android Chrome proof for short and tall mobile viewports. Run `check:design-room`, `check:vibecoded-tells`, `check:scrollytelling`, and `check:landing-funnel`.

package/catalog/generated/firstparty/knowledge/design/mobile-flow-craft.md

@@ -0,0 +1,177 @@
+# Mobile Flow Craft
+
+Use this reference when designing, implementing, or auditing a native mobile flow. It strengthens the Design Room with flow-level research, navigation semantics, native fidelity, mechanical anti-generic checks, motion budgeting, and runtime verification.
+
+This doctrine adapts selected methods from Appllama's MIT-licensed `appllama-app-design-skill` and `appllama-usage` skills into B2C App Builder's cross-platform contracts; the MIT notice travels with the package's third-party notices. It does not copy Appllama's proprietary screen library, require its MCP, or make Expo/React Native the default stack.
+
+## 1. Research the question, not the gallery
+
+Start with a named decision. Examples:
+
+- How should first-run onboarding earn the permission ask?
+- What is the category grammar for a hard paywall after first value?
+- Is this filter a pushed destination, a sheet, or an in-screen state?
+- Which states and recovery paths does this core loop need?
+
+For substantive new or materially changed mobile flows:
+
+1. State the research question and the product constraint before collecting references.
+2. Prefer complete comparable journeys over isolated screenshots.
+3. Compare multiple relevant products when authorized evidence exists. One product shows one implementation; convergence across several products is stronger evidence of a convention.
+4. Record convergence, divergence, and the reason a local choice fits this product. Revenue, popularity, or a provider ranking is context, never causal proof that a design choice is correct.
+5. Stop when additional evidence no longer changes the working specification. Record the saturation judgment instead of harvesting a catalog indefinitely.
+6. Extract patterns, not pixels. Never copy another product's brand, copy, assets, or exact composition.
+
+`design-evidence-stack.md` owns provider selection and evidence resolution. Appllama, when explicitly available and authorized, is one possible reference provider. Its provider-specific tool instructions remain upstream in `appllama-usage`; do not fork its MCP manual into this repository.
+
+## 2. Specify the flow grammar
+
+A screen specification is incomplete when it describes only appearance. Every transition in a primary flow must answer:
+
+- **Destination semantics:** deeper destination, completed/replaced state, modal task, short interruption, overlay, system controller, or peer tab.
+- **Return expectation:** should the user be able to return to the source after the world changes?
+- **Back behavior:** what do navigation back, edge swipe, Android system back, Cancel, and dismissal do?
+- **State consequence:** did the action merely navigate, or did it commit an event that navigation cannot undo?
+- **Interruption behavior:** if authentication, payment, permission, or another gate interrupts an action, where does success return the user and what action resumes?
+
+### One-way doors
+
+Use replacement semantics after a state transition when returning would expose an invalid past state. Common examples include completed first-run onboarding, an authentication wall that has permanently resolved, or a purchase path whose prior hard paywall is no longer valid.
+
+Do not turn every funnel step into a one-way door. Back remains available unless returning is semantically invalid, an irreversible request is briefly in flight with visible progress, or unsaved work requires a confirmation before dismissal.
+
+A paywall opened from an existing feature normally dismisses back to that feature after purchase, now unlocked. A sign-in interruption triggered by a user action should preserve enough context to resume that action. Product intent owns these semantics; the framework implementation follows them.
+
+### Presentation semantics
+
+Use the platform's native presentation model when it fits:
+
+- a deeper durable destination uses normal navigation;
+- a self-contained multi-step task uses a modal task with its own completion/dismissal semantics;
+- a short picker/filter/options interruption may use a sheet;
+- content floating over a still-visible source may use an overlay;
+- destructive confirmation and sharing/picking should use appropriate system surfaces when available;
+- peer tabs preserve independent navigation history rather than pretending to be sequential pages.
+
+If a temporary sheet grows into a multi-step task, reclassify it. If a destination must deep-link or own durable state, treat it as a route rather than hiding it in ephemeral component state.
+
+Record the semantic decision in the applicable `design/flows/` or `design/screens/` contract. Framework-specific code is implementation evidence, not the source of product semantics.
+
+## 3. Native fidelity is correctness, not decoration
+
+Separate three kinds of decisions:
+
+1. **Product semantics:** what the user can do and what state changes.
+2. **Platform fidelity:** controls, navigation, accessibility, safe areas, system conventions, localization, and input behavior users expect on that platform.
+3. **Brand expression:** tokens, type, imagery, composition, shape, and deliberate product-specific departures.
+
+A brand decision cannot silently override a platform behavior. When a custom control replaces a native control, document the user or product reason and verify its accessibility, interaction, state, and platform behavior.
+
+For each selected platform, verify applicable:
+
+- semantic light/dark color behavior;
+- platform-appropriate controls and iconography;
+- dynamic text or text scaling;
+- safe areas, status areas, home/system gesture areas, and supported orientations;
+- keyboard/focus/input behavior;
+- localization of numbers, currency, dates, and pluralization;
+- haptics as supplementary feedback rather than the only feedback;
+- system accessibility settings, including reduced motion and screen reader behavior;
+- scrolling and content overflow rather than fixed-height happy-path layouts.
+
+Do not hard-code framework prescriptions into the cross-platform contract. SwiftUI, UIKit, Flutter, Compose, React Native, and other supported stacks implement the same semantic requirement differently.
+
+## 4. Ship state cycles, not screenshots
+
+Every primary surface must account for the states required by `design-acceptance.md`. At minimum, do not treat a static success state as the whole design.
+
+Loading should preserve expected layout when its shape is known. Empty states should explain how the user can reach useful content. Errors should be specific and recoverable when recovery exists. Offline and permission-denied behavior must be explicit or have a product-specific non-applicability reason.
+
+Optimistic feedback is useful only when rollback and failure are visible and correct. Do not hide network or provider uncertainty behind a success animation.
+
+## 5. Mechanical anti-generic preflight
+
+A design audit should turn objective parts of 'this feels generated' into checks. The exact values come from the accepted design system, not from a universal aesthetic law.
+
+Before runtime acceptance, inspect at least:
+
+- **Accent drift:** every accent belongs to an approved semantic/token family. No surprise hue appears because one screen was built separately.
+- **Shape drift:** radii, borders, elevation, and container shapes come from the declared token system unless a named exception exists.
+- **Intent-label drift:** the same product intent does not accumulate interchangeable CTA labels without a content decision.
+- **Chrome icon drift:** UI chrome uses the selected icon system; emoji or mixed icon families require an explicit brand/content reason.
+- **Unexplained effects:** gradients, glass, glow, blur, confetti, and decorative motion have a recorded purpose or are removed.
+- **State completeness:** applicable loading, empty, error, offline, permission, large-text, screen-reader, dark/light, and reduced-motion cases are represented by the acceptance scope.
+
+These checks are not a beauty score. Mechanical findings fail mechanically. Taste remains governed by `design-worthiness.md` and the independent audit.
+
+## 6. Motion has a budget
+
+Before adding custom motion, classify frequency and purpose.
+
+### Frequency gate
+
+- **Constant/high-frequency interactions** such as scrolling, ordinary back navigation, keyboard movement, and tab switching should default to platform behavior. Custom flourish is usually a regression.
+- **Frequent direct feedback** such as presses and selections should be immediate and restrained.
+- **Occasional state changes** such as sheets, confirmations, or meaningful reveals may use the accepted motion vocabulary.
+- **Rare earned moments** may use expressive choreography when it serves the emotional/product contract.
+
+Zero custom animation is a valid result of the gate.
+
+### Purpose gate
+
+Name the purpose: feedback, spatial continuity, state change, comprehension, preventing a jarring cut, or earned delight. If the motion has no user-facing purpose, remove it.
+
+Gesture-driven motion follows the gesture and preserves continuity. Non-gesture motion follows the accepted token/preset scale in `premium-mobile-craft.md` and `motion-craft-benchmarks.md`. Do not introduce per-screen timing literals when a project preset exists.
+
+Reduced-motion behavior is part of the same interaction contract, not a later accessibility patch.
+
+## 7. Runtime verification is part of design completion
+
+A Design Room render proves authored direction, not native implementation quality. A static screenshot proves one frame, not navigation, motion, recovery, or accessibility.
+
+For implemented mobile flows, verify the complete authored interaction on a current registered runtime using the evidence rules in `design-acceptance.md`.
+
+The review must inspect:
+
+1. entry state and prerequisite state;
+2. the full primary interaction sequence;
+3. navigation and dismissal semantics, including back behavior;
+4. loading/recovery/error or declared non-applicability;
+5. light/dark and accessibility settings required by the accepted surface;
+6. reduced-motion behavior;
+7. scrolling, safe-area, keyboard, and interruption behavior where applicable;
+8. final state and any one-way-door behavior.
+
+When motion is material, capture a recording or interaction artifact that lets the independent reviewer inspect the transition rather than inferring it from before/after frames. When performance is material, use the production/release-like runtime appropriate to the selected stack and device class; a development shell cannot prove release performance.
+
+Do not invent 'simulator verified' as a prose label. `design-acceptance.md` owns strict producer-bound capture and interaction receipts, runtime identity, candidate fingerprints, and independent review.
+
+## 8. Cross-station ownership
+
+The Design station does not own every consequence of a flow.
+
+- Product owns the user job, irreversible state, value sequence, and accepted scope.
+- Design owns presentation, interaction grammar, native fidelity, and visual/motion contract.
+- Engineering owns correct stack implementation and runtime behavior.
+- Monetization owns entitlement and purchase semantics where applicable.
+- Store/operations own provider and release constraints.
+- Analytics owns measurement semantics.
+- Accessibility/device QA independently verifies applicable platform behavior.
+
+A design pattern from a benchmark cannot override another station's accepted constraint. When evidence exposes a conflict, resolve the product decision instead of quietly coding around it.
+
+## 9. Working check
+
+Before calling an implemented mobile flow design-complete, you can answer:
+
+- What question did the reference research answer?
+- Which conventions converged across evidence, and where did this product deliberately diverge?
+- What is every transition's semantic type and return expectation?
+- Which transitions are true one-way doors, and why?
+- Which behaviors are platform correctness versus brand choices?
+- Which mechanical anti-generic checks passed?
+- What purpose and frequency class justifies each custom motion?
+- Which complete interaction was actually observed on the registered runtime?
+- What evidence covers recovery, accessibility, reduced motion, and final state?
+
+If the answer is only 'the screens look good,' the flow is not done.