@fugood/bricks-project 2.24.10 → 2.24.12

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

@@ -0,0 +1,225 @@
+# DESIGN.md — the project's design-system artifact
+
+Every BRICKS design project commits its system to a single durable file: **`DESIGN.md`**, at the project root. It is the source of truth for type, palette, spacing, motion, brand assets, and deployment context — written once in Pass 0, cited by every Brick afterward, and read back at the top of every later session.
+
+The format rests on four ideas:
+
+1. **One named, durable markdown artifact** — not a system scattered across code comments that dies with the file. Markdown is the format an agent reads best; there is nothing to parse.
+2. **Named tokens in YAML frontmatter, referenced by name in the prose.** Declare `accent` once; write `{colors.accent}` everywhere. The body never restates a raw hex or size — one place to change, no drift.
+3. **Real design depth, not surface tokens.** Each token carries its *role* (which colour is CTA vs. body vs. hairline) and the system carries its *signature moves* (the one gesture that makes it recognisable) and the *why* behind each rule.
+4. **An agent guide** that tells the next agent how to *use* the file.
+
+The nine-section schema below is the web-design convention reframed for BRICKS. BRICKS is a fixed-frame, grid-substrate, state-machine runtime, so three of the nine canonical sections are reframed rather than copied — see the mapping table. Importing web habits (breakpoints, scroll, CSS elevation) through this file is the fastest way to fight the runtime.
+
+## DESIGN.md replaces two older artifacts
+
+This file is the merge point for what earlier versions of this skill kept apart:
+
+- The **style-declaration comment block** at the top of the Subspace file → its tokens move into the DESIGN.md frontmatter. The Subspace comment shrinks to a one-line pointer (see [§ The Subspace pointer](#the-subspace-pointer)).
+- **`brand-spec.md`** → its asset bindings, score log, and gaps become the **Assets & Brand** sections of DESIGN.md. One artifact, not two. (The acquisition *protocol* still lives in [`when-the-brief-is-branded.md`](when-the-brief-is-branded.md); DESIGN.md is where its output lands.)
+
+A project has exactly one DESIGN.md. A multi-Subspace Application shares it; per-Subspace deviations are noted as scoped overrides inside it, never as a competing second file.
+
+## The nine sections, mapped to BRICKS
+
+| Web section | BRICKS section | Why it changes |
+|---|---|---|
+| Visual Theme & Atmosphere | **1. Visual Theme & Atmosphere** | Unchanged in spirit — adds the picked visual language × interaction archetype. |
+| Color Palette & Roles | **2. Colour Palette & Roles** | Colours used in 2+ places become theme-token Data bound via DataLink (Truth #2). |
+| Typography Rules | **3. Typography** | Sizes are **grid units**, not px. Families are `ApplicationFont` entries with a fallback ladder. |
+| Component Stylings | **4. Brick & Generator Stylings** | Bricks and Generators, not DOM components. Pressable affordance must read as visually distinct; Generators are headless/async (Truth #5). |
+| Layout Principles | **5. Grid, Spacing & Rhythm** | Frames are grid units (Truth #6). No scroll, overflow, or reflow (Truth #10). |
+| Depth & Elevation | **6. Motion, Standby & Depth** | No CSS z-index / box-shadow model. Depth = Brick draw order + Standby entrance offsets (Truth #7) + shared-id auto-tween (Truth #3). |
+| Do's and Don'ts | **7. Do's & Don'ts** | Each rule tied to what it protects; folds in this system's anti-slop. |
+| Responsive Behavior | **8. Hardware & Orientation** | **Not breakpoints.** Fixed target resolution + orientation; fleet variants are separate Canvas sets or device-scoped Data, never media queries. |
+| Agent Prompt Guide | **9. Agent Guide** | How to cite tokens, add tokens, and verify against this file. |
+
+Two BRICKS-native sections have no web equivalent and sit up front: **Deployment Context** (captures Priority #0 durably) and **Assets & Brand** (the merged `brand-spec.md`).
+
+## Token-reference discipline — the load-bearing habit
+
+This is what separates a system from an accumulation:
+
+- **Declare every reusable value as a named token in the frontmatter.** Reference it by name in the prose and in your reasoning: `{colors.ink}`, `{type.display}`, `{spacing.gap-m}`, `{heroes.brand-logo}`.
+- **Never restate a raw value in the body.** Writing `#1A1A1A` inline instead of `{colors.ink}` forks the source of truth; the next edit updates one and not the other.
+- **Adding a value not already in the tokens requires adding the token first.** Want a third colour or a fourth gap? Edit the frontmatter, then use it. The "first" is the whole mechanism — it forces a deliberate pause where averaging-toward-generic would otherwise sneak a value in.
+- **Sizes and gaps are in grid units (`gu`), never pixels.** The grid substrate is given by the runtime (Truth #6); the design sits on top of it.
+- **Shared colours (2+ uses) become theme-token Data** bound via DataLink, with the token name matching the DESIGN.md key. Single-use decorative colours may stay hardcoded (Truth #2 is loose by design).
+
+## The template
+
+Copy this verbatim into `DESIGN.md` and fill it. Every section is required; an empty section is a declared gap, not an omission.
+
+````markdown
+---
+name: <Application name> — design system
+system: <visual language, e.g. Swiss Editorial (Pentagram lineage)>
+archetype: <glance | browse | interact | transact | monitor | dwell>
+
+deployment:
+  hardware: <size · resolution · orientation · touch? · viewing distance>
+  scene: <where the screen lives, what the user does in front of it>
+  network: <always-on | intermittent | offline>
+  languages: [<en>, <...>]
+  peripherals: [<camera | BLE | MQTT | NFC | payment | printer | sensors | none>]
+  watchdog: <fleet-managed | single-instance>
+
+colors:            # role in the comment; hex is the value
+  ink: "#1A1A1A"        # body text — deep, never pure black
+  ground: "#F5F0E6"     # default Canvas background
+  accent: "#FF3C00"     # callouts only — at most one per Canvas
+  hairline: "#E3E0D6"   # 1gu rules and card edges
+  # forbidden: [<colours the brand explicitly never uses>]
+
+type:              # sizes in grid units (gu)
+  display: { family: "<Brand Sans>", size: 16, weight: 300, tracking: -0.02 }
+  heading: { family: "<Brand Sans>", size: 8,  weight: 400, tracking: 0 }
+  body:    { family: "<Brand Sans>", size: 4,  weight: 400, tracking: 0 }
+  caption: { family: "<Brand Sans>", size: 3,  weight: 400, tracking: 0 }
+
+spacing:           # inter-Brick gaps come ONLY from this set (gu)
+  gap-s: 2
+  gap-m: 4
+  gap-l: 8
+  margin: 8
+
+grid: lean         # lean (strict align, generous margin) | break | breathe
+
+motion:            # Standby Transition vocabulary (Truth #7)
+  entrance: { standbyMode: "<offset, e.g. translateY 4gu>", ease: ease-out, ms: 280, stagger: 40 }
+  exit:     { ease: ease-in, ms: 180 }
+  loops: <none | only on {brick-id}>
+
+heroes:            # Brick ids reused across Canvases → runtime auto-tweens them (Truth #3)
+  - brand-logo
+  - folio-num
+
+fonts:             # ApplicationFont entries → Application.applicationSettings.fonts
+  - { name: "<Brand Sans>", url: "<media-flow-or-cdn-url>", md5: "<optional>" }
+---
+
+# <Application name> — Design System
+> Captured: <YYYY-MM-DD> · Sources: <reference pages / Figma / brand book> · Coverage: <complete | partial | inferred>
+
+## Deployment Context
+The five Priority #0 facts in prose, plus peripherals and watchdog. Every visual
+decision below is downstream of these. If any of the first five was assumed rather
+than confirmed, mark it **ASSUMED** here so the next agent knows what to re-check.
+
+## 1. Visual Theme & Atmosphere
+What the system *says* in two or three sentences. Name the picked **visual language**
+and **interaction archetype**, then the **signature moves** — the one or two gestures
+that make this system recognisable at a glance (e.g. "oversized folio numerals + a
+single hairline rule per Canvas"). When unsure, commit *harder* to these, not softer.
+
+**Key characteristics:** 4–6 bullets, each a concrete, checkable rule.
+
+## 2. Colour Palette & Roles
+Each token by name with its job. Reference `{colors.<name>}` — never the raw hex.
+- `{colors.ink}` — body text on `{colors.ground}`. Deep charcoal, never pure black.
+- `{colors.accent}` — callouts and the single emphasis per Canvas. Never a body colour.
+- `{colors.hairline}` — 1gu rules, card edges.
+- Forbidden: <colours the brand never uses>, if any.
+Shared colours bind as theme-token Data; note which here.
+
+## 3. Typography
+- Families and the **fallback ladder** — what to substitute when the licensed font is
+  absent (e.g. "Söhne → Inter weight 300 + tracking -0.02"). Declared as `fonts` entries.
+- Each role (`{type.display}` … `{type.caption}`) with size in gu, weight, tracking,
+  and *where it is used*. Multilingual note: which scripts the families cover.
+
+## 4. Brick & Generator Stylings
+- **Pressable affordance** — how a tile that responds to a press looks different from a
+  decorative one. A pressable that looks identical to décor is a bug. (Wiring lives in
+  `bricks-ux`; the *visual* distinction lives here.)
+- **Hero Bricks** — the ids in `heroes`, what each is, and how it reads across Canvases.
+- **Generator-driven components** — list / chart / feed surfaces fed by a headless,
+  async Generator (Truth #5). Note their loading, empty, and error appearance.
+- **Media-bound Bricks** — every brand visual reads from Media Flow via DataLink (see
+  Assets & Brand); none is drawn, embedded, or set to a literal path.
+
+## 5. Grid, Spacing & Rhythm
+- **Grid stance** `{grid}` — lean / break / breathe, and what that means in margins.
+- **Spacing scale** — inter-Brick gaps come only from `{spacing.*}`. Ten gaps of
+  7/9/11/13 across siblings is arithmetic drift; snap to the scale.
+- **Density rhythm** — how consecutive Canvases vary (not three identical layouts).
+- **No scroll, overflow, or reflow** (Truth #10). What does not fit does not show;
+  design within the Canvas at the target resolution.
+
+## 6. Motion, Standby & Depth
+- **Standby Transition** `{motion.entrance}` / `{motion.exit}` — every visible Brick
+  gets an entrance offset; the runtime auto-tweens in-flight motion (Truth #7).
+- **Shared-id auto-tween** — heroes keep their id across Canvases so position/size
+  animate for free (Truth #3). This is the highest-leverage polish technique.
+- **Depth** is Brick draw order, not a z/shadow model. State the stacking intent.
+- **Snap-cuts** are reserved for emphasis (alarms), never routine navigation.
+
+## 7. Do's & Don'ts
+Each tied to what it protects. Examples:
+- **Do** reserve `{colors.accent}` for one emphasis per Canvas — sparingness is the signal.
+- **Don't** soften the signature moves "to be safe" — at 30% the language reads hesitant.
+- **Don't** introduce a gap outside `{spacing.*}` — add the token first or don't add it.
+
+## 8. Hardware & Orientation
+Not breakpoints — BRICKS frames are fixed.
+- **Target** resolution and orientation (from Deployment Context). The design is built
+  for this exact frame.
+- **Viewing distance → minimum legible size** in gu, especially for `glance` signage.
+- **Fleet variants** — if the same Application runs on differing resolutions, say how:
+  a separate Canvas set, or device-scoped Data — *not* a media query or reflow.
+- **Language fit** — longest-string behaviour; the design must hold without overflow.
+
+## 9. Agent Guide
+- Reference tokens by name (`{colors.accent}`, `{spacing.gap-m}`); never inline a raw value.
+- To add any value, add the token to the frontmatter first, then use it.
+- Default body to `{type.body}`; default gap to `{spacing.gap-m}`.
+- The Subspace's top comment points here; do not re-declare the system inline.
+- Before declaring done, the design-critique pass cites this file section by section,
+  and every Canvas screenshot is compared against the tokens here.
+
+## Assets & Brand
+(Merged brand spec — populated via the protocol in `when-the-brief-is-branded.md`.)
+
+### First-class assets
+- **Logo** — light / dark / mono → Media Flow IDs → Data keys (`brandLogoDark` …),
+  clearspace, minimum size, source.
+- **Product / UI / scene photography** (per brand type) → IDs → Data keys, each with
+  its 5-10-2-8 score `[R_ P_ B_ C_ N_ = _/10]`.
+- **Motion** — brand reel / animated logo → IDs → Data keys.
+
+### Voice & tone
+Register, capitalization, banned phrases — a constraint on every user-visible Data string.
+
+### Gaps & placeholders
+`<category>: <why missing> → <ask user | generate-with-anchor | accept placeholder> [as of <date>]`
+
+### Score log
+`<asset>: R_ P_ B_ C_ N_ = _/10` for every non-logo asset.
+````
+
+## The Subspace pointer
+
+The Subspace file no longer carries the full system as a comment. It carries a one-line pointer so a reader knows where the system lives and what it is at a glance:
+
+```ts
+/** System: Swiss Editorial · archetype: glance · tokens + assets in ../DESIGN.md */
+```
+
+If a Subspace genuinely needs a scoped deviation (a darker ground for a single monitoring Subspace, say), note the override inside DESIGN.md under that Subspace's name and point the comment at it — never fork a second system silently.
+
+## How DESIGN.md threads through the workflow
+
+- **Pass 0** writes DESIGN.md: frontmatter tokens + Deployment Context + section 1 at minimum. ([`workflow.md`](workflow.md))
+- **Picking a visual language** fills sections 1–3 and `system`/`archetype`. ([`design-languages.md`](design-languages.md))
+- **Branded work** fills Assets & Brand and the colour/type/voice tokens. ([`when-the-brief-is-branded.md`](when-the-brief-is-branded.md))
+- **Variations** are alternate token sets, expressed as a flat preset map keyed to these tokens, not a second DESIGN.md. ([`variations-and-tweaks.md`](variations-and-tweaks.md))
+- **Verification & critique** read DESIGN.md back and check the rendered Canvases against it section by section. ([`design-critique.md`](design-critique.md))
+
+## Anti-patterns specific to DESIGN.md
+
+- **Inlining raw values in the body** instead of `{token}` references — forks the source of truth.
+- **A breakpoint table** in section 8 — that is a web habit; BRICKS frames are fixed (Truth #10).
+- **A CSS-style elevation model** in section 6 — depth is draw order + Standby, not z-index/shadow.
+- **Two artifacts** — a `brand-spec.md` *and* a DESIGN.md, or per-Subspace system blocks competing with the file. One project, one DESIGN.md.
+- **Writing DESIGN.md after the Canvases** — it is a Pass 0 commitment that the build cites, not a doc written to describe finished work.
+- **Tokens with no roles** — `accent: "#FF3C00"` with no note on what it is for is a swatch, not a system. The role is the design depth.

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

@@ -20,13 +20,18 @@ How to inspect, by source type:
 | 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. |
+| 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. If the host only shows 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. |
 | 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.
 
+For PDF-derived page images, keep the artifacts sized for inspection. A giant
+4-13 MB PNG per page is a tool failure waiting to happen, not a useful
+handoff. Prefer downsampled JPEG/PNG previews, page batches, and a simple
+coverage checklist (`seen pages: 1-8 of 8`) before design work starts.
+
 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
@@ -128,7 +133,7 @@ When the source contains brand binaries, you are inheriting them — but only at
 - 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.**
+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 under DESIGN.md's **Gaps & placeholders** 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
 
@@ -136,6 +141,8 @@ Score everything against 5-10-2-8 before binding. If the source's brand binaries
 - 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.
 
+Extracted colors, type, and spacing become the named tokens in [`DESIGN.md`](design-md.md) (referenced by name thereafter), so the translated system is captured once rather than re-derived per Canvas.
+
 ### 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.

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

@@ -26,7 +26,7 @@ Use when variations differ only on values: palette, copy, asset paths, density f
 **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.
+- Source has a `VARIATION_PRESETS` map near the top of the Subspace define file. Each preset is a flat map of the DESIGN.md token keys (`ground`, `ink`, `accent`, `gap-m`, …) — a variation is one alternate token set, not a second DESIGN.md. 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).
 

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

@@ -128,9 +128,9 @@ The bar exists because cosmetic-quality drift is invisible until shipped, then o
 | **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.
+**Logging the scores** under DESIGN.md's **Score log** (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`
+### Step 5 — Bind into Media Flow + record in DESIGN.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`:
 
@@ -145,17 +145,17 @@ Bricks bind via DataLink: `Image.property.source = linkData(() => brandLogoData)
 
 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:
+The brand spec is **not** a separate file — it is the **Assets & Brand** sections of the project's [`DESIGN.md`](design-md.md), alongside the colour/type/voice tokens. Use this structure verbatim under DESIGN.md's `## Assets & Brand` heading — every section is required, even the gap section:
 
 ```markdown
-# Brand spec — <brand name>
+## Assets & Brand
 > Captured: <YYYY-MM-DD>
 > Sources: <list>
 > Coverage: <complete / partial / inferred>
 
-## First-class assets
+### First-class assets
 
-### Logo
+#### Logo
 - Primary (dark ground): <Media Flow ID> → Data: brandLogoDark
 - Primary (light ground): <Media Flow ID> → Data: brandLogoLight
 - Mono / reverse: <Media Flow ID> → Data: brandLogoMono
@@ -163,57 +163,56 @@ Fonts: declare each as an `ApplicationFont` entry in `Application.applicationSet
 - Minimum size: <e.g., 96 px wide>
 - Source: <press-kit URL / inline-svg from <url> / file from user>
 
-### Product photography (if physical brand)
+#### 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)
+#### UI screenshots (if digital brand)
 - Home: ... [score: ...]
 - Core feature A: ... [score: ...]
 
-### Scene / lifestyle (if relevant)
+#### Scene / lifestyle (if relevant)
 - ...
 
-### Motion
+#### Motion
 - Brand reel clip: <Media Flow ID> → Data: brandReel  (1920×1080, 12s, h264)
 - Animated logo: <Media Flow ID> → Data: brandLogoLottie
 
-## Auxiliary
+### 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>
+#### Colours
+The palette lives in the DESIGN.md frontmatter `colors` tokens (shared ones bound as theme-token Data). Record provenance and constraints here:
+- `{colors.primary}` / `{colors.accent}` / neutrals — source: <where each was sampled / documented>
+- Forbidden: <colours the brand explicitly does not use>
 
-### Fonts (ApplicationFont entries)
-- Display: <family / weights / file location / license>
-- Body:    <family / weights / file location / license>
+#### Fonts (ApplicationFont entries)
+- Display: <family / weights / file location / license>  → frontmatter `type.display` + `fonts`
+- Body:    <family / weights / file location / license>  → frontmatter `type.body` + `fonts`
 
-### Voice & tone
+#### Voice & tone
 - Register: <e.g., confident, terse, never effusive>
 - Capitalization: <e.g., sentence case>
 - Banned phrases: <e.g., "innovative", "revolutionary", "AI-powered">
 
-### Signature details
+#### 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
+### Gaps & placeholders
 - <category>: <why missing> → <action: ask user / AI generate / accept placeholder> [as of <date>]
 
-## Score log (for non-logo assets)
+### 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:
+Once DESIGN.md's Assets & Brand sections are populated, 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.
+- **Every Brick that uses a brand asset** has its source traceable to a DESIGN.md Assets & Brand line. Reviewing DESIGN.md is reviewing the design.
 
 ## Creating assets when missing
 
@@ -221,13 +220,13 @@ When a category has no acquirable real asset and the user has no plan to provide
 
 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).
+3. **Accept a labeled placeholder Brick** with the gap tracked under DESIGN.md's **Gaps & placeholders**. 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.
+- **Persist generation metadata** under DESIGN.md's Assets & Brand: 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.
@@ -255,7 +254,7 @@ Some BRICKS deployments are for venues with no prior brand work — small clinic
 
 - 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.
+- 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 in DESIGN.md (tokens + Assets & Brand) — 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
 
@@ -274,11 +273,11 @@ You cannot move from this protocol back into design until all of the following a
 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.
+4. Colors — palette declared as DESIGN.md `colors` tokens (shared ones bound as theme-token Data).
 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.
+9. Spec committed — DESIGN.md's Assets & Brand sections are filled in the project root; not in a chat scrollback or a working file that will be lost.
 
 If any item is incomplete, name it in your reply and either resolve it or pause for user input. Don't proceed silently.

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

@@ -61,31 +61,27 @@ When you do ask, cover these axes — in one batch, omitting any already pinned:
 
 Don't sprint to a finished Subspace. Stage the work so wrong direction is caught at the cheapest point.
 
-### Pass 0 — Deployment context + style declaration
+### Pass 0 — Deployment context + DESIGN.md
 
-Confirm Priority #0 verbatim. Write the style declaration block at the top of the Subspace file before placing any Brick:
+Confirm Priority #0 verbatim, then write the project's **`DESIGN.md`** before placing any Brick. Full schema and template in [`design-md.md`](design-md.md); at Pass 0 you need at minimum:
+
+- **Frontmatter tokens** — `system`, `archetype`, the `colors` / `type` (sizes in grid units) / `spacing` (grid units) / `motion` / `grid` / `heroes` maps. Each token carries its role in a comment.
+- **Deployment Context** — the five Priority #0 facts in prose, with any assumed value flagged `ASSUMED`.
+- **Visual Theme & Atmosphere** (section 1) — what the system says and its one or two signature moves.
+
+The grid substrate is given (Truth #6). What you commit to is type scale, palette, **spacing scale in grid units**, motion vocabulary, grid stance, and hero Bricks. The spacing scale is a small enumeration (3–5 values); inter-Brick gaps come from this set by name (`{spacing.gap-m}`), not arbitrary integers. DESIGN.md keeps the agent's arithmetic consistent across many Bricks and is what the design-critique pass cites.
+
+The Subspace file itself carries only a one-line pointer:
 
 ```ts
-/**
- * System: <picked design language, e.g., Swiss Editorial>
- * Archetype: <interaction archetype, e.g., glance>
- * Type: <font family> · <size scale in grid units, e.g., 2 / 4 / 8 / 16 gu>
- * Color: <ground> on <ink> · accent <#hex> (used only for …)
- * Spacing: <scale in grid units, e.g., 2 / 4 / 8 / 16 gu>
- * Grid stance: lean / break / breathe
- * Motion: <Standby easing + ms> entrance · <ms> exit · loops only on <element>
- * Heroes: <Brick id(s) that persist across Canvases via auto-tween>
- * Asset emphasis: <real photography / type-only / hero video / …>
- */
+/** System: <picked design language> · archetype: <archetype> · tokens + assets in ../DESIGN.md */
 ```
 
-The grid substrate is given (Truth #6). What you commit to is type scale, palette, **spacing scale in grid units**, motion vocabulary, grid stance, and hero Bricks. The spacing scale is a small enumeration (3–5 values); inter-Brick gaps come from this set, not arbitrary integers. This block keeps the agent's arithmetic consistent across many Bricks and is what the design-critique pass cites.
-
 ### Pass 1 — Showcase Canvas (the lockdown moment)
 
 Build **one** Canvas, fully lit, that represents the work at its highest fidelity. Choose the hardest Canvas — the boot screen, the most content-dense state, or the moment that carries the brand most. Run through Verification (compile + screenshot + view back). Show the user.
 
-This is the cheapest point to discover the direction is wrong. If the user wants the type bigger, the photography swapped, the rhythm slower, the language different — fix the Canvas and the style declaration, not twelve Canvases.
+This is the cheapest point to discover the direction is wrong. If the user wants the type bigger, the photography swapped, the rhythm slower, the language different — fix the Canvas and the DESIGN.md tokens, not twelve Canvases.
 
 **Do not** build the full Canvas graph before this checkpoint. The temptation is real because state-machine work feels productive; resist it. Sign-off on one Canvas first.
 
@@ -131,4 +127,4 @@ Don't compress passes on:
 - **Asking one question at a time.** Burns volleys, drains user energy.
 - **Asking nothing and inferring.** The five Priority #0 items are not inferrable; trying to is the most expensive mistake.
 - **Declaring done after Pass 2.** Pass 4 critique is what separates "runs" from "good."
-- **Re-declaring the style block on every iteration.** If you find yourself updating five values at once mid-Pass-3, you're rebuilding the system — back up to Pass 1.
+- **Rewriting DESIGN.md tokens on every iteration.** If you find yourself updating five tokens at once mid-Pass-3, you're rebuilding the system — back up to Pass 1.

package/tools/mcp-tools/compile.ts

@@ -2,6 +2,7 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { readFile } from 'node:fs/promises'
 import { z } from 'zod'
 import { sh } from '../_shell'
+import { appendSimulatorInspectionGuidance } from './simulator-guidance'
 
 // Disable ANSI color codes from spawned tools so MCP text output stays readable
 // (the host renders raw text; escape sequences leak into the result otherwise).
@@ -78,6 +79,7 @@ export function register(server: McpServer, projectDir: string) {
         log = [stdout, stderr].filter(Boolean).join('\n')
         error = true
       }
+      if (!error) log = appendSimulatorInspectionGuidance(log, { testId, testTitleLike })
       let screenshotBase64: string | null = null
       if (!error && responseImage) {
         const toolsDir = `${dirname}/..`

package/tools/mcp-tools/simulator-guidance.ts

@@ -0,0 +1,31 @@
+const quoteShellArg = (value: string) => `'${value.replace(/'/g, `'\\''`)}'`
+
+const buildInteractiveSimulatorCommand = ({
+  testId,
+  testTitleLike,
+}: {
+  testId?: string
+  testTitleLike?: string
+} = {}) => {
+  const args = ['bun preview']
+  if (testId) args.push('--test-id', quoteShellArg(testId))
+  if (testTitleLike) args.push('--test-title-like', quoteShellArg(testTitleLike))
+  return args.join(' ')
+}
+
+export function appendSimulatorInspectionGuidance(
+  log: string,
+  options: { testId?: string; testTitleLike?: string } = {},
+) {
+  return [
+    log.trimEnd(),
+    '',
+    'Inspection guidance:',
+    `- For interactive debugging of this same Preview runtime, run \`${buildInteractiveSimulatorCommand(options)}\` from the project directory. It exposes CDP on localhost:19852 by default and writes .bricks/devtools.json for CLI discovery.`,
+    '- Use `bricks devtools -p 19852 ...` from the project directory to inspect the Simulator. Plain `bricks devtools` may inspect another device on the default port.',
+    '- Useful commands: `bricks devtools -p 19852 brick tree`, `brick query <selector>`, `input tap <x> <y>`, `network list`, `storage data-bank get <S_xxxx>`, and `runtime eval "automation.list()" -j`.',
+    '- Prefer this Preview CDP/runtime path over a separate Playwright browser when validating BRICKS app state, logs, input, storage, or network behavior.',
+    '- If the `bricks-cli` skill is unavailable, run `bricks devtools --help`; the CLI help is authoritative.',
+    '',
+  ].join('\n')
+}

package/types/bricks/Items.d.ts

@@ -269,6 +269,7 @@ Default property:
                   y?: number | DataLink
                   width?: number | DataLink
                   height?: number | DataLink
+                  type?: string | DataLink
                   standbyMode?: 'custom' | 'top' | 'bottom' | 'left' | 'right' | DataLink
                   standbyFrame?: DataLink | {}
                   standbyOpacity?: number | DataLink
@@ -319,6 +320,7 @@ Default property:
                 }
             show?: string | DataLink
             pressToOpenDetail?: boolean | DataLink
+            pressToBackList?: boolean | DataLink
           }
       >
     | DataLink
@@ -346,6 +348,7 @@ Default property:
                   y?: number | DataLink
                   width?: number | DataLink
                   height?: number | DataLink
+                  type?: string | DataLink
                   standbyMode?: 'custom' | 'top' | 'bottom' | 'left' | 'right' | DataLink
                   standbyFrame?: DataLink | {}
                   standbyOpacity?: number | DataLink
@@ -395,6 +398,7 @@ Default property:
                   renderOutOfViewport?: boolean | DataLink
                 }
             show?: string | DataLink
+            pressToOpenDetail?: boolean | DataLink
             pressToBackList?: boolean | DataLink
           }
       >

package/types/bricks/Text.d.ts

@@ -36,7 +36,7 @@ Default property:
   property?: BrickBasicProperty & {
     /* The text content */
     text?: string | DataLink | number | DataLink | boolean | DataLink | string | DataLink | DataLink
-    /* Data to be used in the text template (e.g. `Hello ${name}`). Supports nested data, such as `Hello ${user.name}`. */
+    /* Data to be used in the text template. Must be an OBJECT whose keys are the template variable names: `Hello ${name}` needs `{ name: ... }` (a linked data must resolve to such an object — linking a scalar leaves the template unresolved). Supports nested data, such as `Hello ${user.name}`. */
     templateData?: {} | DataLink
     /* The text template type */
     templateType?: '${}' | '{{}}' | DataLink
@@ -80,6 +80,14 @@ Default property:
     letterSpacing?: number | DataLink
     /* The line height of text content (grid) */
     lineHeight?: number | DataLink
+    /* The text top padding (grid) */
+    paddingTop?: number | DataLink
+    /* The text left padding (grid) */
+    paddingLeft?: number | DataLink
+    /* The text right padding (grid) */
+    paddingRight?: number | DataLink
+    /* The text bottom padding (grid) */
+    paddingBottom?: number | DataLink
     /* The line number limit of text content */
     lineNumber?: number | DataLink
     /* The text align */

package/types/bricks/TextInput.d.ts

@@ -177,7 +177,7 @@ Default property:
     onEmpty?: Array<EventAction>
     /* Event of the TextInput value change */
     onChange?: Array<EventAction<string & keyof TemplateEventPropsMap['TextInput']['onChange']>>
-    /* Event of the TextInput submit */
+    /* Event of the TextInput submit. Fires on EVERY submit attempt, even when the value does not match `regex` — to react only to a valid submit, gate on a data updated from the result outlet (e.g. `valueHit`), or handle the invalid case via `onResultNotMatch` */
     onSubmit?: Array<EventAction<string & keyof TemplateEventPropsMap['TextInput']['onSubmit']>>
     /* Event of the TextInput match regex (check every value change) */
     onMatch?: Array<EventAction<string & keyof TemplateEventPropsMap['TextInput']['onMatch']>>