Resources

Downloads and contributing

The files behind this guide, how it stays equal to the app, and how to change it.

#Downloads

File	What it is
tokens/tokens.css	The full design system as CSS custom properties: color, type, space, shape, elevation, motion. Pulls in the color file
tokens/colors.css	Just the color roles, light and dark
tokens/colors.json	Roles with light and dark hex, jobs, and the stated accessibility measurements
copy/ui-strings.md	Locked customer UI strings
logo/	Mark, wordmark, and lockups as SVG. See Logo for each file
png/	Logo PNGs at several sizes, plus palette, type, and cover sheets

#Use the tokens in a project

Import and use

#Uses roles, not hex

Both themes work with no extra code.

Code

<div class="card" style="max-width:22rem">
  <h2 class="card-title">Uses roles, not hex</h2>
  <p class="card-desc">Both themes work with no extra code.</p>
  <button type="button" class="btn btn-primary">Continue</button>
</div>

Import tokens/tokens.css, then write CSS against var(--color-surface), var(--space-4), var(--radius). Dark mode follows the OS, or set data-theme on <html>.

#How this guide stays equal to the app

Thing	Mechanism
Component CSS	The app’s `base.css`, `components.css`, and `layout.css` are vendored verbatim in `site/vendor/app/`. Every specimen uses them
Colors and type	Swatches, contrast, and scales are generated from `tokens/` at build time
Icons	Extracted from the app’s `Icon.tsx` by `npm run sync`
Drift	`npm run check` fails if the app’s color roles differ from `tokens/`, if a contrast pairing drops below 4.5:1, if a specimen uses a banned word, or if any link is broken

#Changing the guide

Brand first. Change the tokens, strings, or logo in this repo, then update the app. If they ever disagree, the product is the bug.
Refresh from the app when components change: npm run sync -- /path/to/app.
Edit a page in site/src/pages/. Use <demo> for any specimen, so its code is printed from the same markup.
Preview with npm run dev, then run npm run check.
Use the PR template and attach light, dark, and phone screenshots of any visual change.

#Running and deploying

Task	Command
Preview with live rebuild	`npm run dev` → http://localhost:8080
Build and verify	`npm run check`
Build the container	`docker build -t weekwright-guide .`
Run it	`docker run --rm -p 8080:8080 weekwright-guide`

The image is nginx serving static files on port 8080 as a non-root user, with a /healthz endpoint. See DEPLOY.md in the repository for details.