@fugood/bricks-ctor 2.25.0-beta.12 → 2.25.0-beta.13

package/skills/bricks-ux/references/monitoring-screens.md

@@ -0,0 +1,153 @@
+# Monitoring Screens
+
+A monitoring screen is a designed reading surface, not a designed flow. The user — operator, controller, observer — is not driving an interaction; they are absorbing state. The discipline is entirely about what they *see* and *trust*, not what they *do*.
+
+This file is the UX layer. Runtime semantics (Generators, Data event subscriptions, Switch thresholds) live in `bricks-design/architecture-truths.md` — particularly Truth #4 (Switches compare, Data Hit/Not-Hit only matches) and Truth #5 (Generators are headless / async / event-driven). Use them as the substrate. The design question is *what the screen shows about the state of the world*.
+
+## The three states a viewer reads
+
+A monitor screen is always in one of three reading-states. Designing for one without the others produces a screen that works in calm and fails under stress (or vice versa).
+
+### Calm — scanning for the absence of trouble
+
+The default state. Nothing requires attention. The viewer's job is reading at a glance and confirming "still nominal." This state is on the screen 95% of the time.
+
+**Design discipline:**
+
+- **Readable and forgettable.** The viewer should be able to absorb the screen in one peripheral-vision pass, look away, and feel confident nothing changed. Visual rhythm should be calm, predictable, with no demand-attention motion.
+- **Hierarchy by role, not by activity.** The most-important-thing-to-monitor stays in the same place even when it's calm. Operators learn the screen by location; shifting layout based on which metric is most active destroys that mental model.
+- **Subtle motion is permitted.** A sweep-second hand, a gentle pulse on the "live" indicator, a slow re-flow of a chart. The point is to confirm the screen is alive, not to draw the eye. `Animation` `runType: 'loop'` is legitimate here precisely for "the screen is breathing" signalling.
+
+**Failure modes:**
+
+- Calm-state screen so visually busy that the viewer can't tell normal from abnormal at a glance.
+- Calm with no "alive" signal — the operator can't tell if the screen is frozen or actually displaying current state.
+- Hierarchy that shifts based on data values — the top-of-screen item swaps because of recent activity, and the operator's eye-anchor is gone.
+
+### Detect — change worth noticing
+
+Something shifted. It isn't urgent, but it's worth the viewer's attention. A sensor crossed a soft threshold, a counter incremented, a new item entered the queue, a node went from 99.9% to 99.3% uptime.
+
+**Design discipline:**
+
+- **Show, don't ask.** The change should be detectable peripherally — a colour shift, a soft pulse on the affected item, a slow scale-up. The viewer can catch it without breaking focus from other things.
+- **Local, not global.** The change is localised to the affected Brick / region; the rest of the screen stays calm. Global re-styling of the whole Canvas for a single sub-system change is over-reaction.
+- **Time-bounded acknowledgement.** A detect-state visual should hold for long enough to be noticed (say 5–15 seconds), then quietly subside or escalate, depending on what happened next.
+- **Hero continuity.** Truth #3 — the chrome around the changing element does not also re-render. The eye lands on what moved.
+
+**Failure modes:**
+
+- Detect-state styled identically to calm — the viewer can't see anything changed.
+- Detect-state escalates immediately into demand styling (loud, motion-heavy, audible) — false alarm fatigue. The viewer learns to ignore "alarms" that are really just minor changes.
+- Detect-state persists indefinitely — small changes from yesterday still highlighted on today's screen; visual debt accumulates; nothing reads as fresh.
+
+### Demand — compel response
+
+A threshold breach. Something is wrong; the operator needs to act. This is the only state where the screen is allowed to *interrupt* the viewer.
+
+**Design discipline:**
+
+- **Unambiguous shift in register.** A clear visual rupture from calm — bold colour, accelerated motion, on-screen size, possible audio cue. The viewer's eye lands within a second.
+- **Action-pathing visible.** If the operator is expected to do something (acknowledge, dispatch, escalate), the action is on-screen and reachable. If they're expected to look elsewhere (radio, terminal), the screen says so.
+- **No false demand.** Demand state is earned by genuine threshold breaches; not by every-blue-moon variance. Demand-fatigue is the most expensive failure mode of a monitoring deployment — operators learn to dismiss real alarms because there were too many false ones.
+- **Persistent until cleared.** Demand state holds until the underlying condition resolves *or* the operator explicitly acknowledges. It does not time out on its own.
+- **Severity tiers** if the deployment has more than one demand level (warning / critical / emergency). Each tier reads distinctly; an operator under stress must be able to triage in one look.
+
+**Failure modes:**
+
+- Demand state styled subtly — operator misses it because it doesn't stand out.
+- Multiple concurrent demand states styled identically — no priority order; the operator picks one arbitrarily.
+- Demand state auto-clears after a timer — the underlying condition is still active; the screen has gone silent on it; the operator believes things are fine.
+- Demand state uses motion that overwhelms — every demand item flashes; the screen becomes unreadable.
+
+## The transitions between states are designed
+
+Calm → Detect → Demand → Calm is not a state machine the runtime hands you. It's a designed UX transition the agent commits to. Shared Brick auto-tween (Truth #3) carries the affected item across the transition; the chrome around it stays.
+
+- **Calm → Detect.** A subtle promotion. The affected Brick scales by 5–10%, gains a soft colour overlay, gets a subtle Standby Transition pulse. The eye is invited, not yanked.
+- **Detect → Demand.** A clear escalation. The affected Brick gains strong styling — a contrasting outline, a faster pulse, a colour shift to alarm tone — and possibly promotes in screen hierarchy (becomes larger, moves to a dedicated alarm region).
+- **Demand → Calm.** The release is also designed. Operator acknowledges or condition resolves; the affected Brick returns to its calm pose with a Standby Transition. The transition reads as relief, not as the screen forgetting.
+
+Each transition is a Switch on a state Data with thresholds (Truth #4). Each step in the transition has its own Brick configuration. The agent commits to the visual story across the four states, not just the calm baseline.
+
+## Stale-data trust principle
+
+**Stale data is worse than no data.** If the viewer cannot tell whether what they're seeing is current, they will trust what they see and act on it. Staleness must be *visibly declared* — not as fine-print, as a visible state change.
+
+**Design discipline:**
+
+- Every live-data Brick should have a visible "data age" or "last update" indicator, or a Switch-driven visual state for staleness. Background colour shift, opacity drop, "STALE" badge, or full handover to a "feed is down" Canvas if all sources are stale.
+- The threshold for "stale" is a design decision per source. Sub-second feeds (sensor stream) are stale after a few seconds. Minute-cadence feeds (weather, news) tolerate longer. Per-source thresholds belong in Data, not hardcoded everywhere.
+- A feed that loses its source entirely must not silently freeze on its last value — the screen must visibly transition to a no-data state. The operator can then route around it.
+
+**Failure modes:**
+
+- No staleness indicator at all — viewer trusts last-known-value forever.
+- Staleness indicator at 8pt in the corner — invisible to peripheral vision.
+- Stale value styled identically to current value — operator looks at "23°C" and acts on it; the reading is from 4 hours ago.
+- "Last update" shown but in a format the viewer must parse — "15:42:03" with no relative time framing. Relative ("2 minutes ago") beats absolute when "is this current" is the question.
+
+## Show vs ask — a design decision
+
+Some monitor screens *show* — they display state, leave action to operator judgement, never suggest. Air traffic control. Power-grid status.
+
+Others *show and ask* — they display state and surface protocol actions at the right moment. Hospital nurse stations. Building security. A "page nurse" button appears next to a patient whose vitals shifted; an "acknowledge alarm" button appears with a fire-system trigger.
+
+**Decide which it is per deployment, not per Canvas.** A monitor that sometimes asks and sometimes only shows confuses the operator about what they should be doing.
+
+Once decided:
+
+- **Show-only** monitors should not have action buttons at all. Any "do something" lives in a separate system (operator radio, dedicated terminal). The monitor reads as documentation.
+- **Show-and-ask** monitors integrate the action affordance into the alarm hierarchy. The action affordance follows the 7-step journey (see [`user-journey.md`](user-journey.md)) — affordance, instruction, feedback on press, in-flight visibility, continuation, recovery, closure. The monitor returns to calm only after the operator's action is registered and the underlying condition clears.
+
+## Hierarchy under stress
+
+When multiple things demand attention at once — three alarms, two warnings, a stale feed — the screen must already have a priority order designed.
+
+**Design discipline:**
+
+- **Sort by severity, then by recency.** Critical alarms above warnings above advisories; within tier, newest at top. Operators learn the order; reading is faster.
+- **Don't dilute.** Two simultaneous critical alarms don't both shrink to fit; the second one takes a designed "stacked" slot rather than reducing the first.
+- **Aggregate count visible.** When more demand states exist than the screen surfaces in detail, an "N more" indicator preserves operator awareness of the full picture.
+- **The calm Bricks recede.** Under stress, the rest of the screen quietens — backgrounds desaturate, non-alarm items reduce opacity. The eye is led to the demand region.
+
+**Failure modes:**
+
+- All concurrent alarms styled identically — operator picks one arbitrarily, may not hit the most critical.
+- The most recent alarm overwrites the older one — older urgent alarms vanish from view.
+- Screen layout shifts under stress — the chrome moves; the operator's spatial mental model breaks.
+
+## Color is necessary but never sufficient
+
+Critical / warning / normal must be encoded redundantly — colour PLUS shape, position, weight, or text. Operators may be colour-blind; viewing conditions may be unkind to colour (sun glare on screen, monochrome failover, photocopy of the screen sent to a stakeholder, viewing through a tinted shield).
+
+See [`accessibility.md`](accessibility.md) for the universal principle. For monitor screens specifically:
+
+- Critical alarms get a distinctive *shape* (diamond, hexagon, doubled border) on top of colour.
+- Severity indicated by *position* (top-of-list, dedicated alarm strip) as well as colour.
+- Numeric values that exceed threshold get a *prefix or sign* (▲, !, [HIGH]) — not just a colour change.
+
+## Refresh cadence is a UX decision
+
+How fast data updates is a UX decision before it's a wiring decision. A power-grid status board updating every 100ms reads as nervous; the same data refreshing every 5 seconds with a clear "live" pulse reads as in-control.
+
+**Design discipline:**
+
+- Pick a refresh cadence per source that matches how the operator should be reading it. Cadence is about *the reading experience*, not about whether the data exists.
+- Visible animation of updates (a value tweens from 23.4 to 23.7 over 400ms) reads calmer than snap updates. Use it for ongoing readings, not for state transitions (those are snaps).
+- For cadence < 1 second, batch the perceived update — even if the underlying stream is 10Hz, the on-screen change rolls forward in human-readable beats.
+- For cadence > 30 seconds, the absence of motion can read as broken. Add a calm "alive" indicator that ticks even when data hasn't changed.
+
+## How to use this file
+
+Before designing a monitoring screen:
+
+1. **Confirm Priority #0** — who is the operator, what are they reading, under what conditions, what's the cost of missing a state change.
+2. **Pick the show / show-and-ask posture.** Don't decide later; it shapes everything else.
+3. **Design all three reading-states** (calm / detect / demand) at the start, not just the calm one. Sketch the demand-state Canvas before the calm baseline lands.
+4. **Design the transitions** between states using shared Brick auto-tween (Truth #3) for affected items and Standby Transitions for the moment of change.
+5. **Design stale-data state per source.** No source is allowed to silently freeze.
+6. **Stress-test the hierarchy.** Stack 3 concurrent demand states in design preview; verify priority reads correctly.
+7. **Verify redundant encoding.** Take a monochrome screenshot; severity tiers should still be distinguishable.
+
+A monitor screen that passes calm-state critique but hasn't been designed for demand is half a deliverable.

package/skills/bricks-ux/references/pressable-composition.md

@@ -0,0 +1,126 @@
+# Pressable Composition
+
+The composition decision and the wiring decision are the same decision. Affordance — *can I press this?* — is a UX signal the user reads off the screen. Pressable configuration is how that signal lands at the runtime. Get the configuration wrong and the screen lies to the user: a tile looks pressable but isn't, or is pressable but only on certain pixels. Either way, the user fights the design.
+
+This file covers the configuration side. For the affordance discipline above it (when a thing should look pressable in the first place, how it joins the 7-step journey), see [`user-journey.md`](user-journey.md) step 1 and the relevant archetype rule set in [`interaction-archetypes.md`](interaction-archetypes.md).
+
+The single principle: **every composite (multi-element) button needs a deliberate `on_press` decision per Brick, with `pressable` set explicitly wherever press chains layer.** The runtime auto-bypasses safe cases (see below), so the trivial wrapper case works without ceremony — but the design intent should still be readable from the configuration when chains compete.
+
+There is no single mandated shape. Many arrangements work. The discipline is making the decision explicit where presses can collide, not following a recipe.
+
+## The values
+
+`Brick.property.pressable` accepts:
+
+- `'enabled'` — Brick receives press events; if it has an `on_press` chain, the chain runs.
+- `'disabled'` — Brick does not receive press events even if `on_press` is configured. Useful for runtime-disabled state via DataLink.
+- `'bypass'` — Brick is transparent to press events; the press passes through to whatever sits behind/around it.
+
+**Runtime auto-bypass.** Pressable-capable Bricks — `BrickText`, `BrickImage`, `BrickIcon`, `BrickRect`, `BrickSvg`, `BrickLottie`, `BrickRichText`, `BrickVideo`, `BrickVideoStreaming`, `BrickQRCode`, `BrickMaps`, `BrickGenerativeMedia` — with no configured press events (no `on_press`, no `on_focus`, no press/focus outlets feeding Switches or Animations) are auto-bypassed: the runtime renders them with `pointerEvents='none'` so taps fall through to the Brick underneath. A user-set `pressable` value always wins over auto-bypass.
+
+**Non-pressable families** — `BrickTextInput`, `BrickCamera`, `BrickSlideshow`, `BrickItems`, `BrickChart`, `BrickWebView`, `BrickRive` — manage their own interaction internally and are not auto-bypassed. Their pressable behavior is unchanged.
+
+`Brick.events.on_press` is the standard press handler — an array of `EventAction`s that runs on tap.
+
+## Common arrangements
+
+### Text-only press surface
+
+Simplest, most BRICKS-idiomatic.
+
+- One `BrickText` with an `on_press` chain.
+- The entire press surface is the text run itself.
+
+Use when: the visual is the text and only the text. Branding-light text links, in-flow CTAs.
+
+### Wrapped region (background, border, padding)
+
+The moment you add a `BrickRect` (or any shape) as a tile, card, button background, or padded container, the press intent moves to the wrapper.
+
+- `BrickRect` carries `on_press`.
+- Inner Bricks (the text label, an icon, an image) sit on top with no press events of their own.
+- The runtime auto-bypasses pressable-capable inner Bricks without press events, so the wrapper's chain fires regardless of where on the tile the user taps. No explicit `pressable: 'bypass'` is required for the common case.
+- Setting `pressable: 'bypass'` on the inner Bricks is still good practice when the child is purely decorative: it documents the design and protects against later edits that wire press- or focus-driven effects onto the child (e.g., a Switch fed by a press outlet) and silently break the tile.
+
+Use when: the press surface includes background, border, padding, or composition beyond a single text run.
+
+### Composite tile (image + text + meta, all pressable as one)
+
+Same shape as the wrapped region, with more children.
+
+- Backing `BrickRect` carries `on_press`.
+- All visual children — image, headline, subhead, icon, meta — auto-bypass when they carry no press events of their own.
+- The user perceives one tile; the runtime sees one press surface.
+- Explicit `pressable: 'bypass'` per child remains a clarity discipline, especially in tile layouts that are duplicated and later edited — a stray press handler on one child would otherwise break that tile silently.
+
+Use when: a card, a row in a list (note: `Items` Brick has its own row press model — read the template), a media tile.
+
+### Mixed-action composite (rare but real)
+
+A composite where most of the surface does action A, but a small region does action B (e.g., a card whose body opens a detail view but whose corner heart icon toggles favorite).
+
+- Backing `BrickRect` carries `on_press` for action A.
+- Most children auto-bypass (no press events of their own).
+- The exception child (heart icon) carries its own `on_press` for action B. Because it now has a press chain, auto-bypass is off and the icon owns its hit region.
+- Caveat: ensure the exception child is large enough to hit reliably without colliding with the surrounding action A. If it's too small, users will fight it.
+
+Use when: genuinely needed. If you find yourself reaching for this often, the design is probably trying to do too much per tile — split into clearer affordances.
+
+## Failure modes
+
+### Overlapping pressables
+
+Two or more children of a composite each carry their own `on_press` (or a Switch/Animation fed by a press/focus outlet). Auto-bypass doesn't apply — each child has events. The runtime resolves taps to whichever Brick owns that pixel; in practice this means inconsistent behavior depending on where the user actually lands.
+
+**Fix**: pick the press owner (usually the wrapper) and set the others to `pressable: 'bypass'` explicitly. The user-set value wins, so this forces the press through to the intended owner even when the loser Bricks have events.
+
+### Hidden press handlers on inner Bricks
+
+A composite that used to auto-bypass cleanly stops doing so after a Switch is wired to read a press or focus outlet on an inner Brick, or after an `on_press` is added to that child for an unrelated effect. The wrapper appears to lose hit area for that region without an obvious cause — auto-bypass is off the moment any press event is configured.
+
+**Fix**: when you wire any press- or focus-driven effect on a Brick inside a composite, set its `pressable` explicitly. If the effect should run *and* the wrapper should still win the tap, use `pressable: 'bypass'` on the child and drive the effect from the wrapper's chain instead.
+
+### Decorative overlay with unintended press chain
+
+A decorative `BrickRect` (frame edge, gradient overlay, spacing tile) sits in front of a pressable region and has press events wired — usually a leftover Switch trigger or copy-pasted from a real button. Auto-bypass doesn't engage, and the overlay silently consumes taps.
+
+**Fix**: any decorative overlay sitting in front of a pressable region should be `pressable: 'bypass'` explicitly. Treat "transparent in front of pressable" as a code smell that needs an explicit pressable decision — the runtime would auto-bypass a Brick with no press events, but the explicit value documents intent and survives future edits that wire effects into it.
+
+### Phantom hover on no-touch hardware
+
+Carried over from a web design with hover affordances — usually a Brick that brightens or shifts on press but the deployment is signage with no touch.
+
+**Fix**: drop the affordance, or move it to a state driven by a different signal (proximity sensor, scheduled time, Data from a peripheral Generator).
+
+### Web link semantics
+
+Designers used to web habits sometimes add `<a>`-style underlines or color treatments expecting a navigation primitive.
+
+**Fix**: BRICKS has no link semantic. `on_press` triggers `CHANGE_CANVAS` (internal navigation), a Generator (external action — open URL, dial number), or a Subspace action. The visual treatment is a design choice; the navigation primitive is a press handler.
+
+### `pressable: 'disabled'` without visual signal
+
+A Brick is set to `disabled` programmatically (e.g., during a pending submission) but the visual doesn't change. Users tap and nothing happens — looks broken.
+
+**Fix**: pair `pressable: 'disabled'` with a Switch that alters appearance (opacity, color, an overlay) so disabled state is visible. This is also step 3 (immediate feedback) of the journey — the user must see that their tap was received *and* declined.
+
+### Long-press misuse
+
+`delayLongPress` is real — the runtime distinguishes tap from long-press. Useful for secondary actions on a primary tile (long-press to favourite, tap to open). Misuse: hiding *primary* actions behind a long-press because there isn't room for a button. Long-press is discoverable only to users who already know it; primary actions need primary affordances.
+
+### Press feedback collapsed
+
+A press registers — the wiring works — but there is no visual change at the moment of registration (no scale-down, no opacity flash, no Switch-driven highlight). This is the most common silent UX failure: the press works, the user can't tell, so they press again. See [`user-journey.md`](user-journey.md) step 3.
+
+**Fix**: every `on_press` must pair with a visible state change at registration. A 100ms scale-down via Standby is enough; the user's eye needs to land on *something* moving.
+
+## Decision checklist when authoring a composite button
+
+For every Brick in the composite, answer:
+
+1. Does this Brick own a press chain — `on_press`, or a Switch/Animation fed by a press/focus outlet?
+2. If yes — should it own the tap, or should the wrapper own it?
+
+If two or more Bricks answer "yes" on overlapping hit areas, set the loser(s) to `pressable: 'bypass'` explicitly. If only the wrapper has a press chain, pressable-capable inner Bricks auto-bypass — `pressable: 'bypass'` is recommended for clarity but not strictly required. Non-pressable family Bricks (TextInput, Camera, Slideshow, Items, Chart, WebView, Rive) follow their own interaction model and don't auto-bypass.
+
+If any answer is "I haven't thought about it", the failure modes above are how it bites.

package/skills/bricks-ux/references/user-journey.md

@@ -0,0 +1,168 @@
+# The Universal User-Journey Spine
+
+Every interaction in a BRICKS Application — touch press, peripheral input, remote command, external trigger — passes through the same seven steps. Skip any of them and the design has a hole the user will fall into. The shape is universal across QR scan, face detection, BLE proximity, NFC tap, payment terminal, voice mic, touch tile, operator remote.
+
+This file is the spine. Anything that isn't here probably belongs in a more specific reference (transact intensification, peripheral particulars, archetype rule sets).
+
+## The seven steps
+
+### 1. Affordance — "Can I do something here?"
+
+The user must know the channel exists before discovering it by chance. A QR-scan zone with no scan-here label, a BLE-proximity threshold with no "approach to begin" hint, a touch tile that looks decorative — all fail at step 1.
+
+Affordance is the *invitation* to act. Without it, the rest of the journey is invisible.
+
+**BRICKS-native expression:**
+
+- A pressable region's visual treatment must declare "press me" — contrast, weight, a hint of motion via Standby Transition (gentle pulse), an icon. Use the runtime; don't rely on the user inferring touch from a flat Rect.
+- Peripheral channels need an instructive Brick in the line-of-sight: a scan-frame Image, a microphone glyph that lights when listening is possible, a "tap card here" overlay.
+- For ambient peripherals (BLE, camera detection), use a `valueHit` Data event on detection to *promote* the affordance — the screen invites the next step once the user is in range.
+
+**Failure modes:**
+
+- **Affordance hidden.** Pressable Brick visually indistinguishable from non-pressable. User walks past.
+- **Affordance present but ambiguous.** "Touch screen" floating with no anchor — touch *what*?
+- **Affordance promised, channel absent.** A scan frame drawn for a deployment that has no scanner.
+- **Affordance for absent capability.** Hover affordance on a no-touch panel; web-style cursor pointer on touch hardware.
+
+### 2. Instruction — "What do I do?"
+
+Once the user is invited, they need to act. The instruction must be specific enough to act on without overspecifying. Match the user's likely mental model — a payment terminal is not a QR scanner; same Canvas should not pretend otherwise.
+
+**BRICKS-native expression:**
+
+- A short directive in `RichText` near the affordance: "Scan your QR code", "Tap to start", "Hold card to reader". Bind to a Data string for multilingual.
+- Iconography or animation that demonstrates the action (a hand reaching toward the reader, a card moving toward the panel). One demo, not a five-step diagram.
+- For unfamiliar peripherals (NFC, voice for new users), include a one-shot tutorial on first entry — a separate Canvas, not a permanent overlay.
+
+**Failure modes:**
+
+- **Instruction missing.** Affordance present, action unclear. Common with NFC and voice — users don't know they need to *speak* or *tap*.
+- **Instruction overspecified.** Five steps for a one-step action.
+- **Instruction in wrong language** for the actual user — pin to deployment locale.
+- **Instruction stays after the action.** "Scan now" still on screen after the scan succeeded — confuses about whether to scan again.
+
+### 3. Immediate feedback — "Did I do it?"
+
+The instant between the user's action and the system's acknowledgement is the highest-anxiety moment in the flow. The user has *committed* — touched, scanned, tapped, spoken — and now needs proof their action registered.
+
+This is non-negotiable. A flow that skips immediate feedback has a hole the user falls through every time.
+
+**BRICKS-native expression:**
+
+- A snap-cut visual change at the moment of registration (not a fade-in — fades read as ambient, snaps read as acknowledgement). Brick scale, opacity, or color change via Switch on the input event.
+- A Standby Transition on a new Brick that enters at the moment of acknowledgement — a checkmark, a state badge, a progress indicator.
+- For audio-enabled deployments, a short auditory cue at the moment of registration. Silent is OK; ambient music is not enough.
+- If the registration takes any perceptible time (peripheral confirming, network round-trip), step 3 still fires first — the *system received* you — then step 4 takes over for the *processing* state.
+
+**Failure modes:**
+
+- **Feedback skipped, jumps to continuation.** User can't tell if their action registered or the Canvas just changed for unrelated reasons.
+- **Feedback fades in slowly.** Fade reads as ambient, not as response. Use snap on the moment of registration.
+- **Feedback on the wrong Canvas.** User taps, Canvas A doesn't react, Canvas B (the next one) loads after a beat — user assumes nothing happened and taps again.
+- **Same feedback for success and failure.** A check-mark feedback for a payment that's still processing reads as success — user walks away from a partial transaction.
+
+### 4. In-flight visibility — "Is it being handled?"
+
+When the system needs time — peripheral confirming, network round-trip, Generator awaiting response — the user must know the system is working. Silent processing reads as broken.
+
+**BRICKS-native expression:**
+
+- A clear in-flight Brick set: spinner, progress indicator, animated state badge. Use `Animation` `runType: 'loop'` here — this is a legitimate loop use (continuous attention-draw signalling activity).
+- The trigger affordance disables (`pressable: 'disabled'` or Switch-driven hide) so the user can't trigger again.
+- Time-bounded: if the in-flight state can plausibly take > 5 seconds, surface a progress estimate or a continued-activity reassurance ("Still processing — this can take up to 30 seconds"). Don't leave the user staring at an unchanging spinner past their patience threshold.
+- For peripherals: the peripheral's own state (Generator event from the device) should drive Switch transitions, not a guess at how long it'll take.
+
+**Failure modes:**
+
+- **No in-flight state at all.** Action triggered, Canvas frozen until result. User taps again; second action queues; chaos.
+- **In-flight state visually identical to idle.** No motion, no change in tone — user can't tell whether the system is working or stalled.
+- **In-flight state with no time-out.** System hangs; Canvas stays on "processing…" forever. Every in-flight state needs a Generator-driven failure path back to step 6.
+- **In-flight state allows re-trigger.** User can press again, queues duplicate work — especially bad for transact flows.
+
+### 5. Continuation — "What's next?"
+
+The action succeeded; what now? The user needs to know whether they continue here, move to a next state, walk away, or hand over to a peripheral / operator.
+
+**BRICKS-native expression:**
+
+- A Canvas change is the most common continuation — Switch on the success Data event, new Canvas with the next prompt or the result.
+- For flows that loop (slideshow, ambient signage), continuation can mean returning to attract / idle state.
+- The continuation Canvas's hero Brick(s) share id with the previous Canvas's hero — Truth #3 auto-tween carries the user across with continuity, not by hard cut.
+- If continuation is "stay here, do another thing," the prompt must update — the user shouldn't have to guess that they can act again.
+
+**Failure modes:**
+
+- **Continuation ambiguous.** Success acknowledged but the user is left on a static Canvas with no next-step prompt. They wait, then walk away.
+- **Continuation surprises.** Success on Canvas A, but Canvas D loads next — the journey shifts in a way that didn't match the user's mental model.
+- **Continuation lacks closure for some users.** A receipt flow that auto-advances after 3s before the user has read the confirmation.
+
+### 6. Recovery — "What if it went wrong?"
+
+Error states are first-class designed states, not afterthoughts. The recovery path tells the user what failed, why if relevant, and how to proceed — including the option to abandon.
+
+**BRICKS-native expression:**
+
+- A dedicated error Canvas (or a clearly distinct error state on the current Canvas, Switch-revealed). Not a tiny red text in a corner.
+- The error declares the cause in user-language: "Card declined" not "ERR_TRANSACTION_REJECTED". "Couldn't read the code — try moving closer" not "Scanner timeout".
+- The recovery offers a path — retry, alternate method, get help, abandon — never just states the failure.
+- Form input retained across error — user shouldn't re-type after a validation fail.
+- For peripherals, distinguish *user error* (action failed; retry) from *system error* (device unavailable; not the user's fault) from *abandonment* (timeout; resume or restart).
+
+**Failure modes:**
+
+- **Recovery as dead-end.** "Error. Please try again." with no path forward.
+- **Recovery erases progress.** User restarts from step 1 of a 5-step flow after a single-step failure.
+- **Recovery in unrelated language.** Technical error codes shown to end users.
+- **Recovery missing for the silent failures.** Peripheral disconnected mid-flow with no recovery path — user assumed it'd just work.
+- **Same recovery for all error types.** User can't distinguish "try again" from "the system is broken, walk away" from "you need to do something different".
+
+### 7. Closure — "When can I leave?"
+
+Especially in transact flows, the *past-the-point-of-no-return* moment must be explicit. The success state must declare the action complete in a way the user trusts before they walk away.
+
+**BRICKS-native expression:**
+
+- A success Canvas with weight — a confident headline, a check or stamp graphic, a printed-receipt analogue if applicable. Not a transient toast.
+- The success Canvas must hold visibly for enough time that a careful user reads it (5–10 seconds for a transact closure; 2–3 for routine completion) before auto-advancing or resetting to idle.
+- For ongoing actions (registered, will-be-notified), the closure must clarify the future: "You'll receive a confirmation by email" or "We'll call you when ready" with the expected wait clearly stated.
+- For closures that have a physical artifact (receipt, ticket, badge), the artifact's presence is part of the closure — the Canvas waits for the printer event before declaring done.
+
+**Failure modes:**
+
+- **Closure transient.** Success shown for 800ms, auto-advances to idle. User mid-blink, never saw confirmation.
+- **Closure ambiguous with in-flight.** Success badge in the same visual tone as the processing spinner — user uncertain whether they're done.
+- **Closure missing for irreversible action.** Payment confirmed by terminal but no on-screen success — user walks away unsure, doubles up via a second tap.
+- **Closure carries forward as a state the user can edit.** Success Canvas with input fields the user can change — implies the action isn't really committed.
+
+## When the seven steps compress
+
+Some interactions naturally collapse steps. Don't pad; collapse with intention.
+
+- **Glance-archetype loops** (signage, attractor): the user doesn't act. Step 1 (affordance) collapses to "attention", step 5 (continuation) to "loop", steps 3, 4, 6, 7 don't apply. Only 1, 2, 5 are live.
+- **Pure-monitor screens**: user doesn't act. Steps 1–4, 6, 7 collapse; the design is entirely about reading the state (see [`monitoring-screens.md`](monitoring-screens.md)).
+- **One-step transact** (NFC tap-and-go without amount confirmation): steps 1–4 fire in rapid sequence, but each still must be present — affordance, instruction, registration feedback, in-flight visibility, even if the in-flight is <1 second.
+
+Collapse means *fewer steps*, not *skipped steps*. A step you've skipped is a hole, not a compression.
+
+## When the seven steps intensify (transact)
+
+For payment / identity capture / safety-critical actions, the journey tightens:
+
+- **Step 2 (instruction) gets a confirmation step bolted on** — "You're about to charge $42.50. Confirm?" — a designed checkpoint Canvas before commit.
+- **Step 4 (in-flight visibility) cannot be skipped or hurried** — even a sub-second processing moment needs explicit visual presence. The cost of a missed in-flight is the user double-tapping a $42 charge.
+- **Step 6 (recovery) gets explicit categories** — card declined / network error / user cancelled / timeout — each with its own recovery path. A generic "Try again" is insufficient.
+- **Step 7 (closure) gets longer hold time + receipt** — the user must trust the transaction completed; cheap closures invite dispute.
+
+This intensification is enough that transact flows often deserve a separate design pass; for v1 of this skill, treat it as the loudest application of the seven-step spine.
+
+## How to use this file
+
+When designing any interaction:
+
+1. **Open the seven steps.** Walk the flow as the user would.
+2. **For each step, name** what the user sees / what the system does / how feedback manifests / what fails. If you cannot fill all four for a step, that step is unfinished.
+3. **Check the failure modes per step.** Each is a thing agents commonly skip. Caught here is cheap.
+4. **Express in BRICKS primitives.** Each step has expression notes — which Brick families, which architecture truths (Truth #3 hero auto-tween across the journey; Truth #5 Generator async; Truth #7 Standby Transition for feedback).
+
+The spine doesn't tell you what to design. It tells you which holes to *not have*.