@qball-inc/tokens
v1.0.1
Published
QBall Design System tokens — framework-agnostic CSS custom properties, component classes, and a DTCG/Style-Dictionary JSON mirror. Zero build step; public default display face is Fira Code (Berkeley Mono restored per README in private builds).
Maintainers
Readme
Install
pnpm add @qball-inc/tokensUsage
The token layer is plain CSS plus a JSON mirror — there is no build step and no
runtime. Import the CSS in your app's style entry. Order matters: the component
layer reads var(--token) values defined by the layer above it.
/* app.css */
/* REQUIRED — every --token (colors, --data-* finance signals, --font-display,
radii, spacing) + semantic element styles + the button family (.btn). */
@import "@qball-inc/tokens/colors-and-type.css";
/* REQUIRED — the application component layer (.stat, .num, .badge, .meter,
.modal, .switch, .field, …). Must come AFTER colors-and-type.css. */
@import "@qball-inc/tokens/components.css";
/* OPTIONAL — Tailwind v4 @theme export: token-named utilities for your own
markup + the --font-display override seam. */
@import "@qball-inc/tokens/theme.css";Switch themes by setting data-theme on the root — light and dark are both
first-class and swap every token:
<html data-theme="dark">
<!-- … --></html>Consume the tokens as cross-platform data (DTCG / Style-Dictionary shape) from the package root or the explicit subpath:
import tokens from "@qball-inc/tokens"; // → tokens.json
// or: import tokens from "@qball-inc/tokens/tokens.json";What's in the package
| Import | File | Delivers | Required? |
| --- | --- | --- | --- |
| @qball-inc/tokens/colors-and-type.css | colors_and_type.css | Every CSS custom property the components reference + semantic element styles + the .btn family. | Yes |
| @qball-inc/tokens/components.css | components.css | The full application component layer (the rest of the class inventory). | Yes |
| @qball-inc/tokens/theme.css | theme.css | Tailwind v4 @theme export (token-named utilities + the --font-display seam). | Optional |
| @qball-inc/tokens · @qball-inc/tokens/tokens.json | tokens.json | DTCG / Style-Dictionary JSON mirror (cross-platform). | Optional |
Importing only colors-and-type.css then components.css (in that order) paints
the entire component inventory. Omitting either leaves components unstyled — a silent
miss, not an error. Full wiring guide:
docs/consumer-setup.md.
Display font
This package ships with Fira Code as the default display face. The system's intended display face is Berkeley Mono, a commercial typeface that is not redistributed here, so nothing licensed reaches the published package. To restore Berkeley Mono in a private build, see the repository README.
Part of the QBall Design System
- Components:
@qball-inc/react— the token-driven React component library. - Gallery: live component contact-sheet (light + dark).
- Source + docs: QBall-Inc/qball-design-system.
License
Apache-2.0 © QBall Inc. (The Apache-2.0 license covers this package's code; it is distinct from the Berkeley Mono font license, which is not granted here.)
