mock-build
Skill1 starsChanged yesterdayMITView on GitHub
Build or revise a local HTML mock of a UI before implementing it, using the workspace's own theme tokens and the mock kit. Use after design-brief, or whenever asked for a mock, mockup, wireframe, prototype or directions.
In this repository3 other files it gives its agents.
- AGENTS.mdAGENTS.md
- design-briefSkill
- mock-reviewSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 34
Tokens: If the workspace has a tokens.config.json, check the tokens are current: node .agents/skills/mock-build/scripts/mock-tokens.mjs …
- Very specific: line 42
Write the page with the Write tool: Read the template it names, then Write <slug>/v1.html from it, replacing every bracketed placeholder …
- Very specific: line 54
Show it as pictures, never as a bare path: Call show_mock with the mock's folder (or its mock.json): the reply gets a card with the title, …
- Very specific: line 94
Read reference/craft.md before the first version of a session.
- Distinctive: line 101
Check your own page only when the user asks, or before asking for approval: load it at 1280 px and 390 px, in light and dark, and look for …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Mock build
A mock is a folder of plain HTML pages, one per version, drawn with the workspace's own tokens and this skill's kit, and opened beside the conversation. It runs with any model and any harness: no network, no build step, no service.
The folder
docs/design/mocks/
tokens.config.json which theme file and selectors the tokens come from
tokens.css generated from the theme; never edited by hand
<slug>/
mock.json title, status, versions, approved version (kept by new-mock.mjs)
brief.md from design-brief
decisions.md one line per review round (mock-review)
kit/ tokens.css, kit.css, kit.js, copied when the mock was made
shots/ a screenshot per direction and theme (local only, never committed)
v1.html v2.html one page per version, never edited once reviewedEach mock carries its own kit/ copy because the preview serves only the page's folder and what
is beneath it, and so an older mock keeps the look it was reviewed with. A workspace without
docs/design/mocks/tokens.css gets the kit's fallback (Gram's neutral palette); pass --root to
put mocks elsewhere.
Steps
- Tokens. If the workspace has a
tokens.config.json, check the tokens are current:node .agents/skills/mock-build/scripts/mock-tokens.mjs docs/design/mocks/tokens.config.json --check, and regenerate without--checkwhen stale. For a new workspace, write the config (theme file,light/darkselectors, fonts, and amapfor tokens the theme names differently) and run it. - Scaffold.
node .agents/skills/mock-build/scripts/new-mock.mjs <slug> --title "…" --template <name>. Templates:app-screen(one screen in its states),flow(linked steps),options(two to four directions),components(variants and states),landing(a page, desktop and phone). It writeskit/,mock.json,brief.mdanddecisions.md, never the page. - Write the page with the Write tool. Read the template it names, then Write
<slug>/v1.htmlfrom it, replacing every bracketed placeholder with real content or keeping it as a visible gap. Use the Write tool, not a shell redirect or a script: in Claude, a file written that way appears in the workspace's Files view under this feature, where the user finds every version. - Screenshot it. Save each direction's board in dark and light to
shots/, named<direction>-dark.pngand<direction>-light.png, at the board's size. To give a direction its board, add it tomock.json(new-mock.mjs keeps it):"directions": [{ "name": "C Hybrid", "board": "c-hybrid-popover", "shots": { "dark": "shots/c-popover-dark.png", "light": "shots/c-popover-light.png" } }]. A board's id is itsdata-nameslugged (C Hybrid · popoverisc-hybrid-popover). Screenshots stay local:.gitignorekeepsshots/out of commits, and a committed image that no Markdown file embeds failsbun run check:scaffold. Pictures for a pull request go in its body. - Show it as pictures, never as a bare path. Call
show_mockwith the mock's folder (or itsmock.json): the reply gets a card with the title, the version, a thumbnail per direction with a dark/light switch, and Open in Preview. To open a board yourself,show_panelwithpanel: "preview"and<absolute page path>#<board id>. Without these tools (another harness), send the screenshots as images and then the page's path. - Say what to look at in two or three lines: what the version shows, the decision it asks
for, and the assumptions it makes. For directions, name each and its trade-off here, not on
the board. When the user is to pick a direction, ask it with your question tool
(
ask_questionin a worker,ask_userin an orchestrator): one option per direction, each with itsimage(a screenshot fromshots/) and itspreview(v1.html#<board id>), and the mock inmock. The card then shows each option's thumbnail, enlarges it on a click and opens the page at that board.
A new version is never an edit of the last: run new-mock.mjs <slug> --next, Read the current
version, and Write the next file whole. The bar links every version, so the user can compare.
The page contract
- Link
kit/tokens.css,kit/kit.cssandkit/kit.js(deferred), in that order, and nothing from the network except the font import tokens.css already has. No frameworks, no CDN scripts. <body class="mock">holding one<main class="mock-canvas">of boards. An optional<p class="mock-note">first says what to look at.- A board is
<section class="board" data-name="Name" data-size="1280x800">with one<div class="board-frame">inside.data-size="fill"makes it page-wide. Names are stable across versions: the review refers to them. - States:
data-states="full,empty,loading,error"on the board, anddata-when="empty"(or a comma list) on what each state shows. The board strip gets a button per state. - Links between boards:
<a href="#" data-goto="Board name@state">. Clicking a board's name opens it full window, so a flow can be clicked through; Esc returns. - Tweaks are levers, not copy: declare at most three in
<script type="application/json" id="mock-tweaks">(enum,boolean,color,range). Enums and booleans land asdata-tweak-<name>on<html>, colours and ranges as--tweak-<name>; style against those. The kit already reacts todensity(compact,comfortable). - Icons:
<i data-icon="name"></i>; the list isICONSinkit/kit.js. Add none of your own unless the product has them. - Colour comes only from tokens (
var(--accent),var(--fg-muted), the*-tintthe kit derives). A hex value in a mock is a bug.
Craft
Read reference/craft.md before the first version of a session. The short
form: real content or marked gaps, never filler; the product's own type and one accent; real
<button>, <a> and <label>; 4.5:1 contrast; layout with flex or grid and gap; works at
390 px; no gradients, emoji, glow or left-border cards; no fake status bars or keyboards.
Checking
Check your own page only when the user asks, or before asking for approval: load it at
1280 px and 390 px, in light and dark, and look for overflow, unreadable text and a state that
shows nothing. Beyond the shots/ the card needs, don't screenshot every round.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

