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

package/skills/bricks-design/references/translating-inputs.md

@@ -0,0 +1,152 @@
+# Translating Inputs
+
+When the user arrives with a Figma render, an HTML mockup, a screenshot, a competitor URL, or a brand book, you are translating across an impedance mismatch. Web/Figma artifacts encode assumptions (scroll, hover, modal, semantic links, responsive reflow) that BRICKS does not share. Translate intent, not pixels.
+
+## Step 0 — visual inspection is mandatory and exhaustive
+
+You cannot translate from material you have not actually seen. Markdown extractions, text summaries, and `llms.txt`-style indices preserve words and lose every visual signal that makes the reference design-relevant — hierarchy, rhythm, photography style, motion language, brand temperature, typography pairing, density, color weighting. Translating from those alone produces designs that miss the point.
+
+Hard rule before any translation work begins:
+
+- **List every reference artifact** the user supplied (URLs, Figma frames, HTML files, PDFs, screenshots, videos).
+- **Visually inspect each** to completeness — every page, every frame, every state.
+- **State the coverage out loud** in your reply ("inspected: home page, product page, 3 case-study pages, 12 Figma frames, all 8 PDF pages") so the user can spot gaps.
+- If the host environment lacks the tooling to actually see something (no browser automation, no PDF rendering), **ask the user for screenshots before continuing**. Do not pretend.
+
+How to inspect, by source type:
+
+| Source | How to actually see it |
+|---|---|
+| Public URL (website / docs / product page) | Drive a browser automation tool — browser-MCP, Playwright/Puppeteer-style MCP, an `agent-browser`-equivalent skill, or any host-provided browser tool — to navigate the page and capture full-page screenshots. Then read each screenshot back through the host's image-reading capability. `WebFetch` and similar text extractors are **not** visual inspection; use them only as navigation aids to enumerate which pages to visit. |
+| Figma / design-tool URL | Use a Figma-MCP / design-tool MCP if present to enumerate frames and image-export each. Otherwise ask the user for PNG exports of every relevant frame. |
+| HTML project on disk | Serve and screenshot every route via a browser tool, the same as a public URL. Do not infer visuals by reading source HTML/CSS — the rendered output is what you need. |
+| PDF / brand book / slide deck | Read every page through the host's PDF capability, page-by-page when the document is long. Cover all pages, not just the first few. |
+| Local images / screenshots | Read each via the image tool. |
+| Video walkthrough | Ask the user for key-frame screenshots, or to describe each state. Do not claim to have "watched" a video you cannot frame-step. |
+| Live competitor product / app | Run it (or have the user run it and capture screen recordings); inspect the screenshots/states. |
+
+If a reference is partially inaccessible (paywalled page, unauthenticated content, broken link), name the gap explicitly. Don't extrapolate from the visible portion.
+
+Inspection comes before everything else in this file. The translation table below assumes you have already seen every relevant frame.
+
+## A render is one state, not an Application
+
+Most translation mistakes start here. A Figma frame, a screenshot, an HTML page — each is a snapshot of one state. It is never an Application.
+
+Before translating, identify:
+
+- **Which Canvas is this?** Welcome / browsing / editing / confirming / receipt / error?
+- **What Data drives the visible variation in this state?** Which strings, images, lists are dynamic vs. static?
+- **What other Canvases does this flow imply?** A "submit" button implies at minimum a result/confirmation Canvas. A list view implies a detail Canvas (or a Subspace overlay).
+- **What shared chrome carries across?** Logo, header, status bar — these become same-id Bricks across multiple Canvases for auto-tween.
+
+Translating a single render verbatim into one Canvas with no state graph is the most common mistake when porting from web mocks. Don't.
+
+## Translation table — web/Figma → BRICKS
+
+### Scroll
+
+Web overflow scrolling has no BRICKS equivalent. Pick one:
+
+- **Many items, lightweight, glanceable** → `Slideshow` Brick on a timed loop.
+- **Many items, user-driven browse** → `Items` Brick (virtualized list with templated row).
+- **Distinct content sections that don't fit one Canvas** → paginate across Canvases with shared chrome and a paging Brick.
+- **Long form** → Canvas-per-question (Truth #10).
+
+If the source design relies on the user scrolling for hours of content, the information architecture needs a redesign before translation. Don't fake it.
+
+### Hover / focus / `:hover` styles
+
+- **Touch hardware** → hover doesn't exist; the design needs a touch target instead. Move the affordance to the resting state.
+- **No-touch hardware (signage)** → hover doesn't exist; either drop the affordance or convert to a Switch on a non-pointer Data signal (e.g., a peripheral sensor, a state Data toggled by a different Generator).
+- **Web focus rings** → focusable Brick prop where the brick template supports it (TextInput, etc.); for non-input bricks, drop or use Switch-driven outline.
+
+Carrying hover affordances into BRICKS is one of the loudest tells of a sloppy port.
+
+### CSS animations and transitions
+
+CSS keyframes are imperative; BRICKS animations are property-targeted (`transform.translateX | translateY | scale | scaleX | scaleY | rotate | rotateX | rotateY | opacity`) with timing / spring / decay configs.
+
+Translate **intent**, not keyframes:
+
+- A CSS fade-in → a Standby Transition with `standbyOpacity: 0` and a delay.
+- A slide-in from the right → Standby with `standbyMode: 'right'` (or custom standbyFrame) and an x-axis easing.
+- A bounce → an `AnimationSpringConfig` with chosen friction/tension.
+- A continuous CSS pulse → an Animation with `runType: 'loop'` (use sparingly — see performance).
+- A page transition → shared-Brick auto-tween + entrance/exit Standby on non-shared elements (Truth #3 + #7).
+
+### Modal / dialog / popup
+
+Web modals are usually overlays painted via z-index. In BRICKS:
+
+- **Always-on modal pattern (e.g., language picker that any Canvas can summon)** → Subspace with `portal: 'top' | 'left' | 'bottom' | 'right'` invoked from the host.
+- **Single-use confirmation in one flow** → a Canvas of its own. The design is a state; treat it as one.
+- **Inline reveal (e.g., expandable card)** → Switch-driven Brick visibility on the same Canvas. Don't reach for a Subspace for inline behavior.
+
+### Buttons, links, ARIA roles
+
+Translation table:
+
+| Source | BRICKS |
+|---|---|
+| `<button>` (text only) | `BrickText` with `on_press` |
+| `<button>` (with bg, border, padding, icon) | `BrickRect` with `on_press`; children `pressable: 'bypass'` |
+| `<a href="...">` | Same as `<button>` — there is no link primitive. `on_press` triggers `CHANGE_CANVAS` (internal) or a Generator (external) |
+| `<div role="button">` | `BrickRect` with `on_press`; children bypass |
+| `aria-pressed` toggle | A toggle Data + Switch on the visual state |
+| `:hover` | Drop on no-touch; convert to a touch state on touch HW |
+| `:focus` | Focusable Brick prop where supported |
+| `:disabled` | Switch on a `disabled` Data; alter visual + set `pressable: 'disabled'` |
+
+See [`pressable-composition.md`](pressable-composition.md) for the failure modes around composite buttons.
+
+### Form fields / inputs
+
+- Single text input → `BrickTextInput` bound to a Data via DataLink.
+- Long form → Canvas per question (Truth #10), not a scrolling form.
+- Validation → DataCalc producing a `<field>.valid` Data; Switch on the field's appearance to surface error state.
+- Submit → event chain that runs the submission Generator (with idempotency key from Data) and CHANGE_CANVAS to a result Canvas; never a synchronous wait.
+
+### Lists / grids / repeating cards
+
+- Static list (≤ 5 items, never changes) → hand-laid Bricks.
+- Dynamic list, glanceable → `Slideshow` (timed) or `Items` (interactive).
+- Long, browse-heavy → `Items` Brick with templated row Brick; bind `data` to a Data array.
+
+### Images, fonts, video, brand binaries
+
+Lift to **Media Flow** at translation time. Do not embed base64 in Brick props or paste binaries into the Subspace file.
+
+- Images → Data of `kind: { type: 'media-resource-image' }`, referenced by Bricks via DataLink.
+- Fonts → `ApplicationFont` entries in the Application; declare in `applicationSettings`.
+- Video / Lottie / Rive → corresponding `media-resource-video` / `lottie-file-uri` / `rive-file-uri` Data with preload metadata.
+
+When the source contains brand binaries, you are inheriting them — but only at the resolution and quality the source happened to embed, which is often insufficient for the deployment. **Hand the brand-binary work off to the asset protocol** in [`when-the-brief-is-branded.md`](when-the-brief-is-branded.md) rather than translating the visual reference directly into the Subspace as a redraw:
+
+- A logo you can see in the Figma mockup is not the logo you ship — go acquire the official high-resolution source through Step 2/3 of the asset protocol.
+- A product photo embedded in the HTML mockup is the *placeholder* the source designer used; verify it's the brand-current canonical asset before binding, and source a higher-resolution version if the embedded one is below the 5-10-2-8 bar.
+- A redrawn-in-Figma logo or product silhouette in the source design is a tell that the source designer didn't have the real asset either — start the asset hunt from scratch, don't carry the redraw across.
+- Embedded brand fonts may not be license-cleared for embedded display use; verify the license and switch to a documented alternative if the constraint isn't met.
+
+Score everything against 5-10-2-8 before binding. If the source's brand binaries are unclear, low-resolution, or stylized substitutes, surface as a gap in `brand-spec.md` and either acquire properly or — for non-logo categories — escalate to brand-reference-anchored generation per [`when-the-brief-is-branded.md`](when-the-brief-is-branded.md). **Don't ship Sketch-Brick imitations.**
+
+### Brand colors and tokens
+
+- A few colors used in many places → a small set of Data entries acting as theme tokens, bound via DataLink. Worth the indirection.
+- One-off decorative color → hardcode (Truth #2's loose convention).
+- Token system from a brand book (light / dark / accent / semantic) → expose as Data tokens; switch theme by writing to the token Data values.
+
+### Long copy / paragraphs
+
+- A signage screen at 5 m has time for one claim. If the source design has paragraphs of body copy, the design is wrong for the deployment, not the runtime.
+- Cut copy until the screen reads in under 2 seconds.
+- For genuinely long copy (terms of service, instructions), Canvas-per-section + a paging Brick beats fake scrolling.
+
+## Order of operations for a porting task
+
+1. **Verify deployment context** (Priority #0 in SKILL.md). Don't translate before knowing the screen size and orientation; you'll waste the translation.
+2. **Map the source to a Canvas graph.** Sketch which states exist; identify shared chrome.
+3. **Lift binaries to Media Flow.** Don't translate with embedded data; it pollutes the Subspace.
+4. **Walk per-Canvas.** For each Canvas, translate elements via the table above. Make explicit pressable decisions for every interactive element.
+5. **Wire the state machine.** Event chains for transitions; shared-Brick ids for chrome continuity; Standby for entrances.
+6. **Verify against the actual deployment** (see `bricks-ctor/rules/verification-toolchain.md`). The translation is done when it runs on the target hardware, not when it looks right in the Electron preview.

package/skills/bricks-design/references/variations-and-tweaks.md

@@ -0,0 +1,124 @@
+# Variations and tweaks
+
+Two different concerns that look similar from a distance and ruin each other when conflated.
+
+- **Exploration variations** — agent offers the user 2–3 directions to compare during the design phase, picks one, the others are discarded. Lives outside the deployed artifact.
+- **Production tweakability** — knobs the operator or environment will actually change once the Application is deployed (locale, theme accent for franchise variants, content feed URL). Lives in Data, with discipline.
+
+Keep them separate. The deployed Application is not a palette picker. The exploration phase is not a Data-knob proliferation event.
+
+## Why no on-Canvas variation picker
+
+Reference design skills built for unbounded HTML put palette pickers and tweak panels in the artifact corner — the user is at a desktop browser, the panel is welcome. BRICKS deliverables run on target hardware (kiosk, signage, lobby screen). An in-Canvas palette picker is design contamination — a tweak UI bolted into the design, same category as decorative page counters or progress chrome.
+
+The comparison surface for exploration variations is **chat and source tree**, never the Canvas.
+
+---
+
+## Exploration variations — three patterns, token-cost order
+
+Default to **Pattern 1**. Escalate only when the variation can't be expressed by the cheaper pattern.
+
+### Pattern 1 — Data-preset variations (default, cheapest)
+
+Use when variations differ only on values: palette, copy, asset paths, density factor, type tokens, brand text, motion timing constants.
+
+**Shape:**
+
+- One Canvas / Subspace. All variant-specific values are Data with initial constants.
+- Source has a `VARIATION_PRESETS` map near the top of the Subspace define file. Each preset is a flat map of token values. Keep the map flat — nested config trees make per-preset diffs noisy.
+- Active preset is selected by a single line near the top: `const ACTIVE = PRESETS.bauhaus`. Agent flips this line, runs preview, captures screenshot, repeats.
+- All hero Bricks keep **the same id** across all presets — preserves Shared Brick auto-tween if the user later wants to A/B them at runtime in a settings Canvas (different use case, but the door stays open).
+
+**Comparison surface:** screenshot grid in chat reply, captioned with preset name + key choices.
+
+**Token cost:** 1 Canvas tree + ~10 lines per preset. A 3-variation comparison ≈ `1 × Canvas + 30 × preset lines`, not `3 × Canvas`.
+
+**Example skeleton:**
+
+```ts
+const PRESETS = {
+  bauhaus: { ground: '#FFFFFF', ink: '#1A1A1A', accent: '#FF3C00', font: 'Inter', density: 1.0 },
+  hara:    { ground: '#F8F4ED', ink: '#2A2A28', accent: undefined,  font: 'Noto Serif', density: 1.4 },
+  brutal:  { ground: '#000000', ink: '#00FF00', accent: undefined,  font: 'IBM Plex Mono', density: 0.8 },
+}
+const ACTIVE = PRESETS.bauhaus  // ← agent flips this one line per variation
+```
+
+Bricks read from `ACTIVE.ground` / `ACTIVE.ink` etc. via Data. The Canvas tree is authored once.
+
+### Pattern 2 — Shared module + variant Subspaces (medium)
+
+Use when variations share most of the Brick tree but differ on a chunk that can't be expressed as Data — different motion language, different hero element identity, different Canvas-graph rhythm, different Standby Transition feel.
+
+**Shape:**
+
+- A shared module (a Subspace-as-typed-module per Truth #8) exports the common Brick definitions, hero ids, and Data shape.
+- Each variant Subspace imports the shared module and overrides only the variant-specific chunk.
+- Bricks reused by reference, not duplicated.
+
+**Comparison surface:** screenshot per variant via the available preview tool, assembled in chat.
+
+**Token cost:** 1 shared module + N small variant Subspaces.
+
+**Caveat:** if the project's Subspace composition support is limited (some setups don't allow clean cross-Subspace imports of partial Brick trees), escalate to Pattern 1 with a Data-driven Switch on the variant-distinguishing chunk before falling all the way to Pattern 3. A few Switches and a single extra Data value can absorb a surprising amount of "structural" difference.
+
+### Pattern 3 — Separate Subspaces (heaviest, justified case only)
+
+Use when variations differ structurally — Canvas-graph shape (Slideshow vs state-machine vs hybrid), interaction archetype, fundamentally different Brick tree, fundamentally different Data shape.
+
+**Shape:** one Subspace per variation, each stands alone. Previewed individually via the project's Subspace switcher.
+
+**Comparison surface:** chat with screenshots from each Subspace.
+
+**Token cost:** full Subspace × N. Justified only because the variations *aren't* variants of one design — they're different designs.
+
+### Decision rule
+
+```
+Differs only in token values?                            → Pattern 1 (Data presets)
+Differs in some Brick subtree but
+  shares most + same Canvas-graph shape?                 → Pattern 2 (shared module)
+Differs structurally / different shape or archetype?     → Pattern 3 (separate Subspaces)
+```
+
+Default escalation: Pattern 1 first. Move up only when the cheaper pattern would lie about what's varying.
+
+## Token-saving discipline
+
+- **Hero ids identical across presets** — same Brick tree, only Data values differ. Token diff is small; auto-tween stays available for any later A/B Canvas.
+- **Flat preset maps** — each preset is a single object literal, all keys at one depth. Easier to diff, cheaper to edit per variation.
+- **Don't author 3 showcase Canvases inside one Subspace** to compare — triplicates Brick trees for no gain over Pattern 1 + screenshot grid. The temporary-showcase Subspace pattern survives only as a fallback when the user wants to physically walk between variations on real hardware, on explicit request.
+- **Don't escalate proactively** — agent's instinct will be to "just build it three times so the user sees three real things." That's the expensive path. Pattern 1 + a screenshot grid is the same review experience at a fraction of the cost.
+
+---
+
+## Production tweakability — the knob filter
+
+After variations are picked and the production Subspace exists, the question is what should stay user-tweakable in deployment. A Data knob has cost — Generator wiring, history bound, persistence behaviour to reason about, every consumer needs an event handler. The bar is **concrete scenario**, not "maybe someone wants to change this."
+
+**Passes the filter (becomes a Data knob):**
+
+- **Operator-controlled in deployment** — locale switch on a multilingual kiosk, theme accent for franchise variant, content feed URL for menu boards, store hours, item availability.
+- **Environment-driven** — sensor / time-of-day / network state already arriving via a Generator.
+- **Per-instance branding** in fleet deployments where one Subspace serves N venues.
+- **i18n strings** — visible text in a Subspace bound for multilingual deployment, even when only one language is populated at first.
+
+**Fails the filter (hardcode it):**
+
+- Stuff the agent explored during design but the operator won't touch.
+- "Maybe in the future." Three hardcoded lines beat one Data wire until the future arrives.
+- Tweaks meant for the designer's own iteration loop — that's what source edits and Pattern 1 are for, not Data.
+- Speculative theming. If there's no franchise / no white-label requirement, don't make the palette a Data knob.
+
+When in doubt, hardcode. Adding a Data knob later is a small refactor; removing one once consumers exist is a big one.
+
+## Anti-patterns
+
+- **In-Canvas palette pickers / colour swatches / "choose your theme" buttons as a deliverable feature.** Same category as page counters drawn into Canvas content. Allowed only as a literal settings Canvas in a settings Subspace, which is a different use case entirely.
+- **Demo-mode toggles left in production code.** Strip them before declaring done.
+- **Three showcase Canvases inside the production Subspace just for variation review.** Triplicates Brick trees. Use Pattern 1 + screenshot grid.
+- **Speculative Data knobs.** Every Data knob without a named operator scenario is dead weight that complicates the next change.
+- **Pattern-3-by-default** because "the user wants to see real options." User wants to see differences, not duplicated effort. Show differences via Pattern 1.
+- **Triplicated Canvas trees + variant-specific Subspaces for what's actually a palette difference.** Always check: could this be a flat preset?
+- **Forgetting to delete the losing presets after pick.** The production Subspace ships with one preset, hardcoded. The `VARIATION_PRESETS` map is exploration scaffolding, not a runtime selector.

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.