Skip to content
v0.1.1

Getting started

Architecture

How Stance is built: two packages, layered design tokens, a plain-CSS styling model and dependency-free accessibility primitives.

Packages

PackageContentsRuntime dependencies
@bindshq/stance-tokensPrimitives, three themes, CSS variables, JSON, Tailwind presets, contrast utilities, the no-flash theme script.None
@bindshq/stance-reactComponents, icons, accessibility primitives, ThemeProvider.None (React is a peer)

Token layers

  1. Brand: the two official colours, ivory and indigo.
  2. Primitives: the ink scale (an OKLab interpolation between ivory and indigo), functional status colours and the type, space, radius and motion scales.
  3. Semantic roles: what components consume: bg-canvas, fg-muted, border-control, accent-bg, danger-fg… Each theme maps every role.
  4. Component variables: private --_* variables inside each component, derived from semantic roles.

Styling model

Components render stable class names (st-button, st-dialog__title) and expose variants and state as data attributes (data-variant, data-state). Styles are plain CSS with no build step on the consumer side, and selectors are scoped so Stance never restyles host markup.

Accessibility primitives

Stance implements its own interaction layer instead of depending on headless libraries:

  • Focus scope: trap, auto-focus and restore for dialogs and popovers.
  • Dismissable layer stack: Escape and outside-click handling that respects nested, portalled layers.
  • Anchored positioning: collision-aware placement with flip and shift, updated on scroll and resize.
  • Roving focus and typeahead: the WAI-ARIA patterns for toolbars, tabs, menus, listboxes, trees and grids.
  • Portal: SSR-safe, and carries scoped themes into portalled content.

Source layout

text
packages/react/src/
├── components/<name>/
│   ├── <Name>.tsx        component
│   ├── <name>.css        styles (tokens only)
│   ├── <Name>.test.tsx   behaviour, keyboard and axe tests
│   └── index.ts          public exports
├── internal/             focus scope, layers, positioning, roving focus…
├── icons/                the Stance icon set
└── styles/               base keyframes and utilities
apps/docs/content/components/<slug>.tsx   docs + live examples

Distribution

  • ESM only, one module per source file, so bundlers tree-shake unused components.
  • 'use client' appears only in modules that need it, so server components can import from the package root.
  • One styles.css, plus per-component stylesheets at @bindshq/stance-react/components/<name>.css.