Styleguide

Badge — a small status pill. Five tones mapped to the status token families (neutral / brand / success / warning / error). A basic starting point.

Button — the starter action control. Three variants (primary / secondary / ghost) × two sizes. Styled entirely from the semantic design tokens (globals.css), so it re-themes for dark automatically. A basic starting point — extend with icons, loading state, etc. as the project needs.

Input — the starter text field, with an optional label + hint. Styled from the semantic tokens. A basic starting point — extend with icons, error state, and validation as the project needs.

Mark — your project's logo, for use inside the app. One home for the shape, the way lib/project.ts is the one home for the name. The kickoff sets both. Replacing the starter here changes the `/system` wordmark everywhere it renders, in one edit. The starter is a brand-coloured tile with a diamond cut out of it. It is meant to look like a placeholder, because it is one. The centre is a TRUE cutout: the tile and the diamond are one path with `fill-rule="evenodd"`, so the inner region is unpainted and whatever sits behind the mark shows through. That is why this needs no theme prop, no media query, and no colour for the centre at all — it is correct on a light header, a dark header, and anything you re-skin to. If you replace the shape, keeping that property is worth the trouble: a painted centre has to know what is behind it, and every callsite is a chance to get that backwards. The tile takes `var(--brand-main)`, so re-skinning the tokens in app/globals.css recolours the wordmark with everything else. NOT the only copy of this shape, and deliberately so. `app/icon.svg` is a standalone file because a favicon has no stylesheet to inherit from, and `app/opengraph-image.tsx` re-declares it because Satori renders outside CSS entirely. Three renderers, one set of path data — if the shape changes, it changes in all three. The cutout needs no per-renderer mechanism at all, and the **colour is the only thing that differs**: this one reads a custom property, the other two carry a literal, and the favicon's literal is a lighter step because its backdrop is browser chrome rather than a surface we theme. Geometry that lives in one renderer and not the others is a defect, not a feature — `app/icon.svg` records the outline that taught us that. No `viewBox` scaling logic: `size` drives width/height and the 32x32 box does the rest.

PillToggle — a wrapping row of selectable pills. Single-select by default; pass `multi` to allow multiple selections. Uses the canonical `.pill` / `.pill.active` styles from globals.css. Active state is neutral — a strong neutral border + primary text, no action colour, so selection reads as chrome, not meaning.

TabBar — a segmented pill control for switching between sibling views. The track is `--surface-inset`, the active tab lifts onto `--surface-top`, and an optional per-tab badge count carries an unactioned signal. Switching is the caller's: this is controlled (`activeKey` + `onChange`), so a bar backed by routes navigates and one backed by state sets it.

ThemeToggle — three-way appearance control: Light / Dark / System. `System` follows the OS `prefers-color-scheme` and updates live (via `<ThemeWatcher>`); Light / Dark pin an explicit theme. Writes the *preference* to `localStorage['theme-pref']` and applies the resolved `data-theme` to <html> (see `lib/theme.ts`); the pre-paint script in `app/layout.tsx` mirrors the resolution to avoid a flash. Deliberately NOT a `TabBar`: an icon triad reads as a settings control rather than navigation, which a row of text labels in a track never did — it just looked like the /system nav at a smaller size. Labels survive as `title` + `aria-label`. Re-syncs across instances via the `theme-changed` event.

ThemeWatcher — app-global listener that keeps the `system` theme preference live. Mounted once in the root layout so the OS-follow works on every page, not just where a ThemeToggle happens to be rendered. When the preference is `system`, an OS light/dark change re-applies `data-theme` immediately. When the preference is an explicit light/dark, OS changes are ignored. Re-checks on the theme-changed event so switching to/from System takes effect without a reload. Renders nothing.

No demo. Renders nothing. It is an effect mounted once in the root layout so the `system` preference keeps following the OS; there is no surface to put in a canvas. Its behaviour is visible on the ThemeToggle demo above, which is the control it listens to.

Toggle — a starter on/off switch. Controlled: pass `checked` + `onChange`. Styled from the semantic tokens; the track turns brand when on. Off, it is drawn in the control boundary (`--border-stronger`): a ring around a sunken track and a knob in the same colour, so both the switch and its state clear the 3:1 floor for a component on any surface. A light knob on a grey track cannot: the pair the eye needs is the one that measures lowest. A basic starting point.