Semantic tone classes

Ten semantic tones share one class vocabulary. Your skin supplies the colors; the active theme supplies the mode; the nearest tone supplies the context.

How the architecture fits together

The system separates meaning from appearance. A skin can change what accent looks like without changing component markup. Paint classes are shared across all tones, rather than generating another set of paint rules for every color.

The token contract

Every semantic tone has this structure in both theme modes:

semantic.tone.info
├─ tone                         direct accent color
├─ canvas / canvascolor         canvas fill / plain color
├─ overlay                      overlay color
├─ spotlight.field / light      field and radial light
├─ surface / surfaceAlt / button
│  ├─ rest / hover / active / disabled
│  │  └─ background / bgcolor / border / text
│  └─ focusRing
├─ root.text.default / subtle
├─ root.border.subtle / default / focus
├─ text.default / subtle
└─ border.subtle / default / focus

background is the complete fill and may contain a gradient. bgcolor is the plain color used by the flat fill families. Role text and border tokens are paired with that role's fill. General text and border tokens serve typography and structural accents outside a matched role.

From a theme token to a painted element

/* Conceptual binding for tone--info; the framework generates this. */
.tone--info {
  --ps-current-surface-rest-background:
    var(--ps-semantic-tone-info-surface-rest-background);
}

.tone-fill-surface {
  background: var(--ps-current-surface-rest-background);
}

getCurrentThemePalette() returns symbolic CSS variable references for use in style builders. getThemePaletteVarName(path) and getCurrentThemePaletteVarName(path) produce the variable names when you need to inspect or integrate them directly.

The theme root starts with the neutral current palette. At that root, general current text and border variables use neutral's root.text and root.border aliases. An explicit tone--neutral instead selects neutral's regular text and border tokens, just as the other tone selectors do. This allows document chrome and a neutral component to have different typography and border needs.

Implementation: token contract ↗ · current palette bindings ↗ · paint and state presets ↗

Selection, paint, and geometry

<div class="tone--info tone-fill-surface tone-border-surface
            tone-text-surface b-1 rounded-md p-3">
  An information surface
</div>

Tone border classes set color. Add a width such as b-1, b-2, or bl-2 to make the border visible. Spacing and radius remain independent utilities. Pair role fill, border, and text when you want the skin's intended contrast.

All ten semantic tones

Every card uses the same recipe. Its alternate surface and button role inherit the selected tone. These meanings are conventions; your skin determines their actual colors.

All ten fill families

The bare swatches keep the fills visible without placing potentially incompatible text over them. Compare the regular role backgrounds with their flat counterparts: a skin may give the former chrome or gradients, while flat always takes bgcolor.

Use tone-fill for a direct tone accent and tone-fill-canvas for canvas paint. Neither implies matching readable text. Surface, alternate surface, and button each have their own paired text and border classes. Spotlight and glass use alternate surface text and borders in the component recipes.

Inheritance and nested contexts

<section class="tone--accent">
  <div class="tone-fill-surface tone-text-surface">Inherits accent</div>
  <aside class="tone--info">
    <div class="tone-fill-surface tone-text-surface">Inherits info</div>
  </aside>
</section>

Nested theme roots

html[data-theme="light"] and html[data-theme="dark"] set the document mode. .theme--light and .theme--dark create local theme regions, including inside the opposite mode. A theme root supplies its own text color and color-scheme, and rebases the current palette to neutral. Select a tone on that root or inside it to establish another intent. Root bindings use zero specificity so an explicit tone selector can win on the same element.

Inspect a real recipe

Change the tone, role, and state. The inspector reads the generated current variables from the actual preview element. Switch the site theme to see the values change without changing the recipe.

Every role and interaction state

All three matched roles are shown at rest, hover, active, and disabled. Hover snapshots paint the hover tokens directly so they remain visible; the other samples use the actual state selectors. The rest samples also respond to your pointer.

<button type="button" class="tone--accent
  tone-fill-button-all tone-border-button-all tone-text-button-all
  b-1 rounded-md p-2">
  All four states
</button>

The unsuffixed class paints rest. -hover applies under :hover; -active applies under :active or .active; -disabled applies under native :disabled. -all combines the available states for that family. A hover suffix alone does not paint rest, and .active does not create button behavior or an ARIA state. aria-disabled="true" alone does not match :disabled.

Exact class and state reference

The table lists every generated family. Append only the suffixes listed here; state support differs by family.

The general border family has an -all class but no disabled state. The general text, direct fill, canvas, and inset families have no -all class. Focus is a separate concern: these preset families do not generate -focus classes.

Text, borders, and clipped fills

text-subtle, prose-meta, and text-eyebrow read current general subtle text. b-subtle, b-default, b-focus, and b-tone read current general border or tone tokens and set border color with !important. Avoid competing border-color classes on the same element.

Spotlight and glass: all five origins

Spotlight combines a field with radial light. Glass paints radial light and a translucent veil; it does not add backdrop blur. Both read --ps-spotlight-from, which inherits independently of the tone context. Every origin is visible below, with an inner glass panel sharing its parent's light position.

Spotlight's light reach grows from 46% at rest to 60% on hover and 72% when active; disabled paints the field alone. Glass uses a 75% light reach and veil strengths of 45%, 58%, and 70%; disabled paints only a 25% veil. A custom origin can use style="--ps-spotlight-from: 35% 20%".

<div class="tone--feature tone-fill-spotlight tone-text-surface-alt
            spotlight-from-top-right rounded-md p-3">
  <div class="tone-fill-glass tone-border-surface-alt
              tone-text-surface-alt b-1 rounded-md p-3">
    Same light origin, inherited feature palette
  </div>
</div>

Insets: all directions and sizes

Insets paint an internal edge using the direct tone color. x combines left and right; y combines top and bottom. Each class sets box-shadow, so use the combined direction rather than stacking individual inset classes to combine edges.

The default inset width is .25em. inset-size-* changes the width, including zero to remove it; the unit follows the element's font size.

<div class="tone--warning tone-fill-surface tone-text-surface
            tone-inset-l inset-size-2 p-3">
  An attention marker without changing the outer border
</div>

How components compose these classes

Internally, resolveComponentClasses() combines a variant's rest recipe, optional interaction classes, and an explicit tone selector. With no tone supplied, the component inherits its surrounding context. The 18 variants below use the actual resolver with tone: 'accent' and variantMode: 'stateful'; hover and press them to see their behavior.

variantMode: 'stateless' keeps the rest recipe and omits the resolver's interaction additions. stateful adds the appropriate hover and active recipes; it does not automatically add every utility family's disabled classes. Components may provide their own disabled styling and behavior. none removes the variant recipe, while component base styles and an explicitly supplied tone still apply.

<Btn tone="info" variant="surface" variantMode="stateful">
  A component using the surface recipe
</Btn>

Read the complete variant recipes ↗

Focus and custom styles

Each role exposes a focusRing token. Consume it in component or custom styles; the tone presets do not automatically draw a focus indicator. General border.focus is also available for structural focus borders.

import { getCurrentThemePalette } from '@purestack/ts-style'

const current = getCurrentThemePalette()
// Inside your registered style-builder callback:
root.select('.my-action:focus-visible').css({
  outline: `2px solid ${current.button.focusRing}`,
  outlineOffset: '3px',
})

The symbolic reference keeps the style responsive to the nearest tone and theme. Apply tone--danger to that action and its focus ring follows the danger button role without another selector.

Continue with themes and skins for palette authoring and utility classes for geometry and layout.