byensitmagnus sitesmith
A website is not done when the code compiles, and it is not done when the checks pass. The checks are a floor. It is done when it has the fourteen things in v2/00-done.md, and has been rendered, looked at, measured and corrected.
Read v2/. That is the skill. The pipeline it follows is declared once, in
PIPELINE.json — which is also what the command vocabulary and the provider
packages are generated from. references/ is the upstream material this descends from, kept
for attribution and not read during a build.
Progressive disclosure is mandatory. What is always in context is this file, the sixty core rules, and one mode file. Everything else is read at its step and put down again. A routine task must never pull the whole rule set or the 1.4 MB of data into context.
1. Route
Two questions, in this order.
Which mode is this page? Route per page, not per project — a shop's About page is marketing and its order admin is product UI. One design system across all of them.
| Mode | The visitor is | Open |
|---|---|---|
| M Marketing | Deciding whether to care. Company sites, services, launches, portfolios, editorial. | v2/modes/marketing.md |
| E E-commerce | Deciding whether to buy, and from whom. Listings, product pages, checkout. | v2/modes/ecommerce.md |
| P Product UI | Already committed, and now working. Dashboards, admin, forms, consoles. | v2/modes/product-ui.md |
Which task is this?
| The situation | Task | Start at |
|---|---|---|
| Empty directory, no frontend stack | SETUP | references/10-setup.md, then NEW |
| "Build a site / page / portfolio" | NEW | Step 1 below |
| Existing code, "redesign / make it better" | REDESIGN | references/06-redesign-audit.md — audit before touching anything |
| "Build a pricing table / nav / hero" | COMPONENT | blocks/ |
| "Review this UI / is it accessible?" | AUDIT | v2/00-done.md, then the mode file |
2. Three-command product loop
The ordinary journey is init → build → audit. The internal order still matters, but the
user should not have to operate nineteen implementation steps. The exact machine-readable
sequence lives in PIPELINE.json.
init — decide what will be built
- Write
BRIEF.md, including the three justified 1–10 dials: visual density, motion intensity and aesthetic boldness. - Inspect the existing repository and run
scripts/stack-router.mjs detect . --write. It selects one adapter; Next.js and Astro outrank their optional React dependency. - Write the evidence, brand and asset records. Plan what every picture carries before sourcing or generating it.
- Build three structurally different comps. Pass the dials to candidate search, choose one
with reasons, and make the surface, label, figure and depth grammar explicit. Check the
winner against the shared direction history, then write
DIRECTION.md,DESIGN-SYSTEM.mdandINTERACTIONS.mdfrom it.
The order is evidence → direction → contract. A contract written before the direction is the mechanism that made unrelated subjects converge on one house style.
python scripts/search.py "<subject> <trade>" --candidates \
--density <1-10> --motion <1-10> --boldness <1-10>
node scripts/direction-check.mjs directions/
node scripts/direction-history.mjs check DIRECTION.md <winner-url> --project <name>
build — make it work in the detected stack
Structure the argument, read only .sitesmith/STACK.md and its named adapter, implement every
state, and wire at least one journey per surface. The edit loop renders only the changed
surface:
node scripts/verify.mjs <changed-url> --out .sitesmith/shots/preview --no-axe
That explicit axe waiver is preview-only. It keeps a visual iteration cheap; it can never produce a release verdict.
audit — make one release decision
Run the canonical verification once, including axe, direction fidelity, token drift, journeys
and the production gate. Re-check the finished render against the shared direction history and
record it only when it is new. Open the screenshots and write one specific critique. Then walk
all fourteen items in v2/00-done.md and write PRODUCTION-REPORT.md, including
every failure.
node scripts/verify.mjs <url> --out .sitesmith/shots
node scripts/direction-fidelity.mjs DIRECTION.md <url>
node scripts/token-drift.mjs "<pages>" --contract DESIGN-SYSTEM.md
node scripts/journey.mjs journeys/ --base <url>
node scripts/production-gate.mjs "<pages>" --manifest ASSET-MANIFEST.md --production
node scripts/direction-history.mjs commit DIRECTION.md <url> --project <name>
harden reruns only the functional or production checks that failed. polish applies one
round driven by a specific screenshot criticism. doctor checks the installation. None is a
mandatory fourth phase.
Portfolio diversity, assignment-blinded reviews, sealed keys and container isolation belong to the repository's benchmark lab. They run only for an explicit benchmark task, never while building one customer website. They are mandatory before benchmark pages enter the public showcase: an individual critique pass is necessary and insufficient. The boundary is recorded in RELEASE-MAP.md.
3. Precedence
When two things disagree, the higher row wins.
- Accessibility and platform requirements — contrast, touch targets, keyboard, reduced motion. Never overridden by aesthetics.
- The brief — the client's context decides, not your preference.
- The mode file — one answer for this context beats a general answer.
- v2 core — the sixty.
- Aesthetic ambition — commit hard to one direction.
references/ does not appear in this list. It is provenance, not authority.
4. What to read
| File | When |
|---|---|
| v2/00-done.md | First in init, and again at the end of audit |
| v2/05-evidence.md | init — before direction work |
| v2/10-core.md | Once per build |
| v2/modes/ | After routing — one file only |
| v2/20-direction-lab.md | init — after evidence, before the contract |
| v2/24-asset-plan.md | init — before anything is sourced |
| v2/25-assets.md | init, and again during audit |
| v2/30-contract.md | init — after the direction is chosen, never before |
| v2/40-interaction.md | End of init, then journeys in build |
| v2/50-critique.md | audit, after technical verification |
| blocks/ | build |
| references/06-redesign-audit.md | REDESIGN only |
| references/ | Provenance. Not during a build. |
Sixty core rules plus one mode file is what you hold while working. The others are read at their step and put down again. That is the constraint.
5. Anti-slop is judgement, not a ban list
The recognisable patterns — purple gradients, blurred orbs, glassmorphism everywhere, bento grids by default, three equal feature cards, pill shapes on everything, decorative icons, huge type over thin content, centred heroes regardless of sector, animation on everything — are defaults reached for without a reason. Each is correct when the brand, the content or the function asks for it.
A brand colour is never slop. The tell is not the hue; it is a gradient chosen because no decision was made.
Hard tells with no legitimate use, and the only things here stated as absolutes: fabricated testimonials, invented customer logos, made-up metrics, fake prices, Lorem Ipsum, "John Doe", "Acme Corp", "Unlock your potential".
The final question, every time: would a designer look at this and say a machine made it?
6. Scripts
| Script | Purpose | Needs |
|---|---|---|
scripts/stack-router.mjs |
Detect Next.js, React/Vite or Astro and record one adapter | Node 18+ |
scripts/search.py --candidates |
Three contrasting starts shaped by visible dials, with repeat warnings | Python 3.10+ |
scripts/direction-check.mjs |
Are the three comps actually three directions | Node 18+, playwright optional |
scripts/direction-history.mjs |
Block known SiteSmith recipes and remember passing renders across projects | Node 18+, playwright |
scripts/verify.mjs |
Screenshots at 3 widths, axe in both schemes, links, console, overflow, --font-stress |
Node 18+, npx playwright install chromium |
scripts/token-drift.mjs |
Values used that the contract never declared | Node 18+ |
scripts/journey.mjs |
Runs the interaction journeys | Node 18+, playwright |
scripts/production-gate.mjs |
Placeholders, unmanifested images, empty brand marks, missing journeys | Node 18+ |
The prose still works without the scripts, but an audit cannot pass until the canonical checks
have actually run. If a browser tool is unavailable, open the page manually and report that the
mechanical release verdict is missing.
7. Attribution
sitesmith v1 was assembled from four openly licensed projects, credited in NOTICE.md: taste-skill (MIT), ui-ux-pro-max-skill (MIT), frontend-design (Apache 2.0) and impeccable (Apache 2.0). Their material is in references/, and several v2 core rules descend from it.
v2/, blocks/, references/06-redesign-audit.md, references/10-setup.md,
scripts/verify.mjs and scripts/token-drift.mjs are original work, MIT. Full provenance:
LICENSE-AUDIT.md.