@flextudio/scenario 0.1.0

package/skill/design-rules.md

@@ -0,0 +1,282 @@
+# Flextudio scenario styling
+ 
+## Modes — pattern / design / raw
+
+For each unit in `Contents[]`, pick ONE styling mode:
+
+| Mode | Form | When |
+|---|---|---|
+| **Pattern** (preset) | `{ "<patternName>": { ...props } }` | Recurring unit, consistency matters (every CTA, every status badge). Pattern owns its style. |
+| **`design` key on raw control** | `{ "ControlType": "Label", "labeltext": "...", "design": { font: "body-large", color: "body" } }` | One-off control. Default for ad-hoc visuals. |
+| **Raw style fields** | `{ "ControlType": "Label", "labeltext": "...", "FontStyle": { ... }, "Width": { ... } }` | Only when `design` cannot express the case |
+
+The materializer expands `design` to raw style fields before validation.
+
+```jsonc
+// Same Label, three forms
+{ "button": { "label": "확인", "variant": "primary", "width": "full" } }                          // pattern
+{ "ControlType": "Label", "labeltext": "확인", "design": { "font": "title-medium", "w": "full" } } // design
+{ "ControlType": "Label", "labeltext": "확인", "FontStyle": { "UseFont": true, ... } }             // raw — verbose
+```
+
+## The `design` key
+
+A short stylesheet attached to any raw control or raw Group.
+
+## `design` key — slots
+ 
+| key | format | maps to |
+|---|---|---|
+| `font` | typography role | `FontStyle.FontSize` + `FontWeight` |
+| `color` | text color slot | `FontStyle.FontColor` |
+| `align` | `start` / `center` / `end` | `FontStyle.FontAlign` |
+| `w`, `h` | `full` / `text` / `<n>px` / `<n>%` / `<n>vh` / `<n>vw` | `Width` / `Height` |
+| `p`, `m` | CSS shorthand `"16"` / `"16 20"` / `"16 20 8 4"` (TRBL) or `{t,r,b,l}` | `Padding` / `Margin` |
+| `bg` | surface color slot | `BgStyle.BgColor` (auto `UseBackground:true`) |
+| `border` | slot \| `false` \| `"none"` \| `{ color, type?, size? \| sides? }` | `BorderStyle` |
+| `radius` | non-neg int string, or `{ tl?, tr?, br?, bl? }` | `BorderStyle.BorderRadius` (uniform or per-corner) |
+| `elevation` | `rect-shadow` / `radius-shadow` | `ContentStyle` |
+| `flex` | `{ dir, gap?, align?, valign? }` — **Group only** | `DisplayStyle` |
+| `caption` | `{ text?, font?, color?, pos?, align? }` | `text`→root `Caption` (content); 나머지→`CaptionStyle` (auto `UseDesign:true`). 한 행에서 다른 컨트롤과 묶을 땐 캡션 대신 라벨을 상위로 — §Layout "Captioned input in a row" |
+| `abs` | `{ t?, r?, b?, l? }` | `UseAbsoluteLayout:true` + `AbsolutePosition` |
+| `opacity` | int 0..100 | `UseOpacity:true` + `OpacityValue` |
+| `itemBg` | color slot — CheckBox/RadioBox only | `ItemBgStyle` |
+| `tabHeader` | `{ container?, selectedContainer?, item?, selectedItem? }` — Tab only | `TabHeader*` family |
+| `fixed` | boolean | `UseFixedSize` |
+| `surface` | `flat` / `outlined` / `elevated` — **Group only** | expands to `bg`+`border`+`radius`+`elevation` |
+ 
+For inner shape details (`border.sides`, `flex.dir/gap/align/valign`, `caption.pos`, `tabHeader.*`), read `design.schema.json` or validate with `flex-scenario validate --schema design`.
+
+## Slot enums (names only — pixel mappings in §Colors / §Typography below)
+ 
+**Color** (text / bg / border share one enum; slot taxonomy guides intent):
+- Brand: `main`, `main-light`, `sub`, `sub-light`
+- Surface: `canvas`, `card`, `subtle`, `surface-strong`, `dark`
+- Hairline (border): `hairline`, `hairline-soft`, `hairline-strong`
+- Text (color): `ink`, `body`, `body-soft`, `muted`, `on-brand`
+- Semantic: `warning`, `preview`, `success`, `error`
+**Typography roles** (`font`): `display-large/medium/small`, `title-large/medium`, `body-large` (default body anchor), `body-medium`, `body-small`, `caption`, `micro`. Closed enum — no separate weight override. For non-listed combos (e.g. 14px SemiBold), escape to raw `FontStyle`.
+ 
+**Radius**: `"0"` / `"4"` / `"8"` / `"12"` / `"16"` (default cards) / `"20"` / `"9999"` (pill — auto `RadiusSet:"None"`)
+ 
+**Spacing** (base 4px): `4` / `8` / `12` / `16` / `20` / `24` in `p`, `m`, `flex.gap`.
+
+## Rules
+ 
+- **Slot-only inside `design`.** Raw `var(--...)` / hex / arbitrary px are Ajv-rejected. Use slot names; escape to raw style fields if truly needed.
+- **`design` wins on overlap** (leaf-level merge). Non-overlapping raw leaves preserved.
+- **`flex` and `surface` are Group-only.** Putting either on a Control raises `kind:"design"` error.
+- **Column is default.** Omit `flex` for vertical stacks.
+- **Border / radius uniform vs per-side mutually exclusive.** `border` rejects `size` + `sides` together; `radius` rejects string + `{tl,tr,br,bl}` together.
+
+### Layout & sizing semantics
+
+- **Step padding.** Every Step body comes with 20px horizontal padding out of the box (no need to set it). For edge-to-edge content, set the Step padding to **0**:
+
+```json
+"Padding": {
+  "All": "0",
+  "SizeUnit": "px",
+  "UseEach": "false",
+  "UseAuto": "true"
+}
+```
+
+Add this inside the Step JSON.
+- **Row sibling width rule.** Inside `design: { flex: { dir:"row", ... } }`, the renderer can stretch any *content-sized* child (anything not declaring an explicit `w`) to claim leftover flex space, which squeezes a sibling that asked for `w: "full"`. To prevent this, set `design: { fixed: true }` on every content-sized child in a row. Children with explicit `%` widths (`"50%"`, etc.) need no `fixed` flag.
+
+- **Gap defaults to 0.** Multi-child rows need explicit `flex.gap`. Omit only when (a) a child has `w: "full"` (claims the row alone), or (b) `align:"between"` (renderer distributes inter-child space).
+- **Reach for molecule patterns first.** `input-button`, `input-pair` encode gap + `fixed` invariants internally — author hand-rolled rows only after checking the pattern catalog (`patterns/index.json`).
+
+- **Captioned input in a row — lift the label out.** `design.caption` (default `pos:"top"`) grows the control's *box* by the caption height (the materializer adds ~24px to a px `h` to keep the input body at its intended size). Fine for a standalone field, but inside `flex: { dir:"row" }` it breaks vertical alignment: a sibling — typically a button — centers against the *caption-inflated* box, so it sits too low relative to the input body. When an input shares a row with another control, **do not put the label on the input via `design.caption`.** Lift the label to a sibling Label above the row:
+
+```jsonc
+// field block — label on top, input + action centered in the row below
+{ "ContentsType": "Group",
+  "design": { "flex": { "dir": "column", "gap": 4 }, "w": "full" },
+  "Contents": [
+    { "ControlType": "Label", "labeltext": "부서",
+      "design": { "font": "body-small", "color": "body-soft", "w": "full", "h": "text" } },
+    { "ContentsType": "Group",
+      "design": { "flex": { "dir": "row", "gap": 8, "valign": "center" }, "w": "full" },
+      "Contents": [
+        { "ControlType": "InputText", "Placeholder": "부서명 검색",
+          "design": { "w": "full", "h": "48px", "border": "hairline-strong", "radius": "8" } },   // no caption
+        { "ControlType": "Button", "labeltext": "검색",
+          "design": { "h": "48px", "fixed": true } } ] } ] }
+```
+
+  Row rules: give the input and the adjacent control the **same explicit `h`** (e.g. `"48px"`), set `valign:"center"`, set `fixed:true` on the content-sized control (Row sibling width rule), and space label↔row with the column `gap:4`. Keep `design.caption` only for a **standalone** input with no adjacent control in the same row.
+
+### Elevation patterns (composition of slots)
+
+| Level | Compose with | Use |
+|---|---|---|
+| Flat (canvas) | (no `bg`, no `border`) | Step body |
+| Card | `bg: "card"` + `border: "hairline"` + `radius: "16"` | Content cards |
+| Subtle band | `bg: "subtle"` | Section grouping |
+| Hairline-only outline | `border: "hairline"` + `radius: "12"` | Card outline without fill |
+| Shadow card | above + `elevation: "rect-shadow"` (or `"radius-shadow"`) | Floating cards |
+| Dark inversion | `bg: "dark"` + `color: "on-brand"` | Strong CTAs, featured cards |
+
+No custom shadows, gradients, or blurs. `elevation` accepts engine-preset slots only.
+
+### `surface` preset — named elevation recipe (Paper)
+
+`design.surface` packages the elevation recipe above into one named handle, so every elevated container is consistent (MUI Paper 영감). **Group only** — it styles a container surface; on a Control it raises a `kind:"design"` error. Expands to `bg`+`border`+`radius`+`elevation`:
+
+| `surface` | expands to | Use |
+|---|---|---|
+| `flat` | `bg:"card"` + `radius:"16"` | Filled surface, no outline/shadow |
+| `outlined` | `bg:"card"` + `border:"hairline"` + `radius:"16"` | Card outline |
+| `elevated` | `bg:"card"` + `radius:"16"` + `elevation:"radius-shadow"` | Floating card (Paper) |
+
+The preset is a **baseline** — any explicit `bg`/`border`/`radius`/`elevation` key on the same `design` overrides it (`{ "surface":"elevated", "radius":"20" }` → elevated recipe with 20px corners). The engine has no shadow-depth scale (only `rect-shadow`/`radius-shadow`, differing by corner shape), so `surface` is a closed 3-variant enum, not a numeric elevation.
+
+```jsonc
+// Elevated Paper container — styled Group, freeform children
+{ "ContentsType": "Group",
+  "design": { "surface": "elevated", "p": "16", "flex": { "dir": "column", "gap": 12 } },
+  "Contents": [ /* patterns · raw controls · nested Groups */ ] }
+```
+
+`surface` is Group-only, same as `flex`. Wrap content in a Group; do not put `surface` on a Control.
+
+---
+
+## Colors
+
+The slot enum for `design.color` (text), `design.bg` (surface), `design.border` (outline).
+
+### Brand & Accent
+- **`main`** (`var(--colorMain)`) — Primary CTA fill, active state. Default green; per-tenant overridable.
+- **`main-light`** (`var(--colorMainLight)`) — Soft primary surface (selected zone, hover).
+- **`sub`** (`var(--colorSub0)`) — Secondary accent. Default purple; per-tenant overridable. Never on a CTA.
+- **`sub-light`** (`var(--colorSub0Light)`) — Soft accent surface.
+
+### Surface
+- **`canvas`** (`var(--colorWhite)`) — Pure white screen floor.
+- **`card`** (`var(--colorWhite)`) — Default card / sheet fill.
+- **`subtle`** (`var(--colorGray9)`) — Section background.
+- **`surface-strong`** (`var(--colorGray10)`) — Chip / badge default fill.
+- **`dark`** (`var(--colorBlack)`) — Dark feature cards, emphasized featured rows.
+
+### Hairlines (border slot)
+- **`hairline`** (`var(--colorGray5)`) — Default 1px divider, card outline.
+- **`hairline-soft`** (`var(--colorGray9)`) — Lighter divider — section breaks within a card.
+- **`hairline-strong`** (`var(--colorGray4)`) — Stronger panel outline — interactive boundary, focus.
+
+### Text (color slot)
+- **`ink`** (`var(--colorBlack)`) — Strong emphasis, icon stroke.
+- **`body`** (`var(--colorGray1)`) — Heading / body emphasis.
+- **`body-soft`** (`var(--colorGray3)`) — Subtitle, label, caption — most used.
+- **`muted`** (`var(--colorGray4)`) — Placeholder, disabled, soft meta.
+- **`on-brand`** (`var(--colorWhite)`) — Text on Main / Sub / Semantic fill.
+
+### Semantic
+- **`warning`** (`var(--colorSub4)`) — Caution / pending state.
+- **`preview`** (`var(--colorSub3)`) — "Preview" tag, in-progress flag.
+- **`success`** (`var(--colorSub1)`) — Confirmation, approved state.
+- **`error`** (`var(--colorSub2)`) — Validation error, destructive action.
+
+All four color slot groups share one enum — `design.bg: "ink"` is technically accepted (Ajv won't reject), but semantically use Surface for `bg`, Text for `color`, Hairlines for `border`. The slot taxonomy guides intent.
+
+---
+
+## Typography
+
+The role enum for `design.font`. Anchored at **16px body** (1rem).
+
+| Role | `FontSize` | `FontWeight` | Use |
+|---|---|---|---|
+| `display-large` | `"28"` | `"SemiBold"` | Step header, hero title |
+| `display-medium` | `"24"` | `"SemiBold"` | Section heads |
+| `display-small` | `"20"` | `"SemiBold"` | Sub-section heads |
+| `title-large` | `"18"` | `"SemiBold"` | Card group titles |
+| `title-medium` | `"16"` | `"SemiBold"` | Card titles, list labels |
+| `body-large` | `"16"` | `"Regular"` | Default body — anchor |
+| `body-medium` | `"14"` | `"Regular"` | Sub body, input text |
+| `body-small` | `"13"` | `"Regular"` | Caption, secondary meta |
+| `caption` | `"12"` | `"Regular"` | Photo captions, footer text |
+| `micro` | `"11"` | `"Medium"` | Section labels, badges (sparing) |
+
+---
+
+## Shapes — `design.radius` scale
+
+Emit as integer **string** to `design.radius`. The materializer sets `BorderStyle.BorderRadius` directly; pill geometry gets `RadiusSet: "None"` auto-applied.
+
+| `design.radius` | Use |
+|---|---|
+| `"0"` | Flat — no radius |
+| `"4"` | Inline tags |
+| `"8"` | Form inputs, CTA buttons, chips |
+| `"12"` | Default cards, code blocks |
+| `"16"` | Main cards — most used |
+| `"20"` | Strong cards, sheets |
+| `"9999"` | Badges and avatar plates (pill) — auto `RadiusSet:"None"` |
+
+---
+
+## Spacing system
+
+The integer values emitted in `design.p` / `design.m` / `design.row.gap`.
+
+- **Base unit:** 4px. Padding / margin values are quantized to **4×n**.
+- **Allowed values:** `4` · `8` · `12` · `16` · `20` · `24`. Author other values only with strong reason.
+- Every Group and Control already carries an engine-default inset — only set `p` / `m` when the design demands tighter or looser fit.
+
+Typical gap values: `"8"` for tight pairs, `"12"`–`"16"` for card grids.
+
+You need to know the step has a default 20px horizontal padding.
+
+---
+
+## Raw escape — when `design` cannot express it
+ 
+Read the full raw shape from `group.schema.json` / `control/<name>.schema.json`.
+ 
+| Need | Raw target |
+|---|---|
+| Non-default FontWeight (14px SemiBold etc.) | `FontStyle: { FontSize, FontWeight, ... }` |
+| `LetterSpacing` (자간) | `FontStyle.LetterSpacing` |
+| Image background | `BgStyle: { UseImage:true, Image:{...} }` |
+| Non-slot color (brand hex) | raw `FontColor` / `BgColor` |
+| Mixed `BorderType` per side | `BorderStyle` directly |
+| `FlexWrap` independent of `dir` | `DisplayStyle: { ..., FlexWrap:true }` |
+| Per-item CheckBox/RadioBox styling | author `Items[*]` raw |
+| Tab legacy `ArrangeItems` | raw string field |
+ 
+**Raw field-name traps** (strict-fields rejects invented variants):
+- `Padding` / `Margin` use **`Btm`**; `BorderStyle` uses **`Bottom`** (asymmetric)
+- `BorderStyle` toggle is **`Useborder`** (lowercase `b`)
+- `CaptionStyle` toggle is **`UseDesign`** (not `UseCaption`)
+- No `UseMargin` / `UseBorder` / `UseCaption`
+
+## Examples
+ 
+```jsonc
+// Body Label
+{ "ControlType": "Label", "labeltext": "{=Name}",
+  "design": { "font": "body-large", "color": "body", "w": "full", "h": "text" } }
+ 
+// Card Group — padded white surface with hairline outline
+{ "ContentsType": "Group",
+  "design": { "p": "16", "bg": "card", "border": "hairline", "radius": "16" },
+  "Contents": [ ... ] }
+ 
+// Row with space-between + 8px gap
+{ "ContentsType": "Group",
+  "design": { "flex": { "dir": "row", "align": "between", "valign": "center", "gap": 8 }, "p": "12 16" },
+  "Contents": [ ... ] }
+ 
+// Tab with underline selection
+{ "ControlType": "Tab",
+  "design": {
+    "tabHeader": {
+      "container":    { "arrange": { "type": "equal" }, "bg": "card", "p": "0 16" },
+      "item":         { "font": "body-medium", "color": "body-soft", "align": "center", "p": "12 0" },
+      "selectedItem": { "color": "main", "border": { "color": "main", "sides": { "b": "2" } } }
+    }
+  } }
+```

package/skill/design-system.md

@@ -0,0 +1,235 @@
+# Patterns — Design Rationale
+
+A handoff document for picking up the pattern-system discussion across sessions. Captures the reasoning behind decisions, not the implementation details (see `patterns-development-guide-v2.md` for that). Read this when you need to understand *why* the architecture looks the way it does, or when you're about to revisit a decision.
+
+---
+
+## 1. Context: what Flextudio metadata looks like
+
+Flextudio scenarios are deeply nested JSON describing UI controls. A single screen scenario is typically:
+
+- **Depth 7+** — `Sectors[].Controls[].Children[].Children[]...`
+- **50kb+** of JSON for a non-trivial screen
+- **~30 styling fields per control** — `BgStyle`, `FontStyle`, `BorderStyle`, `Padding`, `Margin`, `Width`, `Height`, plus per-ControlType fields
+- **ControlType is the engine primitive** — `Label`, `Group`, `ImageBox`, `TextField`, `Button`, `Icon`, `Checkbox`, `Radio`, etc. Enumerated in `catalog.json`.
+- **Tokens live in `DESIGN.md`** — colors as `var(--colorXxx)`, FontWeight as string enums (`Regular`/`Medium`/`SemiBold`/`Bold`), spacing on a scale (`xs`–`xxl` = 4–24 px)
+- **`validate.mjs` enforces 16 cross-checks** — naming, ID format, legacy-field bans, image-field defaults, font/border rules, etc. This is the actual contract.
+- **Build sequence** — the original MCP server enforced a fixed call order via `build_id`. The CLI replacement (`flex-scenario session start/status/finish`) keeps a build id for traceability but does not force stage order.
+
+The original assumption was that the LLM emits this metadata directly, with `assets.json` providing reference snippets for common shapes.
+
+---
+
+## 2. Why `assets.json` failed
+
+`assets.json` accumulated 174 entries across 9 "kinds" (colors, controls, compositions, layouts, etc.) intended as a reference library. In practice:
+
+1. **Ambiguous positioning** — it tried to be three things simultaneously:
+   - Token reference (but DESIGN.md already does this)
+   - Pattern library (but compositions are prose, not generation-ready)
+   - Search index (but mixing 9 kinds in a flat list fragmented results)
+2. **Low LLM utilization** — the workflow `find → get × 5 → translate prose to JSON → maintain 30 fields consistently` puts the LLM on the steps it does worst.
+3. **Maintenance cost > value** — sync with DESIGN.md required ongoing effort; only ~10 of 174 entries (deprecated mappings + usage-rank stats) carried real value.
+
+Conclusion: replace with something the LLM can actually consume cheaply.
+
+---
+
+## 3. The core question: how should the LLM produce metadata?
+
+Two models on the table:
+
+### Model A — Hybrid output
+
+```
+LLM → [ raw control JSON (escape) , pattern invocation (abstracted) ]
+                                                                    → merge → meta
+```
+
+LLM freely moves between layers. Some controls drawn raw, others via patterns, all in the same scenario.
+
+**Pros**: Maximum flexibility. LLM can always drop down a level when a pattern doesn't fit (e.g. unusual data binding, one-off event hook).
+
+**Cons**:
+- LLM must decide *per control* whether to use a pattern or raw output. This is the kind of judgment LLMs handle worst — and it has to happen continuously.
+- Result quality drifts: two cards in the same list end up styled differently (one token-based, one inline hex) because the LLM made different micro-decisions.
+- The deep-JSON cost stays — every raw control means ~30 fields the LLM must emit consistently.
+- The original principle of the project ("don't push judgment onto the LLM") gets violated.
+
+### Model B — Single layer
+
+```
+LLM → pattern invocations only → materializer → meta
+```
+
+LLM emits only `{ pattern, props }`. Materializer expands to full metadata.
+
+**Pros**:
+- LLM stays in its strong zone — enum selection, shallow schema filling.
+- Computing cost moves from LLM token-generation to deterministic materializer.
+- Output consistency is enforced by the materializer.
+- Validation passes more reliably (materializer produces conformant output by construction).
+
+**Cons**:
+- Patterns might not cover every case → need escape hatches.
+- The pattern library has to be designed carefully; missing coverage forces escape, which is expensive.
+
+### Decision: Model B, with a visible escape ladder
+
+The deciding factor was **computing cost on deep JSON**. The LLM producing 50kb+ of 7-level-nested metadata under a forced build sequence is the worst possible workload — high token cost, easy to hit tool-call limits, easy to lose consistency mid-output. Model B eliminates that entirely for the 90% case.
+
+Model A's "drop to raw" capability is preserved via an escape ladder (§7), but it's deliberately more expensive than the default path. The cost asymmetry steers the LLM toward patterns.
+
+---
+
+## 4. Layer architecture: why three layers, not two
+
+After deciding on Model B, the next question is how to organize the implementation. Naive version: one materializer per pattern, each producing full metadata directly. This works but two problems emerge:
+
+1. **Boilerplate repetition** — every materializer that uses a `Label` repeats the same 8–10 ControlType setup fields (`LabelType: "labeltext"`, `Caption`, `ControlStyle: "None"`, `isColumnCtrl: false`, empty `Width`/`Height`/`BgStyle`/`FontStyle` defaults). New atoms get authored by copying an existing one and tweaking — drift inevitable.
+2. **Mixing concerns** — design decisions (semantic→token mapping) get tangled with engine contract (which fields the ControlType requires).
+
+Three-layer solution:
+
+| Layer | Responsibility | Example |
+|-------|---------------|---------|
+| `_base.controls.mjs` | Engine contract — "to emit ControlType X, the metadata must look like this" | `makeLabel({ text, name })` |
+| `_base.style.mjs` | Design system — "this token translates to this metadata object" | `font({ size, weight, color })` |
+| `<pattern>.materialize.mjs` | Design decision — "this pattern uses control X with tokens Y" | StatusChip = Label + semantic bg + pill |
+
+### Why factory is separate from token helper
+
+Two different domains:
+- Factory answers: "what fields does the engine require for this ControlType?"
+- Token helper answers: "what styling object does this design token become?"
+
+Mixing them produces design-aware factories like `makeStatusChip()`, which:
+- Duplicate the pattern schema's responsibility
+- Hide design decisions inside a helper (materializer becomes one-liner `makeStatusChip(label, color)` with no visible reasoning)
+- Force factories to know about design tokens, blurring the layer boundary
+
+Keeping them split lets the materializer remain the single, readable place where "this pattern is this design" is expressed.
+
+### Why factory ≠ atom
+
+This is subtle but important. A factory is *not* a tiny atom. A factory is an internal author-facing helper. An atom is an LLM-facing semantic primitive. They serve different audiences:
+
+- Factory: visible to whoever writes `<pattern>.materialize.mjs`
+- Atom: visible to the LLM via schema
+
+Confusing them led to the brief consideration of "one atom per ControlType" — which fails because:
+- ControlType is engine-level (~10–15 enums)
+- Atom is design-level (`StatusChip`, `Avatar`, `BadgePill` — meaningful units the LLM picks by intent)
+- The relationship is N:M, not 1:1 (one Label → multiple atoms; one Avatar might use ImageBox + Label fallback)
+
+---
+
+## 5. Atom qualification: what earns atom status
+
+Three tests (must satisfy ≥1):
+
+1. **Semantic pickability** — the LLM would meaningfully choose this by intent. "Status indicator" → `status-chip`. But "text" → `label` is not a meaningful pick; the LLM doesn't think "I need a label," it thinks "I need this card's title."
+2. **Slot suitability** — fits inside an organism's slot as a self-contained unit.
+3. **Absorbs design decisions** — owns semantic→token mapping, geometry choices, or interaction state. Beyond just "wrap a ControlType with styling."
+
+Fails all three → factory helper instead. This is why Label, Heading, Caption, Divider, Spacer are factories, not atoms — they're styling wrappers, not design primitives.
+
+### Practical consequence
+
+The first atom batch isn't "one atom per ControlType" (would be a bloated list of trivial wrappers). It's the design-schema primitives decided in the prior session:
+
+`Button`, `Chip`, `Checkbox`, `RadioGroup`, `TextField`, `Switch`, `Tab`, `IconButton`
+
+These each carry real design decisions (8px radius for CTA, pill geometry as Switch's intentional exception, dual focus-ring system, four IconButton variants) that an atom is the right place to encode.
+
+---
+
+## 6. Tier structure: why Atomic Design
+
+Atomic Design (atom/molecule/organism) maps cleanly to Flextudio's compositional structure:
+
+- **atom** — 1 control, no slots, 2–4 props. Engine-leaf primitives with design opinion.
+- **molecule** — 2–5 controls, no slots, 4–8 props. Fixed compositions (`InfoRow` = label + value).
+- **organism** — composition with slots. The unit of screen-level structure (`ListCard`, `FormSection`).
+
+### Why the constraints
+
+- **Atom has no slot** — if you need composition, you've crossed into molecule/organism territory. Keeps atoms a clear primitive.
+- **Molecule has no slot** — same reason, applied to the next level. Composition is the organism's job. Allowing slots in molecules would create a third "composable" tier and blur the boundary.
+- **Organism slots accept atom/molecule only** — preventing organism-in-organism keeps the composition tree at most three levels deep. Screen-level reuse is a different concern (a separate composition pipeline, not nesting).
+- **Slot names are semantic** (`trailing`, `leading`, `footer` — not `slot1`/`slot2`) — the LLM picks slots by meaning; positional names force it to reason about layout, which is the pattern's job.
+
+---
+
+## 7. Escape hatches: a cost ladder
+
+Coverage gaps are inevitable. The question is how the escape behaves.
+
+Design principle: **escape must exist, but must cost more than the default path.** Otherwise the LLM will gravitate to raw output whenever it's faster — and we're back to Model A.
+
+| Level | Mechanism | LLM cost | When |
+|-------|-----------|----------|------|
+| L0 | `pattern + props` | Lowest | Pattern fits |
+| L1 | `pattern + props + override` (named-anchor deep-merge patch on materialized nodes) | Slightly higher (must pick an anchor + reason about field shape) | Pattern's structure fits, but needs a field the props don't expose (e.g. `UseMove`/`MoveSteps`, a data connection) or a small tweak |
+| L2 | `pattern.escape.raw-control` | Much higher (must emit full control metadata, no token helpers available) | No pattern fits; one-off binding or event |
+| L3 | Add a new pattern | Author cost, not LLM cost | L2 recurs for the same shape |
+
+### Why this shape
+
+- **L1 (override)** absorbs two cases without forcing pattern proliferation: the common "90% of pattern + small tweak" *and* injecting engine metadata the simplified props deliberately don't expose (data binding, navigation, one-off flags). Both are the same mechanism — a deep-merge patch onto a materialized node.
+  - The patch is keyed by **anchor name**, not by mirroring the output tree. Every pattern supports `root` (the result's top node); multi-node patterns (molecules/organisms) expose semantic anchors for their children — e.g. `input-action` has `root` / `input` / `iconButton` / `badge`. The available anchors are listed in each schema's `override.propertyNames`.
+  - Anchors exist because a naive root-only deep-merge can't reach into array children (`Contents[]` gets replaced wholesale, not merged). The materializer knows which built node is which anchor and merges there directly — see `_base.additional-meta.mjs`.
+  - Validation: an injected field passes `[strict-fields]` as long as the field name is defined in *some* engine schema (the global `knownProps` union). A field defined nowhere (a typo) is still rejected — the escape is for real engine fields, not arbitrary keys. Caveat: the field must also be valid on the *node type* it lands on — e.g. `UseMove`/`MoveSteps` (Step navigation) is a Group-level feature, so inject it on a Group anchor (a molecule's `root` / a raw Group), not on an atom control. A field whose nested dynamic keys aren't covered by the target node's schema (e.g. `MoveSteps.StepN` on a Label) will fail strict validation on those keys.
+  - Cheap to specify: `{ "input": { "UseDataConnection": true } }` or `{ "root": { "FontStyle": { "FontSize": "16" } } }`.
+- **L2 (raw-control)** is the (A)-model raw-output capability, reframed as a single named escape pattern. The reframing matters: it makes the cost visible (LLM must populate ~30 fields with no helpers), and it routes through the same validate / materialize path as everything else.
+- **L3** is the maintenance signal: if the same L2 invocation recurs, the pattern library has a gap. Add the pattern; remove the escape.
+
+### Measurement as a coverage signal
+
+In Phase 4 validation (rewriting 4 example scenarios), L1 and L2 usage rates become a coverage metric:
+- L1 > 10% → pattern shapes don't quite match real cases; add variants or relax schema
+- L2 > 1% → real coverage gaps; add atoms/molecules
+
+This is the feedback loop that grows the library to fit actual usage, instead of guessing.
+
+---
+
+## 8. Documentation philosophy
+
+Decision: **no separate `.md` files per pattern.** The schema's `description` field is the doc.
+
+Reasoning:
+- Two-file maintenance (`.schema.json` + `.md`) inevitably drifts.
+- Schema descriptions can be multi-paragraph; nothing forces them to be one-liners.
+- The LLM consumes schemas by reading the static skill assets (`schemas/`, `patterns/`); putting docs anywhere else means the LLM never sees them.
+- `examples` field carries concrete usage; `x-related` carries cross-references. Together with `description` this matches the information density of a typical component `.md`.
+
+The cost is that schema files become longer (~30–80 lines for a typical atom). The benefit is single-source documentation that's actually used.
+
+---
+
+## 9. Migration sequencing: why strict order
+
+The deprecation must happen *after* the replacement is built. Specifically: removing `assets.json` before the pattern library is functional destroys the `deprecated → replacedBy` token mappings (gray, gray-middle, gray-light, gray-6) that normalize legacy metadata.
+
+Order:
+1. Build pattern library (helpers → atoms → molecules → organisms)
+2. Wire the CLI (`flex-scenario`) + skill assets
+3. Salvage migration data into `migrations.json`
+4. Verify on real scenarios
+5. Only then deprecate
+
+Phase 1 has its own internal order: factories must exist before atoms can use them; `_base.materialize.mjs` (slot resolution) must exist before organisms can be authored. Building atoms before factories means writing raw metadata literals, defeating the purpose.
+
+---
+
+## 10. Reading order for re-entry
+
+If you're picking up this work in a future session:
+
+1. This document (rationale)
+2. `patterns-development-guide-v2.md` (implementation brief)
+3. `DESIGN.md` (tokens — single source of truth)
+4. `catalog.json` (engine enums)
+5. `examples/enhanced/search-period-popup.json` (a working scenario; ground truth for what valid metadata looks like)
+6. `validate.mjs` (the actual contract — 16 cross-checks)

package/skill/docs/SKELETON-SHELL.md

@@ -0,0 +1,120 @@
+# Scenario shell — outer wrap of every scenario JSON
+
+> The outer wrap — ScenarioMeta + `Steps` map + each Step's metadata — is **always raw**. Use the skeleton below; schemas (`scenario.schema.json`, `step.schema.json`, `bottom-buttons.schema.json`) are the validation contract.
+
+## 1. Canonical scenario skeleton (copy → fill `…`)
+
+```jsonc
+{
+  // ─── ScenarioMeta — top-level fixed slots (DO NOT vary const fields) ───
+  "modules":           {},                    // ★ const {}
+  "htmlkey":           "stephtml",            // ★ const "stephtml"
+  "ScenarioTitle":     "",                    // ★ const "" — display name lives in fScenarioName
+  "fConverterVersion": 1,                     // ★ const number 1 (not string)
+  "fScenarioName":     "…",                   // display name (free string)
+  "Collections":       {},                    // ★ const {} — engine fills at runtime
+  "FlexSQLService":    {},                    // ★ const {}
+  "ServiceBinding":    {},                    // ★ const {} — [no-service] strict
+
+  // ─── Steps routing ───
+  "StartSteps":        ["Step1"],             // ≥1 required when Steps non-empty
+
+  // ─── Steps map (keys: ^Step[1-9][0-9]*$) ───
+  "Steps": {
+    "Step1": {
+      "StepName":   "…",                       // internal name
+      "StepType":   "StepView",                // "StepView" | "StepSub". Always author explicitly
+      "StepRow":    0,
+      "StepCol":    0,
+      "Contents":   [                          // pattern invocations + raw Groups
+        // { "<patternName>": { ...props } }
+        // { "ContentsType": "Group", "UseDataConnection": false, "Contents": [ … ] }   // raw Group fallback — UseDataConnection 필수(생략 시 [group-dc])
+      ],
+      "Next":            ["Step2"],            // forward-only StepIds. [] for terminal
+      "UseStepHeader":   false,                // true ⇒ author StepTitle
+      "UseBackButton":   false,                // StepSub forces false
+      "UseBottomButton": false,                // StepSub forces false
+      "UseEvents":       false,                // true ⇒ Events is object (§3); false ⇒ Events is []
+      "Events":          []
+    }
+  },
+
+  // ─── Optional top-level slots ───
+  "Language":     {},                          // i18n map for {{key}} substitution
+  "Events":       {},                          // scenario-level handlers — Script / LinkedEvent only (NO Service/API)
+  "DataSources":  {},                          // for Combo / RadioBox / Search / Tree
+  "Scenario":     { "StyleURLs": [] },         // external JS lib URLs
+  "Panel": {                                   // data model slot — AI emits empty shapes
+    "Collection":    { "Ckeys": [] },
+    "Category":      {},
+    "CategoryOrder": [],
+    "Table":         [],
+    "ExternalTable": [],
+    "AuthKey":       []
+  }
+}
+```
+
+**Common rejections by `flex-scenario validate`:**
+- ❌ Scenario name in `ScenarioTitle` → must be `""`; use `fScenarioName`
+- ❌ `fConverterVersion: "1"` string → must be number `1`
+- ❌ `ServiceBinding: { ... }` non-empty → must be `{}` ([no-service])
+- ❌ Missing `StartSteps` when `Steps` non-empty
+- ❌ `Collections` or `Panel.Collection.Ckeys` non-empty
+- ❌ Authoring `EmbedScenarioPrefix` → schema forbids the key
+
+## 2. Step shape
+
+StepId pattern: `^Step[1-9][0-9]*$`. Always author `StepType: "StepView"` explicitly unless embedding a sub-scenario.
+
+| Field | Type | Notes |
+|---|---|---|
+| `StepName` | `string` | Always author — internal display name |
+| `StepType` | `"StepView"` \| `"StepSub"` | Omit ⇒ runtime treats as StepView |
+| `Contents` | `Group[]` | Page body — patterns + raw Groups |
+| `Next` | `string[]` | Forward-only StepIds. `[]` for terminal |
+| `StepTitle` | `string` | Only with `UseStepHeader: true` |
+| `UseStepHeader` | `boolean` | Top header toggle |
+| `FixedContentsTop` | `Group[]` | Sticky top region (top-bar pattern) |
+| `FixedContentsBottom` | `Group[]` | Sticky bottom — canonical place for primary `button` atom |
+| `UseBackButton` | `boolean` | + author `BackButton` block. **StepSub forces false** |
+| `UseBottomButton` | `boolean` | + author `BottomButtons[]` for fixed-bottom CTAs. **StepSub forces false**. For *inline body* buttons use the `button` pattern instead |
+| `UseEvents` | `boolean` | See §3. **StepSub forces false** |
+
+Step-level styling (`Padding` / `Margin` / `BgStyle`, plus dialog-only `Width` / `Height`) uses **raw** shapes. Engine defaults usually fit — author only when overriding. Read `step.schema.json` for shapes.
+
+## 3. `Step.Events` shape
+
+```jsonc
+// UseEvents: true → Events is an OBJECT
+{
+  "UseEvents": true,
+  "Events": {
+    "StepEventOrder": ["Init", "Loaded"],     // enum the events that fire
+    "Init":           "handlerName_a",        // required for each entry in StepEventOrder (matching key)
+    "Loaded":         "handlerName_b"
+  }
+}
+
+// UseEvents: false → Events MUST be an empty ARRAY (not {})
+{ "UseEvents": false, "Events": [] }
+```
+
+Event enum (6): `Init` / `Loaded` / `OnBackLoaded` / `OnLeave` / `OnForeground` / `ScrollEnd`.
+Each handler name must exist in scenario-level `Events` — else `[event-ref]` fails.
+
+**Common mistakes:**
+- ❌ `UseEvents: false, Events: {}` → must be `[]`
+- ❌ Listing `"Init"` in `StepEventOrder` without the matching `"Init": "handler"` key
+- ❌ Authoring `"Init"` handler key but omitting it from `StepEventOrder` (won't fire)
+
+## 4. When to fetch full schemas
+
+The §1 skeleton covers ~95%. Read the schema file directly for edge cases:
+
+- `scenario.schema.json` — top-level scenarioMeta
+- `step.schema.json` — single Step. Required for **StepSub** (`Protocol` block) and **Dialog variants** (`StepDialogType: "SlideUp"` / `"PopUp"` — unlocks `useDim` / `dimTransp` / `Width` / `Height` / `PopupPosition`)
+- `bottom-buttons.schema.json` — BottomButtons[] item
+- `group.schema.json` — raw Group
+- `data-sources.schema.json` — DataSources map
+- `events.schema.json` — Action shapes for scenario-level Events