Design board
npx briefatto-board install places this skill under .claude/skills/ and adds pointers in AGENTS.md and CLAUDE.md. The skills CLI installs it for the selected agents.
If the project has a frozen DESIGN.md, read it before visual work and go straight to making pieces.
Commands shown as board use npx briefatto-board from the project root. If you used the installer from a local Board checkout, run node .claude/skills/briefatto-board/board.mjs. If a render reports missing Playwright Chromium, run the install command it prints and retry.
Write and edit HTML, JSON, Markdown, and scripts with your file tool. Run saved scripts as files. Keep commands compatible with the active shell, including PowerShell on Windows. Quote paths containing spaces and pass globs in quotes for the board to expand. Avoid long heredocs and quoted one-liners that generate files.
Existing sites and work in progress
- For a frozen board, use the current
DESIGN.md. Checkboard statusbefore resuming. A current piece declares the current version. A stale piece declares an older version. For an unrecorded piece, inspect its source and render, revise it against the current guide if needed, then record the version actually used. For pieces outside the board, find their intended output location and save standalone HTML pieces underoutputs/with their assets. Record the version after checking the piece against the guide. - For an existing site without a frozen board, adopt its current look first. Run
board adopt .from the project. It finds top-level HTML pages or a conventional build with an index page. Pass--root <built-directory>for a different build root and repeat--page <file>for chosen files relative to that root. For a running site, repeat--page <url>for the representative routes and states. Leave the site running for freeze. The default captures are desktop and mobile. Repeat--viewport WIDTHxHEIGHTto use other sizes. - Open each screenshot in
.briefatto/adoption/and readevidence.jsonfor computed styles, visible copy and candidate style files. Inspect the page source, CSS variables, Tailwind configuration, theme and logo files that the pages use. Identify which components carry the brand across routes and screen sizes. - Write the root
DESIGN.mdas a handoff from one designer to another. Describe the existing layout, spacing, navigation, components and logo by role. Take the voice and example copy from the real pages. Freeze records the exact computed styles and any supplied brief or client constraints. - For
keep our look,freeze withboard freeze .once the guide is ready. Fortidy it up first,runboard adopt . --checkon the selected pages, show the findings and proposed fixes, and wait for the user's yes. Fix the agreed issues, rerun the capture and floor check, and update the guide from the revised pages before freezing.board freeze . --checkrequires a passing floor as well as guide validation. - Freeze an adopted board with the same page selection for later brand changes. To change the reference pages, rerun adoption with the new selection. If the project has partial pieces and no board, adopt and freeze first, then review and record the existing pieces. If adoption has already been recorded, use the existing captures and draft to resume writing or freezing.
Brief → references → directions → client review
- Read
brief.mdand the client's materials. For a chat brief, save the client's words tobrief.md. Preserve the brand name, offer, copy, URL, details, and literal requirements. When these requirements are in prose, record their exact wording inessentials.jsonfor checking. Userequiredandtermsarrays for shared copy,requiredByFormatto map format IDs to arrays of copy specific to each canvas, andbodyfor body copy. List incoming images inassetsas{"path":"assets/photos/store.jpg","origin":"brief"}or use"origin":"client"for a client attachment or later supply. Include only client-supplied images in this list. Board accepts layout whitespace and a rendered line break in place of a standalone middle dot. Preserve the approved words and other punctuation. - Search for live references and capture them in one command,
board refs . --capture <url1> first.png <url2> second.png, or copy in images supplied by the client. Use bare PNG filenames other thansheet.png. The command saves them underrefs/and flags captures to retake or replace. Open each capture to confirm it shows the intended reference. Inrefs/manifest.json, list{"image":"first.png","source":"https://example.com/page","note":"What to look at"}for each picture. Use a source file URL for a client image. If a picture is unavailable, anoteentry is labelled text-only fallback. Runboard refs ., show the actualrefs/sheet.pngto the client, and ask which parts to work from. Wait for the client's response before drawing directions. Keeprefs/internal to the review. - Choose the places this client's audience will see the work, such as a README header, docs page and link card for a developer tool. Declare the canvases in project-root
formats.json, an array of{"id":"readme","label":"README header","width":1280,"height":360,"seenWidth":900,"source":"Rendered within the repository page"}entries. With no client-specific formats, use hero 1440×900, post 1080×1080 and story 1080×1920. Use the same formats in all three directions and the kit. SetseenWidthto the displayed width in CSS pixels, at mostwidth. The floor scales its 11 px displayed text minimum to the canvas width.- Set
kindtoweb,social,print, orstorywhen the brief identifies the channel. For print, useprint: { widthMm, heightMm, bleedMm }in JSON, with quoted keys, for the physical trim size and bleed per edge. Supply these measurements from the brief or printer. A button-like call to action in a print piece produces a note. - For stories, use
safeZones: { top, right, bottom, left }in JSON, with quoted keys, for unsafe edge insets in canvas pixels. Use values from the brief or the target platform. Copy that crosses into those insets fails the check.
- Set
- Draw three distinct directions with the brief's real copy and a designed wordmark in each. Load open-licence web fonts in the samples. Under each
directions/<id>/, save<format>.htmlfor each canvas and adirection.mdwith its name, reference numbers, format choices and why, exact font load lines and CSS fallback stacks. Describe the recurring graphic device in## Deviceand mark it withdata-devicein the samples. Mark the visible device or a wrapper with its own rendered width and height. Runboard directions .and show the sheets for a pick or changes. - Record the client's words verbatim in
refs/notes.md. Put each confirmed brand must or must-not in its own fencedconstraintblock. If none fits, agree on a direction to revise or show replacements. Apply the requests, runboard directions . <id>, and show the revised sheet. Wait for explicit production approval. To freeze v1, put the client's exact approval in a fencedapproval <id>block, using the chosen direction ID. When the user is their own client and has explicitly approved the direction as a solo developer, useboard freeze . <id> --self-approved. The decision appears inboard log.
Freeze → make pieces → feedback
- Write the prose in the project-root
DESIGN.mdafter the client picks a direction. Open the chosen samples as images and read their HTML and styles. Brief the next designer on the decisions they need to make.- Freeze writes Brand facts, Campaign copy, Client musts and must-nots, and the exact computed styles. Use
board freeze . <id> --dry-runto preview the generated guide without writing files. Leave the marked block to Board on later edits. - If a text role needs a more specific name than its HTML element supplies, label it in the sample with
data-board-role, such asdata-board-role="price numeral". Board records each role's rendered sizes and colours per canvas. - Name each recurring part by its job, then explain how it is built and how the parts sit together. Include details such as base rules, lockups and footer treatments when they carry the identity. Explain how the arrangement recomposes for different canvases. Leave out measured ratios, coverage percentages and centroid coordinates.
- Under
## Typography, explain which parts use each face and include the font load lines as HTML<link rel="stylesheet" href="…">, CSS@import, or@font-facecode. Use resolvable sources. - Make the guide sufficient on its own. Describe how to build the parts directly and refer only to assets that ship with the project. The reader may have only this file and the supplied brand assets.
- Run
board freeze . <id>. Read its validation report, correct any named failures in the draft or required campaign copy in the samples, and rerun. Freeze stamps and archives the guide. Useboard log,board diff v1 v2, andboard statusfor version history and piece status.
- Freeze writes Brand facts, Campaign copy, Client musts and must-nots, and the exact computed styles. Use
- Make the kit in the chosen formats from the frozen
DESIGN.md. Recompose for each canvas. Save final layouts asoutputs/<format>.htmlwith<meta name="board-version" content="v2">for the version used. Keep review proofs underoutputs/review/, or mark them with<meta name="board-purpose" content="review">. Export the actual files for delivery and list every PNG and PDF in project-rootdeliverables.json, an array of entries such as{"file":"delivery/card.png","html":"outputs/post.html","width":1080,"height":1080}. Use editable HTML that renders on its own for each entry. For a transparent mark use"transparent":true. Addviewportif the CSS layout size differs from the export size,"fullPage":truefor full-page PNG capture, andpageSizeMmif a single-page PDF has a specified physical page size.board check .validates the listed exports.board kit . --campaign "<launch name>"checks the layouts and final files and writesoutputs/kit-check.jsonand the kit sheet. Fix failed checks before handoff. If a format has no checkable brief requirements, record the ones it must meet inessentials.jsonand freeze again. - For brand feedback, record the client's exact words, revise and confirm the direction as above, update
DESIGN.md, then runboard freeze . <id> --note "<brand change>". Useboard statusto find pieces to revisit and update each piece's version when revised. For piece feedback, edit only that piece.
board check runs the floor, including visible copy clipping and overlap at the canvas size, and checks the brand name where it appears. Give later one-off pieces their own filenames, such as outputs/holiday-hours-post.html, and check them with board check . <file.html>. To add a later piece to the campaign, give it <meta name="board-campaign" content="campaign-name"> so normal checks enforce required copy and photos. Pass --brief to check all inputs against the campaign requirements for that run. Read each piece's scope and checks in the command output or check.json before handing it off.
Optional tools
-
Add
--checktoboard directions .to see floor and campaign brief findings on each sample. Add it toboard freeze . <id>to make the full sample floor a condition of freezing, alongside guide and required campaign copy validation. -
Add
--consistencytoboard checkfor frozen-board comparisons and composition notes on named kit formats such aspost.htmlormarch-post.html. -
Composition families and sample pages in
board/are optional references. Use their arrangements as options when composing a new piece. -
board export astryxwrites an Astryx theme from the frozen board. -
board freeze . <id> --extractgenerates a guide from measured sample values. It replaces the root guide with its generated file.