Web Craft

web-craft — production web implementation rules

The web counterpart of /swiftui-craft. Load when implementing an approved design in a real web app, or when reviewing/polishing existing web UI code.

Composition, not duplication (read this first)

Three bodies of rules already exist and are better than anything restated here. This skill's job is to route to them correctly and to own only the gap:

| Layer | Authority | When | |---|---|---| | 100+ implementation rules (a11y, forms, perf, content, i18n) | Vercel web-interface-guidelines skill / AGENTS.md / CLI | every implementation and audit — run it, do not paraphrase it | | Aesthetic direction and anti-slop | Anthropic frontend-design skill | new UI from a blank page | | Beauty + experience laws | ios-design/TASTE.md, ux-design/CANON.md, web-design/WEB.md | judgement calls the rule sets do not cover |

If web-interface-guidelines is installed, invoke it for the craft audit and spend your own effort on the rules below, which it does not own: token discipline, the design-system coherence check, and the beauty laws. Disagreements resolve in Vercel's favour on craft, TASTE.md's on aesthetics.

1. Token discipline (the gap the rule sets do not cover)

• Every color, space, radius and type role resolves to a token. A raw hex,

a raw px, or a Tailwind palette utility (bg-blue-600) in a component is a defect — the same law as SwiftUI's "a hardcoded color in a component is a defect".

• Grep-backed audit, not impressionistic: count #[0-9a-fA-F]{3,8},

rgb(, and raw px outside the token file, and the palette utilities (bg-(red|blue|green|…)-[0-9]) outside a theme mapping. Cite the count and the worst offenders by file:line.

• Dark mode is one token set at two values driven by prefers-color-scheme,

not a parallel stylesheet. color-scheme is declared on `` so native scrollbars and form controls follow.

• Tokens nest concentrically for radii (child /` so Cmd/Ctrl-click, middle-click and

right-click work. A div with an onClick that navigates is a defect.

4. URL is state

• Every shareable or back-meaningful view — filters, tabs, pagination,

selected item, open detail — lives in the URL. Refresh and Back/Forward must land where the user was.

• Route vs dialog test: if a user would ever send someone this view, it is

a route. Dialogs are for transient, non-shareable focus only.

• Warn before navigation when unsaved data exists; persist drafts so a

refresh is survivable.

5. Loading, error, and empty are designed states

• The spinner window: show-delay ~150-300ms, minimum visible ~300-500ms.

Below the delay show nothing; a flash of spinner is worse than the wait.

• Skeletons mirror the final content exactly — a skeleton that does not

match what replaces it manufactures layout shift.

• No dead ends: every error offers a recovery action, and error copy names

the cause honestly and says how to fix it. Never assert a cause the code did not observe ("check your connection" when the server call failed).

• Empty states are functional (a ready state or a wayfinder that

demonstrates the loop), never a decorative apology.

6. Layout shift and performance budgets

• Reserve space: explicit image dimensions, fixed-height media containers,

fonts preloaded (and subset) so text does not reflow. CLS is a design defect, not a metric.

• Budgets to hold at realistic data volume: LCP Web Animations API > JS libraries. Animations are cancelable

by user input and are triggered by state, never autoplayed.

• prefers-reduced-motion has a real variant, and the visible END state is

the base style with the animation applied FROM hidden — so print, reduced motion, and no-JS all show content.

8. Forms

Labels associated and clickable; generous shared hit targets for checkbox+label; Enter submits (Cmd/Ctrl+Enter in a textarea); submit is never pre-disabled; autocomplete, name, type and inputmode set; paste never blocked; mobile inputs >= 16px so iOS does not auto-zoom; spellcheck off for emails, codes, and usernames.

9. Content craft

Color is never the only signal — status carries a label or icon too. Icon-only buttons have aria-label. font-variant-numeric: tabular-nums for comparable numbers. Curly quotes, the real ellipsis character, text-wrap: pretty, non-breaking spaces binding units (10 MB). `` reflects the current context.

Review output format

When auditing rather than implementing: findings ranked most severe first, each as [law or rule] — evidence (file:line or screenshot) — minimal fix — altitude, where altitude routes the fix: token layer > shared component > single call site. Prefer one-token fixes that propagate. State plainly which checks came from the Vercel rule set and which from the canons.

Does not do

• Greenfield design exploration, direction, mockups — /web-design.
• Journeys, flows, navigation architecture — /ux-design.
• Auditing a running app's pixels or experience — /ui-review and

/ux-review (web lanes).

• Native iOS/SwiftUI craft — /swiftui-craft.
• Restating the Vercel guidelines — install and run that skill instead.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dndungu
• Source: dndungu/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.