stnd.build

@stnd/styles

Circle 1 — Core Framework (Inviolable Pillar) · Stable · Load-Bearing

Role: Vanilla-first CSS framework: semantic reset, design tokens, OKLCH color engine, 12-column Swiss grid, vertical rhythm, and hybrid utilities.

When to use: Loaded automatically by @stnd/core. Use the intentional guides: Typography, Flexbox, Spacing, Swiss Grid, Color.

Quick Start (TL;DR)

<article class="prose">
  <h1>Semantic HTML First</h1>
  <div class="grid gap-2 no-rhythm">
    <div class="col-6 sm:col-12 bg-surface border rounded p-2">Card</div>
  </div>
</article>

The CSS typography and design system framework for the Standard Ecosystem.


This is the CSS. One seed color in, a whole harmonious palette out; one base font size in, a whole readable type scale out. You almost never touch this package directly — it’s on automatically (see @stnd/modules/styles in the Gold Standard). You touch it when you want to change the numbers behind the look (the golden-ratio scale, the OKLCH color math) rather than a specific theme’s colors (that’s @stnd/themes).

You’re already using it. Nothing to install or configure for a normal site.

Overview

@stnd/styles is a comprehensive design system based on classical book design, the Golden Ratio, and OKLCH color spaces. It provides structural layout grids, clean typography scales, and automated color themes for all Standard applications with zero configuration.


1. Mathematical Spacing & Ratios

The system rejects arbitrary pixel coordinates. All spacing, font scaling, and line heights are tied to three mathematical constants:


2. Typographic Scale

Standard applies a strict modular font scale to prevent typographic clashes. Body font sizes map to CSS custom properties:

CSS Variable Scale Class Value / Application
--scale-8 .scale-8 Large Display Title
--scale-4 h1 Primary Document Header
--scale-2 h2 Subheadings
--scale body Base Body Text ($1\text{rem}$)
--scale-d2 .small, small Captions, Side Notes
--scale-d3 .smaller Footnotes
--scale-d4 .micro Meta Labels, Short Codes
--scale-d5 .nano Micro-badges

3. Spacing Grid (Baseline Rhythm)

Vertical rhythm is managed through a base unit --space (usually $1\text{rem}$ / $16\text{px}$). Multiples and fractions are locked:

Elements align to this grid through a strict rule: the sum of an element’s font-size, line-height, and margins must always be a multiple of --space.


4. Color System (OKLCH Color Space)

Instead of hardcoding colors, the system generates complete color palettes dynamically. By using OKLCH color mathematics, one seed color generates borders, backgrounds, surfaces, and active states with uniform perceived brightness:


5. Layout Modes & Templates

Specialized styling rules load automatically depending on document attributes:

6. Buttons & Cards

Both are read by their elements, not by extra classes.

Buttons

A native <button> (or a.btn) is the primary action by default — no .primary class exists.

Renamed in October 2026

.secondary became .accent (buttons and badges), and .primary was dropped. Migrating a site: replace class="secondary" with class="accent" on buttons and badges, and delete primary from button class lists. Nothing else changes.

Cards

An article.card is composed of three optional structural regions:

<article class="card">
  <header>
    <h3>Title</h3>
    <svg width="1cap" height="1cap">…</svg> <!-- optional icon, outside the heading -->
  </header>
  <div>
    <p>The body keeps its own vertical rhythm.</p>
  </div>
  <footer class="flex-right">
    <a href="#">Read more</a>
    <a href="#" class="btn">Continue</a>
  </footer>
</article>

Roles: which token to reach for

Companion to the generated token reference (/manual/css/color): the CSS reference documents what each token is and its computed value directly from the SCSS source; this section defines which semantic role to reach for, and when.

1. Principles

  1. Industry standards first. A name is not a matter of taste: where an established system already names the role (Apple, Atlassian, GitHub Primer, IBM Carbon, Material, shadcn/ui, CSS itself), we use that word.
  2. Name by role, never by value or by scheme. A component asks for “the raised surface”, not “a lighter background” and not “the dark-mode grey”.
  3. One job per token. If two tokens are used for the same thing, one of them is wrong.
  4. Seeds in, roles out. A theme supplies a handful of seeds. Every role is a deterministic function of those seeds, so a new theme cannot omit a role.
  5. Components never read seeds. Only the semantic layer reads the scheme-specific seeds; everything downstream is scheme-blind and flips automatically via light-dark().
  6. A role is only real if it is testable. Each role carries an automated conformance check (tests/styles/).
  7. Never repurpose a role. Do not use the separator color as text, or a secondary label as a background.

2. The four layers

Layer Who writes it Who reads it Example
Seeds a theme (tokens.yaml) the palette layer only --color-light-background, --color-dark-foreground
Palette the framework (formulas) the semantic layer only --color-dark-border, --color-light-muted
Roles the framework (light-dark()) components, apps, users --color-background, --color-surface, --color-muted
Component aliases a component or an app itself --canvas, --panel-edge

2.1 Overriding a role on a subtree

CSS custom properties that reference another custom property are resolved where they are declared, not where they are read:

3. Role catalogue

3.1 Ground and surfaces

The surfaces form a ladder relative to the ground. Direction is fixed by meaning, not by lightness: raised is toward the viewer, sunken is away from it.

Role Job
--color-background The ground. The main field of the app or page. Sidebars, rails, and content all sit on it.
--color-surface-sunken Inputs, wells, code blocks, table stripes, switch tracks.
--color-surface-raised Cards, panes, panels: anything that sits on the ground (--color-surface is the short alias).
--color-surface-overlay Menus, popovers, dialogs, tooltips: anything that floats over a surface.
--color-stage Neutral backdrop behind media (photos, video, canvas), darker than the ground in both schemes so the picture carries the contrast.
--color-glass Translucent chrome over moving content.

3.2 Content (text and icons)

Role Job
--color-foreground Primary text.
--color-muted Secondary text, captions.
--color-subtle Tertiary text, decorative icons.
--color-placeholder Placeholder text in form fields.
--color-header Headings, when a theme customizes heading color.

3.3 Borders & lighting

Role Job
--color-border Hairlines: separators, card and pane outlines (~10% foreground mix, matching macOS separatorColor).
--color-highlight Specular top light on raised elements (--shadow-raised). Not an outline color.
--color-shadow Shadow seed.

3.4 Interaction

Translucent overlays that work on every rung of the surface ladder without recomputation:

Role Job
--color-hover Row, button, or item under the pointer.
--color-active Pressed state (:active).
--color-selected Selected row or active item.
--color-ring Keyboard focus indicator (defaults to accent).
--color-stripe Alternating row or column background.
Role Job
--color-accent Single brand/interactive color.
--color-on-accent Text drawn on an accent fill.
--color-link Hyperlinks (defaults to blue).
--color-success, --color-warning, --color-error, --color-info Semantic status colors.
--color-<status>-background, --color-<status>-border Tinted fill (12%) and border (30%) for alerts, badges, and highlighted rows.
--color-red … --color-brown Raw hue palette (prefer semantic status or accent roles when meaning exists).

4. “I am building…” — which token?

Building Use
App window, page background
Sidebar that belongs to the app background, separated by border
Recessed sidebar (Claude desktop style) surface-sunken
Floating panel (inspector, side panel, app navigation) .panel: surface + --shadow + --panel-edge, inset by --panel-inset, radius --panel-radius; rows use .item (hover, selected), hairlines use .divider
Card, grouped list surface
Menu, popover, dialog surface-overlay
Text field, code block, well surface-sunken, border
Photo or video backdrop stage
Divider, outline of a card border
Hovered / selected row hover / selected
Placeholder, helper text placeholder / subtle
Disabled control or zone Native platform state (disabled, <fieldset disabled>, inert), dimmed automatically to --opacity-disabled
Focus ring ring / accent
Primary button accent fill, on-accent text

5. Elevation in light and dark

Elevation pairs a surface with its shadow:

Level Surface Shadow
Sunken --color-surface-sunken --shadow-inset
Ground --color-background none
Raised --color-surface-raised --shadow-raised
Overlay --color-surface-overlay --shadow-overlay (alias of --shadow-lg)

6. Conformance checks (tests/styles/)

Executed automatically against every theme in both light and dark schemes:

  1. Monotonic ladder: sunken <= background <= surface <= overlay (tests/styles/conformance.test.mjs).
  2. Neighbor separation: Adjacent elevation levels differ in color or shadow (tests/styles/elevation.test.mjs).
  3. Text contrast: foreground >= 7:1 on background across all themes.
  4. Achromatic stage: stage chroma is ~0 and its lightness sits at or below background.
  5. Single disabled dimming: Disabled controls and zones dim once via --opacity-disabled (tests/styles/disabled.test.mjs).
  6. Zero scheme leakage: No consumer component reads --color-light-* or --color-dark-* seed tokens directly.
  7. WebKit dynamic system colors: Verified against AppKit ground truth in tests/styles/webkit.test.mjs.

7. Industry Cross-Reference

Role Apple (AppKit / UIKit) Atlassian Primer Carbon shadcn/ui Standard Token
Ground windowBackgroundColor / systemBackground default surface bgColor-default $background background --color-background
Recessed textBackgroundColor sunken bgColor-inset — — --color-surface-sunken
Raised controlBackgroundColor / secondarySystemBackground raised — $layer-01 card --color-surface-raised (--color-surface)
Floating Material (Liquid Glass / regular) overlay — $layer-02 popover --color-surface-overlay / --color-glass
Border separatorColor — borderColor-default $border-subtle-01 border --color-border
Text levels labelColor … tertiaryLabelColor — fgColor-default / -muted $text-primary / -secondary foreground / muted-foreground --color-foreground, --color-muted, --color-subtle
Placeholder placeholderTextColor — — $text-placeholder — --color-placeholder
Selected unemphasizedSelectedContentBackgroundColor — — $layer-selected-01 — --color-selected
Focus keyboardFocusIndicatorColor — — $focus ring --color-ring
Accent controlAccentColor — — $interactive — --color-accent
Link linkColor — — $link-primary — --color-link
Hover / Active secondarySystemFill / systemFill — — $layer-hover-01 / -active-01 — --color-hover, --color-active

8. References


Integration

In your main SCSS stylesheet or Astro entry point:

// Load standard variables and layouts
@use "@stnd/styles/standard.scss";

Most apps never need this — the Gold Standard @stnd/modules/styles module injects the stylesheet automatically. Import it manually only when composing your own SCSS entry point.

Style Files Anatomy


This stylesheet package implements the visual system and design tokens of the Standard ecosystem. For further details on visual and engineering specifications, see: