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

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

@@ -0,0 +1,195 @@
+# Design Critique — self-review before "done"
+
+The Verification gate proves the design *runs*. Critique proves it's *good*. Both are required before declaring done; neither substitutes for the other.
+
+This file gives the agent a structured self-review pass: five scoring dimensions with concrete rubrics, a per-deployment-shape focus chart, and an extended anti-slop top-10 with BRICKS-specific failure modes. Run the pass after the screenshots are captured and viewed (per [`verification-toolchain.md`](verification-toolchain.md)), and before declaring done to the user.
+
+The point isn't to be self-critical for its own sake. The point is to catch the specific failure modes that consistently ship if not actively rooted out.
+
+## How to run the pass
+
+1. **Verify** — compile clean + screenshot every Canvas + read screenshots back (see `verification-toolchain.md`).
+2. **Score** — for each Canvas, rate the five dimensions below 0–10 against the rubrics.
+3. **Anti-slop sweep** — walk the top-10 list; flag every match.
+4. **Fix anything < 8** and any anti-slop matches; re-verify.
+5. **Declare done** — only when every Canvas scores ≥ 8 on every dimension and the anti-slop list is clean.
+
+If a dimension cannot be scored ≥ 8 within the deployment's constraints, surface it as an accepted trade-off in the trade-off note rather than silently shipping a 6.
+
+## The five dimensions
+
+### 1. System commitment
+
+*Does the work cite the declared system (the comment block at the top of the Subspace), and does deviation have rationale?*
+
+| Score | Rubric |
+|---|---|
+| 9–10 | Every brick property points back to a Data token, an `ApplicationFont` entry, or the system block. Deviations carry a one-line comment explaining why. |
+| 7–8 | Direction is correct; 1–2 hardcoded values that should be tokens, or 1–2 deviations without rationale. |
+| 5–6 | Visible drift — a third type family slipped in, a fourth color appeared mid-flow, or a brick redrew an asset that exists in Media Flow. |
+| 3–4 | The system block is decorative; the work doesn't follow it. |
+| 1–2 | No system block, or the block contradicts the work. |
+
+**Audit moves:**
+- Open the system block. Pick five values from it (a color, a type size, a Standby duration, a margin, a Brick template). For each, check that the work uses it consistently.
+- Pick five values *from* the work (a `backgroundColor` literal, a `fontSize`, a Standby easing, a hex code in a Rect, a brick template choice). For each, check that the value traces back to the system block or has rationale.
+- If signature moves of the chosen design language (per [`design-languages.md`](design-languages.md)) are absent, score drops regardless of token-discipline. Swiss Editorial without numbered folios and hairline rules is not Swiss Editorial; it's "vaguely minimal."
+
+### 2. Visual hierarchy
+
+*Does the user's eye flow where the designer intended? Is information findable in under 2 seconds?*
+
+| Score | Rubric |
+|---|---|
+| 9–10 | Squint test passes — even at low resolution / low attention, primary / secondary / tertiary are unmistakable. Display:body scale ratio ≥ 2.5×. Three to four clear levels via size, weight, color, and space combined. |
+| 7–8 | Hierarchy is clear with one or two muddy spots. |
+| 5–6 | Title and body distinguished, but mid-levels collapse together; user has to read everything to find anything. |
+| 3–4 | Information is uniform; no entry point. |
+| 1–2 | The eye doesn't know where to land. |
+
+**Audit moves:**
+- The squint test. View the screenshot at 25% zoom or with eyes half-closed. The composition should still read.
+- Measure the display:body scale ratio in grid units. < 2.5× = deduction.
+- Count the levels distinguishable in the Canvas. < 3 = deduction; > 5 = different deduction (over-stratified).
+- For the deployment's viewing distance, simulate the legibility floor (per the scale-floor table in `architecture-truths.md` Truth #6 + `performance.md`'s scale section). If body text won't read at that distance, hierarchy fails regardless of relative ratios.
+
+### 3. Craft execution
+
+*Alignment. Spacing rhythm. Colour discipline. Typography count. Motion vocabulary consistency.*
+
+| Score | Rubric |
+|---|---|
+| 9–10 | Grid stance matches the chosen language (lean / break / breathe) deliberately throughout. Every inter-Brick gap comes from the declared spacing scale. Colours limited to the system tokens (typically ≤ 4). Typography limited (typically ≤ 2 families). Standby Transitions use a consistent easing and timing vocabulary. |
+| 7–8 | Mostly clean; 1–2 alignment slips or one off-scale spacing. |
+| 5–6 | Visible inconsistency — colours creeping past the token set, mixed Standby easings, asymmetric margins without intent, ad-hoc gap values. |
+| 3–4 | Grid stance unclear; multiple type families; arbitrary motion timings; spacing drift. |
+| 1–2 | Looks like a draft. |
+
+**Audit moves:**
+- **Grid stance match.** Off-grid placements should serve the declared language (Brutalist break, Sagmeister theatrical, Risograph hand-placed). Off-grid that drifted in accidentally — flag and snap. A Swiss Editorial Canvas with a Brick at `(3.5, 11.2)` is a tell.
+- **Spacing-scale adherence.** Open the style declaration block. Read the declared spacing scale (e.g., `2 / 4 / 8 / 16 gu`). Pick ten inter-Brick gaps across the Canvas — every one must come from that set. Gaps of 7 / 9 / 11 / 13 across siblings = arithmetic drift, the agent picked values ad-hoc instead of from the scale. Snap to the nearest scale value or update the scale (and re-check everywhere).
+- List every distinct colour used in the Canvas. > 4 = deduction (excluding intentional photography palette spreads).
+- List every distinct type family. > 2 = deduction.
+- List every distinct Standby easing / duration combination. > 3 = deduction.
+
+### 4. Functional fit to deployment
+
+*Does the design solve the deployment's actual constraints?*
+
+This dimension overlaps with the companion `bricks-ux` skill — interaction / accessibility / flow-state correctness is critiqued in depth there (`bricks-ux/references/ux-critique.md`). What stays here is the visual-design contribution to functional fit: does the visual system *enable* the interaction layer to work, or does it actively disable it.
+
+| Score | Rubric |
+|---|---|
+| 9–10 | Type meets legibility floor for viewing distance. Pressable Bricks are visually distinct from decorative. Contrast survives deployment conditions (sunlight / dim lobby / glare). Brand and asset choices accommodate languages in scope. Orientation respected. |
+| 7–8 | One visual choice marginal — type at the floor instead of comfortably above; one asset that doesn't survive a locale; affordance distinction subtle but present. |
+| 5–6 | One visual choice actively disables interaction — pressable tiles indistinguishable from decoration, body type below legibility floor for the distance, palette that fails contrast under deployment light. |
+| 3–4 | Multiple visual-functional conflicts. |
+| 1–2 | Visual design ignores deployment constraints entirely. |
+
+**Audit moves:**
+- Walk the deployment-context block (from Priority #0). For each visible item — what the user must read, find, press, distinguish — point to the visual choice that supports it.
+- Squint test at 25% zoom: primary content readable, pressable elements visually distinct, severity tiers (if monitor) distinguishable.
+- For interaction / accessibility / flow-state critique beyond the visual contribution, cross to `bricks-ux/references/ux-critique.md`. The two passes run in parallel; both block ship.
+
+### 5. Originality within direction
+
+*Is this the chosen design language done at 80% commitment, or 30%?*
+
+| Score | Rubric |
+|---|---|
+| 9–10 | The signature moves of the chosen language are present and confident. The work would be recognized by a designer familiar with the language. There's at least one move that's specific to *this* brief, not just templated language application. |
+| 7–8 | Direction is recognizable; mostly templated execution; one or two moves feel rote. |
+| 5–6 | Recognizable as "the kind of thing that gets called Swiss Editorial / Kenya Hara / etc." but generically — could be any brand. |
+| 3–4 | Cliché-mode application of the language; works that any agent might produce given the same prompt. |
+| 1–2 | The language is unrecognizable in the work. |
+
+**Audit moves:**
+- For the chosen direction, list its top 3–5 signature moves (from `design-languages.md` or your own knowledge of the language). For each, check whether the work executes it.
+- Where signature moves are absent, the direction has been softened toward generic. Restore them.
+- Look for the inverse — moves that *aren't* in the language but the work has imported anyway (a Field.io-style gradient on a Swiss Editorial piece, a Risograph spot color on a Kenya Hara piece). These are the dilutions that drop scores.
+
+## Deployment-shape focus
+
+Different deployments weight the dimensions differently:
+
+| Deployment shape | Strongest weight | Weaker weight |
+|---|---|---|
+| Glanceable signage (single canvas) | Visual hierarchy · Originality | Functional fit (low complexity) |
+| Multi-canvas kiosk (transact / interact) | Functional fit · Craft execution | Originality (don't get cute with money or identity) |
+| Reactive dashboard (monitor) | Visual hierarchy · Functional fit | Originality (data is the work) |
+| Hospitality / lifestyle (dwell) | Originality · System commitment | Functional fit (low input complexity) |
+| Wayfinding | Visual hierarchy · Functional fit (legibility floor) | Originality (recognition over flair) |
+| Presentation / introduction loop | Originality · Visual hierarchy | Functional fit (no input) |
+
+When focus weights diverge sharply, surface the trade-off in the trade-off note. A wayfinding screen that scores 10 on hierarchy and 6 on originality is *correct*; a wayfinding screen that scores 9 on originality and 6 on hierarchy is *wrong*.
+
+## Anti-slop top-10 (BRICKS-specific)
+
+Walk this list every time. Each is a pattern that consistently slips into agent-produced work and consistently degrades it.
+
+### 1. Generic gradient backgrounds on a Rect
+**Tell:** purple → pink → blue full-bleed on the boot Canvas. **Why bad:** it is the literal AI-generated-page tell; reviewers identify the work as machine-made instantly. **Fix:** use a single-color ground from the system tokens, or a reference-anchored gradient that's specific to the brand (declared as a Data token, used deliberately).
+
+### 2. Decorative left-border-accent on every Rect
+**Tell:** every card-shaped Rect carries a 4-grid-unit left border in the accent color. **Why bad:** it is the AI-dashboard-card signature; once seen it cannot be un-seen and it dates the work to the AI-tool era. **Fix:** distinguish cards via background contrast, weight, or composition; or commit to a different card vocabulary that matches the chosen language.
+
+### 3. Emoji decoration in RichText
+**Tell:** ✅, ⚡, 🚀, ✨ next to feature bullets or in headlines. **Why bad:** unless the brand actually uses emoji in its voice (rare, deliberate), this is decoration-as-substitute-for-design. **Fix:** real icon library (Lucide / Phosphor / Heroicons via `Icon` brick), or no icon at all.
+
+### 4. Sketch / SVG-drawn imitations of real assets
+**Tell:** a `Sketch` brick that approximates a logo, a CSS-shape product silhouette, a SVG hero illustration. **Why bad:** AI-drawn imagery reads as AI-drawn imagery. A labeled placeholder is more honest. **Fix:** acquire the real asset via the [Media Flow protocol](when-the-brief-is-branded.md), generate one anchored on real brand reference, or accept a labeled placeholder.
+
+### 5. Fabricated stats / fake user counts
+**Tell:** "10,000+ happy customers", "99.9% uptime", "trusted by Fortune 500" appearing without a source. **Why bad:** invented social proof is dishonest and reviewers usually catch it. **Fix:** request real numbers from the user or use a labeled placeholder ("[insert real metric]").
+
+### 6. Default sans system fonts when the brand has its own
+**Tell:** Inter / Roboto / Helvetica / system-ui shipped despite the brand having a documented type stack. **Why bad:** it leaks "I didn't bother sourcing the brand font" across the entire surface area of the design. **Fix:** declare the brand fonts as `ApplicationFont` entries with the licensed files in Media Flow.
+
+### 7. Naive dark-mode by inverting Data values
+**Tell:** the dark theme is "white background → black, black text → white" with no other adjustments. **Why bad:** a real dark theme rebalances saturation, contrast, accent intensity, and shadow. Inversion produces a theme that looks broken. **Fix:** if the brief wants dark mode, design it as a deliberate second theme — re-author the token Data, don't just toggle.
+
+### 8. Animation `loop` on every visible element
+**Tell:** every brick on every canvas has a `runType: 'loop'` Animation attached. **Why bad:** continuous motion everywhere is visual noise that burns frame budget and dulls genuine attention-draws. **Fix:** reserve `loop` for true attention-draws (alarm pulse, recording dot, hero motion in Field.io); use Standby Transitions and shared-Brick auto-tween for everything else.
+
+### 9. Hover-state treatments imported to no-touch hardware
+**Tell:** a brick's `pressable: 'enabled'` carries a press scale-down animation, but the deployment is a 75" no-touch signage panel. **Why bad:** the affordance promises something the hardware cannot deliver; the design reads as "ported from web." **Fix:** drop hover on no-touch; convert to a Switch driven by a non-pointer signal (sensor, timer, peripheral Generator) if the visual intent matters.
+
+### 10. AI-generated brand imagery without a real brand-reference anchor
+**Tell:** a generated "brand-appropriate" hero image that nobody at the brand has ever seen, produced from a prompt like "modern tech product on a gradient." **Why bad:** generation without anchoring produces uncanny-valley assets that feel adjacent to the brand without being the brand. **Fix:** anchor every generation on at least one verified brand asset (logo, real photo, official color sample); apply 5-10-2-8; log generation metadata in `brand-spec.md`. (See [Media Flow protocol § Creating assets when missing](when-the-brief-is-branded.md#creating-assets-when-missing).)
+
+## Bonus failure modes (BRICKS-specific, less common)
+
+- **Hardcoded English in a Subspace bound for multilingual deployment.** Every visible string should be a Data value, even when only one language is populated at first.
+- **`persistData: true` on transient flow Data.** Resumes a half-complete flow after a watchdog reset and confuses the next user.
+- **DataCalculation chains masquerading as orchestration.** See [`avoiding-complexity.md`](avoiding-complexity.md) — calc → calc → calc is the wrong primitive.
+- **Subspace-as-tidiness.** A Subspace with a single instance and a leaky Props contract is a directory, not a module. See `architecture-truths.md` Truth #8.
+- **Snap canvas transitions on routine navigation.** Reserved for emphasis only.
+- **Inline brand binaries** (logo as base64 in a Brick prop, hero image embedded). Pollutes the Subspace and defeats Media Flow's offline + refresh model.
+- **Pseudo-chrome contamination — page counters, progress bars, chapter numbers drawn into Canvas content.** A "Slide 3/12" Text Brick inside the design competes with the runtime's own transition affordances and reads as duplicated chrome. If the audience genuinely needs to know where they are, render it via a shared chrome Brick (so it auto-tweens with the rest of the chrome) — or drop it entirely. See [`presentation-and-slideshow.md`](presentation-and-slideshow.md).
+- **Density-rhythm collapse — three or more consecutive Canvases at the same layout archetype.** Three "headline + bullet list" Canvases in a row reads as a single Canvas that didn't change. Alternate density across the sequence (full-bleed / two-column / pull-quote / data-figure / breather — see the rotation table in `presentation-and-slideshow.md`).
+- **In-Canvas variation pickers — palette swatches, theme toggles, "choose your style" buttons left in production.** Same category as pseudo-chrome. The variation comparison surface is chat + source tree, not the Canvas. See [`variations-and-tweaks.md`](variations-and-tweaks.md).
+- **Full-set unmount + remount per Canvas change.** Every Brick is Canvas-local; no shared ids; every transition is a hard cut even with Standby Transitions configured. This is what makes a sequence read as "narrated PowerPoint" instead of a designed flow. Pick 1–2 hero Bricks and share their ids across Canvases — see Truth #3.
+
+## First-viewer reaction rubric (for sequenced / narrative work)
+
+For presentations, slideshows, intro decks, explainers — anything sequenced. Predict (or directly ask) the first reaction. The rubric is a separate axis from the 5 dimensions and only applies when the work is a sequence ≥ 3 Canvases.
+
+- *"This is narrated PowerPoint."* — Redesign. Hero architecture missing or broken. Likely full-set unmount per Canvas change. Back to Pass 1.
+- *"Things were just moving."* — Motion is present but hierarchy isn't. Heroes exist but compete with auxiliaries. Quiet down everything except the hero.
+- *"I wanted to keep watching."* — Baseline good. Pacing works, hero continuity reads. Polish from here.
+- *"I wanted to screenshot that frame."* — Memorable keyframe achieved. At least one Canvas is doing more than its job.
+
+Aim for the third reaction overall and the fourth on at least one Canvas in any sequence of ≥ 5 Canvases. Anything ≤ first is a structural failure, not a polish issue.
+
+## Definition of "done" with critique applied
+
+A design is done when:
+
+1. The Verification gate (compile + every-Canvas screenshot + screenshots reviewed) passes.
+2. Every Canvas scores ≥ 8 on every one of the five dimensions, or trade-offs are explicitly accepted with rationale.
+3. The anti-slop top-10 + bonus-failure-modes walk produces zero unaddressed matches.
+4. For sequenced / narrative work, the first-viewer rubric predicts ≥ "I wanted to keep watching."
+5. Reference comparisons (where applicable) have a written delta report.
+6. The trade-off note that ships alongside variations captures every accepted < 8.
+
+If any item is unmet, the work is mid-iteration. Say so explicitly to the user; offer a precise list of what remains.

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

@@ -0,0 +1,265 @@
+# Design Languages
+
+A curated library of visual languages, each with concrete BRICKS-native execution notes. The library exists because *committing to a system* is what separates polished work from generic output — and an agent without anchors averages toward generic. These anchors give you something specific to commit to.
+
+The library does not constrain you. Pick one, blend two, or invent a new one rooted in the same discipline. What it prevents is the no-commitment middle.
+
+## Two orthogonal axes
+
+A picked direction is the combination of two independent choices:
+
+- **Interaction archetype** — *what the user does* in front of the screen (glance / browse / interact / transact / monitor / dwell). Drives the Subspace structure: Canvas count, state-machine shape, dominant Bricks. See [`when-the-brief-is-vague.md`](when-the-brief-is-vague.md).
+- **Visual language** — *what the design says*. Drives expression: type, color logic, motion vocabulary, signature moves, asset emphasis. This file.
+
+A "browse + Kenya Hara emptiness" Subspace is profoundly different from a "browse + Brutalist web" Subspace, even though the user does the same thing. Advisor mode picks 3 candidates spanning both axes.
+
+## The commitment principle — fight your averaging instinct
+
+When unsure, do *more* of what defines the chosen language, not less. A style executed at 30% reads as hesitant; at 80% it reads as deliberate.
+
+- Swiss Editorial without numbered folios, hairline rules, and oversized headlines is just "generic minimal."
+- Kenya Hara without 70%+ negative space is just "a bit sparse."
+- Brutalist web with rounded corners and gradient accents is just "an unfinished page."
+
+If you find yourself softening signature moves to "make it more accessible" — stop. The signature moves are the language. Soften them and you've abandoned the language for no destination.
+
+## How to use the library in Advisor mode
+
+1. **Pick 3 directions from different schools.** Not three minimalist variants. Spread across the schools below so the user sees a real choice.
+2. **For each direction, give:**
+   - One-sentence pitch.
+   - A flagship the user is likely to recognize (designer / firm / brand / institution).
+   - 3 vibe keywords.
+   - The interaction archetypes it fits.
+   - One sentence on what it would mean concretely for this brief.
+3. **Build a 3-cell preview** — three minimal Subspaces (one Canvas each) the user can render. Don't produce finished work; the preview is a chooser.
+4. **Once the user picks, drop out of Advisor mode** and continue the workflow rooted in that direction.
+
+## Style declaration ritual
+
+After the direction is picked, write the committed system as a comment block at the top of the Subspace file. Every subsequent choice should cite this block. Adding a value not in the block requires updating the block first — that's what makes the system structural rather than aspirational.
+
+```ts
+/**
+ * System: Swiss Editorial (Pentagram lineage)
+ * Archetype: glance
+ * Type: <Brand Sans> 4 / 8 / 16 gu · single family · weight contrast
+ * Color: ink #1A1A1A on cream #F5F0E6 · accent #FF3C00 (callouts only)
+ * Spacing: 2 / 4 / 8 / 16 gu (use only these for inter-Brick gaps)
+ * Grid stance: lean (strict alignment, generous margins 4–8 gu)
+ * Motion: ease-out 280ms entrance · ease-in 180ms exit · no loops
+ * Heroes: logo (id `brand-logo`) · folio (id `folio-num`)
+ * Asset emphasis: logo + 1 hero photograph per canvas · no decorative imagery
+ */
+```
+
+The grid itself is given by the runtime (Truth #6). What the block commits to is the set of design decisions on top of the grid: type scale, palette, **spacing scale in grid units** (small enumeration so inter-Brick gaps stay consistent across many siblings), grid stance, motion vocabulary, and hero Brick ids. The comment is not for the runtime; it is for *you*, when you next look at the file and consider adding a third colour or a fourth gap value. The block's existence is what holds the line.
+
+---
+
+## School 1 · Structural modernism
+
+### 1. Swiss Editorial (Pentagram / Vignelli lineage)
+
+- **Pitch:** Precision, authority, editorial gravity. Type, grid, hairline rule, restraint.
+- **Flagships:** Pentagram, Vignelli's Unimark, MIT Press canon.
+- **Keywords:** structural · monochrome · grid-disciplined · quiet.
+- **Fits:** glance / browse / monitor.
+- **BRICKS execution:**
+  - Bricks: large RichText for headlines, smaller Text for body, hairline `Rect` rules (1–2 grid units tall), numbered RichText folios in a corner, `Image` bricks at controlled scale.
+  - Heroes: brand wordmark or logo, numbered folio, masthead hairline rule — same id across Canvases.
+  - Theme tokens (Data): two grounds (cream + ink), one accent reserved for callouts; single sans family declared as `ApplicationFont`.
+  - Spacing scale: `2 / 4 / 8 / 16 gu`. Grid stance: **lean** (strict alignment, generous 4–8 gu margins, body columns at typeset widths).
+  - Density rhythm: dense type Canvases broken by wide-margin breathers every 3–4 Canvases.
+  - Motion: subtle vertical Standby on entrance (`ease-out` 280ms); shared headers across canvases via same-id Bricks; no `loop` animations.
+  - Asset emphasis: real photograph or none; never decorative imagery; logo at restrained scale.
+- **Wrong for:** hospitality warmth, retail playfulness, ambient dwell loops.
+
+### 2. Bauhaus geometric (Müller-Brockmann / Karel Martens lineage)
+
+- **Pitch:** Primary, architectural, confident. Geometry as the composition itself, not decoration.
+- **Flagships:** Müller-Brockmann's Zurich Tonhalle posters, Paula Scher's Public Theater identity.
+- **Keywords:** geometric · primary-color · flat · rhythmic.
+- **Fits:** glance / dwell / monitor.
+- **BRICKS execution:**
+  - Bricks: oversized `Rect` bricks as primary anchors (circles via `borderRadius`, squares, diagonals via `rotate`), `Text` bricks rotated 90° as composition elements, no photographic imagery.
+  - Heroes: one or two large geometric anchors (circle, square, diagonal bar) that re-position and re-scale across Canvases via shared id — the geometry is *the* narrative.
+  - Theme tokens: primary RGB or fluorescent accents (`#FF3C00`, `#0019FF`, `#F5E100`) on flat black or white; tri-color palette fixed in Data.
+  - Spacing scale: `1 / 3 / 6 / 12 gu`. Grid stance: **lean** (geometric anchors snapped hard to grid).
+  - Density rhythm: high-energy geometric Canvases alternating with declarative single-shape pause Canvases.
+  - Motion: bold sweep entrances (400–500ms), shared-Brick auto-tween of geometric anchors across canvases.
+  - Asset emphasis: logo, geometric forms, type-as-image; no scene photography.
+- **Wrong for:** corporate finance, hospitality, hi-fi product UI.
+
+---
+
+## School 2 · Quiet minimalism
+
+### 3. Kenya Hara emptiness (MUJI / Shiseido editorial lineage)
+
+- **Pitch:** Quiet, meditative, reverent, deliberately un-full.
+- **Flagships:** MUJI art direction, Shiseido editorial, Hara's own book design.
+- **Keywords:** generous-whitespace · monochrome · patient · reduced.
+- **Fits:** dwell / glance.
+- **BRICKS execution:**
+  - Bricks: a single hero `Image` (real photo, never redrawn), one small `RichText` caption, lots of empty Canvas; `Slideshow` rotation slow (12–24s per item).
+  - Heroes: the single hero `Image` shifts subtly in scale/position across Canvases (same id) — the photograph is the constant; everything else is breath.
+  - Theme tokens: warm-white ground (`#F8F4ED` or similar), single warm-charcoal ink (never pure black), no accent color.
+  - Spacing scale: `8 / 24 / 48 gu`. Grid stance: **breathe** (the grid is there but mostly unused; content islands placed with precision, 70–80% empty).
+  - Density rhythm: every Canvas is low-density. Variation is in framing (top-third / bottom-third / centered isolate), not density jumps.
+  - Motion: barely perceptible Standby (300–500ms delay, slow opacity easing); no `loop` animations.
+  - Asset emphasis: photography is the work — Media Flow asset must score 9–10 on the 5-10-2-8 craft dimension; one image carries the canvas.
+- **Wrong for:** information-dense kiosks, transactional flows, dashboards.
+
+### 4. Dieter Rams industrial (Braun / Vitsœ / pre-2010 Apple)
+
+- **Pitch:** Useful, honest, restrained, quietly confident.
+- **Flagships:** Braun catalogs, pre-2010 Apple, Vitsœ.
+- **Keywords:** functional · tactile · unobtrusive · long-lasting.
+- **Fits:** glance / browse / monitor.
+- **BRICKS execution:**
+  - Bricks: product `Image` as hero, sparse `RichText` specification blocks, hairline `Rect` grids separating spec columns.
+  - Heroes: the product photograph itself — re-framed and re-scaled across Canvases via shared id; spec callouts are auxiliary.
+  - Theme tokens: monochrome grey scale + one functional accent (used only where it means something — warning, primary action).
+  - Spacing scale: `2 / 4 / 8 gu`. Grid stance: **lean** (tight, even, predictable; nothing breaks rank).
+  - Density rhythm: even and measured across Canvases — no dramatic density jumps; pacing comes from Brick weight not layout shifts.
+  - Motion: minimal — Standby with linear easing, no spring, no `loop`.
+  - Asset emphasis: hero product photography first-class; spec icons as restrained line drawings.
+- **Wrong for:** consumer entertainment, maximalist branding, hospitality warmth.
+
+---
+
+## School 3 · Editorial and narrative
+
+### 5. Magazine editorial (NY Magazine / Bloomberg Businessweek lineage)
+
+- **Pitch:** Opinionated, layered, alive. Real editorial hierarchy.
+- **Flagships:** New York Magazine, Bloomberg Businessweek, The California Sunday Magazine.
+- **Keywords:** layered · photographic · type-driven · maximalist-typography.
+- **Fits:** dwell / browse.
+- **BRICKS execution:**
+  - Bricks: oversized `RichText` display headlines (a strong serif), second sans family for body, `Image` bricks anchored to text columns, pull-quote `Text` bricks at 2× body scale, color-blocked `Rect` sidebars.
+  - Heroes: masthead chrome (publication name + date), pull-quote container, hero photograph — all reposition across Canvases via shared id, giving the layered flip-through feel.
+  - Theme tokens: photograph-driven palette, accent values pulled from the hero images themselves and bound as Data; rich supporting neutrals.
+  - Spacing scale: `1 / 2 / 4 / 8 / 16 gu` (wider scale for editorial-style overlap and pull-quote breaks).
+  - Grid stance: **lean** with deliberate overlaps — content sits on the grid but layers cross gutter lines.
+  - Density rhythm: full-bleed portrait → text-heavy spread → pull-quote → image grid → breather — rotate hard, this language *needs* density variation.
+  - Motion: rich Standby with stagger (50–100ms increments per Brick); shared chrome animates across canvases.
+  - Asset emphasis: editorial-quality photography (full-bleed, scene, portrait); custom display serif as `ApplicationFont`.
+- **Wrong for:** short-attention-span interfaces, transactional kiosks, dashboards.
+
+### 6. Risograph zine (indie print lineage)
+
+- **Pitch:** Handmade, immediate, low-fidelity on purpose, warm.
+- **Flagships:** Independent zines, Rough Trade posters, skate-culture print design.
+- **Keywords:** risograph · two-color · textured · hand-placed.
+- **Fits:** dwell / browse.
+- **BRICKS execution:**
+  - Bricks: 2–3 spot-color `Rect` grounds, slightly off-grid `Image` bricks (deliberate), `Text` in a distinctive display, halftone overlays as low-opacity `Image` bricks (texture asset in Media Flow).
+  - Heroes: a distinctive display-type wordmark or a halftone-textured shape that re-stamps in different positions across Canvases — the hero feels stamped, not placed.
+  - Theme tokens: risograph palette (flo-pink, teal, navy, mustard) — saturated, slightly imperfect overprints.
+  - Spacing scale: deliberately irregular — `1 / 5 / 13 gu` (hand-placed feel; consistent within scale but not evenly stepped).
+  - Grid stance: **break** (Bricks deliberately off-grid by 1–2 units, slight rotations, content kissing edges).
+  - Density rhythm: chunky-and-busy alternating with stark single-image Canvases — the zine flip-through feel.
+  - Motion: hand-placed feel via tiny rotations on Standby (`rotate: 1–2deg` baseline); avoid the runtime's polished auto-tween for primary entries — use `ease-linear` or even snap on Standby for some elements.
+  - Asset emphasis: spot-color illustration, halftone texture, distinctive display type.
+- **Wrong for:** enterprise, premium, anything trust-seeking.
+
+---
+
+## School 4 · Motion and the digital-native
+
+### 7. Field.io motion poetics
+
+- **Pitch:** Alive, computational, mesmerizing. Motion is the medium.
+- **Flagships:** Field.io, Active Theory, Universal Everything.
+- **Keywords:** generative · motion-first · particle · light-as-material.
+- **Fits:** dwell / monitor (high-end).
+- **BRICKS execution:**
+  - Bricks: dominant `Video` / `VideoStreaming` / `Lottie` / `Rive` / `GenerativeMedia` full-bleed; `RichText` overlays at delicate sizes with semi-transparent backgrounds.
+  - Heroes: the brand reel / generative motion piece itself, full-bleed and persistent across Canvases — only the overlaid type changes; the motion is the throughline.
+  - Theme tokens: dark indigo to electric gradient ground, or pure monochrome with one light-based accent.
+  - Spacing scale: `2 / 8 / 24 gu` (delicate gaps for overlay type, large gaps for breathing room around full-bleed motion).
+  - Grid stance: **breathe** — motion is full-bleed; UI sits on the grid but quietly.
+  - Density rhythm: every Canvas is low-density overlay on full-bleed motion; variation is in *what the motion is doing* this Canvas, not in layout density.
+  - Motion: slow continuous motion via `Animation` `runType: 'loop'` — used sparingly, only on the hero. Cross-canvas transitions use shared-Brick auto-tween of full-bleed elements.
+  - Asset emphasis: brand reel video and animated logo Lottie/Rive are first-class — preloaded via Media Flow, hash-verified, offline-safe; the canvas is *driven* by these assets.
+- **Wrong for:** content-heavy displays, purchase funnels, anything requiring careful reading.
+
+### 8. Brutalist web (Are.na / terminal lineage)
+
+- **Pitch:** Raw, direct, anti-polish, confident.
+- **Flagships:** Are.na, Bloomberg Terminal, deliberate "unstyled" indie sites.
+- **Keywords:** unstyled · monospace · text-dense · system-typography.
+- **Fits:** browse / monitor.
+- **BRICKS execution:**
+  - Bricks: system-font `Text` and `RichText` only (or IBM Plex Mono / Times New Roman as `ApplicationFont`); dense `Items` lists with templated rows; hairline `Rect` borders only; no decorative imagery.
+  - Heroes: a single persistent navigation bar or "you are here" address-style label, same id across Canvases.
+  - Theme tokens: black on white, occasional single saturated accent, almost no gradients/shadows/rounded corners.
+  - Spacing scale: `1 / 2 / 4 gu` (tight, monospaced character cell rhythm).
+  - Grid stance: **lean** but ascetic — grid used as a literal table, no decorative breathing.
+  - Density rhythm: uniformly dense — variation is in content depth, not visual density. This language earns its weight by *refusing* the density-rotation principle.
+  - Motion: snap-cuts allowed and even welcome — but only as deliberate emphasis. Most transitions are shared-Brick auto-tween of typographic chrome.
+  - Asset emphasis: type. That's it.
+- **Wrong for:** consumer retail, emotional storytelling, hospitality.
+
+---
+
+## School 5 · Expressive and experimental
+
+### 9. Sagmeister / experimental
+
+- **Pitch:** Provocative, hand-made, emotional, attention-grabbing. The concept drives every choice.
+- **Flagships:** Stefan Sagmeister, Paula Scher in expressive mode, Stefan Walz.
+- **Keywords:** expressive · hand-craft · concept-driven · theatrical.
+- **Fits:** dwell / glance (cultural / event contexts).
+- **BRICKS execution:**
+  - Bricks: anything goes, but every choice serves the concept — `Sketch` for hand-drawn elements, sourced `Image` for hand-crafted typography photographs, `Text` bricks at extreme scale shifts via `rotate` and large grid frames.
+  - Heroes: the conceptual centerpiece (a hand-crafted word, a built-physical-object photograph) re-staged dramatically across Canvases — different angle, different scale, different distance — same id.
+  - Theme tokens: saturated, often clashing pairs used deliberately. No fear of "bad taste."
+  - Spacing scale: deliberately broken — `0 / 7 / 23 gu` (the irregularity is the point; siblings still share the same set so it doesn't read as drift).
+  - Grid stance: **break** — the grid is a foil to push against, not a rule.
+  - Density rhythm: extreme oscillation between maximalist Canvases and empty-pause Canvases.
+  - Motion: theatrical — long durations (600–1000ms), dramatic easing (`easeInOutBack`, `easeInOutElastic`), deliberate "broken" timings.
+  - Asset emphasis: hand-craft photography, custom or modified type, conceptual imagery.
+- **Wrong for:** ongoing systems, B2B utility, any context demanding restraint.
+
+### 10. Y2K / futurist-retro
+
+- **Pitch:** Optimistic, technological, nostalgic-for-futures-past.
+- **Flagships:** Early-2000s tech branding, contemporary nostalgia revivals in fashion and music.
+- **Keywords:** chrome · bubble · glossy · iridescent.
+- **Fits:** dwell / interact (gaming / music / Gen Z contexts).
+- **BRICKS execution:**
+  - Bricks: chrome-treatment `Image` bricks (sourced or brand-anchored generated); pixel/bitmap font as `ApplicationFont` (Departure Mono, VT323) for HUD overlays; scan-line overlay `Rect` bricks at low opacity.
+  - Heroes: HUD frame chrome (scan-line overlay, corner brackets, status readout strip) — persistent across Canvases via shared id, the chrome *is* the throughline; content swaps inside the HUD.
+  - Theme tokens: chrome / iridescence, acid green, electric blue, hot pink. Heavy gradients but in a meant-to-be-retro way (declared as Data tokens, never default web gradients).
+  - Spacing scale: `2 / 6 / 12 gu` (HUD-style regular intervals).
+  - Grid stance: **lean** — HUDs are precise; the chrome stays orthogonal even when content goes psychedelic.
+  - Density rhythm: HUD frame is constant; inner content alternates between data-readout dense and hero-render isolate.
+  - Motion: HUD-style entrances, cursor / scanner animations via `Animation`, pseudo-CRT glow via `Rect` shadow tokens.
+  - Asset emphasis: chrome 3D renders, retro-tech imagery, bubble lettering.
+- **Wrong for:** trust-seeking finance, healthcare, enterprise.
+
+---
+
+## Combining language with archetype
+
+The picked language constrains *expression*. The picked archetype constrains *structure*. They multiply, but with constraints:
+
+| Archetype | Naturally fits | Resistant to |
+|---|---|---|
+| Glance | Swiss Editorial · Bauhaus · Kenya Hara · Brutalist web | Field.io (motion competes with glance) · Sagmeister (concept needs dwell) |
+| Browse | Magazine editorial · Risograph · Brutalist web · Dieter Rams | Field.io · Y2K (too much motion noise) |
+| Interact | Dieter Rams · Swiss Editorial · Brutalist web · Y2K (gaming) | Kenya Hara (precious quiet doesn't survive a tap) · Sagmeister (instability discourages decision) |
+| Transact | Dieter Rams · Swiss Editorial | Field.io · Sagmeister · Y2K · Risograph (trust deficit) |
+| Monitor | Swiss Editorial · Bauhaus · Brutalist web · Dieter Rams | Magazine editorial · Sagmeister (decoration distracts from data) |
+| Dwell | Field.io · Magazine editorial · Kenya Hara · Sagmeister · Y2K | (any of the above can dwell; least natural is Brutalist web) |
+
+When the user picks an awkward combination ("transact + Sagmeister"), surface the tension explicitly. Either talk them into the natural pairing, or commit hard to the awkward one as a deliberate brand statement — but don't middle-ground it into mush.
+
+## Adapting and inventing
+
+The 10 directions are anchors. Real work often blends — "Kenya Hara emptiness with one Risograph spot-color accent for the call-to-action" is a legitimate combination if executed deliberately. What's not legitimate is blending three to dilute commitment.
+
+When inventing a direction not in the library: write its system declaration block as if it were one of the entries above (pitch / flagship / keywords / fits / BRICKS execution / wrong-for). If you can't, the direction isn't real yet — keep working on it before committing.

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

@@ -0,0 +1,116 @@
+# Performance
+
+Second-order rules that keep a BRICKS Application fast on the actual hardware it deploys to (typically lower-spec than the developer's laptop) and resilient across watchdog reboots and offline windows.
+
+## Throttle at the Generator boundary
+
+A high-frequency source (sensor publishing at 100 Hz, MQTT firehose, LLM token stream) written directly to Data will fire `update` / `valueChange` events on every write. Every bound Brick re-renders. Every dependent DataCalc re-runs. The canvas chokes.
+
+**Throttle / aggregate inside the Generator**, not after.
+
+- For sensor / MQTT: cap the published rate in the Generator (sample to 1–10 Hz, or only emit on Δ).
+- For LLM streaming: write progressive deltas, but emit a `complete` event at the end and let downstream chains key off completion.
+- For HTTP polling: respect a backoff; don't re-emit identical payloads.
+
+If the source is upstream of you (a Generator template you can't modify), insert a buffering DataCalc that publishes to a downstream Data on a rate-limited schedule.
+
+## Bound Data history explicitly
+
+Data is not a time-series store. If a design needs "the last N values" (a chart series, recent log lines, a conversation history), keep an explicitly bounded array.
+
+- Use an `Iterator` Generator or a DataCalc that pushes new values and trims the head when length exceeds the cap.
+- Pick the cap to fit the *visible* need, not "for safety" — 60 points for a 60-second chart, not 10 000.
+- Unbounded arrays are a slow memory leak that watchdog will eventually paper over by killing the Application — and the user will see a reset they don't understand.
+
+For longer-term history, push to a backend (Remote Data Bank, GraphQL, HTTP) via a separate Generator and treat the Data side as a recent-window cache.
+
+## `persistData: true` is for survival, not state
+
+`Data.persistData: true` causes the Data value to be persisted across launcher restarts. This is the right knob for:
+
+- Last-known-good content (the most recent fetched menu, the last cached weather payload).
+- Idempotency keys generated at flow start.
+- Locale preference and other long-lived configuration.
+
+It is the *wrong* knob for transient flow state. A half-completed kiosk flow that survives a watchdog reset stuck in the middle is worse than a clean reset to Welcome. Default Path: keep flow Data ephemeral; reset on boot Canvas enter.
+
+## Boot Canvas must render in < 1 second using only cached/persisted Data
+
+The boot Canvas is what the user sees on cold start, after a watchdog reset, after every fleet-managed reboot. It must:
+
+- Render *something* immediately, with no Generator success required.
+- Read from cached / persisted Data only — no synchronous network dependencies.
+- Provide a self-recovery path (Cancel / Restart accessible from any deeper Canvas) so users stuck in a half-completed Subspace can always return.
+- Reset all transient flow Data and Subspace state on entry.
+
+**Failure mode:** boot Canvas waits for an HTTP fetch to render its content; user sees a blank screen on offline cold boot.
+
+## `renderOutOfViewport: false` for legitimate off-grid Bricks
+
+By default the runtime auto-culls Bricks fully outside the grid. For Bricks that intentionally sit partly off-grid (overflow effects, anchored at origin) the in-viewport portion still renders.
+
+If you have a Brick that is *entirely* off-grid for design reasons (a parked element that animates in via Switch / DynamicAnimation), set `renderOutOfViewport: false` to make the cull explicit and reduce per-frame cost on canvases with many such elements.
+
+For Bricks that are off-grid only momentarily during a transition, leave the default — culling mid-tween causes flicker.
+
+## Brick count discipline
+
+Every Brick on a Canvas costs render budget; off-screen-but-on-Canvas Bricks still cost something. Lists of 100 small text Bricks for a daily schedule will outrun a low-spec signage panel.
+
+- Prefer **Items** Brick (virtualized) over hand-laid lists of repeating Bricks.
+- Prefer **fewer-bigger** decorative Bricks over **many-tiny** ones for purely visual texture.
+- Composite tiles often work better as a single Slideshow / Items frame than as N hand-positioned Brick groups per Canvas.
+
+## Offline-first wrap on every networked Generator
+
+The standard wrap for any Generator that touches the network:
+
+1. **Cache layer** — read from local cache (DataBank, File Generator, persisted Data) before / instead of hitting network.
+2. **Fetch layer** — when network is up, fetch and update cache; emit `data updated` event.
+3. **Queue layer** — for writes (form submissions, payments), queue locally on offline; flush on reconnect with idempotency keys.
+4. **Status layer** — expose `network.online` and `data.lastSyncedAt` Data values for the UI to surface.
+
+Default canvases read from the cache. Live fetches happen out-of-band; their results land in cache and trigger re-render via Data events.
+
+**Failure mode:** a Generator that fetches synchronously on Canvas enter and renders blank on failure. Every networked Generator without this wrap is an outage waiting to ship.
+
+## Media in Media Flow is local-first — image/video/Lottie/Rive does NOT break offline
+
+A common misread of "offline-first" is that media-rich designs (lots of images, video loops, Lottie / Rive animations, brand reels) are dangerous for offline deployments. **They are not.** Media bound through Media Flow is **preloaded** to the device at boot (or background-synced when Media Flow content updates) and served from local storage thereafter. Once cached, the media is available with no network at all — that is the whole point of Media Flow.
+
+The mechanism:
+
+- Each Media Flow asset is referenced from the Subspace by a Data of `kind: { type: 'media-resource-image' | 'media-resource-video' | 'lottie-file-uri' | 'rive-file-uri' | ... }` with a `preload: { type: 'url', hashType, hash }` block.
+- The runtime's preload pass downloads every media asset referenced by the Application before letting the boot Canvas activate (or during a controlled progress state), and verifies integrity via the hash.
+- Subsequent renders read from the local cache; the original URL is no longer needed.
+- Cache survives watchdog restarts and reboots; `Application.runtimeCacheOptions` controls the policy.
+
+Implications for design:
+
+- **You can build heavy, image-rich, motion-heavy, video-driven Applications for fully-offline kiosks and signage.** The deployment doesn't lose anything by being offline; it loses something only if media isn't bound through Media Flow.
+- **Brick templates that consume Media Flow assets — Image, Video, Slideshow, Lottie, Rive, GenerativeMedia source bricks — are offline-safe by default**, as long as their `source` (or equivalent) binds to a Media Flow Data with `preload` metadata, not to an arbitrary external URL referenced inline.
+- **The offline-first wrap above is for Generators producing dynamic / runtime data** — current menu, train times, sensor readings, LLM responses, server-fed inventory. Not for design-time media. Don't conflate the two.
+- **Do not** drop image / video / motion bricks "to be safe for offline". The result is generic, text-only design that loses the brand and the polish for no real gain.
+
+The two failure modes to actually worry about:
+
+1. **Inline URLs that bypass Media Flow.** A Brick prop set to a literal `https://...` image URL is fetched at render time; offline = blank. Bind via Media Flow Data, not inline strings. (Truth #2 + the asset protocol enforce this structurally.)
+2. **Generators that fetch *content* synchronously**, even when the bricks displaying that content are bound through Media Flow. The content fetch is what fails, not the rendering. Wrap those Generators per the section above.
+
+When unsure: ask "is this binary baked into the Application via Media Flow, or fetched at runtime from a server?" The first is offline-safe automatically; the second needs the wrap.
+
+## DataCalc trigger discipline
+
+`triggerMode: 'auto'` reruns the calc on every input change. With multiple inputs and multiple downstream consumers, an `auto` calc can fire dozens of times per logical update.
+
+- Use `auto` only when the calc is cheap and the consumers genuinely want every result.
+- For expensive calcs (collection reductions, large object transforms), use `manual` and trigger explicitly via `PROPERTY_BANK_COMMAND` from the relevant event chain.
+- Watch for circular dependencies: A's output is B's input is A's input. Auto mode will spin.
+
+## Animation budget
+
+Standby Transitions are nearly free. Continuous `loop` animations are not.
+
+- Reserve `runType: 'loop'` for genuine attention-draws: alarm pulse, recording-active indicator, "scan in progress" hint.
+- A Canvas with 5+ looping animations on idle bricks burns frame budget for no design payoff.
+- One orchestrated canvas-enter (staggered standby reveals) creates more delight than six scattered loops.