@cupped/tokens 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# @cupped/tokens
+
+## 0.1.0
+
+Initial release. DTCG token source under `tokens/` with generated, committed
+targets in `dist/`:
+
+- React Native theme object (`@cupped/tokens`) — literal-typed, unitless dp.
+- CSS custom properties (`@cupped/tokens/css`) with alias `var()` chains.
+- Web component classes (`@cupped/tokens/css/components`).
+- Tailwind v4 `@theme` (`@cupped/tokens/tailwind`).
+- Flat and DTCG JSON (`@cupped/tokens/json`, `@cupped/tokens/json/dtcg`).
+
+Published to GitHub Packages (`@cupped` scope); also installable as a git
+dependency. Subsequent releases are managed with Changesets — see
+[docs/releasing.md](./docs/releasing.md) and
+[docs/versioning.md](./docs/versioning.md).

package/README.md

@@ -0,0 +1,79 @@
+# @cupped/tokens
+
+Framework-agnostic design tokens for the **Cupped** design system — a
+community-first coffee-logging platform. The canonical source is
+platform-neutral [DTCG](https://www.designtokens.org/TR/drafts/format/)-style
+JSON under [`tokens/`](./tokens); every consumable artifact in
+[`dist/`](./dist) is **generated** from it and committed. The package is
+published to **GitHub Packages** (`@cupped` scope), and because `dist/` is
+committed it also works as a plain git dependency — no registry auth, no
+install-time build — for consumers that prefer that.
+
+> 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](./docs/phoenix.md) —
+  pinned CSS from the GitHub Release, npm git-dep, or zero-npm vendor mode;
+  fonts, lint recipe.
+- **Expo / React Native (SDK 53+):** [docs/expo.md](./docs/expo.md) — the
+  `theme.ts` pattern, expo-font, ESLint recipe.
+- **Brand & a11y invariants:** [docs/rules.md](./docs/rules.md).
+
+Complete copy-paste examples live in [`examples/`](./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/`](./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.
+
+```bash
+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](https://github.com/changesets/changesets)
+and published to GitHub Packages; 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](./docs/releasing.md).
+- **What's a major/minor/patch (the token contract):** [docs/versioning.md](./docs/versioning.md).

package/dist/css/components.css

@@ -0,0 +1,183 @@
+/* ════════════════════════════════════════════════════════════════
+   CUPPED COMPONENTS · v0.4
+   Canonical component classes. Load AFTER tokens.css:
+     <link rel="stylesheet" href="tokens.css">
+     <link rel="stylesheet" href="components.css">
+
+   These are the real design-system components — a prototype's button
+   IS this button, not a lookalike. Colors, type, spacing and elevation
+   reference tokens (var(--…)); a few structural primitives (hairline
+   borders, icon box sizes) stay as raw px where no token exists.
+
+   Hand-maintained web reference (src/css/components.css in
+   @cupped/tokens); shipped via the "/css/components" export.
+   ════════════════════════════════════════════════════════════════ */
+
+/* ——— Buttons ——— */
+.btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--space-sm);
+  font-family: var(--ff-sans);
+  font-size: 15px;
+  font-weight: 600;
+  letter-spacing: -0.005em;
+  border-radius: var(--radius-md);
+  border: none;
+  cursor: pointer;
+  padding: 12px 20px;
+  min-height: var(--hit-target-min);
+  transition: transform .12s, background .15s, box-shadow .2s;
+}
+.btn:active { transform: scale(0.95); opacity: 0.8; }
+.btn:focus-visible { outline: none; box-shadow: var(--focus-ring); }
+.btn[disabled] { background: var(--canvas-border-subtle); color: var(--ink-muted); box-shadow: none; cursor: not-allowed; transform: none; }
+.btn-primary {
+  background: var(--primary-strong);
+  color: var(--ink-inverse);
+  box-shadow: var(--shadow-primary);
+}
+.btn-primary:hover { background: var(--primary-strong-hover); }
+.btn-secondary {
+  background: var(--card);
+  color: var(--ink);
+  border: 1px solid var(--canvas-border);
+}
+.btn-secondary:hover { border-color: var(--ink); }
+.btn-ghost {
+  background: transparent;
+  color: var(--primary-strong);
+}
+.btn-ghost:hover { background: var(--primary-light); }
+.btn-full { width: 100%; }
+
+.btn-stack { display: flex; flex-direction: column; gap: var(--space-sm); align-items: flex-start; }
+.btn-stack .btn { align-self: stretch; }
+.btn-row { display: flex; gap: var(--space-sm); flex-wrap: wrap; }
+
+/* ——— Flavor chips (light · text on white) ———
+   Set --flavor to a flavor TEXT-band token, e.g.
+   style="--flavor: var(--floral-accessible)" */
+.chip-flavor {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding: 6px 12px;
+  border-radius: var(--radius-full);
+  font-size: 13px;
+  font-weight: 500;
+  background: color-mix(in srgb, var(--flavor) 10%, white);
+  color: var(--flavor);
+  border: 1px solid color-mix(in srgb, var(--flavor) 25%, white);
+}
+.chip-flavor .dot {
+  width: 8px; height: 8px;
+  border-radius: 50%;
+  background: var(--flavor);
+}
+.chip-stack { display: flex; flex-wrap: wrap; gap: 6px; }
+
+/* ——— Flavor tags (solid · on photos/cards) ———
+   Set background to a flavor FILL token; the Espresso band
+   guarantees white text passes AA for every flavor. */
+.tag-flavor {
+  display: inline-flex;
+  align-items: center;
+  font-size: 12px;
+  font-weight: 500;
+  padding: 4px 8px;
+  border-radius: var(--radius-full);
+  color: #fff;
+}
+
+/* ——— Inputs ——— */
+.input {
+  width: 100%;
+  padding: 12px 14px;
+  border: 1px solid var(--canvas-border);
+  border-radius: var(--radius-md);
+  background: var(--card);
+  font-family: var(--ff-sans);
+  font-size: 15px;
+  color: var(--ink);
+  transition: border-color .15s, box-shadow .15s;
+}
+.input::placeholder { color: var(--ink-muted); }
+.input:focus {
+  outline: none;
+  border-color: var(--primary);
+  box-shadow: 0 0 0 3px color-mix(in srgb, var(--primary) 18%, transparent);
+}
+.input.error {
+  border-color: var(--error);
+  box-shadow: 0 0 0 3px color-mix(in srgb, var(--error) 12%, transparent);
+}
+.input[disabled] { background: var(--canvas); color: var(--ink-muted); cursor: not-allowed; }
+.input-row { display: flex; flex-direction: column; gap: 6px; }
+.input-label { font-size: 12px; font-weight: 500; color: var(--ink-secondary); }
+.input-hint { font-size: 12px; color: var(--ink-secondary); }
+.input-hint.error { color: var(--error-ink); }
+
+/* ——— Cards ——— */
+.card {
+  background: var(--card);
+  border: 1px solid var(--canvas-border);
+  border-radius: var(--radius-lg);
+  box-shadow: var(--shadow-sm);
+}
+.card-pad { padding: var(--space-lg); }
+
+/* ——— Rating stars ——— */
+.rating { display: inline-flex; gap: 4px; color: var(--xp); }
+.rating svg { width: 20px; height: 20px; }
+.rating .empty { color: var(--canvas-border); }
+
+/* ——— Feedback banners ———
+   The -ink variant tints the icon (≥3:1); the fill tints the border;
+   words stay ink / ink-secondary. */
+.banner {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--space-md);
+  padding: var(--space-md) var(--space-base);
+  border-radius: var(--radius-md);
+  border: 1px solid;
+  margin-bottom: var(--space-sm);
+}
+.banner .icon { width: 20px; height: 20px; flex-shrink: 0; margin-top: 1px; }
+.banner .body { font-size: 14px; }
+.banner .title { font-weight: 600; margin-bottom: 2px; }
+.banner.success { background: var(--success-light); border-color: color-mix(in srgb, var(--success) 25%, transparent); color: var(--success-ink); }
+.banner.error   { background: var(--error-light);   border-color: color-mix(in srgb, var(--error) 25%, transparent);   color: var(--error-ink); }
+.banner.warning { background: var(--warning-light); border-color: color-mix(in srgb, var(--warning) 25%, transparent); color: var(--warning-ink); }
+.banner.info    { background: var(--info-light);    border-color: color-mix(in srgb, var(--info) 25%, transparent);    color: var(--info-ink); }
+.banner .body .title { color: var(--ink); }
+.banner .body p { margin: 0; color: var(--ink-secondary); font-size: 13px; }
+
+/* ——— Chrome (floating bar/header material) ———
+   The sole sanctioned translucent surface — tab bar and sticky screen
+   headers only, one chrome layer per screen. Content surfaces are
+   always opaque. prefers-reduced-transparency collapses this to an
+   opaque card via the material tokens. */
+.chrome {
+  background: var(--material-chrome-bg);
+  -webkit-backdrop-filter: var(--material-chrome-blur);
+  backdrop-filter: var(--material-chrome-blur);
+}
+
+/* ——— Spinner (button loading state) ——— */
+.spinner {
+  width: 14px; height: 14px;
+  border: 2px solid rgba(255,255,255,0.35);
+  border-top-color: #fff;
+  border-radius: 50%;
+  animation: cupped-spin 0.8s linear infinite;
+  flex-shrink: 0;
+}
+@keyframes cupped-spin { to { transform: rotate(360deg); } }
+
+@media (prefers-reduced-motion: reduce) {
+  .btn { transition: none; }
+  .spinner { animation: none; }
+}

package/dist/css/tokens.css

@@ -0,0 +1,144 @@
+/* ════════════════════════════════════════════════════════════════
+   CUPPED · DESIGN TOKENS
+   GENERATED FILE — do not edit. Canonical source: the DTCG token files
+   under tokens/ (npm run build in @cupped/tokens).
+
+   · Components reference semantic tokens, never raw hexes.
+   · --primary (#E07A5F) is ~3.0:1 on white. It NEVER carries text
+     below 24px. Small colored text + text-bearing fills use
+     --primary-strong (4.6:1, WCAG AA).
+   · Aliases stay live var() chains — change the source, every
+     alias follows.
+   ════════════════════════════════════════════════════════════════ */
+
+:root {
+  /* ── Color ── */
+  --canvas: #F8FAFC;
+  --card: #FFFFFF;
+  --canvas-border: #E2E8F0;
+  --canvas-border-subtle: #F1F5F9;
+  --ink: #0F172A;
+  --ink-secondary: #475569;
+  --ink-muted: #94A3B8;
+  --ink-inverse: #F8FAFC;
+  --primary: #E07A5F;
+  --primary-strong: #C05539;
+  --primary-strong-hover: #AD4A30;
+  --primary-hover: #D16A4F;
+  --primary-light: #FDF2F0;
+  --primary-muted: rgba(224, 122, 95, 0.12);
+  --success: #22C55E;
+  --success-light: #F0FDF4;
+  --success-ink: #15803D;
+  --error: #EF4444;
+  --error-light: #FEF2F2;
+  --error-ink: #B91C1C;
+  --warning: #F59E0B;
+  --warning-light: #FFFBEB;
+  --warning-ink: #B45309;
+  --info: #3B82F6;
+  --info-light: #EFF6FF;
+  --info-ink: #1D4ED8;
+  --fruity: #B44C54;
+  --floral: #865CB2;
+  --nutty: #876F49;
+  --chocolate: #916951;
+  --spice: #B4503A;
+  --sweet: #8E6E09;
+  --citrus: #A65F02;
+  --green: #4E8429;
+  --berry: #AC4D7B;
+  --roasted: #896B5E;
+  --fruity-accessible: #9B494E;
+  --berry-accessible: #94496D;
+  --citrus-accessible: #925512;
+  --sweet-accessible: #7E6207;
+  --floral-accessible: #755498;
+  --green-accessible: #49742E;
+  --spice-accessible: #9B4C3A;
+  --nutty-accessible: #79623E;
+  --chocolate-accessible: #825C46;
+  --roasted-accessible: #7B5F52;
+  --on-flavor: #FFFFFF;
+  --xp: var(--sweet);
+  --xp-accessible: var(--sweet-accessible);
+  --ember: #F97316;
+  --ember-accessible: #C2410C;
+  --streak: var(--ember);
+  --streak-accessible: var(--ember-accessible);
+  --badge: var(--floral);
+  --badge-accessible: var(--floral-accessible);
+  --zone-ideal: var(--success);
+  --zone-under: var(--info);
+  --zone-over: var(--error);
+  --zone-strong: var(--warning);
+  --zone-weak: var(--ink-muted);
+  --chart-sca: var(--primary);
+  --chart-ucdavis: var(--floral);
+  --chart-grid: var(--canvas-border);
+
+  /* ── Typography ── */
+  --ff-sans: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+  --ff-serif: 'Instrument Serif', Georgia, serif;
+  --ff-mono: 'JetBrains Mono', ui-monospace, SFMono-Regular, monospace;
+  --text-screen-title: 32px;
+  --text-sheet-title: 24px;
+  --text-card-title: 20px;
+  --text-body: 16px;
+  --text-body-sm: 14px;
+  --text-caption: 12px;
+
+  /* ── Spacing ── */
+  --space-xs: 4px;
+  --space-sm: 8px;
+  --space-md: 12px;
+  --space-base: 16px;
+  --space-lg: 20px;
+  --space-xl: 24px;
+  --space-xxl: 32px;
+
+  /* ── Radii ── */
+  --radius-sm: 8px;
+  --radius-md: 12px;
+  --radius-lg: 16px;
+  --radius-xl: 24px;
+  --radius-full: 9999px;
+
+  /* ── Elevation ── */
+  --shadow-sm: 0 1px 2px rgba(15,23,42,0.04), 0 1px 1px rgba(15,23,42,0.03);
+  --shadow-md: 0 4px 12px rgba(15,23,42,0.06), 0 1px 3px rgba(15,23,42,0.04);
+  --shadow-lg: 0 12px 32px rgba(15,23,42,0.08), 0 4px 8px rgba(15,23,42,0.04);
+  --shadow-primary: 0 12px 28px rgba(224,122,95,0.28), 0 4px 10px rgba(224,122,95,0.18);
+
+  /* ── Motion & interaction ── */
+  --spring-response: 0.55s;
+  --spring-damping: 0.75;
+  --tap-scale: 0.95;
+  --tap-opacity: 0.8;
+  --stagger-delay: 0.08s;
+  --shimmer-duration: 1.5s;
+  --motion-reduced: 120ms;
+  --focus-ring: 0 0 0 2px var(--card), 0 0 0 4px var(--primary-strong);
+  --hit-target-min: 44px;
+
+  /* ── Materials ── */
+  --material-chrome-bg: color-mix(in srgb, var(--card) 95%, transparent);
+  --material-chrome-blur: saturate(1.4) blur(20px);
+  --scrim: rgba(15, 23, 42, 0.45);
+}
+
+/* Motion respects user preference: keep the state change, drop travel. */
+@media (prefers-reduced-motion: reduce) {
+  :root {
+    --spring-response: var(--motion-reduced);
+    --stagger-delay: 0s;
+  }
+}
+
+/* Transparency respects user preference: chrome collapses to opaque card. */
+@media (prefers-reduced-transparency: reduce) {
+  :root {
+    --material-chrome-bg: var(--card);
+    --material-chrome-blur: none;
+  }
+}