Token foundation

Foundation guide

Use @matt-riley/design-tokens for the shared CSS base layer, then layer component-specific behavior from @matt-riley/ui-astro on top. This guide covers the new density controls, focus mode, and spatial shadow tokens added in this branch.

Density modes

3→compact, default, spacious

Focus mode

Opt-in↑html attribute

Spatial shadow tokens

4↑resting to modal

What the token package owns

Base layer

The package exports palette, semantic, spacing, and typography tokens plus the shared CSS foundation used by Snurble components and consumers.

Keep route-owned metadata, application state, and component orchestration outside the token package.

New foundation hooks

density scale on the <html> element
focus mode that suppresses decorative blur, glow, and stagger animation
semantic spatial shadow tokens for resting, elevated, floating, and modal depth

HTML-level controls

Density scale

compact: 0.75× spacing multiplier
default: 1× spacing multiplier
spacious: 1.5× spacing multiplier

Focus mode

Set data-snurble-focus-mode="enabled" on the document root when you want to reduce blur, glow, and decorative motion for more focused reading.

Example

<html data-snurble-density="compact" data-snurble-focus-mode="enabled">
  <body>
    <slot />
  </body>
</html>

Spatial shadow tokens

Token intent

--snurble-shadow-spatial-resting for default cards and panels
--snurble-shadow-spatial-elevated for emphasized surfaces
--snurble-shadow-spatial-floating for hover and floating overlays
--snurble-shadow-spatial-modal for modal or highest-emphasis layers

CSS example

.card {
  box-shadow: var(--snurble-shadow-spatial-resting);
}

.card:hover {
  box-shadow: var(--snurble-shadow-spatial-floating);
}

.dialog {
  box-shadow: var(--snurble-shadow-spatial-modal);
}

Install and public entrypoints

Public entrypoints

@matt-riley/design-tokens
@matt-riley/design-tokens/palette.css
@matt-riley/design-tokens/semantic.css
@matt-riley/design-tokens/typography.json
@matt-riley/design-tokens/spacing.json

Install

@matt-riley:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}

pnpm add @matt-riley/design-tokens@<version>