writing-html-mocks
Write static HTML mocks in docs/mocks/ for EVERY page, dialog and notification of a product in EVERY state (default, loading, empty, error, invalid, busy, success, no-results, forbidden, stacked...), responsive, light and dark, keyboard-accessible, with real copy and a coverage matrix. Use this skill BEFORE writing any frontend code, component, template, view or page; whenever the user says mock, mockup, wireframe, prototype, UI, UX, screen, layout, dialog, modal, toast, banner, empty/error/loading state, "what should this look like", "show me the UI", or describes a feature with a visible result; and whenever docs/specs or docs/detailed-designs exist but docs/mocks does not. Also use it to add missing states to existing mocks. Mocks come before implementation: if asked for frontend code with no mocks, say so and offer this first. Pair with extracting-design-systems to turn finished mocks into docs/design-system/.
- License 许可
- MIT
- 最近更新
- 2026-10-19
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- writing-html-mocks
- description
- Write static HTML mocks in docs/mocks/ for EVERY page, dialog and notification of a product in EVERY state (default, loading, empty, error, invalid, busy, success, no-results, forbidden, stacked...), responsive, light and dark, keyboard-accessible, with real copy and a coverage matrix. Use this skill BEFORE writing any frontend code, component, template, view or page; whenever the user says mock, mockup, wireframe, prototype, UI, UX, screen, layout, dialog, modal, toast, banner, empty/error/loading state, "what should this look like", "show me the UI", or describes a feature with a visible result; and whenever docs/specs or docs/detailed-designs exist but docs/mocks does not. Also use it to add missing states to existing mocks. Mocks come before implementation: if asked for frontend code with no mocks, say so and offer this first. Pair with extracting-design-systems to turn finished mocks into docs/design-system/.
02 资源文件 15
- 参考文档agents/openai.yaml366 B
- 资产文件assets/mock.css2.8 KB
- 脚本assets/mock.js3.2 KB
- 资产文件assets/templates/dialog.html4.5 KB
- 资产文件assets/templates/notification.html3.3 KB
- 资产文件assets/templates/page.html9.3 KB
- 资产文件assets/tokens.css18.7 KB
- 资产文件assets/ui.css41.3 KB
- 参考文档evals/evals.json5.6 KB
- 参考文档references/delight.md7.0 KB
- 参考文档references/html-conventions.md7.9 KB
- 参考文档references/manifest.md2.6 KB
- 参考文档references/screen-inventory.md7.4 KB
- 脚本scripts/check_mocks.py24.5 KB
- 脚本scripts/screenshot_mocks.py6.0 KB
03 SKILL.md 正文
Writing HTML mocks
A mock set is the product on disk before the product exists: one real HTML
file per screen per state, sharing one token file and one component kit, so a
reviewer can click through every state of every page, dialog and notification
in light and dark at phone, tablet and desktop widths, with a keyboard. The set
is complete when the coverage matrix has no gaps and the review checklist has
no unticked box. "A delight to use" is the bar, and it is measurable: see
references/delight.md.
docs/mocks/
README.md cast & catalog, open questions, coverage matrix (generated section)
index.html gallery of every screen with state links (generated)
manifest.json the list of screens, states and requirement IDs
assets/
tokens.css design tokens; the only place colours, sizes and durations live
ui.css component kit shared by every mock; extend, never fork
mock.css mock bar + annotation notes (not product UI)
mock.js theme toggle, ?theme= and ?chrome= handling
pages/<id>/<state>.html one file per page state
dialogs/<id>/<state>.html one file per dialog state, shown over its page
notifications/<id>/<state>.html one file per notification state, shown on its page
Read the references as you reach the steps that need them:
references/screen-inventory.md— how to enumerate every screen and the state matrix per kind.references/manifest.md— the manifest format the checker and gallery use.references/html-conventions.md— file skeleton, semantics, state hooks, responsiveness, theming.references/delight.md— the UX principles and the per-mock review checklist.
Resolve references/, assets/ and scripts/ relative to this installed skill's
folder. Resolve docs/ paths relative to the consuming project.
Step 0 — Gather inputs (never a hard stop)
Read, in this order, whatever exists: docs/specs/L1.md and L2.md (keep the
requirement IDs verbatim), docs/detailed-designs/**/README.md, the router or
navigation code, existing templates and components, docs/design-system/ and
any existing docs/mocks/. Then read the user's request.
Specs are not required; when they are missing, derive the screen list from the
request and the code and write the assumptions into docs/mocks/README.md
under Open questions. Ask the user only when two readings of the request
produce materially different page sets.
If docs/design-system/ already exists, the mocks consume it: link its
tokens/tokens.css and assets/components.css instead of creating local
copies, and add any missing component to the system rather than to a mock.
Step 1 — Inventory every screen and every state
Follow references/screen-inventory.md. Produce docs/mocks/manifest.json
listing every page, dialog and notification with its states, route,
opens_from and requirement IDs. Add the screens every product has (sign in,
reset password, 404, 403, 500, offline, settings, notification center…) even
when nobody mentioned them. Mark a required state not_applicable only with a
reason. Count the files before writing; a mid-sized product is 120–250 mocks.
That number is the task.
Step 2 — Establish the shared assets
Copy assets/tokens.css, assets/ui.css, assets/mock.css and assets/mock.js
from this skill into docs/mocks/assets/ (skip the ones a design system already
provides). Then adapt the tokens to the product before writing any mock:
- Brand: set the accent primitives (
--palette-blue-*→ the brand hue) and the font families. Keep the semantic token names. - Density and shape: adjust
--radius-*,--control-height-*if the product is compact or playful. - Verify every change with the design-system skill's contrast checker if it is
installed (
scripts/check_contrast.py tokens.css --pairs contrast-pairs.json); otherwise keep the shipped values, which pass WCAG AA in both themes.
Define the cast and catalog (people, items, organisations, "today") at the top
of docs/mocks/README.md and reuse it in every mock.
Step 3 — Write the mocks
Start from the matching template in assets/templates/ (page.html,
dialog.html, notification.html) and follow references/html-conventions.md.
Write the default state of a screen first, then derive its other states from
it so the layout is identical and only the content differs. For each file:
- Real semantic HTML, real copy, the shared classes; a new component goes into
ui.csswith the same naming and state hooks, then gets used. - Every interactive element reachable by keyboard, labelled, with a visible
focus ring; dialogs trap focus and make the page behind
inert; toasts sit in a live region. - Mobile first and responsive at 360/768/1280 with no horizontal page scroll; bottom sheets under 640 px; collapsed navigation under 1024 px.
- No colours, sizes or durations outside tokens; both themes look intentional.
- The
mock:*metas, the mock bar with sibling states, and a.mock-notewherever the static page cannot show an intent (timers, animations, focus order). - Loading states use layout-matching skeletons; empty states explain and offer one action; error states keep the chrome and offer a way forward; invalid forms show inline errors plus a summary; success states say what happens next.
Work screen by screen, committing to the manifest as you go; do not leave a screen half-covered to start another.
Step 4 — Generate the gallery and check coverage
python "<installed-skill-folder>/scripts/check_mocks.py" docs/mocks --write
--write regenerates index.html and the coverage section of README.md
from the manifest, then re-checks. The check fails on: a required state with
no file and no reason, a file not in the manifest, mismatched mock:* metas,
missing doctype/lang/title/viewport/<main>/single <h1>, unlabelled form
controls, unnamed buttons or links, images without alt, placeholder text,
broken links or fragments, and a mock that does not link tokens.css. Fix
every error; a warning (no skip link, no mock bar) is a defect too unless you
can say why not.
Step 5 — Look at every mock
Render the set and inspect it; a mock nobody has looked at is not finished:
python "<installed-skill-folder>/scripts/screenshot_mocks.py" docs/mocks
This writes PNGs for every mock at 360×800, 768×1024 and 1280×800 in light and
dark to docs/mocks/.cache/mocks/ with a contact sheet, using the Python
playwright package or the Playwright CLI with Chromium (never commit
.cache/). Open the contact sheet (or read the PNGs) and fix clipped text,
overflow, wrong wrapping, invisible focus, low-contrast dark-theme surfaces
and layout shift between loading and default. If no browser is available,
say so, review the HTML by reading it, and list the screenshot command for the
user.
Then walk the review checklist in references/delight.md for each screen. Tab
through at least one page, one dialog and one toast in a browser when you can.
Step 6 — Hand over
docs/mocks/README.md carries: the cast and catalog, how to open the mocks
(index.html from disk; ?theme=dark, ?chrome=0), the generated coverage
matrix with requirement IDs, open questions and assumptions, and the commands
to re-check and re-screenshot. Commit the HTML, assets, manifest, README and
gallery; never .cache/.
Finish by stating the counts (screens, states, files), what was assumed, and
that the next step is extracting-design-systems to turn the mocks into
docs/design-system/.
Quality bar
A finished mock set lets a stakeholder open docs/mocks/index.html from disk
and click through the entire product: every page, every dialog over its page,
every notification on its page, every state, in both themes, at any width,
with a keyboard, with copy that reads like the shipped product, and nothing
that says "coming soon". Every file traces to the requirement it serves, and
the whole set shares one set of tokens and one component kit so the design
system can be extracted from it without guesswork.
04 同仓库更多 Skills
writing-screen-composition
Create or update docs/screen-composition.md, a document that itemizes every page, dialog, notification and shell part from the HTML mocks and lists, for each, the component-library components it shall be composed of plus the UI that must be built locally. Also ensures AGENTS.md has the "Components library is mandatory (CRITICAL)" section. Use when the user mentions screen composition, which components a page uses, mapping mocks to a component library, local vs library UI, or before implementing an application against a component library; and whenever docs/mocks and a component catalogue exist but docs/screen-composition.md does not or is out of date.
writing-requirements
Create and manage software requirements documents (L1 high-level and L2 detailed with acceptance criteria) in docs/specs/. Use this skill whenever the user mentions requirements, specs, specifications, user stories, features to build, acceptance criteria, ATDD, or wants to define what a system should do before coding. Also use when the user says things like 'what should we build', 'let's plan the feature', 'write up what this needs to do', 'define the behavior', or describes functionality they want implemented -- even if they don't explicitly say 'requirements'. If the user is about to start coding a feature and there are no requirements yet, proactively suggest using this skill first. Requirements come before code. Always.
writing-html-mocks
Write static HTML mocks in docs/mocks/ for EVERY page, dialog and notification of a product in EVERY state (default, loading, empty, error, invalid, busy, success, no-results, forbidden, stacked...), responsive, light and dark, keyboard-accessible, with real copy and a coverage matrix. Use this skill BEFORE writing any frontend code, component, template, view or page; whenever the user says mock, mockup, wireframe, prototype, UI, UX, screen, layout, dialog, modal, toast, banner, empty/error/loading state, "what should this look like", "show me the UI", or describes a feature with a visible result; and whenever docs/specs or docs/detailed-designs exist but docs/mocks does not. Also use it to add missing states to existing mocks. Mocks come before implementation: if asked for frontend code with no mocks, say so and offer this first. Pair with extracting-design-systems to turn finished mocks into docs/design-system/.
writing-feature-prompts
Write a ready-to-run implementation prompt for a feature request or a bug fix in the current repository, save it outside the repository and open it in a text editor (Notepad on Windows). A feature prompt drives mocks, design system, requirements, detailed design, estimate update and incremental acceptance-test-driven implementation end to end without stopping; a bug-fix prompt drives reproduce, root cause, fix and documentation alignment. Use whenever the user asks to "create a prompt", "write a prompt for this feature" or "for this bug", wants a "prompt to build X" or "prompt to fix Y", or asks to open a prompt in Notepad.
writing-design-documents
Create software design documents and architecture write-ups from existing L1/L2 requirements in docs/specs/. Use for detailed designs organized by subsystem and feature, with requirement traceability and rendered PlantUML C4, class, and sequence diagrams in docs/detailed-designs/.
writing-agent-instructions
Writes the agent instruction files a repository needs so coding agents know how to work in it - AGENTS.md plus the CLAUDE.md, GEMINI.md, and .github/copilot-instructions.md pointers - generated from a description of what the project shall be, for a project that does not exist yet. Use this whenever someone mentions AGENTS.md, CLAUDE.md, GEMINI.md, copilot-instructions, "agent instructions", "agent context files", "coding agent guidance", or asks to set up, scaffold, bootstrap, or initialise the conventions for a new project or repository. Use it too when someone describes a project they are about to start and wants an agent to follow its conventions, even if they never name any of these files - if they are standing at an empty directory describing what they intend to build, this is the skill.