@needless-ui/tokens

Design tokens for Needless UI, written in the W3C Design Tokens format (DTCG 2025.10) and compiled to CSS custom properties.

Use

@import '@needless-ui/tokens/tokens.css';

.card {
  padding: var(--nui-space-4);
  border-radius: var(--nui-radius-lg);
  background: var(--nui-color-bg-subtle);
  color: var(--nui-color-text-default);
}

• dist/tokens.css: custom properties with light and dark modes.
• dist/tokens.json: every token resolved per mode, for docs and tooling.
• src/**/*.tokens.json: the DTCG sources, for your own design token pipeline.

Modes

Light values apply by default, dark values when the OS prefers dark. Pin a mode on any element, and nest them freely:

<html data-nui-theme="dark">
  <aside data-nui-theme="light">…</aside>
</html>

Color scales

Each palette (neutral, accent, danger, success, warning) has 12 steps with fixed roles: 1–2 backgrounds, 3–5 element states, 6–8 borders, 9–10 solid fills, 11–12 text. The scales are generated by scripts/palette.ts, which fits every color into sRGB and checks the WCAG 2.2 contrast of each text/background pair before writing the files.

Components use the semantic aliases (--nui-color-accent-solid, --nui-color-bg-canvas, …), so overriding one alias restyles every component that uses it.

Springs

Motion tokens are springs. Each --nui-spring-* is a DTCG transition with its physics in $extensions["com.needlessui.spring"]:

"bouncy": {
  "$value": { "duration": { "value": 490, "unit": "ms" }, "delay": { "value": 0, "unit": "ms" }, "timingFunction": [0.62, 2.35, 0.21, 0.69] },
  "$extensions": { "com.needlessui.spring": { "stiffness": 300, "damping": 14, "mass": 1 } }
}

The $value is the closest cubic-bezier, for other DTCG tools. This package's compiler solves the spring instead and emits its settling time and exact curve: --nui-spring-bouncy: 889ms linear(0, 0.009 0.9%, …, 1). Use one in any transition, transition: transform var(--nui-spring-bouncy), or point --nui-motion at it to change how every component moves. Springs, like durations, collapse to 0.01ms under prefers-reduced-motion.

--nui-radius-scale and --nui-density multiply every component radius and every control size. The data-nui-* presets in @needless-ui/css set all three for a subtree.

Browser support

Colors are oklch() (Chrome and Edge 111, Firefox 113, Safari 15.4 and later); springs are linear() easings (Chrome and Edge 113, Firefox 112, Safari 17.2), and transitions that use one don't run in older browsers. The components need a little more; see the browser support guide.

License

MIT