@invoiceonline/ui-system
v0.18.0
Published
Canonical design system for FakturaOnline. Two-layer tokens (primitives + semantic) with rationale, AI-readable spec, vanilla Node build.
Readme
@invoiceonline/ui-system
Canonical design system for FakturaOnline — the single source of truth that production CSS, Storybook, and Webflow consume.
AI tools (Claude, Codex, Cowork, Stitch, Cursor): the repo's rules are in AGENTS.md (
CLAUDE.mdis a pointer to it); for any visual decision start with DESIGN.md, the session-start contract.Humans: keep reading. Every process doc is indexed in
docs/README.md.
What's here
| Folder | What |
|--------|------|
| tokens/primitives/ | Raw value scales (Layer 1, --ds-*). Optional notes field for production-anchored, legacy, or quirky entries. |
| tokens/semantic/ | Semantic aliases components consume (Layer 2: --primary, --text-*, --bg-*, --status-*, --space-*, --radius-*, …). Each carries a required rationale explaining where to use it, where NOT, and why it exists. |
| spec/ | Markdown specifications: Foundations / Tokens / Atoms / Molecules / Organisms / Patterns / Web + Migration history — start at spec/README.md |
| scripts/ | Build pipeline, validators and audit linter (docs/validation.md) |
| dist/ | Generated CSS / TS / JSON consumed by other repos (gitignored) |
| packages/react/ | @invoiceonline/ui-react — the React components built on these tokens, released on their own (docs/react/README.md) |
| docs/ | Process docs: tokens, Figma sync, component docs, versioning, validation, git, PRs, decisions (docs/README.md) |
| PENDING-UPSTREAM.md | Open questions from the React package to the spec — sections A and B are for the design owner; resolved rows move to PENDING-UPSTREAM-ARCHIVE.md |
Two token layers, both shipped as CSS custom properties in dist/tokens.css; components never reference primitives directly. The architecture, naming and build: docs/tokens.md.
Quickstart
nvm use # 24.13.0
npm install
npm run build # generate dist/tokens.css, dist/tokens.ts, dist/tokens.flat.json
npm run validate # every gate CI runsDetails, including working without node_modules: CONTRIBUTING.md → Local setup.
Consuming the package
Published to npm as @invoiceonline/ui-system (public). No auth needed:
npm i @invoiceonline/ui-system
# or: yarn add @invoiceonline/ui-systemimport '@invoiceonline/ui-system/tokens.css'; // CSS custom properties (:root)
import { primitives, semantic } from '@invoiceonline/ui-system'; // typed TS exports
// '@invoiceonline/ui-system/tokens.flat.json' — flat key/value mapUpgrade to a newer token version with yarn upgrade @invoiceonline/ui-system. A React app installs @invoiceonline/ui-react instead, which ships the same tokens with the components (packages/react/README.md).
Publishing
New token versions are published when a GitHub Release is published; the React package releases through Changesets. The maintainer runbook is PUBLISHING.md.
Contributing
See CONTRIBUTING.md for the setup and the recipe index, GIT.md for the git rules and docs/pull-requests.md for how a PR is reviewed and merged.
License
UNLICENSED — private FakturaOnline repository.
