@invoiceonline/ui-system

Canonical design system for FakturaOnline — the single source of truth that production CSS, Storybook, and Webflow consume.

AI tools (Claude, Cowork, Stitch, Cursor): start with DESIGN.md. It is the session-start contract for any visual decision in this repo.

Humans: keep reading.

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, --color-*, --space-*, --radius-*, --font-size-*, --leading-*, --border-*, --font-weight-*). Each carries a required rationale explaining where to use it, where NOT, and why it exists. | | spec/ | Markdown specifications: Foundations / Atoms / Molecules / Organisms / Patterns + Migration history | | scripts/ | Build pipeline (build-tokens.mjs) and audit linter (audit.mjs) | | dist/ | Generated CSS / TS / JSON consumed by other repos (gitignored) |

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:tokens
npm run audit

Architecture

Two layers, both shipped as CSS custom properties in dist/tokens.css:

Figma — FODS - WIP (source of truth for values + types)
  └─→ tokens/primitives/*.json    Layer 1 — raw scales (value + optional notes)
        └─→ tokens/semantic/*.json   Layer 2 — { alias, rationale } pointing at Layer 1
              └─→ dist/tokens.css         Closed token layer, consumed by all FO frontends
              └─→ dist/tokens.ts          Typed exports for TS consumers
              └─→ dist/tokens.flat.json   Flat key/value for Webflow / Storybook / others

Components NEVER reference primitives directly. Always semantic.

Consuming the package

Published to npm as @invoiceonline/ui-system (public). No auth needed:

npm i @invoiceonline/ui-system
# or: yarn add @invoiceonline/ui-system

import '@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 map

Upgrade to a newer token version with yarn upgrade @invoiceonline/ui-system.

Publishing

New versions are published when a GitHub Release is published. The maintainer runbook is in PUBLISHING.md.

Contributing

See CONTRIBUTING.md.

License

UNLICENSED — private FakturaOnline repository.