mockup-architect
Standards for UI mockups as self-contained HTML — dated folders, a gallery index, tokens as CSS variables, and the fixed preview bar that flips palette, corners, accent and mark variants (state in dat
SKILL.mdskills/frontend/mockup-architect/SKILL.md
GitHubMockup architect
How to build mockups that can be compared, screenshotted and decided on. Companion to landing-page-designer (what a landing page must say) and ui-ux-architect (what the shipped UI must satisfy).
1. Rules
- Self-contained. One
.htmlopens fromfile://: inline or sibling CSS/JS, no build step, no CDN. A mockup never imports the app's code. - Dated folder
mockups/<collection>/<YYYY-MM-DD>/, anindex.htmlgallery linking every page, and a row in the collection README (file, what it decides). Superseded rounds move toarchive/; do not edit them. - Tokens, not literals. Colours, radii and fonts are CSS variables on
:root; variants are:root[data-<axis>=<value>]blocks. Same names as the app (--bg --card --text --muted --line --line-strong --accent --btn-bg --btn-fg --shadow) so the bar and the port both work. - One question per page. A page that offers options says what is being decided and recommends one.
- Honest data. Numbers are real or marked sample.
- Draw, do not ship. Mockups never touch the app's source.
2. The preview bar (use it whenever a page offers options)
assets/pv-bar.css + assets/pv-bar.js; assets/example.html is a working page. Copy both files next to the
mockups (or inline them); do not link across repos.
- Declare axes in
<script type="application/json" id="pv-config">in<head>, beforepv-bar.js. Each axis haskey,label,values: [{v, label, sw?}]; the first value is the default;when: {key, is}shows an axis only while another has that value (e.g. accent only on palette B). - Style variants with
:root[data-<key>=<v>]. The bar itself reads the page's tokens, so it needs no variants. - State is written to
<html data-<key>>, persisted inlocalStorageaspv-<key>, and forced by the query string (?palette=b&accent=ink). The query wins and is not persisted. A screenshot or parity script renders an exact variant by URL; never click in a script. - Add class
pv-clearto the last section so the bar never covers content. Hide the bar in captures with.pv{display:none}. - Accessibility: it is a
role=regionwitharia-pressedbuttons, 36px targets and a forced-colors rule. Check the contrast of every variant, not only the default; a variant that fails is a finding, not a footnote.
Axes worth offering: palette, corners (soft/sharp), accent, logo mark, density, theme (light/dark).
Keep each axis to what the owner can actually choose; a bar with ten axes decides nothing.
3. Retrofit checklist (existing mockups)
- Only pages that compare options get the bar; single-spec pages do not. Rounds with one file per option (palettes or directions generated as separate files), JS-driven switchers that set properties from a map, and canvas exports are left alone: converting them means reworking the generator, which is a separate job. If a page is generated, change the generator and regenerate, never only the output.
- Move the page's variant colours into
data-blocks; remove ad hoc toggles. - Add the config, the two assets and
pv-clear; keep the page working with the bar removed. - Open it with each
?queryonce; check no console errors. - Record the change in the collection README.
4. Verification bar
Parser check (no unclosed tags), an axe run per variant and theme, a 390px and a 1440px screenshot per variant,
no console errors, works from file://.