editable-design

# Editable Design Design the complete requested fixed-canvas visual, verify it, then deliver it. The default deliverable is a fixed-canvas `index.html`, a mouse-editable `editor.html` with scan and exploded-layer views, a poster-specific visual system built from generated artwork, live typography, and/or HTML geometry, and a rendered PNG. It also includes `replay/index.html`, a deterministic visual account of the real input, reference, plan, asset prompts, code, review, and layer output, plus a standalone animated `layers.html` breakdown. ## Communicate clearly Assume the user is a nontechnical knowledge worker. Talk about their poster, choices, progress, and results. Keep tools, commands, files, renderers, browser software, dependencies, source control, paths, and exit codes out of user-facing messages unless the user asks or must take action. Use no more than one short update for each user-visible phase: preparing, designing, and delivering. If a phase takes longer than 60 seconds, give one plain-language update. Keep recoverable technical problems private; say only that you hit a problem and are trying another method. **You are the designer, not a consultant.** Decide the layout, hierarchy, palette, type, composition, and white space yourself. Do not generate design options or pause for a visual selection unless the user explicitly asks to compare designs. When undecided, pick one and say why; do not hand the choice back. Ask one concise group of up to three discovery questions only when the missing information would materially change the finished poster or force you to invent something. **The only thing you must ask about is fact**: prices, dates and times, locations, contact details, exact brand and product names, legal notices. Inventing one of those ships a falsehood, which is worse than leaving it out. Everything else is a judgement call, and judgement is your job. ## Choose the execution path Use the **one-shot fast path** only when all of these are true: - this is a new poster in an empty or projectless workspace; - the layout needs no generated shipping imagery, because type, colour, or CSS shapes carry it; - the request does not involve multiple artwork slots, a cutout subject, print DPI, or revising an existing poster; and - the deliverable is a single screen-resolution render. Use the **capability path** otherwise. ## Prepare academic PDF inputs When the source is a research-paper PDF, complete a compact evidence pass before the reference or design plan. Read the whole paper's text structure and inspect the pages containing its principal figures, tables, and diagrams; an abstract-only summary is not enough. Write `source-brief.md` with: - the research question and why it matters; - the method as a short causal or procedural chain; - three to five result claims, preserving every reported number, unit, baseline, and comparison exactly; - the conclusion and any limitation needed to avoid overstating the paper; and - a visual-evidence inventory naming the strongest source figures or tables and what claim each one supports. Record the PDF path and `source-brief.md` with the input evidence. Use the brief as the factual boundary for all poster wording. Prefer a real, legible source figure, table crop, or faithful code-native reconstruction when it carries a key result. Generated artwork may establish atmosphere or explain a concept, but it must not replace empirical evidence or introduce unreported quantities. When the paper contains usable visual evidence, the final poster must include at least one evidence-bearing visual tied to a live caption or result claim. ## Generate the imagery Generated artwork is a first-class visual material, not a required full-canvas layer. Use it wherever photographic, illustrative, material, atmospheric, or subject-specific content carries the design. Live typography and HTML geometry may instead form the primary visual system when their precision, repetition, and spatial relationships are the composition. Do not replace imagery the design genuinely needs with a generic gradient, flat fill, or improvised CSS illustration. Equally, do not generate a backdrop merely to prove that artwork was used. Generated support does not need to dominate the page; compact visual assets are worthwhile when they make a section easier to scan, compare, or remember. Avoid model-authored SVG illustrations. Graphic content is either generated raster artwork or it is typography and geometry. Codex's bundled Node runtime includes Lucide; for common small icons, prefer a coherent locally embedded Lucide subset over ad hoc CSS drawing, without adding runtime external requests. ### Choose the reference mode Treat reference handling as a four-value mode even when the host exposes no formal setting: - `auto` — the default. Resolve it to `art-directed` for every new poster, including an open brief and the one-shot fast path; the composition reference is a standard design step, not an optional enhancement that depends on the user describing a finished picture. Resolve it to `off` only when the user explicitly declines reference generation, or when a small revision to an existing poster does not change its composition. Resolve it to `reproduce` when the user supplied an image as the target or asked to match one closely. A loose style or mood reference does not imply reproduction. - `off` — skip composition-reference generation. - `art-directed` — generate one enhanced, non-shipping composition concept. - `reproduce` — treat the supplied reference as a high-fidelity specification. Respect an explicit user choice over `auto`. Whenever `art-directed` is active, run the creative prompt enhancer below; it is not a separate switch. When image generation is unavailable, resolve `auto` to `off` when live typography, HTML geometry, local icons, and user-provided assets can satisfy the request. If the requested result fundamentally requires generated photography, illustration, or cutouts, report the missing capability instead of silently substituting a materially weaker design. A supplied target can still use `reproduce` without image generation when it can be rebuilt from live elements. ### Create an art-directed composition reference Generate **one reference composition** before planning anything, and read the layout off it. Pass the request through a **creative prompt-enhancement step** and ask the image model for one opinionated, fully art-directed finished-poster concept rather than a literal transcription. Lock every user-specified fact, string, subject, required placement, palette requirement, and exclusion. Freely intensify only the composition, hierarchy, crop, scale relationships, photographic direction, lighting, materiality, typography treatment, grid behaviour, and spatial rhythm. This reference-only step deliberately has more creative freedom than shipping-asset generation, and it is the only step where the image model is allowed to render text. Creative expansion changes the design language, not the requested content. Do not invent facts, dates, locations, prices, brand names, slogans, people, products, narrative subjects, or extra scene objects. Preserve minimalism when requested, but express it through tension, scale, atmosphere, material depth, and precise hierarchy rather than by making the frame merely empty. Three boundaries make this safe. Breaking any of them wrecks the rest of the run: - **The reference never becomes artwork.** Save it under `reference/`, never `assets/`, and never crop it into a backdrop — it has generated lettering all over it. - **The reference's pixels never ship.** Every character is re-set in HTML. A generated glyph cannot be edited or re-flowed, and generated Chinese in particular is often subtly wrong. Its *wording*, though, is fair game: if the reference invented a line that fits, adopt it as live HTML text and name the added lines in the handoff. Facts are the exception. Prices, dates, locations and brand names still come from the user; a plausible date the image model made up is still a false date. - **Choose the shipping asset architecture after reading the reference.** The reference determines composition, hierarchy, visual regions, and depth relationships; it does not require a backdrop. Generate a clean full-bleed backdrop when the integrated design decision selects a continuous scene. Otherwise generate the selected slots, cutouts, or fragments, or rebuild the graphic relationships as live typography and geometry when the reference's visual force is fundamentally graphic and modular. Read off the reference: major visual regions and their proportions, band positions when they are actually present, visual weight, palette relationships, text-bearing regions, depth and overlap relationships, and any supporting visuals, large or small, that materially contribute to meaning, comparison, or recall. Write these observations into the integrated design plan below. Before calling the image model, save the exact enhanced prompt in `reference/composition-prompt.md`; after the result is imported as `reference/composition-reference.png`, record both under `P02_reference`. These are evidence for the Replay, not extra design prose. ### High-fidelity reproduction When the user asks for the reference to be reproduced closely — "make it look like this" — or supplied the image explicitly as the target, treat it as a specification rather than a sketch. Work element by element: match positions, proportions, decorative marks and where each colour sits, and adopt its wording wholesale as live HTML text. Two things do not change under this mode. Text is still re-set in HTML, never lifted as pixels. And facts still come from the user. Say in the handoff that you were reproducing a reference, and name whatever you could not reproduce — a hand-drawn contour edge, a texture, a script face that is not installed. ### Choose the asset architecture before prompting Before finalizing the asset plan, identify every visual component that materially contributes to subject, hierarchy, atmosphere, comparison, recall, semantic distinction, or fidelity to the reference. Let the composition determine the asset count. Generate all main and supporting assets needed for the finished poster, and do not consolidate distinct visual roles merely to reduce generation work. Use the image model proactively for supporting visual assets when they would strengthen communication; do not reserve generated imagery only for the main visual or explicitly requested detail shots. A generated raster is not the only way to preserve a strong visual reference. For example, a dense Memphis-style exhibition poster may be strongest as a live modular composition: monumental typography, saturated colour fields, black keylines, checker and halftone patterns, label rails, inline pictograms, and independently placed icon panels. Rebuild those relationships as live HTML/CSS geometry and inline SVG when flattening them into a background would weaken their structure, precision, or editability. This is a complete visual system derived from the same mandatory art-directed reference, not a fallback from generated imagery. Choose by visual topology, not by habit. No topology is the default: - **Slot matrix** — one image per bounded card, product cell, specimen, or timeline node; HTML owns the grid and captions. - **Code-native modular field** — live typography, colour blocks, rules, patterns, icon cells, diagrams, and inline geometry form the primary visual system. Use this when the reference's force comes from graphic composition, precision, repetition, and modular rhythm rather than photographic material. - **Continuous scene** — one zoned full-bleed backdrop plus HTML typography. Use this when the meaningful imagery depends on shared lighting, perspective, atmosphere, or physical continuity. - **Cutout stack** — independent transparent subjects arranged across explicit back, middle, text, and foreground layers. - **Layered collage** — a base field plus a small set of independently placed photo fragments, paper pieces, textures, stickers, or cutouts. Keep elements together when their shared lighting, perspective, material, or physical interaction makes them one visually continuous scene. Separate or rebuild them independently when their position, crop, replacement, repetition, semantic role, or overlap is part of the design. Do not split elements that share continuous light and perspective merely to make the file count larger; their seams will show. Visuals assigned to distinct meanings must remain perceptually and semantically distinct. Reuse is acceptable only when each instance clearly communicates its own intended meaning; unintended repetition is a defect. For a slot matrix, cutout stack, or layered collage, read [Asset architecture](references/asset-architecture.md). When two or more shipping assets are needed, create `asset-plan.json` before generating anything; record each asset's form, target rectangle, layer order, and dependencies. ### Prompt the shipping assets Before writing shipping prompts, read [Imagery](references/imagery.md) and follow it exactly. The art-directed composition reference may render poster text; shipping assets may not. Use one call per distinct asset. After every shipping prompt and destination filename is frozen, dispatch up to ten independent generations concurrently in one batch; do not split a run of ten or fewer assets into smaller waves. For more than ten, use consecutive batches of ten. Parallelism applies only to assets without dependencies on another returned image; corrections based on a returned image remain sequential. Orchestrate the batch with all-settled semantics rather than fail-fast semantics so one rejected call cannot cancel or hide the successful results. Let the whole batch settle, preserve every successful result, and retry only the failed calls immediately rather than rerunning or delaying the successful ones. Retry a transient failure once with the same prompt. For a safety refusal or an obvious prompt-specific failure, revise only that asset's prompt and retry it once; stop automatic retries after that second attempt and continue with the successful assets while choosing a safe substitute or reporting the missing slot. Do not ask for several unrelated cutouts in one sheet: one call returns one raster, not several independently editable transparent files. Import all successful results in one post-batch pass with `scripts/import-asset.sh GENERATED_PATH assets/NAME.png`. Check dimensions, unwanted lettering, and obvious slot mismatch together in that same pass, then record the prompt file and selected asset results once. Do not pause for per-image narration, rewrite already-frozen planning files between successful results, or introduce a second selection phase when the outputs satisfy their slot prompts. For ten or fewer independent assets, post-generation handling should add only local import and one consolidated inspection, not another multi-minute reasoning stage. ## Start new posters immediately Before setup, if the intended target directory already exists or the workspace contains an apparent same-title poster project, ask whether to continue that project or create a new one. Do not treat matching titles, copy, assets, or timestamps as authorization to modify user-owned files. Make no writes to the existing project until the user answers; skip this confirmation only when the user explicitly identified that existing project as the target. This collision check happens before and overrides the immediate-setup rule below. For a new poster in an empty or projectless workspace, make setup the first task action. From an existing parent directory, run this skill's `scripts/init-poster.sh TARGET`; do not set the command's working directory to a target that does not exist yet. Do not run a second initializer. It copies the starter plus project-local runtime scripts and reports whether a renderer is available. Change into the target before running the remaining commands. **Complete this before asking any discovery questions**, then open the starter's `index.html` in the browser so the user sees the placeholder layout while you work. Begin the trace in the same breath: ```bash scripts/trace.sh init "<one line about this poster>" ``` Immediately write the active user-authored brief to `brief.md`, verbatim and in order, including user-supplied attachment paths. Do not copy ambient UI state, system instructions, or hidden context into it. Record it with `scripts/trace.sh artifact brief.md P01_input`. This is the Replay's source of truth; the trace label is not a substitute for the original request. If no renderer is available, do not abort: the HTML is still deliverable, it just produces no PNG. Say so once in the final handoff rather than repeatedly. In a delegated, background, or invisible thread, initialize normally but do not open a browser purely for preview. **Reading the render is not preview and is never skipped.** ## One-shot build After setup and any necessary clarification, design and produce the poster in one focused pass. Trace only the stable artifacts named below. 1. Read `index.html`, `poster.json`, and the contract in `README.md`. Read other files only when the implementation needs them. Avoid broad scans and speculative research. 2. **Fix the canvas.** Infer the size from the intended use, and tell the user which one you chose and why in your first update. Write it into `poster.json`; the root element's `width`/`height` must equal its `data-canvas-*` values. `scripts/trace.sh decision canvas "<W>x<H>" "<why>" P09_canvas` 3. **Complete the reference stage before planning the design or shipping assets.** Resolve the reference mode. Under `art-directed`, save the enhanced prompt, generate and import the composition reference, read it, and record its prompt and image under `P02_reference`. Under `reproduce`, inspect the supplied target as the specification. Under `off`, continue without creating reference artifacts. 4. **Make one integrated design decision after the reference settles.** In one pass decide the final live HTML wording, information hierarchy, asset topology, text and image regions, layer order, palette roles, font stacks, and asset or region geometry. Keep every user-supplied string verbatim; name any non-factual wording adopted from the reference in the handoff. Write the decision once in `design-plan.md`. When two or more shipping assets are required, also write the minimal machine-readable `asset-plan.json` from that same decision. Record both together under `P11_asset_plan`. When typography is a primary visual material or the editor needs stronger alternatives, read [Font system](references/font-system.md), choose fonts by role, and use the self-hosted kit rather than defaulting to the same system sans/serif pair. 5. **Generate the artwork** per the batching, retry, import, and inspection policy above, into `assets/`. Record the completed batch once. In multi-asset runs, every `asset-plan.json` entry's `prompt` value must exactly match one `##` heading in `prompts.md`, and the imported filename stem should match the asset `id`: `scripts/trace.sh artifact prompts.md P12_generate_imagery`. 6. **Make one complete layout patch.** One file, CSS inline, zero external requests, absolute positioning inside the canvas, fixed px for every layout dimension. Declare the palette and font stacks on `:root` and reference them throughout. Do not write comments. When the plan selects a bundled font, run `scripts/font-kit.mjs add <id> index.html` after the HTML exists, then assign its generated `--font-kit-<id>` variable to the intended type roles before checking fonts. For selected Lucide icons, resolve them from the bundled runtime at build time and inline only their SVG markup in the poster HTML; keep their size, stroke width, and color treatment consistent, and add no runtime import. 7. **Check the final HTML font stacks once** with `scripts/check-fonts.sh index.html`. A missing family raises no error in the browser, and a family marked `latin only` must not set CJK text. Fix any failure before rendering. 8. **Clear the scaffolding**, see below. 9. **Check the deterministic contract**: `scripts/check-poster.sh index.html`. Fix every failure before opening Chrome. 10. **Run the editable-layout preflight before the first render**: `scripts/trace.sh run P14_contract -- node <poster-building-skill>/scripts/check-contract.mjs index.html`. It checks fixed geometry, layer and group structure, viewport stability, font loading, and whether live-text hit areas are blocked by another layer. Fix every failure now; this is the cheap point to change structure. 11. **Render**: `scripts/trace.sh run P15_render -- scripts/render-poster.sh index.html out/poster.png`. It reads the PNG's real pixel dimensions back and compares them with `poster.json`; a mismatch is an error. 12. **Review, fix, and optimize the render** through the single review loop below. Keep every real pass in `render-review.md`; do not create a second review record for optimization. After the final render, record the consolidated review once under `P16_read_render`, and record the current `index.html` and `out/poster.png` under `P15_html` so Replay cannot select an obsolete version. 13. **Wire the bundled editor runtime** without changing `index.html`: `node scripts/wire-editor.mjs index.html`. Confirm that `editor.html`, `layer-editor.css`, and `layer-editor.js` exist, then `scripts/trace.sh artifact editor.html P17_editor`. 14. **Verify the editor and exploded view** with `scripts/trace.sh run P17_verify -- node <poster-building-skill>/scripts/verify.mjs index.html`. The same browser run writes the verified standalone result to `layers.html`; do not launch a second generation pass. It must pass the geometry-plus-pixel zero-drift, edit/export round-trip, overview/background component extraction, one-level gallery spread, theme, scan, replay, collapse, and standalone-render checks. After it passes, record `scripts/trace.sh artifact layers.html P17_layers`. Read [Editor and exploded views](references/editor-runtime.md) for setup and commands. 15. **Generate the Agent Design Replay** only after the poster and editing contract pass: `node scripts/build-replay.mjs .`, then `node scripts/verify-replay.mjs replay/index.html`. Record the `replay/` directory under `P18_replay`, then `scripts/trace.sh finish ok`. For an older project without those project-local scripts, run this skill's bundled `scripts/build-replay.mjs PROJECT` and `scripts/verify-replay.mjs PROJECT/replay/index.html` instead. Open the generated Replay once and confirm that the seven nodes, Prompt/result pairs, render, Review, and layer preview load. The fixed template, not the agent, designs this page. Read [Agent design replay](references/replay-contract.md) only when recording or diagnosing its evidence contract. ## Record the creative path without constraining it The Replay is a post-build view of real artifacts. It does not add a visual selection gate, require multiple directions, or change how the poster is designed. Preserve the exact user request, enhanced reference prompt, plan, shipping prompts, imported results, HTML, render review, and verified layer output while working; the builder groups them into seven story stages. Do not ask the model to redesign the Replay, summarize the run from memory, add generic “why this was done” commentary, or reconstruct missing prompts. The viewer displays recorded Agent content and marks absent evidence as missing. Optional alternatives and selection branches appear only when the run actually contains them. ## Capability path ### Project setup - For a new poster use the flow in **Start new posters immediately** and keep the starter's canvas, runtime, and validation contract. Its preview scaffolding is not a composition, asset-topology, image-coverage, or text-placement guide. - For an existing poster, preserve its file organisation, `poster.json`, and asset paths. A copy change is only a copy change; do not re-flow the layout along the way. - Keep poster code within the project directory. ### Shape the poster - Hierarchy is the whole job. A viewer takes a poster in three passes: hook, then claim, then detail. Build that staircase with size, weight, colour, and white space, and make the steps genuinely different. Two elements of similar visual weight fight each other and both lose. - White space is structure, not what is left over. - Build a controlled palette with explicit roles for the field, text, accents, and semantic states. Add colours when the brand, reference, imagery, or information encoding requires them; no colour exists merely to fill space. - Commit to one direction — editorial, luxury, brutalist, playful, technical — and let it drive every decision. - Give every typeface a clear role and verify that it covers the script it sets. Use as many families as the composition genuinely needs while preserving a coherent hierarchy. Every step of the size ramp must be clearly different from the last. - Distinguish the active type system from the editor palette. A poster normally uses two or three families, while three to five verified `:root` font roles may be exposed as meaningful alternatives. For a poster, cover, flyer, or campaign, do not ship only one generic sans stack unless the brief or brand deliberately requires it. - For vertical CJK type, set `white-space: nowrap` and centre it with flex. `text-align` controls the vertical axis under `writing-mode`, so a fixed-width box leaves the text against its right edge. - Where text sits over artwork, guarantee contrast explicitly: a solid panel, a scrim, or a directional gradient sized to the text block. Do not count on the image being dark enough exactly where you need it. - Do not default to a coloured or black text box: first use an existing calm region or a local scrim, and add a panel only when its material, edges, palette, and overlap make it an intentional part of the composition rather than a generic card. - When unsure about the layout, read [Layout and typography](references/layout-typography.md). - When typography is prominent or the available choices feel generic, read [Font system](references/font-system.md) and use its self-hosted font kit. ### Build the default editing contract Every poster ships with the bundled editor runtime for human micro-adjustments and presentation. It can drag layers; resize width, height, or both with side and corner handles; edit text; change font size or a declared font family; delete and undo; save a local draft; scan and spread layers into an exploded view; and download clean edited or exploded HTML. A manually resized text width remains fixed during later text or font-size edits so the user's intended wrapping is preserved. It is not a second design application. Mark each independently movable semantic unit with a unique `data-layer-id`; keep full-bleed backdrops, textures, scrims, fixed frames, and `data-explode-group` wrappers unmarked. Use `hf-slot` for independently editable styled-text leaves, and use a non-nested `data-explode-group` only when it contains at least two meaningful leaf layers; never nest layer IDs or explode groups. Declare selectable font stacks on `:root` with a generic fallback. Keep the prebuilt editor runtime unchanged, generate `editor.html` only with `node scripts/wire-editor.mjs index.html`, render and validate `index.html`, and run the bundled browser verification before delivery. ### Deliver the standalone layer breakdown Every poster includes `layers.html` in addition to the live breakdown in `editor.html`. The bundled `scripts/verify.mjs` generates and verifies it in one browser run. Groups remain whole modules by default; when fewer than five primary content components would be visible, the same one-level gallery also adds the grouped text leaves as companion tiles so the breakdown does not feel empty. Do not hand-edit it, wire it back into the editor, or substitute it for the poster render. Read [Editor and exploded views](references/editor-runtime.md) before diagnosing a failure. ### Clear the scaffolding before delivery Apply the starter cleanup contract in `README.md` and record the sweep with