baseline-design

Baseline Design

A baseline is a record of what ships today, not a design. The designer will make every later decision on top of it, so one wrong pixel, one missing state or one invented word in the baseline becomes a wrong decision downstream.

The output is an HTML artifact showing real renders of the running app for every state in a code-derived state matrix, with each state traced to the code that produces it.

Everything that names this project's apps, commands, data setup and tokens lives in the Project config at the end of this file. The procedure itself names no repo.

The five laws

These override convenience, speed and your own taste. Breaking one makes the baseline worthless.

1. Source of truth is the running app, then the code. Never memory, never your judgment. A screen you rebuilt by hand is a reconstruction, and it is labelled so on every frame.
2. Zero interpretation. No fixes, no tidying, no reordering, no "probably meant". A bug in production is reproduced faithfully and logged in the Bugs list, not corrected.
3. Verbatim copy only. Every string comes from the DOM of a render or from a literal in the code. A string you cannot find is shown as ⚠️ copy not found in code, never written by you.
4. Every branch is accounted for. Each conditional in the screen's code is either shown in a state or listed as unreachable with the reason. Two different conditions are two different states, even if they look alike.
5. Provenance on every claim. Each state, string and value says where it came from (render, file:line, seed). Anything unconfirmed carries ⚠️. Silence means unverified.

Phase 0: Scope, confirmed before any work

Read the request, then post this table and wait for the user's OK. Do not start Phase 1 on assumptions.

Item	Default if the user doesn't say
App and route	Ask. If the repo has more than one app or surface, never guess between them
Entry points included	The page plus every modal, drawer, sheet, accordion, menu and multi-step flow reachable from it
Viewer(s) and roles	Every role or account type that can open the page, plus the locked or signed-out view if it is reachable
Viewports	390, 768, 1200, 1440 (CSS px), deviceScaleFactor: 2
Where it runs	Where Project config says (this machine, a container, a shared dev environment read-only). See references/environment.md
Out of scope	Anything the user excludes, written down

If the app cannot be run anywhere, say so now and ask whether a code-only reconstruction is acceptable. Never discover this at the end and quietly ship a reconstruction.

Phase 1: Branch ledger (code inventory)

Walk the code from the route file down to the leaves inside the repo (stop at shared UI primitives and third-party components, but record their props). Read files fully. Don't skim.

For every one of these, add a ledger row:

• conditional render: &&, ternary, early return, switch, if in code that produces UI
• class or style switches: class-name helpers with conditions, tone or variant props, disabled, aria-* states
• loading, skeleton, error, empty and not-found paths, including error boundaries
• permission and role gates (locked-not-hidden counts as a state)
• settings and feature flags that change the UI
• data-shape branches: 0, null, one vs many, long text, missing optional field, currency, units
• time-dependent branches: due today / tomorrow / overdue, countdowns, phase windows
• form validation messages (copy them verbatim from the schema or the code) and server error mappings
• multi-step flow steps and their transitions

Ledger columns: ID (B1, B2…) · file:line · condition (verbatim code) · what renders · data that triggers it · how to reach it (seed, setting, click).

Completeness check (mandatory): grep the screen's files for &&, ?, if (, switch, return null, your class-name helper, disabled= and compare the count to the ledger. Explain every gap. Put the result in the report.

Phase 2: State matrix

1. Name the independent axes (e.g. status, setup, viewer role, data shape, viewport).
2. List each axis's values, each traced to ledger IDs.
3. Build the states: every value of every axis appears at least once, plus every combination the code treats specially (a branch that reads two axes needs its combos).
4. Mark impossible combinations as impossible with the code reason. Never show a combination the code cannot produce.
5. Coverage: every ledger ID appears in at least one state, or is listed as unreachable with the reason.

Post the matrix to the user before capturing if it has more than ~30 states or any judgment call. Otherwise proceed.

Phase 3: Data setup

Order of preference. Use the first that works.

1. The repo's own seed scripts, fixtures and test recipes. Read the recipe; use its documented fields.
2. The app's real API, acting as an ordinary user or as an impersonated one if the app has a test-only way to do it.
3. Direct changes to the local database only, for configuration with no seed. Log every statement in the report. Soft-delete; never hard-delete rows other rows reference.

Never write to a shared or production environment. Never wipe a database you did not create. Seed every state's data in one script so the run is repeatable, and save the seed responses (ids) to seeds/*.json.

Phase 4: Capture

Use scripts/capture.mjs from this skill as the starting point (config-driven; see its header). Per state × viewport:

• A real session (cookie, saved storage state, or a login request), never a faked UI.
• Wait for the network to settle, then for the page's root selector, then until no skeleton remains.
• Hide only what Project config lists (a framework dev overlay, for example). Change nothing else on the page.
• Open modals, drawers, accordions and flow steps with real clicks, and capture each step.
• Full-page screenshot, deviceScaleFactor: 2.
• Record console errors and page errors per shot. A shot with errors is flagged, not dropped.
• State assertion: before each shot, check one DOM fact that proves the state is right (e.g. a status label's text). A shot whose assertion fails is invalid; fix the setup, don't ship it.
• A fresh browser context per shot, so stored state never carries an earlier variant into this one.
• Write capture/index.json: state, viewport, seed ids, ledger IDs, assertion, errors, file.

Phase 5: Pixel database (spec extraction)

From the live DOM of each state, extract with getComputedStyle (also in scripts/capture.mjs):

• every text node: string, font family, size, weight, line height, letter spacing, colour
• every box that has a border, background or radius: its size, padding, gap, radius, border and background
• the design tokens these resolve to (match values against the project's token file); a value with no token is listed as raw

Save as capture/spec/<state>-<viewport>.json and summarise in the artifact's Spec tab. This is what "pixel perfect" means: the numbers come from the browser, not from reading class names.

Phase 6: Verify

Run all of these and report each as passed, or failed with the detail:

Check	Passes when
Branch coverage	Every ledger ID is in a state or listed as unreachable with a reason
State assertions	Every shot's DOM assertion passed
Render health	No page errors; any console errors are listed per shot
Copy provenance	Every visible string (from the DOM) is found as a literal or template in the code; misses are listed
No invention	grep the artifact for strings not in capture/ or the code: zero
Repeatability	Re-running the seed + capture for one state gives the same screenshot

Phase 7: Deliver

Build the artifact per references/artifact-format.md: a controls bar for every axis and the viewport, the real screenshot of the current state, the ledger rows that state exercises (with file:line), the Spec tab, and the Gaps and Bugs tabs. Every frame carries a provenance badge: Render (the running app) or Reconstruction (from code; only if Phase 0 agreed to it).

Publish it where the user reads such pages (a private artifact, a shared doc, a local HTML file), and keep capture/, seeds/, the ledger and the scripts in a working folder so the next session (the redesign) can reuse them.

Close with the verified / unverified list, one line each, then stop. Don't propose design changes in this skill; the baseline ends here.

Known failure modes

Failure	Guard
A hand-built HTML "Before" presented as pixel perfect	Law 1; the provenance badge on every frame
A combination shown that the code can't produce	Phase 2 step 4
Variants silently missing (a single-option setup, an empty optional place)	Phase 1 completeness check; Phase 2 coverage
Invented copy (an error message nobody wrote)	Law 3; the copy-provenance check
A modal flow simplified (saved items, a payment form, an extra checkbox skipped)	Capture every step by real clicks
A colour or size estimated "by eye"	Phase 5 computed styles
Hard-deleting rows that other rows reference broke the seed run	Phase 3: soft-delete only
Stale UI state restored from browser storage showing an old variant	Fresh browser context per shot
Dev servers left running at the end	Stop every server you started

Boundaries

• This skill reads code and writes only to its working folder and the local database. It makes no repo commits.
• If anything blocks a law (the app won't start, a state can't be seeded), stop and tell the user which law is at risk and the options. Don't trade accuracy for completion.

---

Project config (fill this in for your repo)

Read values from these sources at run time. Keep the answers here short; point at files, don't copy them.

Question	Answer
How to start the app (command, port, first-compile time)	(e.g. npm run dev, port 3000)
Which app or surface a route belongs to, if there are several	(path or naming rule)
Where seed scripts, fixtures or test recipes live	(paths)
How a session is made (see scripts/capture.mjs: cookies, storageState or login)	(one of the three, with the values or the route)
Root selector of a loaded page, and the skeleton selector	(e.g. [data-testid=page], .skeleton)
What to hide before a shot, if anything	(e.g. a framework dev overlay selector)
Where the design tokens live	(path to the token or theme file)
Which environments are read-only	(names; never write to them)
Date or time zone rules that change a state	(e.g. "due today" uses the account's zone)

See references/environment.md for the generic runbook and the usual snags.