08 / Implementation
Implementation
Copyable CSS, APIs, data boundaries, and verification
Run the static reference
python3 -m http.server 8000
Open the root, then use the recipe links. The guide has no install step, remote runtime, cookies, analytics, or framework dependency. All asset URLs are relative. Serve this static directory from a web server and open its index page.
Source of truth
| File | Owns | Rule |
|---|---|---|
| assets/reference.css | Reconstructed product tokens, shell geometry, controls, and responsive layout | Change the named shared class before adding a route-specific override. |
| assets/fidelity.css | Measured type, desktop grid, mobile, and document-family corrections | Load after reference.css. Do not omit this layer when copying a recipe. |
| assets/reports.css and assets/reports.js | Dense report tables, mobile metric selection, task cards, and chart controls | Load on benchmark report pages after the shared CSS. |
| assets/reference.js | Local fixture state and component behavior | No network mutation. Preserve form values through local errors. |
| assets/guide.css / guide.js | Original guide navigation, catalog layout, and search | Do not mistake guide-only UI for a product component. |
| assets/source/ | Recovered brand, imagery, fonts, and icons | Keep source hashes, transform history, and rights labels current. |
| examples/ | Live component families and full-page compositions | Every new public route or component needs an inventory mapping and tests. |
| assets/data/ | Published copies of the current evidence ledgers | Read prose and specimens first; use JSON for exact record retrieval. |
Retrieve product CSS · Retrieve fixture JavaScript · Report CSS · Report interactions · Retrieve measured tokens
Component API conventions
- Use native links for navigation and buttons for state changes. A shape that has no action must not receive button semantics.
- Use explicit labels and stable IDs. A field message connects through aria-describedby; invalid state uses aria-invalid.
- Keep one primary action per form. Optional consent never becomes required just to make validation simpler.
- The tool picker owns its open state and selection values. The parent form owns field layout and submission status.
- Use the local specimen markup as the import contract. Source selectors and computed probes establish fidelity, not a guessed React API.
- Avoid innerHTML for user values. Update textContent or native value properties. URLs in fixtures stay local or use fixed allowlisted first-party links.
Acceptance checks
Local verification scripts and raw logs are not part of this public bundle. Check the example pages at desktop and mobile widths, follow every internal link, and exercise keyboard navigation and local form fixtures. The historical verification summary is not a certification of this draft.
Budgets and ownership
| Risk / budget | Acceptance | Owner / recovery |
|---|---|---|
| Publication | Only site/. No evidence scripts, secrets, credentials, private logs, or source checkout. | Package maintainer inspects output before every publish. |
| Interaction | Every enabled visible control produces its documented result with pointer and keyboard. | Component author supplies expected outcomes and updates the control contract. |
| Layout | No document overflow at 390, 768, 1440, 1920. 320 px and long text receive stress probes. | Page author fixes ownership or wrapping, not by hiding overflow. |
| Assets | Every referenced local file resolves; brand hashes match ledger; no remote SVG content. | Asset reviewer regenerates technical and visual comparisons after changes. |
| Data safety | No real data, upload, storage, analytics, credentials, or external mutations. | Reference fixtures use example.test and reset on reload. |
| Performance | No remote runtime fetch; local JavaScript stays under 100 KB uncompressed per file. | Maintainer checks asset sizes and lazy-loads evidence images. |
| Change management | Any evaluated content change requires fresh manifests and review. | Release owner can roll back the complete static directory; never mix score from one version with another. |
Extension and migration
Before adding a component, search the inventory, compare two source occurrences, and add a fixture that demonstrates why the existing pattern is insufficient. New local states must be labeled reconstructed. A changed public behavior needs a new version, migration note, updated examples, and regression checks. Delete obsolete classes only after all recipe and ledger references are updated.
Local extension contract
New reference-only components may combine the measured design rules with explicitly original behavior. Private permissions, storage, payments, and upload-service contracts remain excluded. Do not invent them to complete a local exercise.
A deterministic local fixture may accept a success, empty, or error outcome and a bounded delay. Activation moves idle → loading → the selected outcome. Ignore duplicate activation while loading, retain entered values on error, and let Retry return to loading. Use an inline role=status message; focus stays on the triggering button unless a field is invalid.
Verify pointer and keyboard input, exact status changes, focus, 320px reflow, long labels, and no outbound mutation. New patterns need documented inputs, events, ownership, two composition contexts, and a provenance label.