@putdotio/design 1.3.0 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@putdotio/design",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Public put.io design tokens, brand assets, and design-system guidance.",
   "license": "MIT",
   "type": "module",
@@ -66,11 +66,13 @@
     "dev": "node scripts/serve-system.ts",
     "tokens:build": "node scripts/build-tokens.ts",
     "tokens:check": "node scripts/check-generated-tokens.ts && node scripts/verify-design-system.ts",
+    "design:mirror": "node scripts/export-design-mirror.ts",
+    "test:mirror": "node --test tests/export-design-mirror.test.mjs",
     "typecheck:scripts": "tsc --noEmit --ignoreConfig --skipLibCheck --module ESNext --moduleResolution Bundler --target ES2022 --strict --types node scripts/*.ts playwright.config.ts tests/e2e/*.ts sst.config.ts infra/*.ts",
     "smoke": "node scripts/smoke-static.ts",
     "html:check": "html-validate \"system/**/*.html\"",
     "e2e": "playwright test",
-    "verify": "pnpm typecheck:scripts && pnpm tokens:check && pnpm html:check && pnpm smoke && sst version",
+    "verify": "pnpm typecheck:scripts && pnpm tokens:check && pnpm test:mirror && pnpm html:check && pnpm smoke && sst version",
     "verify:full": "pnpm verify && pnpm e2e && npm pack --dry-run",
     "check": "pnpm verify",
     "deploy:production": "sst deploy --stage production"
@@ -78,11 +80,11 @@
   "devDependencies": {
     "@axe-core/playwright": "^4.11.3",
     "@playwright/test": "^1.60.0",
-    "@types/node": "^25.9.1",
+    "@types/node": "^26.0.0",
     "html-validate": "^11.2.0",
     "sst": "^4.14.3",
     "style-dictionary": "^5.4.1",
-    "typescript": "^6.0.2",
+    "typescript": "^7.0.2",
     "yaml": "^2.9.0"
   },
   "packageManager": "pnpm@11.2.2"

package/system/README.md

@@ -18,8 +18,22 @@ project root/
 
 ## Fonts
 
-Preview pages load the public put.io font CSS from `static.put.io`: GT America,
-GT America Mono, and Berkeley Mono. Do not commit font files here.
+Preview pages load the public put.io font CSS from `static.put.io` (the same
+source as the product), so the design system always matches production. Do not
+commit font files here. Two families, so each HTML file links two stylesheets in
+`<head>`:
+
+```html
+<link rel="stylesheet" href="https://static.put.io/fonts/gt-america/standard/font.css">
+<link rel="stylesheet" href="https://static.put.io/fonts/berkeley-mono/variable/font.css">
+```
+
+GT America Mono is retired. `--font-ui-mono` no longer exists and everything mono
+reads `--font-mono` (Berkeley Mono), whose tabular figures carry the numerics the
+UI mono used to. Do not re-add the `gt-america/mono/font.css` load.
+
+Canonical weight mapping (matches the brand font host):
+`100 ultra-light · 200 thin · 300 light · 400 regular · 500 medium · 700 bold · 900 black`
 
 ## Using tokens
 
@@ -33,10 +47,17 @@ The canonical source is DTCG-compatible JSON in [`../tokens`](../tokens). This
 site stylesheet (`system/tokens.css`) and the package stylesheet
 (`dist/css/tokens.css`, exported as `@putdotio/design/css`) are generated from
 the same source. Guide and component CSS should consume custom properties rather
-than hard-coded palette values. Brand yellow is emitted as
-`var(--yellow-solid)`; its CSS token value is `hsl(44.7, 97.9%, 63.1%)`, the
-hsl form of canonical `#FDCE45`. Primary hover feedback uses
-`--yellow-solid-hover`, exposed to consumers as `--button-primary-bg-hover`.
+than hard-coded palette values. Brand yellow is `var(--yellow-solid)` —
+canonical `#FDCE45`; the emitted hsl form is pinned in
+[`../DESIGN.md`](../DESIGN.md) front-matter, and the `--yellow-solid-hover` →
+`--button-primary-bg-hover` derivation is specified in the repo's
+`docs/DISTRIBUTION.md`.
+
+Stacking and breakpoints are tokenized (`--z-*`, `--bp-*`) and the root
+font-size is responsive; the canonical values live in
+[`../DESIGN.md`](../DESIGN.md) (Layout & Spacing, Typography). Guide-specific
+rule: CSS media queries can't read custom properties, so write the literal px
+in `@media` and keep it in sync with the `--bp-*` token.
 
 Web package consumers import the package CSS export:
 
@@ -44,33 +65,113 @@ Web package consumers import the package CSS export:
 @import "@putdotio/design/css";
 ```
 
-For **TV preview cards**, also load `preview/tv-shell.css` — it adds the `.tv`, `.topnav`, `.scr`, glass tiers, and player chrome on top of the tokens. This is preview-only support CSS; platform repos implement TV components in their native UI stacks:
+For **TV preview cards**, also load `preview/tv-shell.css` — it adds the `.tv`,
+`.scr`, `.row`, solid surface tiers, and player chrome on top of the tokens.
+Every component selector is scoped under `.tv`, so the file is safe to bundle
+globally without bleeding into web components. This is preview-only support CSS;
+platform repos implement TV components in their native UI stacks:
 
 ```html
 <link rel="stylesheet" href="./tokens.css">
 <link rel="stylesheet" href="./preview/tv-shell.css">
 ```
 
+TV surfaces are **solid token colors** — no `backdrop-filter`, no translucent
+white fills. Focus is a fill: rows go transparent → `--component-bg-active`,
+buttons go `--component-bg` → `--component-bg-active` with the border stepping
+to `--border-hover`. There is no scale, shadow, halo, or white invert.
+
+The 10-foot scale itself is graph data, not CSS. The `tv` token group
+(`--tv-text-*`, `--tv-space-*`, `--tv-overscan-*`,
+`--tv-radius`, `--tv-z-*`) carries the 1:1 values for native emitters and is
+`mode: "tv"`, so it is deliberately **not** emitted into `tokens.css` — read it
+from `dist/tokens.flat.json`. Only `--radius-tv` (12px, the single radius for
+every TV surface) is global and reachable in CSS. Two things must not be folded
+into the web scales: TV has no mono face, and TV orders `--tv-z-overlay` (300)
+*above* `--tv-z-toast` (200), the opposite of the web `--z-*` stack.
+
 ## Core rules
 
-- **Yellow `#FDCE45` is the brand fill in both modes.** Use it for primary CTAs, folder icons, button/nav/TV focus rings (at 35% alpha), and progress bars. Use `--yellow-solid-hover` / `--button-primary-bg-hover` for CTA hover feedback, `--primary-foreground` for labels on yellow, and `--yellow-text-secondary` for yellow text on light backgrounds.
+- **Yellow `#FDCE45` is the brand constant at rest** — full rule and approved uses in [`../DESIGN.md`](../DESIGN.md) (Colors). Guide specifics: `--yellow-solid-hover` (`#F3C435`) is the hover peer with its own canonical hex in both modes, and focus rings use the yellow at 35% alpha (`--shadow-focus-color`).
+- **Yellow as text on light needs `--yellow-text-secondary`** (≈5:1, AA) — the brand `--yellow-solid` is fill-only on light backgrounds.
+- **Labels on yellow** use `--primary-foreground` (`hsl(38, 65%, 10%)` — warm dark, never pure black). Passes AA on the yellow fill without feeling "hard."
 - **Icons: Phosphor-style inline SVG.** No emoji, ever.
-- **One design, two modes.** Light and dark are the same markup and components with different token values. Toggle `.dark` on `<html>`; do not fork the page or rebuild a light-specific copy.
-- **Fields stay quiet.** Use `--field-bg`, `--field-border`, and `--field-ring` for text entry. Invalid fields use `aria-invalid="true"` with red border/text only, never a red fill.
-- **Panels are shared.** Use `--panel-bg`, `--panel-border`, `--panel-radius`, and `--panel-shadow` for raised cards and auth-style shells instead of screen-specific variables.
+- **One design, two modes.** Light and dark are the same markup and components with different token values. Toggle `.dark` on `<html>`; do not fork the page or rebuild a light-specific copy. Components must consume semantic tokens (`--bg`, `--text`, `--border`, `--accent`, …), not raw `#hex` or `hsl()`.
+- **Fields and panels use the shared aliases** (`--field-*`, `--panel-*`) — full rules, including the `aria-invalid` red-border-only requirement, in [`../DESIGN.md`](../DESIGN.md) (Components).
 - **Content-agnostic.** put.io doesn't know what the user's files are. Never parse `The.Wire.S03E04.1080p.mkv` into `The Wire`. Raw filenames only. See the root [`DESIGN.md`](../DESIGN.md) for the full principle.
 
 ## Theme System
 
-The guide owns the theme toggle. It stores `putio-ds-theme` in `localStorage`,
-updates `html.dark`, and broadcasts the current mode to embedded preview iframes.
-Standalone preview pages read the same storage key before paint. A URL query
-(`?theme=light` or `?theme=dark`) can override the preview mode for screenshots.
+The guide (`design-system.html`) owns the theme toggle. It writes
+`putio-ds-theme` to `localStorage`, updates `html.dark`, and broadcasts
+`{type:'__theme', theme}` to every embedded preview iframe via `postMessage`,
+so embeds flip live without reloading. Each preview's inline bootstrap reads
+the same storage key on standalone open, and `preview/_resize.js` listens for
+the parent broadcast when embedded. A URL query (`?theme=light` or
+`?theme=dark`) overrides both — useful for screenshots.
 
 Fixed-mode previews opt out with `<html data-theme-lock="dark">`. This is only
-for product mockups whose visual language is intrinsically one mode, such as TV
-and mobile shell specimens. Component previews should stay token-driven and work
-in both modes.
+for product mockups whose visual language is intrinsically one mode — a 10-foot
+screen and on-video player chrome are dark-only surfaces, so `tv-*.html`,
+`mobile-shell.html`, and `components-player-web.html` are locked. Locked previews ignore both `localStorage` and parent broadcasts.
+If you write a new component preview, you almost certainly don't want the
+lock — let the tokens do the work and your specimen will render correctly in
+both modes.
+
+## shadcn / Base UI interop
+
+The token layer ships a name-alias bridge so external component libraries that
+read canonical shadcn token names theme correctly without renaming. Drop in a
+shadcn/ui block, install a Base UI component, paste a Tailwind preset — they
+resolve against our values via the aliases. Always alias, never duplicate, so
+the two name systems can't drift.
+
+| shadcn name | put.io target |
+| --- | --- |
+| `--primary` / `--primary-foreground` | `--yellow-solid` / `var(--primary-foreground)` (warm dark) |
+| `--destructive` / `--destructive-foreground` | `--red-solid` / `var(--destructive-foreground)` (= `#fff`) |
+| `--success` / `--success-foreground` | `--green-solid` / `var(--success-foreground)` (= `#fff`) |
+| `--muted` / `--muted-foreground` | `--bg-secondary` / `--text-secondary` |
+| `--accent` / `--accent-foreground` | `--component-bg` / `--text` |
+| `--card` / `--card-foreground` | `--component-bg` / `--text` |
+| `--popover` / `--popover-foreground` | `--component-bg` / `--text` |
+| `--input` | `--border` |
+| `--ring` | `--shadow-focus-color` |
+| `--background` / `--foreground` | `--bg` / `--text` |
+
+There is also a full `--input-*` set (`-bg`, `-border`, `-border-hover`,
+`-border-focus`, `-ring`, `-text`, `-placeholder`, `-radius`) that aliases the
+`--field-*` tokens one-for-one, so shadcn-shaped input code themes without
+renaming. **Author against `--field-*`;** the `--input-*` names exist only as the
+alias bridge and must never carry their own value.
+
+The foreground tokens (`--primary-foreground`, `--destructive-foreground`,
+`--success-foreground`) encode the mode-safe inverse pair — always read these
+instead of writing literal `#000` / `#fff` on a solid surface.
+
+Use whichever name reads cleaner in context. Our own components prefer the long
+descriptive names (`--component-bg-hover`, `--yellow-text-secondary`) because
+they describe the role exactly. shadcn-imported code prefers the short names.
+
+### State via `data-state`, not class flags
+
+Base UI / headless primitives set
+`data-state="open|closed|checked|unchecked|active|completed|pending|loading"`
+on the DOM. Our components target those same attribute values in CSS — see the
+wizard step bar in `components-form-layouts.html`
+(`.step[data-state="completed"]`) and the menu/table cards. Prefer `data-state`
+over inventing class flags (`.is-active`, `.on`, `.current`) so the same DOM
+contract works whether the controlling code is React, Vue, vanilla JS, or
+hand-written HTML, and so devtools can read the component's state at a glance.
+
+### Compound parts via `data-slot`
+
+shadcn marks parts of compound components with `data-slot="card-header"`,
+`data-slot="card-title"`, etc. We do the same on the folder picker
+(`data-slot="modal" / "modal-header" / "modal-body" / "modal-footer"`) and the
+auth card in `components-form-layouts.html` (`data-slot="auth" / "auth-header"
+/ "auth-body"`). This lets external CSS tweak one part without inventing
+nested class chains.
 
 ## Design variants
 
@@ -85,4 +186,4 @@ Four documented type stacks — pick one per surface:
 
 ## Preview cards
 
-Open `system/design-system.html` for the full index. Each card renders a single concept against the actual tokens; treat it as the visual spec.
+Open `system/design-system.html` for the full index. Each card renders a single concept against the actual tokens — read it like a spec.