@skra/tokens

Project status — built primarily for the author's own applications and published quietly. No support, roadmap, or stability guarantees beyond the documented SemVer contract. Licensed under Apache-2.0 (see LICENSE / NOTICE).

Skra Design System token artifacts — the value half of the product (@skra/ui is the component half). Framework-agnostic: every file is plain CSS (shipped with a .scss extension so it drops into Sass pipelines verbatim) or JSON. No JavaScript, no framework coupling.

Versioned in lockstep with @skra/ui and @skra/shadow-dom-bridge; @skra/ui declares a peerDependency on this package so a component/token version skew is uninstallable.

Layout

<skin>/                  Per-skin artifacts (published skins only)
  _theme.scss            ref + sys value layer → :root
  _comp.scss             comp defaults → :where(:root, :host)
  _theme.dark.scss       dark scheme → [data-skra-color-scheme="dark"]
  _density.compact.scss  density overrides → [data-skra-density="compact"]
  _density.comfortable.scss
  _baseline.scss         opt-in document baseline → [data-skra-baseline]
  _form-controls.scss    cross-encapsulation residual slice (if the skin ships one)
  _overlay.scss          top-layer slice: ::backdrop + scroll-lock (if the skin ships one)
  utilities.scss         utility classes (skra-sr-only, …) (if the skin ships one)
  *.scoped.scss          runtime-scoped coexistence artifacts → [data-skra-skin="<skin>"]
  skin.config.json       skin metadata (fonts incl. loading sources, defaults, profile)
overlays/                Skin overlay presets → [data-skra-overlay="<name>"] (ADR 029)
manifests/<component>.json  Consumer Token API — skin-surface.json manifests (ADR 029 §3.2)

Usage

Load the value layers into your global stylesheet, in this order. Every layer is plain CSS — it declares no Sass members — so load each one with @use … as *:

@use 'pkg:@skra/tokens/skra/_theme.scss' as *;
@use 'pkg:@skra/tokens/skra/_comp.scss' as *;
@use 'pkg:@skra/tokens/skra/_theme.dark.scss' as *; // opt-in dark scheme
@use 'pkg:@skra/tokens/skra/_baseline.scss' as *; // opt-in document baseline
@use 'pkg:@skra/tokens/skra/_form-controls.scss' as *;
@use 'pkg:@skra/tokens/skra/_overlay.scss' as *;
@use 'pkg:@skra/tokens/skra/utilities.scss' as *;
@use 'pkg:@skra/tokens/skra/_density.compact.scss' as *; // opt-in runtime densities
@use 'pkg:@skra/tokens/skra/_density.comfortable.scss' as *;

Three things about that snippet are load-bearing. Skipping any of them fails the first build, with a message that names Sass rather than Skra:

1. as * is required, not stylistic. @use derives a namespace from the file name, so _theme.scss and _theme.dark.scss both want the namespace theme and Sass aborts with "There's already a module with namespace 'theme'". The same collision hits _density.compact / _density.comfortable and every .scoped pair. Because the layers define no Sass members — only CSS custom properties — there is nothing for a namespace to disambiguate, and as * is free.

2. pkg: resolves the package without build config. The Sass package importer reads this package's exports map directly. It is enabled by default in the Angular CLI / @angular/build, Vite, and sass ≥ 1.78 when the importer is registered.

If your toolchain does not wire the package importer, drop the pkg: prefix and put node_modules on the load path instead — the layer set and order are identical:

// angular.json / project.json — build target options
"stylePreprocessorOptions": { "includePaths": ["node_modules"] }

@use '@skra/tokens/skra/_theme.scss' as *; // bare specifier + includePaths

sass --load-path=node_modules styles.scss   # CLI equivalent

3. @import is not supported. Dart Sass has deprecated @import and will remove it; earlier versions of this README showed it. Use @use as above.

Runtime switches are plain DOM attributes: data-skra-color-scheme="dark", data-skra-density="compact|comfortable", data-skra-overlay="<preset>", and — for multi-skin coexistence via the *.scoped.scss artifacts — data-skra-skin="<skin>".

Manifests

manifests/<component>.json is the machine-readable Consumer Token API contract per component: which --skra-comp-* tokens are public override targets, their types, constraints, and permitted tiers. Tokens absent from a manifest are private regardless of technical overridability.

Private skins

Only skins marked "publishable": true in their skin.config.json are included in this package. Brand/client skins are distributed separately (see the Skra skin-distribution ADR, forthcoming).