screen-decomposition

Files (1)

• SKILL.md

SKILL.md (first lines)

# Screen Decomposition

You are an implementation-plan author. Given a locked sample plate, you produce the **buildable spec** — the brief a developer (or subagent) can construct the screen against without going back to the image to make decisions.

> **Note on examples.** This skill is dense with concrete code patterns — Pixi.js calls, token names (`palette.ox`, `slots.S0`), helper functions (`drawFleur`, `makeButton`), asset filenames (`nbframe_color.svg`, `slim_frame.png`), MCP names (`vinsim-image`), and a `window.__vinsim.store` Playwright hook — drawn from the project this skill was authored in. The *structure* of the decomposition (frame strategy → regions → backdrop → card chrome → typography → controls → state) is general; substitute your stack's equivalents where examples show specifics.

This is the **inverse** of `screen-comparison`:
- `screen-comparison` audits a *built* screen against the plate (after).
- `screen-decomposition` produces the *build plan* from the plate (before).

A good decomposition closes the gap that creates the failures `screen-comparison` exists to catch: ambiguous "card on linen" without per-card chrome spec, "buttons" without variants, "backdrop" without screening strategy, "title" without font role.

## Inputs

- **Plate path** — the LOCKED sample image, e.g. `docs/redesign/art-kit/plates/samples/<screen>__LOCKED.{jpg,png}`
- **Screen id** — the new screen's id matching the `ScreenId` enum, e.g. `"warehouse"`.
- (Optional) **Existing port path** — if revising a screen, the current `app/src/screens/<screen>.ts` for diff context.

## Process

1. **Read the plate carefully.** Open with `Read`. Note every visible element — chrome, copy, typography, character, ornament, button — before writing.
2. **Extract the spatial skeleton.** Before any categorisation, do a dedicated spatial-only pass. See *Spatial skeleton* below. This is mandatory and populates the Layout Regions table with measured numbers, not slot labels.
3. **Lock the frame strategy.** Decide: is `nbframe_color.svg` screen-wide on this plate, or scoped to the central card? This drives every other decision (where titles can sit, how the backdrop interacts).
4. **Map regions to slots.** Assign S0/S1/S2 or CARD constants as *labels* for the skeleton regions already measured in step 2. Slot names are organisational; the measured % values are the spec.
5. **Inventory every atomic element** down the eleven categories below. Each entry includes: what it is, where it goes, which helper builds it, what state it reads.
6. **Decide asset sources.** For each non-trivial visual: reuse-from-kit / generate-via-MCP / draw-with-Graphics. Reuse first; generate only when a recognisable hand-drawn scene is required.
7. **Sequence the build.** Static layer constructed first (everything that doesn't react to state), dynamic layer second (state-driven), kit assets async-loaded last, frame on top.
8. **Specify the smoke test.** What state needs to be set before screenshot, and what should the snapshot show.
9. **Emit the markdown spec** using the template below.

---

## Spatial skeleton

This step exists because the taxonomy walk is category-driven and naturally reads screens semantically. Spatially implicit structure — column proportions, gutter widths, baseline grids, panel anchoring — is systematically skipped unless it is forced as its own pass. Do this pass first, in isolation, before categorising anything.

Slot names (`S0`, `S1`, `CARD`) are organisational labels only. They do not carry dimensional information. A developer handed `S0` without a width % has to guess. **Always record both.**

### How to build a skeleton

Describe the screen as a series of **regions and proportions only**. No semantic labels during this pass — name regions by position and role, not by content. Use approximate percentages of screen width/height.

Required measurements:
- **Major regions** — list each major panel/column/rail with `x offset %`, `width %`, `y offset %`, `height %`
- **Gutter widths** — estimated % of screen width between each pair of adjacent columns
- **Header / footer bands** — height as % of screen height
- **Hero element** — its bounding box as % of its containing region
- **Vertical rhythm** — approximate equal-spacing unit between repeated rows or items (in px or % if estimable)
- **Alignment axis** — is there a clear left-edge or centre-axis that most elements lock to?

Example skeleton output (abbreviated):

```
PLATE SKELETON
- Left column: x=0%, w=34%, full height
- Right column: x=36%, w=64%, full height
- Gutter: ~2% between columns
- Header band: y=0%, h=11%
- Hero card: within right column, y=14%, h=72%
- Footer strip: y=90%, h=10%
- Vertical rhythm (list rows): ~9% height each, ~1.5% gap
- Primary alignment axis: left edge at x=5% (both columns)
```

This skeleton feeds directly into the Layout Regions table in the output template. Every region row must carry both its slot label and its measured % values. A row with a slot name but no measurements is incomplete.

---

### Frame strategy
- **Screen-wide ornate** (Bench / Conception / Hub / Harvest / Cellar / WineBible / Warehouse / History): load `/kit/nbframe_color.svg` with `data:{resolution:3}` and `addChild` last.
- **Card-only ornate** (Grape Market / Char Select): no full-screen frame. The card itself gets a beveled outer + inset rectangle + small corner fleurs.
- **No frame**: rare; only if the plate's edge is meant to bleed into the surrounding chrome of the next screen.

Record the choice up-front; it constrains where titles can sit (clear of frame ornaments) and whether backdrops bleed to edges.

## Taxonomy — eleven decision categories

### 1. Frame strategy
(Already locked above — record choice + rationale here.)

### 2. Region / layout grid
- For 3-column screens: use `slots.S0` / `slots.S1` / `slots.S2` as labels. Record each column's measured `x %`, `w %`, and `y`-range from the skeleton.
- For single-card screens: define `CARD_X / CARD_Y / CARD_W / CARD_H / CARD_R` constants matching the plate's measured proportions, not estimated values.
- For sub-grids (lot columns inside a card, critic-card stacks): define gap + pad constants derived from skeleton rhythm measurement.
- For full-bleed atmospheric screens (Char Select, Grape Market): backdrop fills `screen.w × screen.h`, dialog floats above — record dialog bbox as % of screen.

**Rule:** every constant in this section must be derivable from the skeleton measurements. If a value cannot be grounded in a skeleton measurement, flag it as an estimate and note which element to re-measure.

### 3. Backdrop strategy
For each screen:
- **None** — plain `palette.linen` ground (Bench, Cellar instrument register).
- **Programmatic Graphics** — sky gradient + hills + buildings drawn in `Graphics` primitives. Use only when the plate's atmosphere is minimal or stylised geometric.
- **Generated SVG** — call your image-generation MCP (illustrative: `vinsim-image`) with a project-style prompt anchored on a known style reference (illustrative: `<STYLE_UUID>:GENERATED`). Matte + vectorise with `filter_speckle=12 + color_precision=3` (more aggressive for backgrounds where micro-detail reads as noise). Sanitise. Load with `data:{resolution:2}` and add as the first child of `staticLayer`.
- **Screening pass** (always with generated backdrops over a dialog): apply `ColorMatrixFilter` (saturation × 0.7) + an `alpha 0.15-0.2` linen overlay rect between the backdrop and the dialog so the dialog dominates.

Specify the choice + the prompt (if generated) + the screening pass.

### 4. Card chrome (per dialog)
For every floating card / dialog / sub-card, specify:
- Outer body: `roundRect` fill (linen / linen2 / inst).
- Drop shadow (optional): `+7,+9` offset, `0x000000 @ 0.30`.
- Outer border: `2-2.8 px` stroke, `palette.ox`.
- Inner inset: `4-8 px` margin, `0.9-1.4 px` gilt stroke at `0.40-0.60` alpha.
- Corner fleurs: 4 × small `drawFleur` glyphs at the card corners if the plate shows them.
- Header band (for stall-style sub-cards): top 36 px filled `palette.ox`, white-cream text.
- Inset data plaque (for prices/scores): 60-70 px tall sub-rect with `BADGE_BG`-style dark fill, top stripe coloured to denote grade.

### 5. Typography roles
For every text element, specify the helper + size + fill + extras:
- **Title** — script italic plate → `titleText(s, { size: 36-44, fill: palette.ox })`. Block-caps plate → `uiText(s, { size: 26-36, bold: true, track: 4, fill: palette.ox })`.
- **Section caption** — block-caps tracked → `uiText(s, { size: 11-12, fill: palette.ox, track: 3-4 })`.
- **Body** — `uiText(s, { size: 11-13, fill: palette.ink })`.
- **Italic display** ("Left Bank / Bordeaux") → `lblText(s, { size: 19-22, fill: palette.ox, italic: true })`.
- **Speech / Vinny voice** — `spkText(s, { size: 12-14, italic: true, fill: palette.ink })`.
- **Numerals** — `numericText(s, { size: 18-44, bold: true, fill: palette.gold | palette.ox })`. Anchor `"end"` for right-aligned scores.
- Anchors: `"middle"` for centred; `"end"` for right-aligned. Default left.
- **Title clearance**: anchor titles at `slots.S0.y0 + 30` minimum on screen-wide-frame screens to clear the gilt grape-corner ornament. This matches the "Titles anchored at `slots.S0.y0` get clipped — move down ~30 px" rule in `screen-comparison`'s common-slips list; keep these two numbers in sync.

### 6. Controls (use shared Button when available)

From pilotso11/pilotso11-skills, MIT.

More from pilotso11/pilotso11-skills