Spec

What this page is

Stisla is a design specification. The Introduction covers why this is the shape. This page covers what is in it. The contract every implementation honors for the components it ships. The vanilla bundle is the first implementation, and the React + Base UI and Vue ports come against the same surface. Coverage varies per port, so check the matrix on each component table below.

The component pages (Button, Card, Dialog) document how to use the vanilla implementation. This page documents what is fixed for every implementation. Per-component CSS variables, default values, and Sass internals are implementation detail and live on the component pages.

Coverage

The spec describes the full design language, and each implementation ships a subset of it. CSS and HTTP work the same way. The spec catalogs features, the implementations cover what they cover, and a matrix tells you what to expect on a given stack.

Two guardrails keep the spec honest.

• A component lands here only when at least one implementation has committed to shipping it. The spec is not a wishlist.
• Every component row carries a coverage cell per port, so a reader on any stack can tell at a glance what they actually get.

The anatomy tables below use Ships for present in the current release, Planned for committed but not yet built, and a blank cell for components that are out of scope on that port. Token, state, scale, and theming surfaces above are foundational and apply equally to every implementation. Only component coverage varies.

Tokens

The token surface is flat. Every component reads from --st-* via var(), and every override flows through hover, active, and focus because state derivations run at runtime through color-mix(in oklch, …). The names are the spec. Values are implementation defaults. See Customization for the shipped ones and how to override them.

Intent

Five paired tokens for semantic color. Each pairs a base with a foreground so text contrast survives a base swap.

Surface tier

Background, foreground, and the three surface levels for stacked panels. --st-muted-foreground is the secondary text color paired with every surface.

Interactional

Tokens that paint interactive states regardless of intent.

Geometry

Type

Per-component tokens

Every component exposes a --<block>-* surface that falls back to the global tokens above. --btn-radius falls back to --st-radius, --card-bg falls back to --st-surface, and so on. The names of those per-component tokens are part of the spec, but the defaults are set by each implementation. See the Customization section at the bottom of each component page for the catalog.

Component anatomy

Every component is a BEM block with a fixed set of element slots. A port can render those slots with any tag or framework primitive it likes, but the slot names are the contract. A user who learns Card on the vanilla port should find the same parts on the React port.

Forms

Components

Overlays

Layout

States

Interactive surfaces answer to a fixed vocabulary. Implementations choose how each state paints (the tokens decide that), but the state names and the runtime hooks below are part of the contract.

Interactive states

Every interactive component supports the same six states. Pseudo-classes drive the first four, and the rest are explicit.

Runtime state hooks

Two prefixes, split by origin. Radix-aligned states use [data-state], and Stisla-original states use .is-*. Pick one per concept and stick to it.

Scales

Three knobs reshape the system proportionally. Implementations expose them as global tokens, and per-component overrides ride on top.

Theming

Light and dark are deltas on the same token surface rather than separate themes. A port honors them by writing two blocks. A base, and a dark override scoped to [data-theme="dark"] or .dark.

Per-component -foreground pairings are mandatory. If a component introduces a new background variable, it introduces the paired foreground at the same time, so a token override never strands a text color.

Focus

One ring rule across the system. The visible ring derives from --st-ring, which defaults to --st-primary so a brand swap repaints every focus. The ring is rendered with box-shadow or outline, but not both. Only :focus-visible paints the ring. :focus on its own is invisible because it fires on mouse clicks too.

Motion

Disclosure components (Accordion, Collapsible, Dialog, Drawer, Dropdown, Popover, Toast, Tooltip) transition between data-state="open" and data-state="closed". The shape of that transition is up to the implementation. The contract is that both states are settled and addressable. prefers-reduced-motion collapses the transition to zero duration but keeps the start and end states intact.

Implementations

One spec, many implementations. Status as of 3.0.0-beta.1.

Every implementation reads from the same --st-* token surface and ships the same BEM class names. A page authored against one implementation should swap to another without rewriting markup.