@fugood/bricks-project 2.24.10 → 2.24.12

package/compile/index.ts

@@ -720,6 +720,17 @@ const compileAutomation = (automationMap: AutomationMap) =>
     }),
   )
 
+const buildDefaultExpandedState = (subspace: Subspace) => ({
+  brick: false,
+  generator: true,
+  canvas: (subspace.canvases || []).reduce((acc, canvas) => {
+    if (canvas?.id) acc[canvas.id] = false
+    return acc
+  }, {}),
+  property_bank: false,
+  property_bank_calc: true,
+})
+
 export const compile = async (app: Application) => {
   await new Promise((resolve) => setImmediate(resolve, 0))
   const timestamp = Date.now()
@@ -800,7 +811,7 @@ export const compile = async (app: Application) => {
               property_bank: !subspace.unexpanded.data,
               property_bank_calc: !subspace.unexpanded.dataCalculation,
             }
-          : undefined,
+          : buildDefaultExpandedState(subspace),
         layout: {
           width: subspace.layout?.width,
           height: subspace.layout?.height,

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@fugood/bricks-project",
-  "version": "2.24.10",
+  "version": "2.24.12",
   "main": "index.ts",
   "scripts": {
     "typecheck": "tsc --noEmit",
     "build": "bun scripts/build.js"
   },
   "dependencies": {
-    "@fugood/bricks-cli": "^2.24.10",
+    "@fugood/bricks-cli": "^2.24.12",
     "@huggingface/gguf": "^0.3.2",
     "@iarna/toml": "^3.0.0",
     "@modelcontextprotocol/sdk": "^1.15.0",

package/package.json.bak

@@ -1,13 +1,13 @@
 {
   "name": "@fugood/bricks-ctor",
-  "version": "2.24.10",
+  "version": "2.24.12",
   "main": "index.ts",
   "scripts": {
     "typecheck": "tsc --noEmit",
     "build": "bun scripts/build.js"
   },
   "dependencies": {
-    "@fugood/bricks-cli": "^2.24.10",
+    "@fugood/bricks-cli": "^2.24.12",
     "@huggingface/gguf": "^0.3.2",
     "@iarna/toml": "^3.0.0",
     "@modelcontextprotocol/sdk": "^1.15.0",

package/skills/bricks-ctor/SKILL.md

@@ -26,6 +26,7 @@ This skill covers advanced BRICKS features not in the main project instructions.
 
 - **Complex flows**: See [Architecture Patterns](references/architecture-patterns.md) for decomposing multi-step workflows
 - **Multi-device**: See [Local Sync](references/local-sync.md) for LAN coordination
+- **Fonts**: See [Font Families](references/fonts.md) for supported `fontFamily` names, native fallback behavior, and Google Font fallback guidance
 - **Cloud data**: See [Remote Data Bank](references/remote-data-bank.md) for sync and API access
 - **Media assets**: See [Media Flow](references/media-flow.md) for centralized asset management
 - **AI offloading**: See [Buttress](references/buttress.md) for GPU server delegation

package/skills/bricks-ctor/references/fonts.md

@@ -0,0 +1,322 @@
+# Font Families
+
+Use this when choosing or answering questions about `fontFamily` for Text, TextInput, RichText, or nested Items text Bricks.
+
+## Runtime Rules
+
+- Use exact family names from the target platform list; BRICKS matches comma-separated fallbacks left-to-right on native platforms.
+- Prefer cross-platform stacks such as `Arial, sans-serif`, `Helvetica, Roboto, sans-serif`, `Times New Roman, serif`, or `Courier New, monospace` when the same project runs on iOS/tvOS and Android.
+- Android supports generic system families plus `Roboto`; iOS/tvOS use the larger built-in Apple font set below.
+- Web keeps the supplied CSS font-family value. Native ignores unsupported names unless a dynamically loaded or Google Font preload resolves them.
+- Google Fonts can be used by setting a Google font family and letting the config preload path materialize it; keep a platform fallback after it, for example `Roboto Mono, monospace`.
+
+## Android
+
+- normal
+- notoserif
+- sans-serif
+- sans-serif-light
+- sans-serif-thin
+- sans-serif-condensed
+- sans-serif-medium
+- serif
+- Roboto
+- monospace
+
+## iOS/tvOS
+
+- San Francisco
+- Academy Engraved LET
+- AcademyEngravedLetPlain
+- Al Nile
+- AlNile-Bold
+- American Typewriter
+- AmericanTypewriter-Bold
+- AmericanTypewriter-Condensed
+- AmericanTypewriter-CondensedBold
+- AmericanTypewriter-CondensedLight
+- AmericanTypewriter-Light
+- Apple Color Emoji
+- Apple SD Gothic Neo
+- AppleColorEmoji
+- AppleSDGothicNeo-Bold
+- AppleSDGothicNeo-Light
+- AppleSDGothicNeo-Medium
+- AppleSDGothicNeo-Regular
+- AppleSDGothicNeo-SemiBold
+- AppleSDGothicNeo-Thin
+- AppleSDGothicNeo-UltraLight
+- Arial
+- Arial Hebrew
+- Arial Rounded MT Bold
+- Arial-BoldItalicMT
+- Arial-BoldMT
+- Arial-ItalicMT
+- ArialHebrew
+- ArialHebrew-Bold
+- ArialHebrew-Light
+- ArialMT
+- ArialRoundedMTBold
+- Avenir
+- Avenir Next
+- Avenir Next Condensed
+- Avenir-Black
+- Avenir-BlackOblique
+- Avenir-Book
+- Avenir-BookOblique
+- Avenir-Heavy
+- Avenir-HeavyOblique
+- Avenir-Light
+- Avenir-LightOblique
+- Avenir-Medium
+- Avenir-MediumOblique
+- Avenir-Oblique
+- Avenir-Roman
+- AvenirNext-Bold
+- AvenirNext-BoldItalic
+- AvenirNext-DemiBold
+- AvenirNext-DemiBoldItalic
+- AvenirNext-Heavy
+- AvenirNext-HeavyItalic
+- AvenirNext-Italic
+- AvenirNext-Medium
+- AvenirNext-MediumItalic
+- AvenirNext-Regular
+- AvenirNext-UltraLight
+- AvenirNext-UltraLightItalic
+- AvenirNextCondensed-Bold
+- AvenirNextCondensed-BoldItalic
+- AvenirNextCondensed-DemiBold
+- AvenirNextCondensed-DemiBoldItalic
+- AvenirNextCondensed-Heavy
+- AvenirNextCondensed-HeavyItalic
+- AvenirNextCondensed-Italic
+- AvenirNextCondensed-Medium
+- AvenirNextCondensed-MediumItalic
+- AvenirNextCondensed-Regular
+- AvenirNextCondensed-UltraLight
+- AvenirNextCondensed-UltraLightItalic
+- Bangla Sangam MN
+- Baskerville
+- Baskerville-Bold
+- Baskerville-BoldItalic
+- Baskerville-Italic
+- Baskerville-SemiBold
+- Baskerville-SemiBoldItalic
+- Bodoni 72
+- Bodoni 72 Oldstyle
+- Bodoni 72 Smallcaps
+- Bodoni Ornaments
+- BodoniOrnamentsITCTT
+- BodoniSvtyTwoITCTT-Bold
+- BodoniSvtyTwoITCTT-Book
+- BodoniSvtyTwoITCTT-BookIta
+- BodoniSvtyTwoOSITCTT-Bold
+- BodoniSvtyTwoOSITCTT-Book
+- BodoniSvtyTwoSCITCTT-Book
+- Bradley Hand
+- BradleyHandITCTT-Bold
+- Chalkboard SE
+- ChalkboardSE-Bold
+- ChalkboardSE-Light
+- ChalkboardSE-Regular
+- Chalkduster
+- Cochin
+- Cochin-Bold
+- Cochin-BoldItalic
+- Cochin-Italic
+- Copperplate
+- Copperplate-Bold
+- Copperplate-Light
+- Courier
+- Courier New
+- Courier-Bold
+- Courier-BoldOblique
+- Courier-Oblique
+- CourierNewPS-BoldItalicMT
+- CourierNewPS-BoldMT
+- CourierNewPS-ItalicMT
+- CourierNewPSMT
+- Damascus
+- DamascusBold
+- DamascusLight
+- DamascusMedium
+- DamascusSemiBold
+- Devanagari Sangam MN
+- DevanagariSangamMN
+- DevanagariSangamMN-Bold
+- Didot
+- Didot-Bold
+- Didot-Italic
+- DiwanMishafi
+- Euphemia UCAS
+- EuphemiaUCAS-Bold
+- EuphemiaUCAS-Italic
+- Farah
+- Futura
+- Futura-CondensedExtraBold
+- Futura-CondensedMedium
+- Futura-Medium
+- Futura-MediumItalic
+- Geeza Pro
+- GeezaPro-Bold
+- Georgia
+- Georgia-Bold
+- Georgia-BoldItalic
+- Georgia-Italic
+- Gill Sans
+- GillSans-Bold
+- GillSans-BoldItalic
+- GillSans-Italic
+- GillSans-Light
+- GillSans-LightItalic
+- GillSans-SemiBold
+- GillSans-SemiBoldItalic
+- GillSans-UltraBold
+- Gujarati Sangam MN
+- GujaratiSangamMN
+- GujaratiSangamMN-Bold
+- Gurmukhi MN
+- GurmukhiMN-Bold
+- Heiti SC
+- Heiti TC
+- Helvetica
+- Helvetica Neue
+- Helvetica-Bold
+- Helvetica-BoldOblique
+- Helvetica-Light
+- Helvetica-LightOblique
+- Helvetica-Oblique
+- HelveticaNeue-Bold
+- HelveticaNeue-BoldItalic
+- HelveticaNeue-CondensedBlack
+- HelveticaNeue-CondensedBold
+- HelveticaNeue-Italic
+- HelveticaNeue-Light
+- HelveticaNeue-LightItalic
+- HelveticaNeue-Medium
+- HelveticaNeue-MediumItalic
+- HelveticaNeue-Thin
+- HelveticaNeue-ThinItalic
+- HelveticaNeue-UltraLight
+- HelveticaNeue-UltraLightItalic
+- Hiragino Mincho ProN
+- Hiragino Sans
+- HiraginoSans-W3
+- HiraginoSans-W6
+- HiraMinProN-W3
+- HiraMinProN-W6
+- Hoefler Text
+- HoeflerText-Black
+- HoeflerText-BlackItalic
+- HoeflerText-Italic
+- HoeflerText-Regular
+- Iowan Old Style
+- IowanOldStyle-Bold
+- IowanOldStyle-BoldItalic
+- IowanOldStyle-Italic
+- IowanOldStyle-Roman
+- Kailasa
+- Kailasa-Bold
+- Kannada Sangam MN
+- KannadaSangamMN
+- KannadaSangamMN-Bold
+- Khmer Sangam MN
+- Kohinoor Bangla
+- Kohinoor Devanagari
+- Kohinoor Telugu
+- KohinoorBangla-Light
+- KohinoorBangla-Regular
+- KohinoorBangla-Semibold
+- KohinoorDevanagari-Light
+- KohinoorDevanagari-Regular
+- KohinoorDevanagari-Semibold
+- KohinoorTelugu-Light
+- KohinoorTelugu-Medium
+- KohinoorTelugu-Regular
+- Lao Sangam MN
+- Malayalam Sangam MN
+- MalayalamSangamMN
+- MalayalamSangamMN-Bold
+- Marker Felt
+- MarkerFelt-Thin
+- MarkerFelt-Wide
+- Menlo
+- Menlo-Bold
+- Menlo-BoldItalic
+- Menlo-Italic
+- Menlo-Regular
+- Mishafi
+- Noteworthy
+- Noteworthy-Bold
+- Noteworthy-Light
+- Optima
+- Optima-Bold
+- Optima-BoldItalic
+- Optima-ExtraBlack
+- Optima-Italic
+- Optima-Regular
+- Oriya Sangam MN
+- OriyaSangamMN
+- OriyaSangamMN-Bold
+- Palatino
+- Palatino-Bold
+- Palatino-BoldItalic
+- Palatino-Italic
+- Palatino-Roman
+- Papyrus
+- Papyrus-Condensed
+- Party LET
+- PartyLetPlain
+- PingFang HK
+- PingFang SC
+- PingFang TC
+- PingFangHK-Light
+- PingFangHK-Medium
+- PingFangHK-Regular
+- PingFangHK-Semibold
+- PingFangHK-Thin
+- PingFangHK-Ultralight
+- PingFangSC-Light
+- PingFangSC-Medium
+- PingFangSC-Regular
+- PingFangSC-Semibold
+- PingFangSC-Thin
+- PingFangSC-Ultralight
+- PingFangTC-Light
+- PingFangTC-Medium
+- PingFangTC-Regular
+- PingFangTC-Semibold
+- PingFangTC-Thin
+- PingFangTC-Ultralight
+- Savoye LET
+- SavoyeLetPlain
+- Sinhala Sangam MN
+- SinhalaSangamMN
+- SinhalaSangamMN-Bold
+- Snell Roundhand
+- SnellRoundhand-Black
+- SnellRoundhand-Bold
+- Symbol
+- Tamil Sangam MN
+- TamilSangamMN-Bold
+- Telugu Sangam MN
+- Thonburi
+- Thonburi-Bold
+- Thonburi-Light
+- Times New Roman
+- TimesNewRomanPS-BoldItalicMT
+- TimesNewRomanPS-BoldMT
+- TimesNewRomanPS-ItalicMT
+- TimesNewRomanPSMT
+- Trebuchet MS
+- Trebuchet-BoldItalic
+- TrebuchetMS-Bold
+- TrebuchetMS-Italic
+- Verdana
+- Verdana-Bold
+- Verdana-BoldItalic
+- Verdana-Italic
+- Zapf Dingbats
+- ZapfDingbatsITC
+- Zapfino

package/skills/bricks-ctor/references/media-flow.md

@@ -31,6 +31,7 @@ const mediaListGenerator: GeneratorMediaFlow = {
   description: '',
   property: {
     boxId: 'promo-box-id',
+    passcode: 'box-read-only-passcode',
   },
   outlets: {
     files: () => promoFilesData, // Array of file objects
@@ -40,6 +41,12 @@ const mediaListGenerator: GeneratorMediaFlow = {
 }
 ```
 
+When hand-writing `GENERATOR_MEDIA_FLOW`, do not use a bare `boxId`. The editor
+flow creates the required authorization, but manual config must include either
+`property.passcode` from a Media Box passcode or `property.accessToken`.
+Without one, devices cannot read the box and the generator will report an
+authorization error.
+
 ## Property Kinds for Media
 
 Link Data properties to Media Flow for asset selection:

package/skills/bricks-ctor/references/verification-toolchain.md

@@ -26,6 +26,15 @@ What does **not** count as done:
 
 If any item is unmet, the work is mid-iteration. Say so explicitly to the user; offer a precise list of what remains.
 
+## Debug loop discipline
+
+Before cycling on a runtime or Automation bug, establish what you can observe. A green or red Automation alone is often not enough to explain a race or branch miss.
+
+- Use one repeatable probe at a time: DevTools state/storage/runtime reads, network/console output, Automation screenshots, or a targeted screenshot after a known event.
+- If branch execution or race timing is unclear, add the smallest temporary log/trace point in the relevant data-calculation script, event handler, or generator path, then compile and rerun the same probe.
+- Do not bounce between CLI, DevTools, and Automation without a hypothesis. State what signal will prove or disprove the next fix before changing code again.
+- Remove temporary traces before declaring done, unless the user asked for persistent diagnostics or the trace is intentionally part of the fix.
+
 ## Path 1 — Electron preview (no device required)
 
 The default loop. Always available; deterministic; no device wear; safe for side-effecting flows because nothing real fires.

package/skills/bricks-design/SKILL.md

@@ -2,7 +2,7 @@
 name: bricks-design
 description: >-
   Visual design discipline for Applications and Subspaces — type, palette, asset
-  acquisition, design language, system commitment, visual rhythm, brand. TRIGGER
+  acquisition, design language, DESIGN.md system, visual rhythm, brand. TRIGGER
   for visual / aesthetic / system / style / brand-asset work even when named in
   product terms — slideshow, pitch deck, explainer, kiosk, signage, menu board,
   lobby, wayfinding, retail, museum, transit; translate or rebuild from Figma /
@@ -40,7 +40,8 @@ How to inspect, by source type:
 - **Website / docs site URL** — drive a browser automation tool (browser-MCP, Playwright/Puppeteer-style MCP server, `agent-browser`-equivalent skill, or any host-provided browser tool). Visit the home page, every primary navigation entry, every page the user explicitly named, and every page that looks like it carries the brand's visual signature (hero, product, gallery, customers). Capture a full-page screenshot of each. Then read each screenshot back via the host's image-reading capability so you actually *see* it. If no browser automation is available, ask the user for screenshots before proceeding.
 - **Figma / design-tool link** — use a Figma-MCP / design-tool MCP if available to enumerate every frame and image-export each; otherwise ask the user for PNG exports of every frame. Inspect each image.
 - **HTML project on disk** — serve and screenshot every route via a browser tool, the same way as a public URL. Don't infer visuals from the source HTML/CSS.
-- **PDF / brand book / slide deck** — read every page via the host's PDF-reading capability (page-by-page if the document is long). Do not summarize from a text extraction.
+- **PDF / brand book / slide deck** — read every page via the host's PDF-reading capability (page-by-page if the document is long). Do not summarize from a text extraction. If the host only exposes a cover preview or has no PDF capability, use an installed PDF skill when available. If no PDF skill or local PDF tool is installed and you cannot inspect the PDF fully, stop and respond in chat with the limitation instead of designing from partial evidence. Never proceed from only page 1.
+- **Large rendered PDF pages** — do not hand the vision tool 4-13 MB page PNGs and call the PDF unreadable. Downsample to inspection-sized JPEG/PNG previews, split long PDFs into page batches, and keep a page coverage checklist so every page is either inspected or explicitly marked inaccessible.
 - **Local images / screenshots** — read each one via the image-reading tool.
 - **Video walkthrough** — ask the user to provide key-frame screenshots, or to describe each state explicitly. Do not claim to "watch" a video you cannot actually frame-step.
 
@@ -55,7 +56,7 @@ Pass-based delivery, not sprint-to-finished. Full discipline in [`references/wor
    - Branded brief → [`references/when-the-brief-is-branded.md`](references/when-the-brief-is-branded.md) (Media Flow protocol).
    - Figma / HTML / screenshot input → [`references/translating-inputs.md`](references/translating-inputs.md).
    - Presentation / slideshow / intro / explainer / storyboard → [`references/presentation-and-slideshow.md`](references/presentation-and-slideshow.md) (Canvas-graph shape decision, hero continuity).
-2. **Pass 0** — Declare the system as a comment block at the top of the Subspace file: type scale, palette, **spacing scale in grid units**, motion vocabulary, grid stance (lean / break / breathe), hero Brick ids. The grid substrate is given by the runtime (Truth #6); the design decisions sit on top.
+2. **Pass 0** — Write the project's [`DESIGN.md`](references/design-md.md): named tokens in the frontmatter (type scale, palette, **spacing scale in grid units**, motion vocabulary, grid stance, hero Brick ids) plus Deployment Context and the Visual Theme section. The grid substrate is given by the runtime (Truth #6); the design decisions sit on top. The Subspace file carries only a one-line pointer to DESIGN.md; every Brick cites its tokens by name.
 3. **Pass 1 — Showcase Canvas lockdown.** Build one Canvas fully lit, verify, show the user. This is the cheapest moment to redirect; do not build the full Canvas graph before sign-off.
 4. **Pass 2** — Build out the full Canvas graph with hero ids shared across Canvases (Truth #3 as narrative principle). Mid-review checkpoint partway through.
 5. **Pass 3** — Polish: spacing-scale adherence, density rhythm, Standby Transition vocabulary consistent, multilingual fits.
@@ -79,7 +80,7 @@ The load-bearing laws. Each is unpacked in [`references/architecture-truths.md`]
 
 ## Commit to a design language
 
-A BRICKS Application that doesn't commit to a design language reads as generic regardless of how well it runs. After Direction Advisor (or directly, when the brief is concrete enough), pick a visual language from [`references/design-languages.md`](references/design-languages.md) — Swiss Editorial / Kenya Hara emptiness / Field.io motion poetics / Brutalist web / Y2K futurist-retro / etc. — and write its system declaration as a comment block at the top of the Subspace file. Every subsequent choice cites the block; adding a value not in the block requires updating the block first. That's what makes the system structural rather than aspirational.
+A BRICKS Application that doesn't commit to a design language reads as generic regardless of how well it runs. After Direction Advisor (or directly, when the brief is concrete enough), pick a visual language from [`references/design-languages.md`](references/design-languages.md) — Swiss Editorial / Kenya Hara emptiness / Field.io motion poetics / Brutalist web / Y2K futurist-retro / etc. — and commit it as named tokens in the project's [`DESIGN.md`](references/design-md.md). Every subsequent choice cites a token by name; adding a value not already in the tokens requires adding the token first. That's what makes the system structural rather than aspirational.
 
 The commitment principle: 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. Soften signature moves and you've abandoned the language for nowhere.
 
@@ -98,9 +99,9 @@ Two reference files cover the second-order rules. Read them when the design is n
 
 ## Asset discipline
 
-Brand work succeeds or fails on assets, not on colors. Logo, product photography, UI screenshots, scene photography, and motion assets are first-class — colors and fonts are auxiliary. Acquire them through the protocol in [`references/when-the-brief-is-branded.md`](references/when-the-brief-is-branded.md): five steps, the 5-10-2-8 quality bar with five named scoring dimensions, three fallback paths per asset category, and structural enforcement that Bricks reference Media Flow Data via DataLink rather than embed, redraw, or skip.
+Brand work succeeds or fails on assets, not on colors. Logo, product photography, UI screenshots, scene photography, and motion assets are first-class — colors and fonts are auxiliary. Acquire them through the protocol in [`references/when-the-brief-is-branded.md`](references/when-the-brief-is-branded.md): five steps, the 5-10-2-8 quality bar with five named scoring dimensions, three fallback paths per asset category, and structural enforcement that Bricks reference Media Flow Data via DataLink rather than embed, redraw, or skip. The acquired assets, scores, and bindings land in the **Assets & Brand** sections of [`DESIGN.md`](references/design-md.md) — one artifact, not a separate brand spec.
 
-When an asset category genuinely cannot be acquired and the user has no plan to provide one, the priority is: stop and ask (always for logo) → compose the host environment's image / motion generators (canvas-design / imagen / generative MCP), brand-reference-anchored, scored at the same bar → labeled placeholder with the gap tracked in `brand-spec.md`. **This skill does not duplicate generative or composition skills — it composes them.** Where the host has none, surface the constraint to the user; don't silently degrade.
+When an asset category genuinely cannot be acquired and the user has no plan to provide one, the priority is: stop and ask (always for logo) → compose the host environment's image / motion generators (canvas-design / imagen / generative MCP), brand-reference-anchored, scored at the same bar → labeled placeholder with the gap tracked under DESIGN.md's **Gaps & placeholders**. **This skill does not duplicate generative or composition skills — it composes them.** Where the host has none, surface the constraint to the user; don't silently degrade.
 
 ## Anti-slop, terse
 
@@ -130,7 +131,7 @@ Ship a one-paragraph trade-off note alongside so the user can pick or blend with
 
 A single hero-Canvas screenshot is **not** done. A "looks roughly like the reference" handwave is **not** done. A claim of done without screenshots in evidence is **not** done. If you have not produced and reviewed a screenshot of every Canvas, you are still mid-iteration and must say so explicitly to the user.
 
-**Self-critique pass before declaring done** — every Canvas scored on 5 dimensions (system commitment / visual hierarchy / craft / functional fit / originality), anti-slop top-10 swept clean, < 8 scores either fixed or surfaced as accepted trade-offs. See [`references/design-critique.md`](references/design-critique.md). Verification proves it runs; critique proves it's good — both required.
+**Self-critique pass before declaring done** — every Canvas scored on 5 dimensions (system commitment / visual hierarchy / craft / functional fit / originality), checked section by section against [`DESIGN.md`](references/design-md.md) (does every colour, gap, and motion in the render trace to a declared token?), anti-slop top-10 swept clean, < 8 scores either fixed or surfaced as accepted trade-offs. See [`references/design-critique.md`](references/design-critique.md). Verification proves it runs; critique proves it's good — both required.
 
 For the toolchain itself — `compile` / `preview` MCP usage, `bun preview` flags, Project Automation cases, on-device DevTools setup, the Path 1/2/3 decision rule, and per-deployment-shape verification checklists — see the `bricks-ctor` skill's `rules/verification-toolchain.md`.
 
@@ -150,6 +151,7 @@ Interaction / flow / journey / affordance / feedback / recovery / accessibility
 
 | When you need to... | Read |
 |---|---|
+| Write or update the project's design-system artifact (tokens, schema, brand merge) | [`references/design-md.md`](references/design-md.md) |
 | Decide when to ask vs build; pace the work across passes | [`references/workflow.md`](references/workflow.md) |
 | Deepen any of the 10 truths | [`references/architecture-truths.md`](references/architecture-truths.md) |
 | Tune for performance / offline | [`references/performance.md`](references/performance.md) |

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

@@ -20,19 +20,19 @@ If a dimension cannot be scored ≥ 8 within the deployment's constraints, surfa
 
 ### 1. System commitment
 
-*Does the work cite the declared system (the comment block at the top of the Subspace), and does deviation have rationale?*
+*Does the work cite the declared system (the named tokens in `DESIGN.md`), 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. |
+| 9–10 | Every brick property points back to a DESIGN.md token, a Data token, or an `ApplicationFont` entry. 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. |
+| 3–4 | DESIGN.md is decorative; the work doesn't follow it. |
+| 1–2 | No DESIGN.md, or its tokens contradict 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.
+- Open DESIGN.md. Pick five tokens 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 a DESIGN.md token 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
@@ -67,7 +67,7 @@ If a dimension cannot be scored ≥ 8 within the deployment's constraints, surfa
 
 **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).
+- **Spacing-scale adherence.** Open DESIGN.md. Read the declared `spacing` tokens (e.g., `gap-s 2 / gap-m 4 / gap-l 8 / margin 8`). 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.
@@ -155,7 +155,7 @@ Walk this list every time. Each is a pattern that consistently slips into agent-
 **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).)
+**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 DESIGN.md's Assets & Brand. (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)
 

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

@@ -35,25 +35,31 @@ If you find yourself softening signature moves to "make it more accessible" —
 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
- */
+## Style declaration ritual — into DESIGN.md
+
+After the direction is picked, commit the system as named tokens in the project's [`DESIGN.md`](design-md.md) frontmatter (full schema there). Every subsequent choice cites a token by name; adding a value not already in the tokens requires adding the token first — that's what makes the system structural rather than aspirational.
+
+```yaml
+system: Swiss Editorial (Pentagram lineage)
+archetype: glance
+colors:
+  ink: "#1A1A1A"      # body text — never pure black
+  ground: "#F5F0E6"   # default Canvas background
+  accent: "#FF3C00"   # callouts only — one per Canvas
+type:                 # sizes in grid units
+  display: { family: "<Brand Sans>", size: 16, weight: 400 }
+  heading: { family: "<Brand Sans>", size: 8,  weight: 400 }
+  body:    { family: "<Brand Sans>", size: 4,  weight: 400 }
+spacing: { gap-s: 2, gap-m: 4, gap-l: 8, margin: 8 }   # inter-Brick gaps come only from here
+grid: lean            # strict alignment, generous margins
+motion:
+  entrance: { ease: ease-out, ms: 280 }
+  exit:     { ease: ease-in,  ms: 180 }
+  loops: none
+heroes: [brand-logo, folio-num]   # persist across Canvases → auto-tween (Truth #3)
 ```
 
-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.
+The grid itself is given by the runtime (Truth #6). What the tokens commit 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. DESIGN.md is not for the runtime; it is for *you*, when you next consider adding a third colour or a fourth gap value. Its existence is what holds the line.
 
 ---
 
@@ -262,4 +268,4 @@ When the user picks an awkward combination ("transact + Sagmeister"), surface th
 
 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.
+When inventing a direction not in the library: write its system declaration into DESIGN.md 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.