Design System

The rules that get broken most

1. Never write a raw color, spacing, radius, or duration value. Use a token.
2. Components reference semantic tokens, never primitives.
3. Only two font weights exist: 400 and 700. 500 and 600 are browser-synthesized fakes.
4. --brand-purple is a fill color only. It cannot be read as text on any of our surfaces.
5. Surfaces step down in luminance as they recede. Elevation comes from a border.
6. --surface-overlay is not a text surface. Hover fills and dividers only.
7. If it repeats, it is a primitive. A hand-styled button in page markup is a defect.
8. :focus-visible only, never bare :focus, and never outline:none without a replacement.
9. Never transition all. Animate only transform, opacity, filter, and color.
10. Any /dashboard/admin/* link needs data-astro-reload.

Surfaces

Surfaces step down in luminance as they recede. Elevation is a 1px border plus, only for things that genuinely float, a shadow — never a lighter fill. On a dark ground a shadow alone is nearly invisible, so borders carry the work.

The logo

Four assets in public/media/logos/, all a fixed 7:1 lockup. The logo is an asset, never type — setting “SHUTTERPAWS” as text to stand in for it means a substitute quietly becomes the brand in every screenshot and mockup.

shutterpaws_logo.svgTwo-color (default) · What Layout.astro ships today

shutterpaws-logo-2-white.svgWhite · Dark and busy grounds

shutterpaws_workmark_white.svgWordmark, white · When the paw mark is already nearby

Black or white grounds only

The lockup’s two halves want opposite grounds, so a mid-tone always compromises one of them. Which variant to use follows from the ground: two-color on white, white variant on black. Ratios computed at build time from the logo art’s own values (#6a0d83 / #fb9062), which are not the brand tokens — see below.

The logo art does not use the brand tokens. Its purple is #6a0d83 against the token’s #692a80 — a perceptual delta of ΔE_OK 0.041, roughly twice a just-noticeable difference, so a --brand-purple fill beside the logo is a visibly duller purple. The orange is within tolerance (0.009). Someone needs to pick which is authoritative; until then, do not place a --brand-purple surface directly against the logo.

Color primitives

Generated in OKLCH at fixed lightness steps, chroma clipped to sRGB. Reference these only through the semantic tokens below. Brand purple is a fill-only color — at 1.15:1 against the page it cannot be read as text or an icon stroke, which is arithmetic rather than preference.

Contrast, proven

Every cell is real text in the real color on the real surface, labeled with its computed ratio. AA clears 4.5:1 and is safe for body text; UI clears 3:1 and is valid only for large text, icons, and borders.

Typography

Fluid clamp() interpolation between a 360px and a 1240px viewport — ratio 1.2 at the small pole, 1.25 at the large one. Resize the window and the whole scale moves. The two down-steps are floored at 12px and 14px; the pure ratio wanted 11.1px, which is below a readable floor.

Only two weights exist

astro.config.mjs registers Avenir Regular and Bold, nothing else. The middle two cards below ask for weights the font does not contain, so the browser fakes them — differently per platform. To de-emphasize, use a smaller size or --text-secondary.

--font-brand (Library 3 AM, for the wordmark only) has no specimen here because it is not registered in astro.config.mjs yet — rendering it would silently fall back and mislead.

Iconography

One SVG sprite (IconSprite.astro), inlined once per page and referenced with <use href="#icon-name">. These are the real shipped symbols. Never inline a one-off <svg> in a page or island — it escapes every rule below and cannot be audited.

UI icons — 24×24 grid, inherit currentColor

Size tokens

Brand marks are not UI icons

Platform logos are trademarks. They keep their own geometry, may not be redrawn to fit the 24px grid, and may not be recolored beyond monochrome. They belong under an icon-brand-* prefix so a sweep over UI icons cannot accidentally restyle one. An icon-only control needs its own aria-label; the glyph itself stays aria-hidden, and the control gets a 44×44 target regardless of glyph size.

Spacing & radius

A 4px base unit, eight steps. Every margin, padding, and gap comes from it.

Nesting rule: an inner radius is the outer radius minus the padding between them, so concentric corners stay concentric.

Motion

Hover or focus a card to run it. Reduced-motion preferences disable all of it.

Data visualization

Six categorical series colors, used in order — a two-series chart is --chart-1 and --chart-2, not whichever two look nice. Each clears 3:1 against every text surface, the threshold for non-text UI.

Because the six sit at near-equal lightness, the palette gives strong hue separation on a dark ground but does not survive grayscale — which is why labeling directly, rather than via a legend, is a rule and not a preference. Status colors stay reserved for status; using --status-success as a series color makes a neutral category read as a judgment. Platform brand colors are valid only when the series is that platform. Magnitude uses the orange ramp, not these.

Interaction & feedback states

Every interactive control specifies all six states below. A control missing a disabled or loading treatment is incomplete, not minimal. A loading control must not change size, or the layout jumps and the pointer lands on something else.

Four view states, all designed

A view that can load forever but cannot fail is a defect. A permanent “Loading…” with no path to an error state is the most common serious bug in this codebase's history — the adminApi timeout, AdminErrorBoundary, and showAdminLoadError rules in CLAUDE.md each exist because it shipped.

Shared primitives

Anything appearing more than twice is a primitive in site/src/components/ui/, not a pattern re-styled per page. Utilities are for layout and genuine one-offs. The controls below are specimens of the target styling, not the real components — but they are live: hover them, and tab through them to see the focus treatment from section 6.1. A reference whose buttons do nothing cannot demonstrate the state rules it specifies.

Button

Every button, link-button, and CTA

Card

Event cards, press cards, admin panels

Badge

Status pills, tier labels, tags

Field

Label + input + error + hint

Panel

Bordered content panel with an optional head

Stack

The flex-column-plus-gap triplet

Alert

Error / success / info callouts

Spinner

Loading indicators

Mockups

Tokens judged in isolation always look fine. See the homepage and event page rebuilt on this system, so the composition can be judged as a page.