@cupped/tokens

Framework-agnostic design tokens for the Cupped design system — a community-first coffee-logging platform. The canonical source is platform-neutral DTCG-style JSON under tokens/; every consumable artifact in dist/ is generated from it and committed. The package is published public on npm (npm install @cupped/tokens — no auth), and because dist/ is committed it also works as a plain git dependency with no install-time build, for consumers that prefer pinning a commit.

Never hard-code a hex or pixel value that exists as a token.

Exports

| Import | What you get | |---|---| | @cupped/tokens | React Native theme object (tokens), literal-typed, unitless dp numbers, dual-shape shadows, Reanimated spring params | | @cupped/tokens/css | CSS custom properties (--ink, --space-base…), alias var() chains preserved, prefers-reduced-motion / prefers-reduced-transparency blocks built in | | @cupped/tokens/css/components | Canonical web component classes (.btn, .input, .chip-flavor, .banner, .chrome…) — optional reference styles | | @cupped/tokens/tailwind | Tailwind v4 @theme file → utilities (bg-canvas, text-ink-secondary, rounded-lg, shadow-primary, p-base, text-card-title…) | | @cupped/tokens/json | Flat resolved map keyed by CSS names | | @cupped/tokens/json/dtcg | The merged DTCG source tree |

No components, no icons, no font binaries — components stay app-specific; fonts are self-hosted per platform (documented).

Consuming

• Phoenix LiveView (Tailwind v4): docs/phoenix.md — pinned CSS from the GitHub Release, npm dependency, or zero-npm vendor mode; fonts, lint recipe.
• Expo / React Native (SDK 53+): docs/expo.md — the theme.ts pattern, expo-font, ESLint recipe.
• Brand & a11y invariants: docs/rules.md.

Complete copy-paste examples live in examples/.

Architecture

tokens/primitive/*.tokens.json      raw palettes & scales (never consumed directly)
tokens/semantic/*.tokens.json       the public API — every token aliases a primitive
        │
        ▼  Style Dictionary v5 + custom formats (build/)
dist/css/tokens.css                 var() chains preserved (--xp: var(--sweet))
dist/tailwind/theme.css             @theme namespaces, fully resolved
dist/native/index.{js,cjs,d.ts}     resolved literals, as-const types
dist/json/tokens.{flat,dtcg}.json

Aliases use DTCG {dot.path} references; the build fails on unresolved or circular references. Accessibility requirements are encoded as data ($extensions["app.cupped"].contrast) and machine-checked in CI, alongside name-collision checks and a parity test against the frozen source-export/ (the refreshed design-system export this package mirrors — kept as reference, never edited).

Developing

Building requires Node 22+ (the build uses node:fs/promises glob). Consuming the published package has no Node version requirement.

npm install
npm run build   # tokens/ → dist/  (dist is committed)
npm test        # parity + contrast + collisions + snapshots + type-checks
npm run check   # build, fail on dist/ drift, then test — what CI runs

Releasing & versioning

Releases are automated with Changesets and published to public npm; each release also attaches version-pinned CSS to its GitHub Release. Add a changeset with npx changeset in any PR that changes tokens.

• Release mechanics & first-publish runbook: docs/releasing.md.
• What's a major/minor/patch (the token contract): docs/versioning.md.