@fugood/bricks-ctor 2.25.0-beta.5 → 2.25.0-beta.50

package/skills/bricks-ux/references/flow-states.md

@@ -0,0 +1,175 @@
+# Flow States
+
+Idle, loading, empty, error, attractor, boot, maintenance — these are not afterthoughts. They are states the deployment will spend real time in. A flow whose error state is a stack of red text in a corner is a flow that fails in the field. A kiosk whose idle state is "whatever the last user was looking at" is a kiosk that confuses every next user.
+
+This file treats each as a **first-class designed state**. Universal principles, BRICKS-native expression notes, and the failure mode that consistently slips into agent-produced work.
+
+The common thread across all of them: every state has a *who arrives*, a *what they see*, a *what they need to know*, and a *how they leave*. If you cannot answer all four, the state is unfinished.
+
+## Idle
+
+**The state when the screen is on, the user is not present, and no peripheral / sensor event is active.**
+
+Most kiosks and interactive deployments spend the majority of their hours idle. Yet idle is the most-skipped designed state in agent work — it gets treated as "whatever Canvas is loaded when nobody's using it," which is wrong.
+
+**Design discipline:**
+
+- **Idle is a designed Canvas (or set of Canvases), not a side-effect.** The flow returns to it after every session via an idle-timeout reset.
+- **Idle invites.** A passerby should look at the idle screen and understand what's offered here. This is the affordance layer for the eventual interact flow — see [`user-journey.md`](user-journey.md) step 1.
+- **Idle resets cleanly.** No state from the previous user persists into idle — no half-built order, no name still on screen, no "please confirm". The reset wipes flow Data; `persistData: true` is reserved for *deployment* state (last-known-good, config), not session state.
+- **Idle rotates if needed.** For deployments where idle runs hours, a slow Slideshow / Canvas rotation prevents burn-in and gives the screen rhythm. Don't loop a single static Canvas indefinitely.
+- **Idle is calm.** No spinners, no progress indicators, no "loading" residue. The screen is at rest.
+
+**Failure modes:**
+
+- Idle = "last interact Canvas frozen." Next user arrives mid-flow, doesn't know whose order is on screen, may complete or cancel someone else's.
+- Idle with a spinner or "please wait" — implies the system is busy when it isn't.
+- Idle without an attractor element — passersby see "this is on" but not "this is for them".
+- Idle timeout reset that doesn't actually reset all Data — partial state leaks into next session.
+- Idle too noisy — looping animation that demands attention from people not interacting; reads as broken.
+
+## Attractor
+
+**The active state of "no current user, but invite the next one."**
+
+Some deployments differentiate idle (passive) from attractor (actively inviting). A kiosk in a quiet store may use the same Canvas for both; a kiosk in a busy mall might cycle a deliberate attractor sequence to pull users in.
+
+**Design discipline:**
+
+- **A clear value proposition.** "Order here", "Check in", "See today's events", "Find your room". One line, large, immediately readable from approach distance.
+- **A demonstration of action.** A subtle animation showing the kind of interaction the user will do — a finger graphic tapping a tile, a card moving toward a reader, a face-detection frame breathing.
+- **Brand presence, not brand wallpaper.** The brand is in the attractor; the attractor isn't *only* brand. A wordmark-only attractor doesn't tell the passerby what's possible.
+- **Calibrated motion.** Enough to catch the eye from peripheral vision (10–15° off-axis), not enough to read as broken or anxious.
+- **Time-of-day / context aware** if the deployment runs long hours — morning rush attractor differs from afternoon quiet differs from late-night.
+
+**Failure modes:**
+
+- Attractor that's only logo + tagline — looks like signage, not like an invitation to act.
+- Attractor that demos a different action than what's available — promises one experience, delivers another.
+- Attractor with hover-style affordances on no-touch hardware — implies pointing-device interaction that doesn't exist.
+- Attractor competing with the deployment's surroundings — the screen drowns in a busy retail wall, or shouts over a quiet hotel lobby.
+
+## Boot
+
+**The state when the device just started — pre-content, pre-user.**
+
+Per `bricks-design/performance.md`, the boot Canvas must render in < 1s using only cached/persisted Data. That's the runtime floor. The design floor is *what the user sees during that second and what arrives after*.
+
+**Design discipline:**
+
+- **Boot is brand, not work.** The first second is brand presence — wordmark, logo lockup, a confident moment. Not a spinner. Not "loading…".
+- **Boot transitions into idle gracefully.** Standby Transitions carry the boot chrome into the idle Canvas; Truth #3 shared Brick ids preserve continuity. The user doesn't see a blank moment between boot and idle.
+- **Boot is fault-tolerant.** If a Generator fails, if a Data source is unreachable, if a peripheral hasn't initialised — boot completes anyway, with the failure surfaced in the affected component (a sensor that hasn't reported reads as "—", not as a frozen screen).
+- **Boot is what a watchdog reset returns to.** A reset is a fresh boot; design boot so the operator and any in-progress user can recover gracefully. Persistent state restores last-known-good, not last-current-screen.
+
+**Failure modes:**
+
+- Boot as a loading spinner over a blank background — every reset reads as "this is broken."
+- Boot Canvas different from idle Canvas — the user sees the brand appear, then a layout shift to idle; instability tell.
+- Boot that requires network / Generator success — offline boot fails; deployment goes dark.
+- Boot that doesn't acknowledge watchdog reset — operator or user in-flight is suddenly back at boot with no explanation.
+
+## Loading
+
+**The state when the user has acted (or the system has triggered) and a response is pending.**
+
+This is step 4 of the user journey (in-flight visibility, see [`user-journey.md`](user-journey.md)). Loading is a *state visibility* discipline, not a decorative flourish.
+
+**Design discipline:**
+
+- **Loading is not blankness.** A pending response gets a visible state — spinner, progress indicator, animated tile, "processing" badge — that confirms the system is working.
+- **Loading is bounded by time-out.** Every loading state has a failure path. If the response doesn't arrive in N seconds (deployment-relative, typically 10–30 seconds for network operations, 2–5 for peripheral), the state transitions to error recovery (step 6 of the journey).
+- **Loading disables the trigger.** While loading, the affordance that triggered it is `pressable: 'disabled'` or Switch-hidden — user can't re-trigger.
+- **Loading scales with expected wait.** A < 1s wait is a snap-cut visual change; a 1–5s wait is a spinner; a 5s+ wait surfaces progress estimate or "still working".
+- **Skeleton screens** (showing the *shape* of incoming content with a placeholder) work for content that arrives gradually. Less appropriate for transact-flow loading (a fake-result skeleton would mislead).
+
+**Failure modes:**
+
+- Loading visually identical to idle — user doesn't know if they pressed something or not.
+- Loading without a time-out — system hangs; loading state persists forever; user walks away.
+- Loading that allows re-trigger — user impatient, presses again, queues duplicate work.
+- Loading dressed as success — skeleton that looks complete; user assumes the action finished and acts on the placeholder.
+- Loading on a transact flow that reads ambiguous between "still processing" and "approved" — user walks away from a partial transaction.
+
+## Empty
+
+**The state when there's nothing to show — no items in the list, no events today, no notifications, no search results.**
+
+Empty is the most-forgotten state in agent work. Loading gets designed because it follows from acting; empty gets skipped because it follows from *not* acting and the agent thinks "there's nothing to design".
+
+**Design discipline:**
+
+- **Empty explains the absence.** Not "nothing here". Specifically: "No bookings today. New bookings appear here." or "No events scheduled. Check back tomorrow." or "No matches. Try a different spelling."
+- **Empty offers a path forward.** Even on monitoring deployments, empty should suggest what will populate it ("Sensor will report every 30 seconds") or how the user can change the state ("Add an item to begin").
+- **Empty is not error.** A bookings list with no bookings today is a perfectly normal state — design it as content, not as failure.
+- **Empty preserves the layout.** The list area / grid area is still occupied — by an empty-state composition, not by collapsed-away whitespace that resizes the rest of the screen.
+- **Empty is rare on dense deployments and frequent on others.** A retail menu board never has an empty menu (it would close instead). A queue display is empty when there's no queue — which is most of the time.
+
+**Failure modes:**
+
+- Empty rendered as collapsed space — the screen's layout shifts because there's nothing there; users perceive the screen as broken.
+- Empty rendered as "—" everywhere — placeholders never replaced by content; design forgot to handle the populated case (or vice versa).
+- Empty as error — "No results" styled as red and alarming; the user thinks they made a mistake.
+- Empty without explanation — the user can't tell if there's truly nothing or if data hasn't loaded.
+
+## Error
+
+**The state when something went wrong — peripheral disconnected, validation failed, network unavailable, Generator timed out, content feed broken.**
+
+Error is step 6 of the user journey. It is a first-class designed state, not a corner-text afterthought.
+
+**Design discipline:**
+
+- **Error declares the failure.** Specifically. "Card declined." "Couldn't reach the menu. Try again in a moment." "Scanner can't see the code." Not "An error occurred." Not "ERR_TX_REJECTED."
+- **Error explains in user-language.** Technical codes belong in logs, not on the user's screen. If the underlying cause is genuinely useful to surface (network-down state for an interactive kiosk in a corporate setting), translate.
+- **Error offers a path forward.** Retry, alternate method, get help, abandon. Never a dead-end. Even "the system is unavailable, please come back later" is a path (the user knows to leave).
+- **Error preserves user input.** Form input retained; user shouldn't re-type after a single validation fail. Selection state preserved; user shouldn't re-select after a "couldn't connect, try again".
+- **Error distinguishes categories.** *User error* (action didn't succeed, retry sensibly). *System error* (the system has a problem, not the user's fault). *Abandonment* (timeout, idle reset). Each has its own treatment.
+- **Error is calm in tone where possible.** A "card declined" screen designed in shouting red feels accusatory; the user did nothing wrong (the bank declined). Match the tone to what's actually happened.
+
+**Failure modes:**
+
+- Error as a stack of red text — accusatory and unhelpful.
+- Error as a generic toast — disappears before the user reads it.
+- Error with no recovery path — user stuck on an error Canvas with no way forward except staff intervention.
+- Error that erases user progress — single-field validation fail dumps the user back to step 1 of a 7-step flow.
+- Error category collapsed — every kind of failure ("declined" / "network down" / "wrong card type") shown identically; user can't pick the right recovery.
+- Error styled as alarm-grade visual when the failure is mundane — fatigues the user and the operator.
+
+## Maintenance
+
+**The state when the deployment is intentionally taken out of service — software update, content refresh, scheduled downtime, manual operator pause.**
+
+**Design discipline:**
+
+- **Maintenance is a Canvas, not a black screen.** The screen tells the user / operator that the deployment is intentionally offline and when it'll return.
+- **Maintenance distinguishes itself from error.** "We're updating menus — back in 5 minutes" reads differently from "Something went wrong." Different visual tone, different language.
+- **Maintenance has a return path.** Specific return time if known; vague "shortly" if not, with a contact route if relevant.
+- **Maintenance is operator-aware.** A factory-floor monitor in maintenance shows the operator badge / contact / instructions to bring it back online. A passerby-facing deployment shows a friendly message; the operator interface for resuming is gated by some access (Settings, password, key combo).
+
+**Failure modes:**
+
+- Maintenance = black screen — user thinks the device is broken.
+- Maintenance = the most-recent error state — implies failure, not intentional pause.
+- Maintenance without a return signal — operator forgets the deployment is paused; users walk away assuming the venue is closed.
+- Maintenance accessible to passerby — anyone can put the kiosk into maintenance and walk away.
+
+## When to design each state
+
+Different deployments live in different states most of the time.
+
+- **Signage / glance**: idle (= the running state), boot, occasional maintenance. Loading / empty / error rare; design lightly. Attractor sometimes a separate state for higher-energy deployments.
+- **Self-service kiosk / interact / transact**: idle, attractor (often = idle), boot, loading (per step), error (per failure category), occasional empty, maintenance. **All states must be designed**; this is the highest-flow-state-count category.
+- **Dashboard / monitor**: calm (= the running state, see [`monitoring-screens.md`](monitoring-screens.md)), stale-data variant, demand / alarm states, occasional empty (no data yet), error if feed is dead, maintenance.
+- **Dwell / ambient**: looping content (= idle), boot. Error / empty rare; treat lightly.
+
+Design the states that will actually be visited. Skipping a state because it's "rare" is correct *only if* you can confirm it actually is rare in this deployment.
+
+## How to use this file
+
+1. **List which states this deployment will visit.** Not all states apply to every deployment.
+2. **For each, design the four answers** — who arrives, what they see, what they need to know, how they leave.
+3. **Verify the state's existence in preview.** Force-trigger each state via Automation or by editing Data values; capture a screenshot; view it back. A state you haven't seen is a state you haven't designed.
+4. **Surface every gap in the trade-off note.** If a state is in-scope but unverified for some reason (peripheral simulation not available, error mode hard to trigger), say so explicitly. The user reading the handoff should know which states have been actually tested in design.
+
+A flow declared done where only the golden path has been screenshot-verified is a flow with undesigned states. The next user will find them.

package/skills/bricks-ux/references/interaction-archetypes.md

@@ -0,0 +1,189 @@
+# Interaction Archetypes
+
+The user in front of a BRICKS screen is doing one of six things. The archetype determines Subspace shape — Canvas count, dominant Brick families, motion vocabulary, what carries forward across the flow — and which UX disciplines weight strongest.
+
+Pick the archetype first, then commit. Archetypes don't blend gracefully; a "glanceable + interact" hybrid is a sign that you need two Subspaces or one designed-as-archetype-X Subspace with a clearly bounded archetype-Y moment.
+
+## Glance
+
+**What the user does:** reads the screen in 1–2 seconds while passing. No interaction. No commitment. Often peripheral vision.
+
+**Where it lives:** lobby signage, transit platform info, queue-number displays, menu boards, ambient information screens, attractor loops between active sessions.
+
+**Rule set:**
+
+- Type at the *legibility floor for viewing distance* — calibrate to the deployment, not to instinct. A 75" panel viewed from 4m needs body text at ≥ 4 grid units (with appropriate hardware); a 32" panel at 1m can read smaller.
+- One primary idea per Canvas. Two competing headlines = neither lands.
+- Refresh cadence calm — content rotates on a slow rhythm (8–15 seconds per item). Anything faster crosses into demand-attention territory.
+- Hero continuity (Truth #3) — even glanceable signage benefits from a persistent element (logo, time, brand chrome) so the viewer's eye knows where they are returning to.
+- No affordance for interaction the hardware can't deliver. No hover, no implied "tap for more" on a no-touch panel.
+
+**Carries forward:** nothing. Each glance is self-sufficient.
+
+**Failure modes:**
+
+- Two-line headline at the edge of legibility — viewer can't read in 1.5 seconds, looks away.
+- Slideshow rotates faster than read time — viewer catches "Item 4 of 12" but never the title.
+- Content-dense layout imported from web — five sections fighting for the eye.
+- Affordance signals (chevrons, button-styled tiles, "click here" copy) where the hardware can't deliver.
+
+**Critical UX dimensions:** visual hierarchy, legibility floor, dwell-pacing.
+**Negligible UX dimensions:** in-flight visibility, error recovery, closure (the user doesn't act).
+
+## Browse
+
+**What the user does:** scans options without commitment. Reads multiple things looking for what's relevant. Looks at, doesn't necessarily decide.
+
+**Where it lives:** menu boards with multiple categories, schedule boards, room-availability displays, retail-shelf overhead screens, museum exhibit info.
+
+**Rule set:**
+
+- Layout supports comparison. Adjacent items should be visually parallel (same Brick shape, same scale) so the eye can shift between them.
+- One axis of variation per dimension — sort by category OR by time OR by price, not all three simultaneously without UI separation.
+- If the deployment is touch-capable, browse can promote to interact: tiles with deliberate pressable affordance (see [`pressable-composition.md`](pressable-composition.md)). On no-touch, browse stays pure read.
+- Carry forward minimal — if the user wanders away and comes back, the screen should be in the same readable state (no half-completed selection clogging the view).
+- Dwell time is real — viewer may stand there 5–20 seconds. Plan for it. Content should *reward* dwell with subtle motion (Standby on Brick lists, gentle highlights) without crossing into demand attention.
+
+**Carries forward:** sometimes selection state if browse promotes to interact; otherwise nothing.
+
+**Failure modes:**
+
+- Items styled too differently — eye can't compare, fragments instead of scans.
+- Excessive depth — a browse screen that requires drilling reads as interact, not browse.
+- Auto-rotation while user is browsing — content shifts mid-read, viewer loses place.
+- Empty browse state (no items today, gallery closed) treated as forgotten case — see [`flow-states.md`](flow-states.md).
+
+**Critical UX dimensions:** visual hierarchy, comparison legibility, empty/sparse state design.
+**Negligible UX dimensions:** transact discipline, alarm hierarchy.
+
+## Interact
+
+**What the user does:** drives a flow. Taps to choose, navigates between Canvases, completes a non-financial task — order something, request information, configure a setting, sign in to a non-payment portal.
+
+**Where it lives:** self-service ordering, ticket selection, info-kiosk requests, queue ticket dispensers, event check-in, configuration interfaces, language pickers.
+
+**Rule set:**
+
+- Every action gets the full 7-step journey (see [`user-journey.md`](user-journey.md)). Skipping any step is a UX failure.
+- Hero Bricks carry continuity across the flow Canvases (Truth #3). The brand chrome / progress indicator / step number should never disappear mid-flow.
+- Pressable affordance is unambiguous (see [`pressable-composition.md`](pressable-composition.md)). Tiles that look like tiles, taps that visibly land.
+- Idle reset — interact deployments are often left mid-flow. The Subspace must have an idle timeout that returns to attractor / boot state without preserving the abandoned session for the next user (unless explicitly designed for resumption).
+- Position memory — the user should be able to back out one step without losing the whole flow. Switch on a `flowStep` Data with persistent intermediate states.
+- Reduce decision pressure — short on-Canvas option lists (≤ 5 primary choices on one Canvas); promote to multi-Canvas if more.
+
+**Carries forward:** flow state (selection, configuration, pending submission) across Canvases until completion or reset.
+
+**Failure modes:**
+
+- 12-option grid that needs scrolling on Canvas 1 — overload, no scroll on BRICKS (Truth #10).
+- Continuation Canvas changes the location of the back action — user can't return.
+- Mid-flow content overload — every Canvas tries to summarise everything before, instead of advancing.
+- Idle timeout missing — next user inherits previous user's half-built order.
+- Recovery for no-input dead-ends absent — user walks away without completing; no abandonment cleanup.
+
+**Critical UX dimensions:** journey completeness (all 7 steps), affordance clarity, idle reset, position memory.
+**Negligible UX dimensions:** alarm hierarchy, monitoring discipline.
+
+## Transact
+
+**What the user does:** completes an action with stakes — payment, identity capture, signed agreement, regulated action. The cost of error is real (financial, legal, safety).
+
+**Where it lives:** payment terminals, self-checkout, identity verification, age check, regulated-document signing, controlled-access entry.
+
+**Rule set:**
+
+- The 7-step journey *tightens* (see `user-journey.md` § "When the seven steps intensify"). Confirmation before commit. In-flight visibility cannot be skipped. Recovery has explicit categories. Closure declares completion.
+- The *point-of-no-return moment* must be visually distinct from everything before and after. The user knows when they've committed.
+- Peripherals dominate — payment terminal, NFC reader, camera for ID. Each peripheral's state must be visible to the user. Generator events drive Switch transitions; never guess at peripheral state.
+- Audio cues if hardware allows — financial transactions benefit from non-visual confirmation (the user is often looking at the terminal, not the screen, mid-tap).
+- Path 2 verification (on-device DevTools) is mandatory for these deployments; the design must be tested on the real hardware with the real peripherals before declaring done.
+- No idle timeout *during* an active transact step — the system waits for the user, not the other way around. Idle timeout only between sessions.
+- Receipt / artifact handoff is part of the design — the closure Canvas waits for the printer event or the email-sent confirmation before declaring done.
+
+**Carries forward:** transaction state through to closure; nothing after.
+
+**Failure modes:**
+
+- Confirmation step skipped — user commits without realising.
+- In-flight state ≤ 200ms — the user double-taps because they don't see acknowledgement; second tap queues a duplicate.
+- Generic error recovery — "Try again" doesn't distinguish card-declined (try a different card) from network-down (wait and try) from user-cancelled (start over).
+- Closure transient — success Canvas auto-advances to idle in 1.5 seconds; user mid-blink, never saw confirmation; calls customer service.
+- Peripheral assumed instead of observed — design assumes card-tap is instant; in production the reader takes 2–3 seconds; users walk away thinking it failed.
+
+**Critical UX dimensions:** journey intensification, point-of-no-return clarity, in-flight visibility, recovery categories, closure weight, peripheral state visibility.
+**Negligible UX dimensions:** ambient pacing, dwell rhythm.
+
+## Monitor
+
+**What the user does:** watches changing state. Often peripheral attention — the screen is a stand-by surface that becomes the centre of attention when something changes. Not always actively read; trusted by reference.
+
+**Where it lives:** control rooms, factory floor monitors, network operations dashboards, security camera grids, transport-control screens, sensor-driven status boards, hospital nurse stations, AI-assistant monitoring panels.
+
+**Rule set:**
+
+- Calm-state default. The screen at rest should be readable and forgettable — operator can scan, look away, return.
+- Change must be detectable without being demanding — a subtle motion / colour shift / hierarchy promotion that draws the eye but doesn't startle. Demand attention is reserved for true alarms.
+- Stale-data trust principle — if the operator can't tell what's current, they will trust what they see. Stale state must be visibly declared.
+- Alarm hierarchy under stress — multiple simultaneous alarms must already have priority order designed. The screen sorts; the operator doesn't.
+- Show vs ask — a monitor screen often only *shows* state, leaving action to operator judgement; sometimes it *suggests* action (highlighted protocol button). Decide which it is; not both.
+- Full coverage in [`monitoring-screens.md`](monitoring-screens.md).
+
+**Carries forward:** operator's mental model of "what was last normal" — design with this in mind, since change-from-baseline is the operator's real read.
+
+**Failure modes:**
+
+- Every data field updates identically — operator can't distinguish meaningful change from background fluctuation.
+- Alarms styled the same regardless of severity — minor warning indistinguishable from critical alert.
+- Stale-data badge in 8pt corner type — operator never sees it.
+- Color-only encoding (red for alarm, green for normal) — fails for colour-blind operators and in low-contrast environments.
+- Loading state designed, empty state forgotten — fresh deployment shows "—" everywhere with no explanation.
+
+**Critical UX dimensions:** calm/detect/demand hierarchy, stale-data trust, alarm priority, accessibility (operators may be on shift, fatigued, in suboptimal viewing conditions).
+**Negligible UX dimensions:** dwell pacing, single-action affordance discipline.
+
+## Dwell
+
+**What the user does:** inhabits the space. The screen is ambient — wallpaper for a hospitality lobby, a hotel-room TV channel, a restaurant ambient display, a museum atmospheric backdrop, a brand-experience wall.
+
+**Where it lives:** hotel and hospitality lobbies, restaurant ambiences, retail mood walls, brand-experience installations, event backdrops, spas, premium reception areas.
+
+**Rule set:**
+
+- Content rotates slowly — 15–60 seconds per item depending on register. Field.io-style motion poetics can run continuous loops; Kenya Hara photographs hold longer.
+- No interaction. No affordance. The screen does not invite touching.
+- Visual quality at maximum — assets must score high on the 5-10-2-8 craft bar (see `bricks-design/when-the-brief-is-branded.md`); poor assets in a dwell context degrade the surrounding brand more than they would in a glanceable signage context.
+- Motion has continuity — Truth #3 hero auto-tween across Canvases keeps the dwell experience reading as one piece rather than a slide rotation.
+- Day-night awareness if relevant — dwell deployments often run 24-hour; design adapts to ambient luminance, time-of-day, scheduled content.
+- Sound (if hardware allows) is part of the design — ambient music selection, volume scheduling, silence as deliberate.
+
+**Carries forward:** nothing per-user; only the slow rhythm of the loop itself.
+
+**Failure modes:**
+
+- Looped motion at the wrong speed — too slow reads as broken, too fast reads as nervous. Calibrate.
+- Content variation insufficient — the same three Canvases looping every 30 seconds for 14 hours reads as broken signage.
+- Day-night neglected — dwell loop blasting bright content into a darkened lounge at 11pm.
+- Decorative motion competing with the brand chrome — the dwell loop should feel of-a-piece with the venue, not be a separate visual register.
+
+**Critical UX dimensions:** asset quality, motion continuity, content variation, ambient-luminance awareness.
+**Negligible UX dimensions:** affordance, journey completeness, alarm hierarchy.
+
+## Hybrid and transitions
+
+Real briefs sometimes span archetypes:
+
+- **Glance → Interact**: signage that becomes interactive when a user approaches (BLE proximity, camera detection). Treat as a Subspace state machine — glanceable Canvas as default, transition into interact Subspace on approach event. Don't try to make one Canvas serve both; the design discipline differs.
+- **Browse → Transact**: retail menu that promotes to ordering. Same — boundary Canvas with explicit "I want to order" affordance.
+- **Monitor → Interact**: dashboard with an action button (acknowledge alarm, dispatch protocol). The action follows the full 7-step journey; the monitor part follows monitoring discipline.
+- **Dwell → Glance**: ambient screen that occasionally surfaces information (welcome message for VIP, time-sensitive promotion). Add a glance Canvas as a temporary state, return to dwell after.
+
+In every case, the transition itself is a designed moment, not an accident.
+
+## How to use this file
+
+1. **Pick the archetype** as part of Priority #0 — what is the user doing in front of the screen?
+2. **Apply the rule set** as the design's starting constraints.
+3. **Check the failure modes** before declaring the design done — most are specific to the archetype.
+4. **Note the UX dimension weights** — let critique focus where it matters for the chosen archetype.
+
+If you find yourself wanting to follow rules from a different archetype, the brief may actually be that archetype. Pick again.

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.