Styling

A closed subset of Tailwind v4 utilities, theme tokens in lib/theme.css and component styles scoped by the build. It ships one hashed, minified stylesheet with only the utilities your pages use.

Utilities, variants and what check rejects

The card below is styled only with utilities. Variants are hover:, focus:, focus-visible:, active:, disabled:, group-hover:, dark: and the breakpoints sm: to 2xl:; they combine (md:hover:bg-primary-600), and colors take an opacity (bg-accent/20). The palette is white, black, transparent, current and the scales neutral, primary, danger, success, warning in shades 50 to 950, and the full list is core/docs/classes.md.

Anything else is a check error, not a silent no-op: arbitrary values, negative utilities, unknown classes such as shadow-inner, and style="…". The other tabs show the output.

routes/examples/styling/_components/build-card/build-card.html

<button type="button" class="group grid w-full max-w-sm gap-3 border border-line bg-surface p-4 text-left transition-colors hover:border-accent focus-visible:border-accent active:bg-raised sm:p-5">  <span class="flex items-center justify-between gap-4">    <span class="font-mono text-sm text-ink">pragma build</span>    <span class="font-mono text-xs text-faint group-hover:text-accent">6 ms</span>  </span>  <span class="block h-1 bg-accent/20"><span class="block h-1 w-3/4 bg-accent"></span></span>  <span class="text-sm text-muted md:text-base">Hover, focus or press: every state here is a utility variant.</span></button>

routes/examples/styling/_snippets/utilities/rejected.html

<h1 class="w-[37px] -mt-2 text-fuchsia-500 shadow-inner" style="color: red">Hello</h1>

routes/examples/styling/_snippets/utilities/check.txt

$ pragma check --strictroutes/index.html:2:5 error [css/arbitrary-value] arbitrary value "w-[37px]" is not supported; use a utility from core/docs/classes.md or add a class in lib/theme.cssroutes/index.html:2:5 error [css/unknown-class] class "-mt-2" is not a supported utility nor defined in the project CSSroutes/index.html:2:5 error [css/unknown-class] class "shadow-inner" is not a supported utility nor defined in the project CSSroutes/index.html:2:5 error [css/unknown-class] class "text-fuchsia-500" is not a supported utility nor defined in the project CSSroutes/index.html:2:58 error [html/style-inline] the style attribute is not allowed; use classes5 error(s), 0 warning(s)

Live result

Only the classes used in the source end up in the CSS bundle.

Tokens generate utilities

Each --color-<name> or --color-<name>-<shade> in @layer tokens becomes bg-, text-, border- and the other color utilities. These swatches use this site's own tokens; redefining --color-primary-* rebrands every primary utility at once. The starter ships theme-aware bg-surface, text-ink, text-muted, border-line and the classes .card, .btn, .btn-primary, .btn-danger, .dialog.

The redefinable tokens are --color-*, --font-sans, --font-serif, --font-mono, --radius-*, --shadow-* and --spacing. A new font name such as --font-display does not create font-display. core/base.css also reads --page-bg, --page-fg and --skeleton-bg, which switch in dark mode, plus --container-* for the max-w-* sizes.

routes/examples/styling/_snippets/tokens/theme.css

@layer tokens {  :root {    --color-ground: oklch(0.158 0.006 255);    --color-sunken: oklch(0.132 0.006 255);    --color-surface: oklch(0.192 0.007 255);    --color-raised: oklch(0.225 0.008 255);    --color-line-strong: oklch(0.38 0.01 255);    --color-muted: oklch(0.74 0.008 255);    --color-accent: oklch(0.9 0.185 127);    --color-primary-800: oklch(0.45 0.1 127);    --font-mono: "Martian Mono", ui-monospace, monospace;    --font-sans: "Hanken Grotesk", ui-sans-serif, system-ui, sans-serif;  }}@layer components {  .nav-link[aria-current="page"] { color: var(--color-accent); }}

routes/examples/styling/_components/swatches/swatches.html

<ul>  <li class="swatch"><span class="swatch-chip bg-ground"></span><code>bg-ground</code></li>  <li class="swatch"><span class="swatch-chip bg-sunken"></span><code>bg-sunken</code></li>  <li class="swatch"><span class="swatch-chip bg-surface"></span><code>bg-surface</code></li>  <li class="swatch"><span class="swatch-chip bg-raised"></span><code>bg-raised</code></li>  <li class="swatch"><span class="swatch-chip bg-line-strong"></span><code>bg-line-strong</code></li>  <li class="swatch"><span class="swatch-chip bg-muted"></span><code>bg-muted</code></li>  <li class="swatch"><span class="swatch-chip bg-accent"></span><code>bg-accent</code></li>  <li class="swatch"><span class="swatch-chip bg-primary-800"></span><code>bg-primary-800</code></li></ul><style>  [data-c="swatches"] {    display: grid;    grid-template-columns: repeat(2, minmax(0, 1fr));    gap: 0.5rem 1.25rem;    width: 100%;    max-width: 24rem;  }  .swatch {    display: flex;    align-items: center;    gap: 0.625rem;    color: var(--color-muted);    font-size: 0.75rem;  }  .swatch-chip {    flex: none;    width: 1.75rem;    height: 1.75rem;    border: 1px solid var(--color-line-strong);  }</style>

Live result

  • bg-ground
  • bg-sunken
  • bg-surface
  • bg-raised
  • bg-line-strong
  • bg-muted
  • bg-accent
  • bg-primary-800
The theme.css tab is an excerpt of this site's lib/theme.css. Custom global classes go in @layer components.

Component CSS, scoped by the build

A component's <style> is for what utilities cannot say: here, :has(:checked) drives the selected segment and a custom property that sets the row padding, with no JavaScript at all. Write plain selectors: the build scopes each one to the component.

  • The build marks the root with data-c and adds a :where(…) that matches the root and everything inside it to the last part of every selector, as the app.css tab shows: .density-option:hover or even li never styles anything outside the component, and the scope adds no specificity.
  • Only the last part is scoped, so an outside ancestor needs nothing special: html[data-theme="dark"] .density-option still matches only this component's options.
  • The root is [data-c="density"], and a selector that names it stays as written. :global(…) opts out only what is inside it: .density-rows :global(.hit) keeps .density-rows scoped and lets .hit match anything inside it, child components included. A selector that is all :global, such as :global(:root) { --row-pad: 1rem; }, is global.
  • A page's <style> is scoped to its <main data-page> the same way. All of it goes into @layer components of the single app stylesheet; a separate density.css works the same, and having both is a check error.
  • For a p- component the build makes the scope unique per folder (density-97d4f0 in the tab), so two private components with the same name never share a rule. Forbidden: !important, ID selectors and external @import.

routes/examples/styling/_components/density/density.html

<fieldset>  <legend class="density-legend">Row density</legend>  <div class="density-options">    <label class="density-option"><input type="radio" name="density" value="compact">Compact</label>    <label class="density-option"><input type="radio" name="density" value="cozy" checked>Cozy</label>    <label class="density-option"><input type="radio" name="density" value="roomy">Roomy</label>  </div>  <ul class="density-rows">    <li>routes/index.html</li>    <li>lib/components/card/card.html</li>    <li>lib/theme.css</li>  </ul></fieldset><style>  [data-c="density"] {    --row-pad: 0.625rem;    display: grid;    gap: 0.875rem;    width: 100%;    max-width: 20rem;  }  [data-c="density"]:has([value="compact"]:checked) { --row-pad: 0.25rem; }  [data-c="density"]:has([value="roomy"]:checked) { --row-pad: 1rem; }  .density-legend {    margin-bottom: 0.5rem;    color: var(--color-faint);    font-family: var(--font-mono);    font-size: 0.75rem;    letter-spacing: 0.06em;    text-transform: uppercase;  }  .density-options {    display: grid;    grid-template-columns: repeat(3, 1fr);    border: 1px solid var(--color-line-strong);  }  .density-option {    padding: 0.5rem;    color: var(--color-muted);    font-family: var(--font-mono);    font-size: 0.75rem;    text-align: center;    cursor: pointer;    transition: background-color 0.15s var(--ease-out), color 0.15s var(--ease-out);  }  .density-option + .density-option { border-left: 1px solid var(--color-line-strong); }  .density-option:hover { color: var(--color-ink); }  .density-option:has(:checked) { background: var(--color-accent); color: var(--color-accent-ink); }  .density-option:has(:focus-visible) { outline: 1px solid var(--color-accent); outline-offset: 2px; }  .density-option input {    position: absolute;    opacity: 0;    pointer-events: none;  }  .density-rows li {    padding-block: var(--row-pad);    border-bottom: 1px solid var(--color-line);    color: var(--color-ink);    font-family: var(--font-mono);    font-size: 0.75rem;    transition: padding 0.2s var(--ease-out);  }  @media (prefers-reduced-motion: reduce) {    .density-option,    .density-rows li { transition: none; }  }</style>

routes/examples/styling/_snippets/scoped/app.css

@layer components {  [data-c="density-97d4f0"] {    --row-pad: 0.625rem;    display: grid;    gap: 0.875rem;    width: 100%;    max-width: 20rem;  }  [data-c="density-97d4f0"]:has([value="compact"]:checked) { --row-pad: 0.25rem; }  .density-option + .density-option:where([data-c="density-97d4f0"],[data-c="density-97d4f0"] *) { border-left: 1px solid var(--color-line-strong); }  .density-option:hover:where([data-c="density-97d4f0"],[data-c="density-97d4f0"] *) { color: var(--color-ink); }  .density-option:has(:checked):where([data-c="density-97d4f0"],[data-c="density-97d4f0"] *) { background: var(--color-accent); color: var(--color-accent-ink); }  .density-rows li:where([data-c="density-97d4f0"],[data-c="density-97d4f0"] *) {    padding-block: var(--row-pad);    border-bottom: 1px solid var(--color-line);  }}

Live result

Row density
  • routes/index.html
  • lib/components/card/card.html
  • lib/theme.css
Native radios: arrow keys move the selection, Tab leaves the group. The app.css tab is an excerpt of the build output for this component.

Dynamic styles: .name toggles and data-*

There is no :class and no style: every class name is written out in the source, so check can validate it and the build can generate it. Toggle a class on a condition with .text-accent="$passed". When the value itself varies, bind a data-* attribute (:data-status="$status") and style each value with an attribute selector in the component's <style>. Only the bound form is allowed: a hand-written data-status="ok" fails check with html/data-attribute.

routes/examples/styling/_components/build-status/build-status.html

<script>  const buildMs = 900  let status = 'idle'  const running = () => status === 'running'  const passed = () => status === 'passed'  const failed = () => status === 'failed'  function build(outcome) {    status = 'running'    setTimeout(() => { status = outcome }, buildMs)  }</script><div :data-status="$status">  <p class="status-line">    <span class="status-dot" aria-hidden="true"></span>    <span class="font-mono text-sm text-muted" .text-accent="$passed" .text-danger-300="$failed">{$status}</span>  </p>  <div class="flex flex-wrap gap-2">    <button type="button" class="btn btn-small" @click="build('passed')" :disabled="$running">Run build</button>    <button type="button" class="btn btn-small" @click="build('failed')" :disabled="$running">Run with an error</button>  </div></div><style>  [data-c="build-status"] {    display: grid;    justify-items: center;    gap: 1rem;  }  .status-line {    display: flex;    align-items: center;    gap: 0.625rem;  }  .status-dot {    width: 0.5rem;    height: 0.5rem;    background: var(--color-faint);  }  [data-c="build-status"][data-status="running"] .status-dot {    background: var(--color-warning-400);    animation: status-blink 0.8s steps(2) infinite;  }  [data-c="build-status"][data-status="passed"] .status-dot { background: var(--color-accent); }  [data-c="build-status"][data-status="failed"] .status-dot { background: var(--color-danger-400); }  @keyframes status-blink {    50% { opacity: 0.2; }  }  @media (prefers-reduced-motion: reduce) {    [data-c="build-status"][data-status="running"] .status-dot { animation: none; }  }</style>

routes/examples/styling/_snippets/build-status/rejected.html

<span :class="$tone"></span>

routes/examples/styling/_snippets/build-status/check.txt

$ pragma check --stricterror [html/class] :class is not allowed: write static classes in class="…" and toggle each one with .name="path" (e.g. .text-warning-700="$warn")

Live result

idle

The text color is two utility toggles; the dot reads data-status from the root.

Light and dark theme

Dark mode keys off data-theme="dark": tokens redefined under [data-theme="dark"] switch on their own, and palette colors pair with dark: (bg-white dark:bg-neutral-900), which matches the element or any ancestor. In an app, setTheme() from core/theme.js sets it on <html> and saves it, as the theme-switch.html tab shows; importing that module also adds an inline script that restores the choice, or follows prefers-color-scheme, before first paint.

This site is dark only, so the live box sets data-theme on its own root to keep the switch inside the box. Without the core/theme.js import, dark mode never activates: there is no media-query fallback. The import may also be written in the absolute form '/core/theme.js'.

routes/examples/styling/_components/theme-preview/theme-preview.html

<script>  let dark = false  const mode = () => (dark ? 'dark' : 'light')  const pressed = () => String(dark)  function toggle() {    dark = !dark  }</script><div :data-theme="$mode">  <div class="preview-bar">    <span class="preview-mode">data-theme="{$mode}"</span>    <button type="button" class="preview-toggle" @click="toggle" :aria-pressed="$pressed">Dark theme</button>  </div>  <article class="rounded-lg border border-neutral-200 bg-white p-4 shadow-md dark:border-neutral-800 dark:bg-neutral-900">    <h3 class="text-sm font-semibold text-neutral-900 dark:text-neutral-100">Invoice 2041</h3>    <p class="mt-1 text-sm text-neutral-600 dark:text-neutral-400">Due in 3 days, 48.00 EUR</p>    <span class="mt-3 inline-block rounded-full bg-success-100 px-2 py-0.5 text-xs text-success-800 dark:bg-success-900 dark:text-success-200">Paid</span>  </article></div><style>  [data-c="theme-preview"] {    display: grid;    gap: 1rem;    width: 100%;    max-width: 20rem;    padding: 1rem;    border: 1px solid var(--color-line-strong);    background: var(--page-bg);    color: var(--page-fg);    color-scheme: light;    font-family: var(--font-sans);    transition: background-color 0.2s var(--ease-out), color 0.2s var(--ease-out);  }  .preview-bar {    display: flex;    align-items: center;    justify-content: space-between;    gap: 1rem;  }  .preview-mode {    font-family: var(--font-mono);    font-size: 0.75rem;  }  .preview-toggle {    padding: 0.375rem 0.75rem;    border: 1px solid currentColor;    border-radius: 2px;    font-family: var(--font-mono);    font-size: 0.75rem;    cursor: pointer;  }  .preview-toggle[aria-pressed="true"] {    background: var(--page-fg);    color: var(--page-bg);  }  .preview-toggle:focus-visible { outline-color: currentColor; }  @media (prefers-reduced-motion: reduce) {    [data-c="theme-preview"] { transition: none; }  }</style>

routes/examples/styling/_snippets/theme-switch/theme-switch.html

<script>  import { theme, setTheme } from '../../../core/theme.js'  let dark = theme() === 'dark'  const label = () => (dark ? 'Light theme' : 'Dark theme')  const pressed = () => String(dark)  function toggle() {    dark = !dark    setTheme(dark ? 'dark' : 'light')  }</script><button type="button" class="btn" @click="toggle" :aria-pressed="$pressed">{$label}</button>

Live result

data-theme="light"

Invoice 2041

Due in 3 days, 48.00 EUR

Paid
--page-bg and --page-fg come from core/base.css; the card uses only palette utilities with dark: variants.