create-design-board

# create-design-board Point at a directory of images, get a design board. Supports iterative rounds, composite PNG grids, size previews, and comparison tables. **Critical lessons** (learned the hard way across 9 rounds of Embry OS icon design and the /learn-datalake viewer design): 1. Every design iteration MUST start with persona assessment. Visual direction, typography, color palette, and icon metaphors all derive from the persona's personality, background, and domain. Without this step, you'll waste rounds on directions that don't fit (cursive/serif E killed 2 rounds before we assessed Embry Lawson's persona). 2. The board must capture design REASONING, not just images. Round 8→9 of the Embry icon went through font weight reduction (500→300), glow shell elimination, and font reassessment — none of which was on the board until we caught the gap. Image tables without context are useless for future rounds. 3. **Persona rationale is MANDATORY.** Every design decision must include the persona's thought process IN THEIR VOICE — why they chose this layout, why they rejected alternatives, what their workflow demands. Without rationale, `/test-interactions` doesn't know WHAT to test or WHY, and the manifest can't define success criteria. Learned on 2026-03-14 when the /learn-datalake board had trait→decision mapping but no thought process — the human couldn't evaluate whether the choices were right because the reasoning was absent. 4. **Rendered mockup images are MANDATORY for interface boards.** ASCII wireframes are supplements, not replacements. For UI/interface mockups, write HTML/CSS with the actual theme colors, fonts, and layout, then render to PNG via browser screenshot. NEVER use diffusion models (`/create-image`, FLUX, etc.) for UI mockups — they produce stretched images with garbled text. Diffusion models are only appropriate for icons, logos, and artwork. Learned on 2026-03-14 when the /learn-datalake QuarantineView mockup was generated via `/create-image` FLUX and came out stretched with unreadable text, while the CascadeView was rendered from HTML/CSS and looked pixel-perfect. 5. **Board structure must follow: image → dialogue → next pane.** The board must be scannable pane-by-pane. For each pane/component in a view: show the mockup image FIRST, then the designer↔persona dialogue about it, then move on. NEVER bury images after walls of ASCII wireframes, spec tables, or rationale text. Spec tables go in collapsed `<details>` blocks. The human reads: see image, read conversation, next pane. Learned on 2026-03-15 when the /learn-datalake board was 1,423 lines of spec tables with buried dialogue — the human said "the whole point of a design board is clarity, legibility, and organization" and graded it D. Restructuring to image→dialogue→pane cut it to 657 lines and made it actually readable. 6. **Per-pane mockups, not just full-view composites.** Each view needs BOTH a full-view composite screenshot AND individual per-pane/per-section mockups. A single composite for a 3-panel view shows the layout but not the details. Individual pane mockups (960px wide HTML rendered to PNG) let the human inspect each component's typography, spacing, colors, and data density. For a view with N panes, produce N+1 images: 1 composite + N pane mockups. Learned on 2026-03-15 when Views 1-7 each had only ONE composite screenshot and the human asked "why do you still refuse to create an image per component?" 7. **Reality-check every feature via `/dogpile` before designing dialogue.** Run `/dogpile` for each major feature BEFORE writing persona dialogue about it. Research may kill features that no practitioner actually uses, saving hours of design and implementation effort. Include findings as a "Reality Check" subsection. If research validates the feature, proceed with confidence. 8. **`/dogpile` can search at the wrong altitude — domain personas must correct it.** Research may return results at the wrong abstraction level (e.g., industry-wide cadence vs. program-level cadence). Always let domain personas push back on research findings — they know their operational reality. Record both the research AND the persona correction as canon. Format: `**Persona** (pushback on /dogpile research): "..."`. 9. **Shared components need one mockup, multiple entry points documented.** When a component (slide-over, panel, modal) is accessed from multiple views, create one HTML mockup and document each view's entry point (trigger button, context passed, persona who uses it). Avoid duplicating the mockup per view. 10. **Human interjection protocol.** The human MUST be able to interject in persona dialogues. Format: `**Human** (interjection): "..."`. Human corrections replace the original dialogue and become canon. Human can also direct personas to `/dogpile` mid-conversation. Document this protocol in the board's preamble. 11. **Functional spec BEFORE mockups (FAIL if missing).** Every interface design board MUST include a concrete list of exactly what the interface will do — the pipeline/workflow steps it visualizes, with skills, inputs, outputs, and human gates documented per step. This goes BEFORE any mockups. Without this, the designer has nothing to compare their mockups against and the mockups drift into generic dashboards that don't match the actual system. Learned on 2026-03-16 when the music-lab design board R1 produced generic dashboard mockups (empty card covers, invisible pipeline content) because there was no concrete pipeline spec to compare against. R2 fixed this by writing the full 7-phase pipeline first, then designing views to show each phase's artifacts. `/review-plan` will grade design boards as **FAIL** if no functional spec section exists before the first mockup image. ## Rules (non-negotiable) 1. **DESIGN_BOARD.md is the single source of truth.** Every round, every decision, every eliminated direction MUST be recorded there. If it's not on the board, it didn't happen. 2. **Update the board after EVERY round** — not just image tables. Include: - What changed and WHY (font weight, color, layout decisions) - What was eliminated and WHY (directions that don't fit persona) - User feedback quotes that drove the change - Cross-round progression (e.g. "Round 8→9: eliminated glow shell") 3. **The `append` command adds image tables.** Design reasoning must be added separately — either via `--notes` (brief) or by manually appending a "Key Decisions" section after the image table. The tool handles images; YOU handle reasoning. 4. **Never skip persona assessment.** Round 1 must start with `assess-persona`. 5. **Board structure: image → dialogue → next pane.** Each view section follows: - Full-view composite image (overview) - For each pane: pane mockup image → Steve↔Nico dialogue → `<details>` spec - Test implications summary at end of view section - Appendices (info architecture, data flow, test manifest) at board end Spec tables, ASCII wireframes, and implementation details go in collapsed `<details><summary>Spec</summary>` blocks — never inline. 5. **Persona rationale in first person.** Every design decision MUST include the persona speaking in their own voice explaining WHY. The format is: ```markdown > **Why [design choice]?** > > "[Persona's reasoning in first person, referencing their workflow, > preferences, and constraints from their persona YAML]" > > **Test implication**: [What `/test-interactions` should verify based > on this rationale — specific, measurable criteria] ``` This is not optional. Without persona rationale: - `/test-interactions` doesn't know what to test or why - The manifest can't define success criteria from the user's perspective - The human reviewer can't evaluate whether choices are correct - Future rounds lose context on why decisions were made 6. **Render UI mockups from HTML/CSS, not diffusion models.** For each view: 1. Write an HTML file with inline CSS using the exact theme (colors, fonts, spacing from the board's palette) 2. Populate with realistic data (real filenames, plausible scores, actual labels — not Lorem Ipsum) 3. Render to PNG via browser screenshot (`playwright screenshot`, `wkhtmltoimage`, or Python `playwright`/`selenium`) 4. Save HTML to `figures/<view>_mockup.html` (viewable in browser) 5. Save PNG to `figures/<view>_mockup.png` (embedded in board) The HTML file IS the mockup — it's deterministic, readable, and pixel-accurate. The PNG is a screenshot for embedding in DESIGN_BOARD.md. **When to use `/create-image` (diffusion models):** - Icons, logos, artwork, visual concepts - NOT for UI layouts, dashboards, data tables, or anything with text ASCII wireframes may accompany HTML mockups as technical reference, but every view section MUST have a `` image. The Verification Checklist enforces this. ## Workflow (learned from 9 rounds of Embry OS icon design) 1. **Assess persona** (`assess-persona`) — Read persona YAML, extract traits, map to typographic and visual attributes. This eliminates wrong directions before any images are generated. 2. **Generate visuals** — For UI/interface boards: write HTML/CSS and render to PNG (see Rule 6). For icon/logo/artwork boards: use `/create-image` 3. **Build board** (`board` or `append`) — Create/update the design board markdown 4. **Generate composite** (`composite`) — Visual grid for quick comparison 5. **Collect feedback** — User reviews, provides quotes 6. **Update board with reasoning** — ALWAYS update DESIGN_BOARD.md after every round. Add BOTH the image table (via `append`) AND a design decisions section explaining what changed, what was eliminated, and why. The board must tell the story of the design evolution, not just show thumbnails. 7. **Repeat** from step 2 with narrowed direction ## Interface & Pipeline Design Boards Not all design boards are about icons. For UI interfaces, pipeline outputs, and report formats, the design board must show **what the output actually looks like**. ### Rules for Interface Boards 1. **Show the exact output.** Include rendered examples of what the skill produces — report sections, pipeline stages, data tables. Not descriptions of them. 2. **Use HTML color swatches** in markdown, not plain hex strings. Colors must be visible in the document: ```html <span style="background:#e74c3c;color:white;padding:2px 8px;border-radius:3px">RED #e74c3c</span> ``` 3. **Generate figures** using available skills, don't describe them in ASCII: - `/create-figure workflow` — pipeline flow diagrams (SVG/PNG) - `/create-gsn-diagram` — assurance case / evidence structure diagrams - `/create-figure architecture` — system architecture diagrams - Mermaid code blocks — for inline flowcharts in markdown 4. **Include a rendered output example.** Show what one complete unit of output looks like (one report section, one evidence case, one pipeline run). Use real data from a test fixture, not placeholder text. 5. **Link generated figures** from `figures/` subdirectory. Design boards that describe visual output without showing it are unacceptable. ### Interface Board Sections | Section | Purpose | How | |---------|---------|-----| | Color Palette | Show actual colors | HTML `<span>` swatches | | Pipeline Flow | Show processing stages | `/create-figure workflow` SVG | | Evidence Structure | Show CAE/GSN tree | `/create-gsn-diagram` SVG | | Output Example | Show one rendered unit | Actual markdown/HTML output | | Viewer Layout | Show UI arrangement | HTML/CSS rendered to PNG (see Rule 6) | ### Shared Component Pattern (Slide-Over Panels) When a component is accessed from multiple views, design it as a **slide-over panel** (not a modal or page navigation). Slide-overs preserve context — the user sees the triggering view behind the panel. - **Width**: 480px (standard), `#0f1216` background, 1px `#1e252d` left border - **Entry points**: Document each view's trigger button/action - **One mockup**: Create one HTML mockup of the panel, link it once, reference from all views - **Example**: A detail panel accessed from a data table ("+ Detail" button), a graph view ("Verify" on node), and a list view ("Check" on row). Same React component, multiple triggers. ### Human Interjection Protocol For boards with persona dialogues, the human must be able to: 1. **Interject** with domain knowledge: `**Human** (interjection): "..."` 2. **Correct** persona misconceptions: `**Human** (correction): "..."` 3. **Direct** personas to research: `**Human** (directing /dogpile): "..."` 4. **Provide context** before persona speaks: `**Human** (context for Persona): "..."` Human corrections replace the original dialogue and become canon. This protocol must be documented in the board's preamble section (before View 1). ### Persona Assessment for Interfaces For interface design boards, persona assessment maps to: - **Audience expertise** — determines information density and jargon level - **Review workflow** — determines what needs to be scannable vs. detailed - **Compliance context** — determines printability, color choices, accessibility ## Commands ### `assess-persona` -- Assess persona YAML for design direction (ALWAYS DO THIS FIRST) Reads a persona YAML file and generates a persona-to-design mapping section for the design board. Maps personality traits to typography, color, iconography, and visual style recommendations. Composes `/assess` and `/review-persona`. ```bash ./run.sh assess-persona --persona /path/to/persona.yaml --output ./DESIGN_BOARD.md ./run.sh assess-persona --persona /path/to/persona.yaml # stdout only ``` ### `board` -- Generate design board markdown from image directory ```bash ./run.sh board --images ./icons/v7/ --output ./icons/DESIGN_BOARD.md --title "Embry OS Icon Concepts" ``` ### `append` -- Add a new round to an existing board ```bash ./run.sh append --images ./icons/v8/ --board ./icons/DESIGN_BOARD.md --round "Round 6" --notes "Clean sans-serif E with dense starfield" ``` ### `composite` -- Generate composite PNG grid ```bash ./run.sh composite --images ./icons/v7/ --output ./icons/v7/board.png --cols 3 --bg "#0e0e1c" --title "Round 5" ``` ### `compare` -- Side-by-side comparison of specific images ```bash ./run.sh compare --images img1.png img2.png img3.png --output comparison.png --labels "Option A" "Option B" "Option C" ``` ### `sizes` -- Generate size variant previews ```bash ./run.sh sizes --image ./icons/v7/F2_minimal_nebula.png --output ./icons/v7/F2_sizes/ ``` ### Options | Flag | Description | |------------|------------------------------------------| | `--images` | Directory of PNGs/JPGs or list of files | | `--output` | Output file or directory | | `--title` | Board or section title | | `--cols` | Grid columns (default: 3) | | `--bg` | Background color (default: `#0e0e1c`) | | `--round` | Round name for append | | `--notes` | Round notes for append | | `--labels` | Labels for compare mode | | `--board` | Existing board markdown for append | ## Verification Checklist (MANDATORY — run before declaring board complete) **After generating a design board, you MUST verify these items. Do NOT skip this.** 1. **Per-pane mockups exist.** For each view with N panes, `figures/` must contain N+1 images: 1 full-view composite + N individual pane mockups. A single composite per view is NOT sufficient. Each pane must have its own 960px-wide HTML mockup rendered to PNG. 2. **Board follows image → dialogue → pane structure.** Each view section must: - Start with the full-view composite - Then for each pane: show pane mockup, then Steve↔Nico dialogue about it - Spec tables must be in `<details>` blocks, not inline - Test implications at end of view section - NO ASCII wireframes without an accompanying rendered mockup 3. **Images are linked in the board.** Every PNG in `figures/` must appear as a `` reference in DESIGN_BOARD.md. Unlinked images are invisible to readers. 4. **No spec-table dominance.** The board must be readable by a human scanning pane-by-pane. If spec tables, CSS values, or implementation details appear outside of `<details>` blocks, they must be brief (< 5 rows). Long specs go in collapsed sections. 5. **Color swatches are HTML spans, not plain hex.** Every color in the palette table must use `<span style="background:...">` for visual rendering. 6. **Persona rationale exists for every pane.** Each pane must have both a Steve quote (designer disposition) and a Nico quote (persona response). Check: - Does the dialogue flow naturally after the image? - Are pushbacks clearly marked and resolved? - Would `/test-interactions` be able to derive tests from the dialogue? 7. **Test implication → manifest mapping table exists.** The board must include a summary table mapping persona rationale to test scenarios with pass criteria. This table is the bridge between design intent and `/test-interactions` manifest. 8. **Board length is proportional to content, not ceremony.** A 7-view workbench should be ~500-700 lines, not 1400+. If the board exceeds 800 lines, audit for duplicated rationale, redundant spec tables, and dialogue that restates what Steve already said. Cut ruthlessly. 9. **Reality check section exists for complex features.** Any feature that involves a non-obvious workflow (auto-generated data, cross-view shared components, cascade feedback loops) must have a "Reality Check" subsection with `/dogpile` research findings BEFORE the persona dialogue about it. The research validates or kills the feature before design effort is spent. 10. **Shared component entry points documented.** If a component (slide-over, modal, panel) is accessible from multiple views, each view's section must reference the component and explain HOW that persona accesses it (button label, trigger action, context). One mockup, N entry point descriptions. 11. **Human interjection format present.** If the board includes persona dialogues, verify that `**Human** (interjection)` or `**Human** (context)` lines exist where the human provided domain corrections. Boards without any human voice in multi-persona dialogues are suspect — the human likely wasn't engaged in the review.