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

package/skills/bricks-design/references/when-the-brief-is-branded.md

@@ -0,0 +1,284 @@
+# When the Brief is Branded — Media Flow Protocol
+
+Brand fidelity is *the* differentiator on branded scene work. Every branded BRICKS deployment that "looks generic" got there by skipping the asset hunt and going straight to colors-and-fonts. Most agent-produced branded work fails at the same stop: the agent describes assets it should have, then proceeds to design without acquiring them.
+
+This file is operational, not aspirational. It tells the agent **what to actually do**, with concrete recipes, a quality bar with named dimensions, structural enforcement that prevents redraw shortcuts, and a sanctioned path for *creating* assets when none exist — by composing the host environment's image / motion generators, not by drawing in Sketch.
+
+In BRICKS, brand binaries live in **Media Flow** and are referenced from Subspaces by Data of `kind: { type: 'media-resource-image' | 'media-resource-video' | 'media-resource-audio' | 'media-resource-file' | 'lottie-file-uri' | 'rive-file-uri' | 'binary-asset' }`. **Never embed brand binaries inline in Brick props.** The Application config travels light; binaries refresh on a different cadence; reuse demands an indirection.
+
+**Media Flow is offline-safe by design.** Assets bound this way are preloaded to the device with hash-verified integrity and served from local storage thereafter. Image, video, Lottie, Rive, brand reels — none of these are "offline risk" categories when bound correctly. Do not water down a branded design with text-only fallbacks because the deployment is offline; richness through Media Flow is precisely how the runtime supports offline-first scenes. (See [`performance.md`](performance.md#media-in-media-flow-is-local-first--imagevideolottierive-does-not-break-offline) for the full mechanism.)
+
+## Asset categories — first-class vs. auxiliary
+
+The single most common branded-work failure: agent collects colors and fonts, calls it a brand spec, and ships generic-looking output. Brand identity is *recognized*, not *measured* — and recognition runs on:
+
+| Asset type | Recognition contribution | Required when |
+|---|---|---|
+| **Logo** (vector, light + dark + mono) | Highest — any scene with a logo is instantly identifiable | Always, for any branded work |
+| **Product photography** (real renders, multiple crops) | Very high — physical products are recognized by themselves | Physical-product brands (hardware, consumer goods, hospitality, retail) |
+| **UI screenshots** (real captures, current version) | Very high — digital products are recognized by their interface | App / SaaS / dashboard / portal brands |
+| **Scene / lifestyle photography** (brand-shot, real venues) | High — sets the brand's environmental temperature | Hospitality / retail / experiential / real-estate brands |
+| **Motion assets** (brand video, Lottie, Rive) | High — BRICKS canvases are time-based; brand motion is first-class | Any brand with extant motion identity (launch films, brand reels, animated logos) |
+| **Color palette** | Medium — supporting role; orphans without the above | All work |
+| **Typography** | Medium — supporting role; same caveat | All work |
+| **Voice & tone** | High where used (constraint on visible Data) | Where copy is non-trivial |
+
+**Rule that follows:** acquiring colors and fonts only — without logo / product / UI / motion — is **not** a brand spec. It is a partial spec at best. Surface the missing categories as gaps before you start designing.
+
+## The acquisition flow — five steps, each with concrete actions
+
+### Step 1 — Ask, with a full checklist
+
+Don't ask "do you have brand guidelines?". That gets a yes from people who only have a logo and a hex code, and the gap stays invisible until you're already designing. Ask explicitly, in one batch:
+
+```
+For <brand>, do you have any of these? (priority order)
+  1. Logo — vector source (SVG / AI / PDF) or high-res PNG. Light + dark + mono variants ideal.
+  2. Product photography (physical brands) — official renders or real photos, multiple crops.
+  3. UI screenshots (digital brands) — current-version captures of key screens.
+  4. Scene / lifestyle photography (hospitality / retail / experiential).
+  5. Motion assets — brand films, animated logos, Lottie / Rive files.
+  6. Brand colors — palette + usage rules.
+  7. Brand fonts — files licensed for embedded display, or named alternatives.
+  8. Brand book / design system / voice guide.
+
+Send what you have; I'll source the rest from official channels and tell you what's missing.
+```
+
+### Step 2 — Search official channels first
+
+Before any aggregator:
+
+| Asset | Primary channels |
+|---|---|
+| Logo | `<brand>.com/brand`, `<brand>.com/press`, `<brand>.com/press-kit`, `brand.<brand>.com`, the live site's header inline-`<svg>` |
+| Product photos | `<brand>.com/<product>` hero + gallery, official launch films (capture frames), official press releases |
+| UI screenshots | App Store / Play Store product page captures, the live site's screenshots section, official demo videos (capture frames) |
+| Scene / lifestyle | Brand campaign archive on the live site, brand's official social media accounts |
+| Motion | Brand's official YouTube channel, brand's launch microsites, the brand's own design-system Lottie library |
+| Colors | Brand book PDF, brand design-system repo, the live site's CSS variables / Tailwind config |
+| Fonts | The live site's `<link rel="stylesheet">` references, Google Fonts trace, brand book |
+
+**`WebSearch` fallback queries** when official is dry:
+- `<brand> logo download SVG`, `<brand> press kit`
+- `<brand> <product> official renders`, `<brand> product photography hi-res`
+- `<brand> app screenshots`, `<brand> dashboard UI`
+- `<brand> launch film`, `<brand> brand reel`
+
+Aggregators (Brandfetch, Logo.dev, etc.) are placeholders, not sources of truth. When you use one, label it as such in the spec and continue searching for the official source in parallel.
+
+### Step 3 — Acquire, with three fallback paths per category
+
+Each category has a fallback ladder by yield. Walk down the ladder; don't stop on the first hit.
+
+#### Logo — never approximate
+
+1. Independent SVG / PNG file from the brand's press kit.
+2. Inline `<svg>` extracted from the official site's HTML (`curl -A "Mozilla/5.0" -L <url>` then locate the logo node).
+3. Official social-media avatar (typically 400×400 or 800×800, transparent PNG) — last resort.
+
+If all three fail: **stop and ask the user**. A logo is not optional; it's the recognition root. Do not draw a Sketch-Brick imitation. Do not generate a "logo-shaped" thing with AI. Either acquire a real logo or escalate the gap.
+
+#### Product photography (physical brands)
+
+1. Official product page hero image — usually 2000 px+; fetch directly.
+2. Official press kit / brand center — often the highest resolution available.
+3. Official launch video frame-grab — for products with strong launch content. Use the host's video tools or extract via `yt-dlp` + `ffmpeg` if available.
+4. Wikimedia Commons — public-domain or freely licensed for some products.
+5. **AI generation, brand-anchored** — see [§ Creating assets when missing](#creating-assets-when-missing). Allowed only as a last resort and only with the discipline below.
+
+#### UI screenshots (digital brands)
+
+1. App Store / Play Store product captures (verify they're real screenshots, not mockup-generator output).
+2. The live site's screenshots section.
+3. Demo-video frame-grabs.
+4. The brand's own social posts at recent product launches (often the freshest captures).
+5. The user's own account, captured live. Most accurate when the user has access.
+
+#### Scene / lifestyle photography
+
+1. Brand campaign archive on official channels.
+2. Authorized licensed library (Getty / brand-specific contracted libraries) where the user has access.
+3. AI generation with reference anchoring — last resort.
+
+#### Motion assets
+
+1. Brand's official channel (YouTube, Vimeo) — download with permission, frame-grab where embedding the full clip is overkill.
+2. Lottie / Rive files in the brand's design-system repo, where they exist.
+3. AI motion generation with reference anchoring — last resort, very high failure rate, expect to discard 9 of 10 candidates.
+
+#### Colors and fonts (auxiliary)
+
+- Colors: brand book → live-site CSS → sampling from official imagery (last resort, document the sample point).
+- Fonts: brand-issued license + files → documented alternative if the license isn't available → closest licensed family with a note.
+
+### Step 4 — Score every asset against the 5-10-2-8 bar
+
+The bar exists because cosmetic-quality drift is invisible until shipped, then obvious. Without it, the agent rates every found asset 8/10 and the floor sinks.
+
+**Quantity bar:** search **5** rounds across multiple channels; collect at least **10** candidates per non-logo category before filtering; keep **2** winners; each scoring **≥ 8/10**.
+
+**Quality dimensions** — for each candidate, score 0–10 on each, take the average. Below 8 → discard or use as a labeled placeholder. Logo is exempt from this filter (any real logo beats no logo).
+
+| Dimension | What 8+ looks like | What's a deduction |
+|---|---|---|
+| **Resolution** | ≥ 2× the largest render size; for signage / 4K / print ≥ 3000 px on the long edge | Pixelation visible at target render scale; aliasing on transparent edges |
+| **Provenance** | Official source, dated, license-clear; press-kit asset > brand-controlled aggregator > public-domain repository | Aggregator-only, undated, or third-party-redistributed; suspected scraped copy |
+| **Brand fit** | Matches the spec's vibe keywords; matches campaign era you're working from | Off-era (2018 logo for a 2024 rebrand); wrong product variant; sub-brand bleed |
+| **Composition / craft** | Lighting, framing, background all consistent with the rest of the asset set | Mixed lighting across "set"; orphan background colors; visible artifacts |
+| **Narrative weight** | Carries one story alone; can be a hero on its own merits | Only works as decoration / filler; needs surrounding chrome to read |
+
+**Logging the scores** in `brand-spec.md` (per category) is what makes the bar real. If you didn't log a score, you didn't apply the bar.
+
+### Step 5 — Bind into Media Flow + persist `brand-spec.md`
+
+Upload acquired assets into a Media Flow workspace (use the host's Media Flow MCP tools where available — `list_media_workspaces`, `get_media_workspace`, `media_box_upload`, `update_media_file_meta`). Reference each from the Subspace via Data with the appropriate `kind`:
+
+- Image → `kind: { type: 'media-resource-image', preload: { type: 'url', hashType, hash } }`
+- Video → `media-resource-video`
+- Audio → `media-resource-audio`
+- Lottie → `lottie-file-uri`
+- Rive → `rive-file-uri`
+- General binary → `media-resource-file` or `binary-asset`
+
+Bricks bind via DataLink: `Image.property.source = linkData(() => brandLogoData)`. Refreshing an asset is a Media Flow operation; the Subspace doesn't need to know the URL changed.
+
+Fonts: declare each as an `ApplicationFont` entry in `Application.applicationSettings.fonts` (`name`, `url`, optional `md5`). Reference by name in Brick `property.fontFamily`.
+
+`brand-spec.md` lives next to the Subspace. Use this template verbatim — every section is required, even the gap section:
+
+```markdown
+# Brand spec — <brand name>
+> Captured: <YYYY-MM-DD>
+> Sources: <list>
+> Coverage: <complete / partial / inferred>
+
+## First-class assets
+
+### Logo
+- Primary (dark ground): <Media Flow ID> → Data: brandLogoDark
+- Primary (light ground): <Media Flow ID> → Data: brandLogoLight
+- Mono / reverse: <Media Flow ID> → Data: brandLogoMono
+- Clearspace: <e.g., 1× cap-height>
+- Minimum size: <e.g., 96 px wide>
+- Source: <press-kit URL / inline-svg from <url> / file from user>
+
+### Product photography (if physical brand)
+- Hero front: <Media Flow ID> → Data: productHero  (3000×2000, transparent)  [score: R9 P9 B8 C9 N9]
+- Detail crop A: ... [score: ...]
+- Scene context: ... [score: ...]
+
+### UI screenshots (if digital brand)
+- Home: ... [score: ...]
+- Core feature A: ... [score: ...]
+
+### Scene / lifestyle (if relevant)
+- ...
+
+### Motion
+- Brand reel clip: <Media Flow ID> → Data: brandReel  (1920×1080, 12s, h264)
+- Animated logo: <Media Flow ID> → Data: brandLogoLottie
+
+## Auxiliary
+
+### Colors (theme tokens — exposed as Data when shared)
+- --brand-primary    #XXXXXX   OKLCH(...)   source: <where>
+- --brand-accent     #XXXXXX
+- --brand-neutral-100 / -900
+- Forbidden: <colors the brand explicitly does not use>
+
+### Fonts (ApplicationFont entries)
+- Display: <family / weights / file location / license>
+- Body:    <family / weights / file location / license>
+
+### Voice & tone
+- Register: <e.g., confident, terse, never effusive>
+- Capitalization: <e.g., sentence case>
+- Banned phrases: <e.g., "innovative", "revolutionary", "AI-powered">
+
+### Signature details
+- <One or two design moves the brand is known for — a specific corner radius, a hairline rule, a particular typographic treatment.>
+
+## Gaps & placeholders
+- <category>: <why missing> → <action: ask user / AI generate / accept placeholder> [as of <date>]
+
+## Score log (for non-logo assets)
+- <asset>: R<n> P<n> B<n> C<n> N<n> = <avg>/10
+```
+
+## Structural enforcement — assets are referenced, not redrawn
+
+Once `brand-spec.md` exists, the discipline that keeps the design honest is structural, not behavioural. Encode it in the build:
+
+- **Every brand visual** is a Brick reading from a Media Flow Data via DataLink. No `Image.property.source` set to a literal URL or path. No `Sketch` Brick drawing a "logo-shaped" graphic. No `Svg` Brick reproducing the logo as a path. The pattern enforces "you cannot ship a redrawn logo because the project structure doesn't allow it."
+- **Brand colors used in 2+ places** become theme-token Data, bound via DataLink. Single-use decorative colors can stay hardcoded (Truth #2's loose convention).
+- **Theme tokens are the single source of truth.** Want to add a new color? Add a Data entry first, then bind. The "first" is what makes it a system instead of an accumulation.
+- **Every Brick that uses a brand asset** has its source traceable to a `brand-spec.md` line. Reviewing the spec is reviewing the design.
+
+## Creating assets when missing
+
+When a category has no acquirable real asset and the user has no plan to provide one, **do not** quietly substitute a placeholder and proceed. Three options, in priority order:
+
+1. **Stop and ask.** For logo, this is the only allowed option.
+2. **Compose the host environment's generative tools.** If a canvas-design / imagen / image-generation MCP / motion-generation MCP / Banana-style tool is available in the host, use it — *anchored on a verified brand reference*. This skill does not duplicate them; it composes them.
+3. **Accept a labeled placeholder Brick** with the gap tracked in `brand-spec.md`. Use this when generation is unavailable or known to fail for the asset type (e.g., generating a "real product photo" for a niche industrial product almost always fails).
+
+### Generative discipline (when option 2)
+
+- **Anchor on real brand material.** Feed at least one verified brand asset — the logo, a verified product photo, a brand color sample — as conditioning to the generator. Generation from "the brand's general vibe" produces uncanny-valley assets that feel adjacent to the brand without being the brand. Almost always recognized as fake by reviewers.
+- **Generate at the 5-10-2-8 quantity bar.** 8–10 candidates per slot, scored on the same 5 dimensions, keep 2.
+- **Persist generation metadata** in `brand-spec.md`: prompt, seed (where supported), reference assets used, model version. Reproducibility matters when the user later asks for a refresh in the same style.
+- **Never generate logos, wordmarks, or named characters.** These are identity, not imagery — generation produces look-alikes that legal will reject.
+- **Avoid AI-design tells.** Gradient orbs as "AI". Glassy translucent panels with no source. Generic happy-diverse-people-in-a-bright-office. Tech-y blue-purple gradients as backgrounds. Float / hover dot patterns. Watch for these in generated output and re-generate or discard.
+- **Motion generation is high-failure.** For Lottie / Rive / video, expect to discard 9 of 10 outputs. Budget the iteration; don't ship the first plausible result.
+
+### What "compose, don't rebuild" looks like in practice
+
+- This skill does **not** teach typography pairing, color theory, image composition, or generative prompting from scratch. Those domains are deep and other skills cover them well.
+- This skill **does** insist that when the host has a canvas-design / imagen / image-generation skill available, the agent invoke it for the relevant sub-task — generation, motion, composition — rather than substitute its own freehand work or skip with a placeholder.
+- Where the host has none, surface that constraint to the user. "There's no image generator available in this environment; we have three options: (a) you supply, (b) we accept labeled placeholders, (c) you bring a generator skill / MCP into the environment." Don't silently degrade.
+
+## Anti-patterns — recurring failures
+
+- **Colors-and-fonts-only branding.** Visual identity lives in photography and logo treatment, not hex codes. If logo + product/scene aren't acquirable, surface it as a blocker before continuing.
+- **Aggregator-as-source-of-truth.** Brandfetch is a placeholder; not a final source.
+- **Eyeballing a hero color from a competitor's site or a stylistic neighbour.** Leaks the wrong brand into the work; reviewers catch it immediately.
+- **CSS-drawn imitations of real assets.** A gradient orb is not a logo. A Sketch path is not a product photo. Source or generate-with-anchor or labeled-placeholder. There is no fourth option.
+- **Embedding base64 in Brick props.** Pollutes the Subspace, defeats Media Flow refresh, balloons the file. Lift to Media Flow.
+- **Generating without a brand-reference anchor.** Produces uncanny-valley assets adjacent to the brand. Always anchor.
+- **Demo-content color contamination.** A Stripe-style hero from an aggregator site that has a third-party brand's accent color baked in. Either request a clean asset or note the contamination in the spec.
+- **Skipping the score log.** Without it, the bar is aspirational. Log scores per non-logo asset; commit the log alongside the spec.
+
+## When the brand has nothing
+
+Some BRICKS deployments are for venues with no prior brand work — small clinics, community lobbies, one-off pop-ups. In that case:
+
+- Skip the protocol; admit the gap up front.
+- Switch into Direction Advisor mode ([`when-the-brief-is-vague.md`](when-the-brief-is-vague.md)) and propose 3 differentiated visual directions.
+- The picked direction *becomes* the brand spec for this Application. Persist the picked direction's tokens, motion language, photography style guidelines, and (if any) generated assets via the same `brand-spec.md` template — even when invented from scratch. Treat it as a real spec, not a working note. The next person to touch the deployment will need it.
+
+## Voice & tone as a constraint on user-visible Data
+
+Voice and tone don't live in Bricks; they live in the strings inside Data values. The brand spec's voice section becomes a **content-author constraint**:
+
+- All user-visible Data values follow the register (sentence case, no exclamation marks, banned phrases avoided, length budget respected).
+- Translations follow the register in their target language — work with a localizer who understands the voice.
+- Generator-produced strings (LLM responses, formatted dates, error messages) need explicit prompts or templates that respect the voice. Do not trust default LLM phrasing; constrain it.
+
+Surface this to whoever maintains content post-deploy so it doesn't quietly drift.
+
+## Coverage checklist before declaring asset work complete
+
+You cannot move from this protocol back into design until all of the following are true:
+
+1. Logo — present in Media Flow with light + dark + mono where applicable; bound via Data.
+2. Product / UI / scene category appropriate to the brand type — present, scored ≥ 8/10 on each kept asset, bound via Data.
+3. Motion category — present where the brand has motion identity; absent and noted otherwise.
+4. Colors — palette declared as theme-token Data (for shared colors) and / or as `brand-spec.md` entries.
+5. Fonts — declared as `ApplicationFont` entries; license confirmed.
+6. Voice & tone — captured as constraint or marked TBD with stakeholder + date.
+7. Gaps — every missing or placeholder asset listed under "Gaps & placeholders" with action and date.
+8. Score log — every non-logo asset scored on the 5 dimensions and logged.
+9. Spec committed — `brand-spec.md` exists alongside the Subspace; not in a chat scrollback or a working file that will be lost.
+
+If any item is incomplete, name it in your reply and either resolve it or pause for user input. Don't proceed silently.

package/skills/bricks-design/references/when-the-brief-is-vague.md

@@ -0,0 +1,85 @@
+# When the Brief is Vague — Direction Advisor
+
+If the brief is too open to execute ("design me a signage app", "make something for the lobby", "I don't know what kind of kiosk I want"), do not improvise on generic intuition. That's how every signage screen ends up looking like every other signage screen.
+
+Switch into **Direction Advisor** mode. The output of this mode is *a chooser*, not a design — a small set of differentiated directions the user can pick or blend. Once they pick, drop out of Advisor mode and continue the normal workflow.
+
+## What "differentiated" means
+
+Pick directions that disagree on a real axis. Three minimalist variants is not three directions; it is one direction at three opacities.
+
+The strongest axis is **interaction archetype** — what the user *does* in front of the screen. Six archetypes:
+
+| Archetype | The user... | Dominant Brick(s) | Generator load | Canvas count |
+|---|---|---|---|---|
+| Glance | reads in 1–2 seconds while passing | Slideshow, RichText, Video | Light — content fetch only | 1 |
+| Browse | scans options without commitment | Items, Slideshow, Maps | Light to medium | 1–3 |
+| Interact | drives a flow, taps to choose | Items, BrickRect tiles, TextInput | Light | 2–5 |
+| Transact | completes a task with stakes (payment, identity) | TextInput, BrickRect, Camera, payment | Heavy — peripheral generators | 4–8 |
+| Monitor | watches changing state | Chart, Items bound to live Data | Heavy — MQTT/HTTP/MCP | 1–2 |
+| Dwell | inhabits the space; the screen is ambient | Video, Slideshow, Lottie | Light — looped media | 1 |
+
+Full rule sets per archetype (what carries forward, failure modes, which UX disciplines weight strongest) live in the companion skill — see `bricks-ux/references/interaction-archetypes.md`. Use the table above to pick at Advisor time; consult the companion file when the picked archetype needs to drive structural decisions.
+
+For most vague briefs you can spread three options across this set — e.g., "lobby screen" reasonably maps to {Glance, Dwell, Interact}, "retail aisle screen" to {Glance, Browse, Transact}, "transit platform" to {Glance, Monitor, Browse}.
+
+You can also differentiate on:
+- **Visual system** — Editorial / Cinematic / Brutalist / Soft minimalist / Maximalist. Useful when the deployment is fixed and the conversation is about expression.
+- **Brick set** — what the design is *built from* (image-led / type-led / map-led / video-led / chart-led).
+- **Motion language** — calm vs. cinematic vs. snappy.
+
+But interaction archetype is the most useful starting axis because it changes the entire shape of the Subspace, not just its skin.
+
+## What to deliver in Advisor mode
+
+A direction is the combination of three choices — two axes the user perceives, and one structural decision that flows from them:
+
+- **Interaction archetype** (above) — *what the user does*. Drives Subspace structure.
+- **Visual language** — *what the design says*. Drives expression: type, color, motion, signature moves, asset emphasis. Pick from the curated library in [`design-languages.md`](design-languages.md) (Swiss Editorial / Kenya Hara emptiness / Field.io motion poetics / Brutalist web / Y2K futurist-retro / etc.) or invent one rooted in the same discipline.
+- **Canvas-graph shape** — when the brief reads as a presentation / pitch deck / introduction / explainer / slideshow / storyboard / demo / training-loop / kiosk-welcome, the choice between **Shape A** (Slideshow Generator — uniform layout, content-driven), **Shape B** (multi-Canvas state machine — bespoke layouts, hero continuity), and **Shape C** (hybrid) is a real direction differentiator. See [`presentation-and-slideshow.md`](presentation-and-slideshow.md). When the brief is not sequenced (single Canvas signage, dashboard, dwell loop), this collapses to "single Canvas" and isn't a real axis.
+
+For each of 3 directions, write:
+
+- **One-sentence pitch** combining the axes ("Glanceable signage in the Kenya Hara emptiness register — a single hero photograph holding the canvas, captions smaller than instinct demands.").
+- **A real-world flagship** for the visual language (the user is unlikely to recognize an interaction archetype on its own, but they will recognize "MUJI lobby loops" or "Bloomberg Terminal").
+- **3 vibe keywords**.
+- **Interaction archetype + visual language pairing**, named explicitly so the user can refer back.
+- **Canvas-graph shape** (only for sequenced work — Shape A / B / C).
+- **Dominant Brick / Generator** the work will be built from.
+- **Canvas-count shape** — single canvas / 2–3 / state machine.
+- **Trade-off** — what this direction gives up.
+
+Keep each direction to ~5 lines. The chooser is the artefact, not finished work.
+
+**Spread across the axes.** Three directions all in the same archetype but different languages is a thin spread. Three different archetypes paired with the same language is also thin. For sequenced work, also spread across Canvas-graph shapes when it changes the user's experience meaningfully (Slideshow Generator vs multi-Canvas state machine is a different *kind* of presentation, not just a different look). Aim for at least two different archetypes and at least two different language schools across the three options.
+
+## The 3-cell preview
+
+Build a lightweight preview that lets the user compare side by side:
+
+- **Best**: 3 minimal Subspaces (one Canvas each, placeholder content, real Brick layout) loadable in `bricks-ctor` `preview`. The user can render each.
+- **Good**: 3 sketches in a single Canvas — three frames within one Subspace, each labelled. Use this when speed matters more than fidelity.
+- **Acceptable**: 3 hand-drawn or screenshot-style images placed as Image Bricks with captions.
+
+Don't build full Subspaces. Direction Advisor is a 5–10 minute cycle. If you're 30 minutes in, ship what you have and let the user redirect.
+
+## When the user picks
+
+Once they pick (or pick a blend):
+
+1. **Drop out of Advisor mode.** Stop offering alternatives. Commit.
+2. **Re-confirm deployment context.** The pick changes some assumptions (e.g., picking Transact when the deployment is no-touch is wrong; surface that and renegotiate).
+3. **Continue the normal workflow.** Declare a system, build a runnable skeleton, iterate, ship variations within the chosen direction (variants on visual / motion / content rhythm — not on archetype anymore).
+
+## Anti-patterns
+
+- **Three options that all want the same archetype.** Three "elegant minimalist" variants is not a chooser. The user can't decide because the options haven't disagreed yet.
+- **Naming the visual style without naming the interaction.** "Editorial / Brutalist / Soft" tells the user nothing about what they'll do in front of the screen. Lead with archetype.
+- **Building all three to high fidelity.** You're spending design budget you should spend after the user picks.
+- **Skipping Advisor when the brief is "kind of vague" but you have a strong opinion.** State your opinion in plain language ("I'd default to a glanceable signage loop because of the lobby context — want me to start there, or see two other options?") and let them redirect. Skipping the chooser without checking is how design budgets get burned on the wrong direction.
+
+## When to skip Advisor mode
+
+- The user supplied concrete references (a Figma render, an HTML mockup, a competitor URL). The translation rules in [`translating-inputs.md`](translating-inputs.md) take over; Advisor is unnecessary.
+- The brief is concrete enough to act on — specific screen, specific interaction, specific brand. Don't manufacture ambiguity.
+- The user is impatient and named a clear preference. State your default and proceed; offer to revisit if they want options later.

package/skills/bricks-design/references/workflow.md

@@ -0,0 +1,134 @@
+# Workflow — questions and staged delivery
+
+Two disciplines bundled because they're both about how the work moves through time: deciding when to ask vs. when to build, and pacing the build itself so misalignment is caught early instead of after twelve Canvases.
+
+## Ask vs. build
+
+Ask when the design space has too many free variables. Build when constraints are already pinned.
+
+**Ask** if any of these are unclear:
+
+- Hardware / scene / network / language / brand (Priority #0 — never improvise on these).
+- Fidelity expectation — rough Canvas with tokens only, fully lit single scene, or full system across all Canvases.
+- Variation scope — one direction or multiple to choose from.
+- Variation axes — visual language, palette, density, motion, Canvas-graph shape.
+- Content provenance — does the user have copy/assets, or should you write placeholder in a declared voice?
+
+**Build** if:
+
+- Deployment context is concrete, brief names a recognisable shape, brand is supplied or absent-by-design.
+- Reference material was supplied (Figma / HTML / screenshot / website) — translation rules in [`translating-inputs.md`](translating-inputs.md) take over; ask only the residual.
+- The user named a strong preference. State your default, build, offer to revisit.
+
+**Batch the asks.** Single round of questions, not staged. Volleys cost user momentum. Aim for 5–10 well-targeted questions per round; fewer than 3 means you're missing problem-specific depth; more than 12 means you're stalling.
+
+## Question playbook by axis
+
+When you do ask, cover these axes — in one batch, omitting any already pinned:
+
+**Deployment context** (Priority #0 — covered in SKILL.md, repeat checklist if any is missing).
+
+**Output shape**
+
+- Single Canvas / multi-Canvas state machine / Slideshow Generator / hybrid?
+- How many Canvases roughly? (Calibrates effort, not a contract.)
+
+**Fidelity**
+
+- Rough skeleton with tokens declared / one fully-lit hero Canvas / full system across every Canvas?
+- Is the deliverable for review, for handoff to another designer, or for direct deployment?
+
+**Variations**
+
+- One direction, or three to pick from?
+- Axes that should vary — visual language, palette, density, motion, Canvas-graph shape, interaction archetype?
+- Conservative spread or one bold option included?
+
+**Tone and content**
+
+- Audience for the deployed Application (passersby / customers / employees / operators / VIPs)?
+- Tone register (formal / warm / playful / technical / quiet / loud)?
+- Copy supplied or placeholder-in-voice?
+
+**Problem-specific** (3–5 questions tailored to output shape — examples below):
+
+- *Slideshow / pitch deck*: how many slides, target duration per slide, narration or silent, branching or linear, who advances (auto-timer / operator remote / interaction).
+- *Kiosk / interactive*: peripherals attached, identity capture, payment terminal, queue/wait behaviour, idle reset interval.
+- *Dashboard / monitor*: data sources, refresh cadence, alert thresholds, what action a viewer might take from each state.
+- *Signage / glanceable*: dwell-time at the screen, day/night cycle, ambient sound, fleet vs. single-instance, content feed.
+
+## Staged delivery — five passes
+
+Don't sprint to a finished Subspace. Stage the work so wrong direction is caught at the cheapest point.
+
+### Pass 0 — Deployment context + style declaration
+
+Confirm Priority #0 verbatim. Write the style declaration block at the top of the Subspace file before placing any Brick:
+
+```ts
+/**
+ * System: <picked design language, e.g., Swiss Editorial>
+ * Archetype: <interaction archetype, e.g., glance>
+ * Type: <font family> · <size scale in grid units, e.g., 2 / 4 / 8 / 16 gu>
+ * Color: <ground> on <ink> · accent <#hex> (used only for …)
+ * Spacing: <scale in grid units, e.g., 2 / 4 / 8 / 16 gu>
+ * Grid stance: lean / break / breathe
+ * Motion: <Standby easing + ms> entrance · <ms> exit · loops only on <element>
+ * Heroes: <Brick id(s) that persist across Canvases via auto-tween>
+ * Asset emphasis: <real photography / type-only / hero video / …>
+ */
+```
+
+The grid substrate is given (Truth #6). What you commit to is type scale, palette, **spacing scale in grid units**, motion vocabulary, grid stance, and hero Bricks. The spacing scale is a small enumeration (3–5 values); inter-Brick gaps come from this set, not arbitrary integers. This block keeps the agent's arithmetic consistent across many Bricks and is what the design-critique pass cites.
+
+### Pass 1 — Showcase Canvas (the lockdown moment)
+
+Build **one** Canvas, fully lit, that represents the work at its highest fidelity. Choose the hardest Canvas — the boot screen, the most content-dense state, or the moment that carries the brand most. Run through Verification (compile + screenshot + view back). Show the user.
+
+This is the cheapest point to discover the direction is wrong. If the user wants the type bigger, the photography swapped, the rhythm slower, the language different — fix the Canvas and the style declaration, not twelve Canvases.
+
+**Do not** build the full Canvas graph before this checkpoint. The temptation is real because state-machine work feels productive; resist it. Sign-off on one Canvas first.
+
+### Pass 2 — Full Canvas graph
+
+After Pass 1 sign-off, build the remaining Canvases and the Switch / Data wiring that connects them. Hero Bricks use the same id across Canvases (Truth #3). Every visible Brick has a Standby Transition (Truth #7).
+
+Mid-review checkpoint partway through: show the user 3–4 representative Canvases (not all of them) and the navigation flow. Caught here is still cheap. Wait until everything is finished and you've spent the budget.
+
+### Pass 3 — Polish, edge cases, content rhythm
+
+Pass over every Canvas for:
+
+- Spacing-scale adherence (every gap from the declared set).
+- Density rhythm across consecutive Canvases (not three identical layouts in a row).
+- Standby Transitions consistent vocabulary, not 6 different easings.
+- Asset fidelity at the 5-10-2-8 bar (per `when-the-brief-is-branded.md`).
+- Multilingual content fits without breaking layout, if relevant.
+
+### Pass 4 — Verification + self-critique
+
+The non-negotiable Definition of done from SKILL.md plus the 5-dimension self-critique in [`design-critique.md`](design-critique.md). Compile, screenshot every Canvas, view back, critique pass, fix anything < 8 or surface as an accepted trade-off.
+
+Only after Pass 4 do you declare done.
+
+## When to compress passes
+
+Smaller deliverables don't need all five.
+
+- **Single-Canvas glanceable signage**: Pass 0 + a one-pass build + Pass 4. Pass 1 *is* the deliverable.
+- **Iterative changes on existing Subspace**: skip to the affected passes; don't re-declare the system.
+- **Direction Advisor mode**: 3 lightweight Pass 1 candidates, no Pass 2/3 until the user picks.
+
+Don't compress passes on:
+
+- Multi-Canvas state machines (3+ Canvases).
+- Anything with branding (Pass 1 lockdown catches asset-bar problems before they propagate).
+- Anything with peripherals, payment, or identity (Path 2 verification mandatory in Pass 4).
+
+## Anti-patterns
+
+- **Sprinting to a finished Subspace and showing it.** The user can't easily redirect a finished thing. Pass 1 is for redirection.
+- **Asking one question at a time.** Burns volleys, drains user energy.
+- **Asking nothing and inferring.** The five Priority #0 items are not inferrable; trying to is the most expensive mistake.
+- **Declaring done after Pass 2.** Pass 4 critique is what separates "runs" from "good."
+- **Re-declaring the style block on every iteration.** If you find yourself updating five values at once mid-Pass-3, you're rebuilding the system — back up to Pass 1.

package/skills/bricks-ux/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: bricks-ux
+description: >-
+  Interaction design and end-user experience for any Application or
+  Subspace built on Canvases, Bricks, Generators, Data, DataCalculation.
+  TRIGGER on usability / flow / interaction / journey / state /
+  affordance / feedback / recovery / accessibility audits and design
+  work — "audit this flow", "improve usability", "design the wait
+  state", "fix the error path", "make the kiosk usable", "what does the
+  user do when X breaks", "design the QR scan UX", "design the payment
+  flow", "design the mic / listening state", "design the monitor's
+  alarm state", "design for multilingual", "design for low vision",
+  "design idle and attractor states". Also triggers in parallel with
+  visual-design work for end-to-end deliverables (kiosk / signage /
+  dashboard / interactive screen / pitch deck) where the interaction
+  shape matters as much as the look. SKIP for purely visual / aesthetic
+  / system / style / brand-asset / typography / palette work — those
+  are visual design, not interaction design. Encodes a universal
+  user-journey spine, interaction archetypes, pressable composition,
+  monitoring-screen discipline, designed flow states, accessibility,
+  and a tiered UX critique. Hardware floors are deployment-relative;
+  web habits (hover affordances, modal-as-default, scroll, page-submit
+  forms) do not transfer.
+---
+
+# BRICKS UX
+
+You are a BRICKS interaction designer. Your output is a **designed user journey** expressed through Canvas graphs, Brick affordances, Standby Transitions, Switch thresholds, and Data states. The deliverable is a Subspace whose interaction shape, not just its visual surface, is intentional.
+
+Web interaction habits do not transfer. There is no hover, no scroll, no `<form>` submit, no modal-as-default, no semantic link, no document flow. Hardware varies wildly — a phone-shaped PWA, a 32" landscape kiosk, a 75" portrait signage panel, a curved retail display. **Floors and discipline are deployment-relative**; pinning pixel measurements is the wrong altitude. Express discipline in grid units, viewing distances, fractions of viewport, deployment-shape categories.
+
+## Priority #0 — Verify the end user
+
+Before designing any flow, confirm:
+
+- **Who** uses the screen — passersby, customers, employees, operators, VIPs, mixed.
+- **What they're doing** in front of it — passing through, queuing, ordering, paying, monitoring, dwelling, troubleshooting.
+- **What state they arrive in** — fresh / mid-task / returning / interrupted / under time pressure / under emotional pressure (payment, identity).
+- **What stress they're under** — daylight glare, queue behind them, low literacy, accessibility need, multilingual mix, watchdog reset just happened.
+- **How they leave** — completion, abandonment, idle timeout, peripheral disconnect, someone else taking over.
+
+If any of the first four is missing, stop and ask in a single batch. UX without a named end user is decoration.
+
+## Priority #0.5 — Walk the journey end-to-end before designing
+
+Before placing Bricks for a flow, narrate the journey step-by-step out loud in your reply. Every step gets:
+
+- **Who's acting** — the user, the runtime, a peripheral, an operator.
+- **What they see** — Canvas + dominant Bricks at that moment.
+- **What they feel** — confident / hesitant / waiting / stuck / relieved.
+- **What can go wrong** — including the silent failures (peripheral delay, network blip, watchdog reset, language fallback).
+
+A flow you cannot narrate is a flow you cannot design. This step catches the missing-state cases (no in-flight visibility, no error recovery, no closure) before they ship.
+
+## The universal user-journey spine
+
+Every interaction — touch, peripheral, remote, external trigger — follows the same seven steps. Skipping any of them is the most common failure mode. Full file: [`references/user-journey.md`](references/user-journey.md).
+
+1. **Affordance** — "Can I do something here?"
+2. **Instruction** — "What do I do?"
+3. **Immediate feedback** — "Did I do it?"
+4. **In-flight visibility** — "Is it being handled?"
+5. **Continuation** — "What's next?"
+6. **Recovery** — "What if it went wrong?"
+7. **Closure** — "When can I leave?"
+
+This scaffold replaces device-specific recipes. QR scan, face detection, BLE proximity, NFC tap, payment, voice mic, touch — all the same seven steps, expressed through different Brick families and Generator events.
+
+## Interaction archetypes
+
+The user does one of six things in front of a BRICKS screen. The archetype determines Subspace structure (Canvas count, Brick dominance, motion vocabulary, what carries forward across Canvases).
+
+Glance · Browse · Interact · Transact · Monitor · Dwell.
+
+Each has its own rule set, what reads as fail, and which UX disciplines weight strongest. See [`references/interaction-archetypes.md`](references/interaction-archetypes.md).
+
+## Flow states are first-class
+
+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. See [`references/flow-states.md`](references/flow-states.md).
+
+## Pressable composition
+
+Every composite (multi-element) button needs a deliberate decision about where `on_press` sits and how overlapping press chains resolve. Pressable-capable Bricks with no press events auto-bypass at the runtime, so the trivial wrapper case works without ceremony; explicit `pressable: 'bypass'` matters when inner Bricks carry their own chains. Affordance is a UX signal — the user must be able to *see* what's pressable before discovering it by accident. See [`references/pressable-composition.md`](references/pressable-composition.md).
+
+## Monitoring screens have their own discipline
+
+Calm state must be readable and forgettable. Change must be detectable without being demanding. Demand must compel response without crying wolf. Stale data is worse than no data. See [`references/monitoring-screens.md`](references/monitoring-screens.md).
+
+## Accessibility is non-optional, deployment-relative
+
+Universal access is not a checkbox; it's a deployment-floor commitment. Contrast, scale, motor, reduced-motion, color-not-only, predictable navigation, audio cues — each applies at a deployment-specific floor (viewing distance, ambient light, user posture, hardware capability). See [`references/accessibility.md`](references/accessibility.md).
+
+## Verification — UX critique
+
+Verification proves the flow *runs*. UX critique proves the flow is *usable*. Tiered by deployment risk (CRITICAL on transact / identity / safety-critical; HIGH on interact / monitor with alarms; MEDIUM on browse / dwell; LOW on glance / loop) with Must Have / Anti-Pattern pairs per section. See [`references/ux-critique.md`](references/ux-critique.md).
+
+UX critique runs alongside visual-design critique (in `bricks-design`), not after. The two are concurrent; a Canvas can fail one and pass the other, and both block ship.
+
+## Boundaries
+
+- Do not design flows for users not yet identified — Priority #0 must be answered first.
+- Do not invent peripheral behaviour — if a peripheral's behaviour at threshold is unknown, the journey has an unsafe step; surface it before designing past it.
+- Do not declare a flow done after testing only the golden path. Edge states (timeout, error, abandon, watchdog reset, peripheral disconnect) are part of the design.
+- Do not import web interaction patterns — hover affordances, scroll-to-reveal, modal overlays, page-submit forms — to no-touch or peripheral-bound hardware without translation.
+
+## Companion skill
+
+For visual design — type, palette, asset acquisition, design language, system commitment, visual rhythm — use `bricks-design` (companion skill). Most end-to-end briefs ("design a kiosk for X", "build a presentation about Y") invoke both in parallel.
+
+## Reference index
+
+| When you need to... | Read |
+|---|---|
+| Walk the universal interaction journey | [`references/user-journey.md`](references/user-journey.md) |
+| Pick the right interaction archetype + apply its rule set | [`references/interaction-archetypes.md`](references/interaction-archetypes.md) |
+| Compose a button so taps land where intended | [`references/pressable-composition.md`](references/pressable-composition.md) |
+| Design monitoring / dashboard / status-board UX | [`references/monitoring-screens.md`](references/monitoring-screens.md) |
+| Design idle / loading / empty / error / attractor / boot / maintenance states | [`references/flow-states.md`](references/flow-states.md) |
+| Ensure universal access at deployment-relative floors | [`references/accessibility.md`](references/accessibility.md) |
+| UX critique before declaring done | [`references/ux-critique.md`](references/ux-critique.md) |