@putdotio/design 3.5.0 → 3.6.0

package/DESIGN.md

@@ -22,17 +22,17 @@ colors:
     danger: "hsl(358, 75%, 59%)"
 typography:
   ui:
-    family: "\"GT America\", sans-serif"
+    family: '"GT America", sans-serif'
     weight: 400
     size: "1rem"
     lineHeight: 1.45
   display:
-    family: "\"GT America\", sans-serif"
+    family: '"GT America", sans-serif'
     weight: 900
     size: "96px"
     lineHeight: 1.1
   mono:
-    family: "\"Berkeley Mono\", monospace"
+    family: '"Berkeley Mono", monospace'
     weight: 400
     size: "0.875rem"
     lineHeight: 1.45
@@ -62,131 +62,90 @@ components:
 
 ## Overview
 
-put.io is a content-agnostic cloud file product. The interface should feel premium because the file browser is useful, fast, quiet, and honest about the data it has. Design for raw filenames, folders, transfers, storage, playback controls, and settings without pretending that structured media metadata is always available.
-
-The canonical source for tokens is DTCG-compatible JSON in `tokens/`. Generated artifacts in `dist/` and `system/tokens.css` are outputs. This file explains how to use those tokens.
+put.io is a content-agnostic cloud file product. Its interface is a file browser: fast, quiet, and honest about the data it has. Design for raw filenames, folders, transfers, storage, playback, and settings; media metadata is usually absent.
 
 ## Binding Tiers
 
-A web-rendered mock is never a native spec. Every surface binds to the system at one of five tiers, and every specimen card in `system/preview/` declares its tier in a strip above the artboard (`system/preview/_tier.css`; if the wording here changes, change that file in the same PR).
+A web mock is never a native spec. Every surface binds at one tier, and every card in `system/preview/` names its tier in a strip worded by `system/preview/_tier.css`.
 
-- **Tier 0: Foundations.** The token graph. Binds every tier, values only, never a component recipe.
-- **Tier 1: www · app · auth.** The full design system: the component library and `system/components.css` recipes. The recipes are the contract here, and only here.
-- **Tier 2: iOS · iPadOS · tvOS · watchOS · Android · Android TV.** Tokens only. Every component, composition, and page comes from the platform's human interface guidelines; the cards document how a stock control receives put.io tokens, never how to rebuild one.
-- **Tier 3: Roku.** Tier-2 token inheritance, plus room for put.io conventions in custom SceneGraph components.
-- **Tier 4: tv.put.io · Tizen · webOS.** The design system as on web, restrained to a generic, calm, list-first 10-foot interface.
+- **Tier 0: Foundations.** The token graph. Values only; binds every tier.
+- **Tier 1: www · app · auth.** The full system: tokens plus the `system/components.css` recipes, which are the contract here only.
+- **Tier 2: iOS · iPadOS · tvOS · watchOS · Android · Android TV.** Tokens only. Components and pages come from the platform's guidelines; cards show how a stock control takes put.io tokens.
+- **Tier 3: Roku.** Tier 2, plus put.io conventions in custom SceneGraph components.
+- **Tier 4: tv.put.io · Tizen · webOS.** The web system, restrained to a calm, list-first 10-foot interface.
 
-A tier-1/3/4 card is a Component: put.io owns the recipe. A tier-2 card is an Element: the platform owns the control. Per-platform binding contracts live in `platforms/<platform>/DESIGN.md`. One rule holds on every tier: every file-type icon is brand yellow, Phosphor, never a text glyph.
+Tier 1, 3, and 4 cards are Components (put.io owns the recipe); tier 2 cards are Elements (the platform owns the control). Per-platform contracts: `platforms/<platform>/DESIGN.md`. On every tier, file-type icons are brand-yellow Phosphor icons.
 
 ## Colors
 
-Yellow `#FDCE45` is the resting `--yellow-solid` brand value in both light and dark modes. Use it for the put.io brand mark, primary action fill, folder/file emphasis, progress, and focus affordances. Use `--yellow-solid-hover` for primary button hover feedback; do not invent alternate yellows, gradient yellow into a different accent, or use yellow as foreground text on light surfaces.
-
-Dark app surfaces are the default product mode, but the token contract includes both dark and light palettes. Light surfaces are allowed for landing, docs, and narrow product states where readability is stronger. Semantic red, green, and neutral scales should come from tokens rather than one-off CSS values.
+- Yellow `#FDCE45` (`--yellow-solid`) is the brand value in both modes: brand mark, primary actions, folder and file emphasis, progress, focus. Hover is `--yellow-solid-hover`.
+- Every yellow is one of these tokens, flat. Yellow text on light surfaces is `--yellow-text-secondary`.
+- Dark is the default product mode; light serves landing pages, docs, and states that read better light.
+- Red, green, and neutral come from their token scales.
 
 ## Typography
 
-Use GT America for product UI and display. Berkeley Mono is the single mono face: numerics, timestamps, file sizes, ETAs, counts, code, logs, identifiers, hashes, magnet URIs, and filenames. Its tabular figures keep metadata columns aligned, so pair it with `font-variant-numeric: tabular-nums` wherever numbers sit in a column.
-
-The mono role is web and mobile only. TV surfaces have no mono face; 10-foot numerics render in GT America and should ask for its tabular figures wherever a number ticks or sits in a column. GT America Standard carries `tnum`, so any platform that can select OpenType features can honour this: web through `font-variant-numeric: tabular-nums`, React Native through the same font feature settings. Platforms that cannot select features get the default proportional figures, where `1` is 399/1000 em against `0` at 636, so a running timecode visibly reflows. Roku is the current example (its SceneGraph `Font` node accepts only a `uri` and a `size`), so budget 10-foot numeric layouts for proportional figures rather than assuming the columns line up.
-
-GT America is a Latin face: 523 codepoints covering Western and Central European Latin plus Turkish, with no Cyrillic, Greek, CJK, Arabic, Hebrew, Thai, or Hangul, and no dingbats: no `U+2713 ✓`, `U+2714`, `U+25B6 ▶`, or `U+2605 ★`. Two rules follow. Symbols are always icons, never text glyphs, because a checkmark typed as text renders as nothing. And because put.io shows raw filenames, user content routinely arrives outside that coverage: keep a fallback family behind GT America for any text that can hold a filename. Web gets this for free, since `"GT America", sans-serif` falls back per glyph, so the gap is invisible there and shows up on platforms that resolve one font per label with no per-glyph fallback, where uncovered characters become `.notdef` boxes. Treat a platform's fallback story for content text as part of adopting the face, not an afterthought.
-
-Body UI text should stay readable and dense. Use medium weight for labels and controls, bold weight only where the hierarchy earns it, and black weight for deliberate display moments.
-
-The root font-size is responsive like the product: 14px, stepping to 15px at the `--bp-lg` breakpoint. Body, labels, and inputs sit at `--fs-base` (1rem, equal to the root); captions and button labels sit at `--fs-sm` (0.875rem). The display tiers (`--fs-2xl`, `--fs-3xl`, `--fs-display`) are fixed pixel sizes and do not scale with the root.
+- GT America sets product UI and display. Labels and controls are medium, hierarchy is bold, display is black.
+- Berkeley Mono is the one mono face: numerics, timestamps, sizes, ETAs, counts, code, logs, identifiers, hashes, magnet URIs, filenames. Columns of numbers add `font-variant-numeric: tabular-nums`.
+- TV product UI has no mono face (a debug overlay may use the platform's system monospace): 10-foot numerics use GT America `tnum`. Platforms without OpenType feature selection (Roku: `Font` takes only `uri` and `size`) get proportional figures, so budget timecodes for reflow (`1` is 399/1000 em, `0` is 636).
+- GT America is Latin only (523 codepoints, Western and Central European plus Turkish, no dingbats such as `✓` `▶` `★`). Symbols are icons. Text that can hold a filename keeps a fallback family; web falls back per glyph, while one-font-per-label platforms must ship a fallback or render `.notdef` boxes.
+- Root font-size is 14px, 15px from `--bp-lg`. Body, labels, inputs: `--fs-base`. Captions, button labels: `--fs-sm`. `--fs-2xl`, `--fs-3xl`, `--fs-display` are fixed pixels.
 
 ## Layout & Spacing
 
-put.io layouts are file-browser layouts first: lists, rows, columns, sidebars, toolbars, and sheets. Prefer whitespace and subtle dividers before card-heavy composition.
-
-The spacing scale is intentionally steep: `4, 8, 16, 32, 64, 128, 256, 512`. Use it consistently rather than tuning one-off gaps.
-
-Stacking uses the token scale, gapped for platform chrome: `--z-dropdown` (1000), `--z-sticky` (1100), `--z-modal` (1300), `--z-notification` (1400), `--z-tooltip` (1500). Never invent z-index numbers. Breakpoints (`--bp-sm`/`--bp-md`/`--bp-lg` = 640/768/1280px) mirror the product's responsive tiers; CSS media queries cannot read custom properties, so write the literal pixels in `@media` and keep them in sync with the tokens.
+- Layouts are file-browser layouts: lists, rows, columns, sidebars, toolbars, sheets. Whitespace and dividers come before cards.
+- Spacing steps: `4, 8, 16, 32, 64, 128, 256, 512`. Every gap is one of them.
+- z-index: `--z-dropdown` 1000, `--z-sticky` 1100, `--z-modal` 1300, `--z-notification` 1400, `--z-tooltip` 1500.
+- Breakpoints `--bp-sm`/`--bp-md`/`--bp-lg` are 640/768/1280px; `@media` takes the literal pixels.
 
 ## Elevation & Depth
 
-Elevation should clarify interaction, not decorate. Use borders and soft shadows for popovers, modals, menus, TV focus, and draggable/drop targets. Avoid decorative glow except where it is part of a focused TV state.
+Borders and soft shadows mark interaction: popovers, modals, menus, TV focus, drag and drop targets. Glow belongs only to focused TV states.
 
 ## Shapes
 
-The default radius is `6px`. Use `4px` for tight controls, `8px` or `10px` for larger panels, and pill radius for segmented controls and badges.
-
-TV is the exception: every 10-foot surface (list rows, buttons, sheets, cards, code tiles, keys) uses the single `--radius-tv` (`12px`). TV has one radius, not a scale; the only other radii on a TV surface are intentional pills and circles.
+Default radius `6px`; `4px` for tight controls, `8px` or `10px` for panels, pill for segmented controls and badges. TV uses one radius, `--radius-tv` (`12px`), plus intentional pills and circles.
 
 ## Components
 
-The component recipes below and in `system/components.css` are the
-**web binding** of the token graph, and they bind the web surfaces in full.
-Other tiers inherit as [Binding Tiers](#binding-tiers) describes; every TV
-surface, native ones within their platform conventions, treats the web TV
-list-first look as the shared family look.
-
-Buttons have three tiers on one axis: emphasis. **Primary** is the brand fill: `--button-primary-bg` at rest, `--button-primary-bg-hover` on hover so the CTA never feels inert, label `--button-primary-fg`. Yellow is reserved for primary commands, and an action group carries at most one. **Secondary** is a quiet fill: `--button-default-bg` (aliased as `--button-secondary-bg`) plus a border at `--border`, with hover stepping both (`--button-default-bg-hover`, `--border-hover`). Because it fills, it reads to a hard edge exactly like the primary, so the two compare safely side by side. **Ghost** is text only: no fill, no border. `--button-ghost-fg` at rest; hover paints `--button-ghost-bg-hover` behind the label and lifts it to `--button-ghost-fg-hover`. The label lift is mandatory: the faint fill is never the only hover cue. Disabled drops the colour to `--solid` at full opacity rather than fading the box. Use ghost for anything quieter than a filled secondary: a header `Sign in`, toolbar text actions, `Cancel` beside a filled confirm. An icon-only ghost is the quiet icon button, on the same tokens.
-
-Outline is not a tier. The system ships no transparent-background bordered button, and consumers must not hand-roll one. The pairing rule behind that: never place a border-only button in the same action group as a solid fill. At identical box heights the outlined shape reads smaller, because a solid resolves to a hard edge while a low-contrast hairline resolves to a soft one, and the eye compares the two extents differently. It is worst on dark surfaces, where a 15%-white hairline is barely visible at all. If a bordered treatment must sit near a fill, it must itself fill (the secondary tier) and carry its border at `--border`-step contrast, never a sub-20% hairline on transparent.
-
-Button geometry is tokenized so every tier and variant of a given size shares an identical box; tiers change colour only, which makes cross-variant comparison safe by construction. There are four sizes and no others. The default is `36px` tall with `12px` of horizontal padding, an `--fs-sm` uppercase label and `1px` of tracking; `md` is `32px` at `0.8px` tracking, `sm` is `28px` at `0.6px`, and `xs` is `24px` with `8px` padding, an `--fs-xs` label and `0.3px` tracking. Read them from `--button-height` (`-md`, `-sm`, `-xs`), `--button-padding-x` (`-xs`), `--button-label-size` (`-xs`), `--button-tracking` (`-md`, `-sm`, `-xs`), `--button-icon-size` and `--button-gap` rather than restating the numbers. Every button token aliases the neutral scale, which carries both modes, so a dark bar on a light page is a `.dark`-scoped region and never hand-picked dark literals. The sticky site top bar is `--nav-height` (`56px`), or `--nav-height-compact` (`52px`) on narrow viewports, and its CTA is the `md` box via `--nav-cta-height`.
-
-TV needs no carve-out here: TV buttons keep the `tv` scale box and `--radius-tv`, and TV focus restores a visible box (`--component-bg-active` plus a border step), so the ghost tier stays legible in the 10-foot focus model.
-
-File rows are the core component: preserve raw names, keep metadata compact, and make hover/focus states obvious without inflating row height.
-
-Form fields use the shared `--field-*` aliases: `--field-bg` for the fill, `--field-border` for the resting border, and `--field-ring` for focus. Invalid fields opt in with `aria-invalid="true"` and use red border/text only; do not add red fill. Raised panels use the shared `--panel-*` aliases instead of auth- or screen-specific panel variables.
-
-Browser Auth composition is fluid up to a `340px` column. It uses the standard
-`36px` field recipe, a `30.33px` wordmark box (the `26px` ink height multiplied
-by its `7/6` view-box ratio), and centered headings at `19px` / weight
-`500`. The prompt and its action form a centered two-line footer. User-facing
-actions say “Sign in” and “Sign up”, and an invalid credential response uses
-“That username or password doesn't look right” with no terminal punctuation.
-The shipped
-`web-s06-auth` screen plus `web-p00c-auth-signin`, `web-p00d-auth-signup`, and
-`web-p00e-auth-2fa` are the Tier-1 composition references for this contract.
-
-Form feedback uses the exported `.form-callout` recipe. Its block form reads
-the `--alert-*` families and selects `info`, `success`, or `error` with
-`data-state`; `.inline` removes the surface and border while keeping the same
-semantic text colour. Callouts remain messages, not containers for unrelated
-form layout. Their parent uses `.form-group`, whose `6px` gap owns the spacing
-between a control and its inline feedback.
+`system/components.css` is the web binding and binds web surfaces in full. Every TV surface shares the web TV list-first look; native ones within their platform conventions.
 
-One-time passwords use one semantic `.otp-input`, never six independent
-inputs. Place it with two three-slot `.otp-group` elements, one
-`.otp-separator`, and six visual `.otp-slot` elements. The input carries
-`inputmode="numeric"`, `autocomplete="one-time-code"`, `maxlength="6"`, and
-`aria-invalid`; script synchronizes slot text plus `filled` / `active` state.
-Pointer interaction maps the clicked visual slot to the backing input's
-selection; do not rely on the transparent input's native glyph hit testing.
-Editing an invalid code clears its stale error and disables retry until all six
-digits are present. Retrying enters the same locked verifying state as the
-default form.
-The root uses `data-state="verifying"` while submission is in flight and keeps
-the entered digits visible; the backing input is disabled for the same period,
-and the action label announces the transition through a polite live region.
-Successful verification uses `data-state="success"`, retains the six digits in
-a read-only input, announces automatic continuation with a `role="status"`
-callout, and does not leave another action on screen. The consumer owns the
-backend transition and navigation timing.
-The reference omits recovery-code entry until its consumer owns a working
-route. Do not expose a specimen-only recovery action.
-Groups, not slots, own the responsive width, so the complete control contracts
-to narrow Auth cards without horizontal scrolling.
+### Buttons
 
-TV components are list-first and focus-first. A TV app is still a file browser, not a poster wall. Roku, native Apple, Android, and web TV repos should consume the generic tokens and generate their own platform bindings.
+- **Primary:** `--button-primary-bg`, hover `--button-primary-bg-hover`, label `--button-primary-fg`. At most one per action group.
+- **Secondary:** `--button-default-bg` plus a `--border` border; hover steps both (`--button-default-bg-hover`, `--border-hover`).
+- **Ghost:** text only, `--button-ghost-fg`; hover adds `--button-ghost-bg-hover` and lifts the label to `--button-ghost-fg-hover`. Use it for anything quieter than secondary: header `Sign in`, toolbar actions, `Cancel` beside a confirm, icon-only buttons.
+- **Disabled:** colour drops to `--solid` at full opacity.
+- A bordered button always fills (secondary). Border-only buttons read smaller beside solid fills and vanish on dark.
+- Four sizes share one box per size across tiers: default 36px, `md` 32px, `sm` 28px, `xs` 24px. Read `--button-height*`, `--button-padding-x*`, `--button-label-size*`, `--button-tracking*`, `--button-icon-size`, `--button-gap`.
+- A dark bar on a light page is a `.dark`-scoped region.
+- The sticky top bar is `--nav-height` (`--nav-height-compact` on narrow viewports); its CTA is `md` via `--nav-cta-height`.
+- TV buttons use the `tv` scale and `--radius-tv`; focus restores a visible box.
 
-TV surfaces are solid token colors: no translucent materials and no blur. Focus is expressed as a fill, never a lift: rows go transparent to `--component-bg-active`, and web TV buttons step both their fill and their border at one fixed edge width. The `tv.focus` group carries every value: `tv.focus.row.*` for the row fill that web TV and Roku share, `tv.focus.control.*` for the web TV fill and border step, and `tv.focus.borderWidth` (`3px`) for the edge. Roku dialog buttons are borderless and follow their primary, secondary, or danger variant instead. Navigation is a Home hub that pushes full screens onto a stack; there is no tab bar. Menus are centred modals, not popovers anchored to a trigger. These focus and material rules bind the web TV and Roku surfaces; a native TV binding follows its platform's own control conventions where the platform owns focus. Apple tvOS buttons use the system focus treatment (adopted 2026-08) while non-control TV surfaces stay solid everywhere.
+### Rows, fields, and panels
 
-The 10-foot scale (type steps, spacing ramp, overscan ratios, radius, focus, and z-indices) lives in the `tv` token group, carried as data for platform adapters rather than emitted into web CSS. Overscan ratios declare their viewport axis: multiply `tv.overscan.x` by viewport width and `tv.overscan.y` by viewport height, then compose screen padding locally with the spacing tokens. Two rules do not cross over: TV has no mono face, and TV stacks `tv.z.overlay` above `tv.z.toast`, the reverse of the web `--z-*` order. Emit the two scales separately. Cite the `tv` group by its graph path, never as `--tv-*`: those names are read from the DTCG artifacts by platform adapters and are deliberately absent from `dist/css/tokens.css`, so CSS-variable syntax would promise a `var()` that resolves to nothing.
+- File rows are the core component: raw names, compact metadata, obvious hover and focus at the same row height.
+- Fields read `--field-bg`, `--field-border`, and `--field-ring` (focus). `aria-invalid="true"` turns border and text red; the fill stays.
+- Raised panels read `--panel-*`.
+- Feedback uses `.form-callout`: `--alert-*` colours, `data-state` `info`, `success`, or `error`; `.inline` drops surface and border. It holds a message only. `.form-group` (`6px` gap) spaces a control and its feedback.
 
-## Do's and Don'ts
+### Auth
 
-Do show raw filenames such as `The.Wire.S03E04.Back.Burners.1080p.BluRay.x264-DEMAND.mkv`.
+- A fluid column up to `340px`, the `36px` field recipe, a `30.33px` wordmark box (26px ink × 7/6), centred `19px`/500 headings, and a centred two-line prompt footer.
+- Copy: “Sign in”, “Sign up”, and “That username or password doesn't look right” with no terminal punctuation.
+- References: `web-s06-auth`, `web-p00c-auth-signin`, `web-p00d-auth-signup`, `web-p00e-auth-2fa`.
+- One-time codes are one `.otp-input` (`inputmode="numeric"`, `autocomplete="one-time-code"`, `maxlength="6"`, `aria-invalid`) shown through two `.otp-group`s, one `.otp-separator`, and six `.otp-slot`s; script syncs slot text and `filled`/`active`, and maps a clicked slot to the input selection.
+- Editing an invalid code clears the error; retry waits for six digits. `data-state="verifying"` disables the input, keeps the digits, and announces through a polite live region. `data-state="success"` keeps the digits read-only, announces continuation in a `role="status"` callout, and shows no further action; the consumer owns navigation.
+- No recovery-code action until a consumer owns the route. Groups own the responsive width, so the control fits narrow cards without scrolling.
 
-Do use Phosphor-style inline SVG for forward-looking icon guidance and no emoji in product UI.
+### TV
 
-Do keep `DESIGN.md`, `tokens/`, `dist/`, and `system/tokens.css` in agreement.
+- TV is list-first and focus-first: a file browser, not a poster wall. TV repos consume the generic tokens and own their bindings.
+- Surfaces are solid token colours, no blur or translucency. Focus is a fill: rows go to `--component-bg-active`; web TV buttons step fill and border at `tv.focus.borderWidth` (`3px`). Values live in `tv.focus.row.*` and `tv.focus.control.*`. Roku dialog buttons are borderless and follow their variant.
+- Navigation is a Home hub pushing full screens; no tab bar. Menus are centred modals.
+- These rules bind web TV and Roku. Native TV follows its platform where the platform owns focus; tvOS buttons use system focus, other surfaces stay solid.
+- The `tv` token group (type, spacing, overscan, radius, focus, z) is adapter data, absent from web CSS: cite it by graph path, never `--tv-*`. Overscan multiplies `tv.overscan.x` by width and `tv.overscan.y` by height. `tv.z.overlay` sits above `tv.z.toast`, the reverse of web.
 
-Don't publish private material in this public repo; the enumerated list lives in the repo's `docs/DISTRIBUTION.md` (Public Safety).
+## Content and Icons
 
-Don't generate platform-native outputs (Swift, Kotlin, Android XML, Roku) from this repo; platform repos own their adapters. Policy in the repo's `docs/DISTRIBUTION.md`.
+Show filenames exactly as stored, such as `The.Wire.S03E04.Back.Burners.1080p.BluRay.x264-DEMAND.mkv`. Icons are Phosphor-style inline SVG; product UI carries no emoji.

package/README.md

@@ -18,20 +18,12 @@
 
 Live guide: [design.put.io](https://design.put.io)
 
-This repo owns the public contract behind it: DTCG token sources, generated
-CSS/JSON/TypeScript artifacts, brand assets, preview cards, and deployable
-static guidance.
-
 ## Install
 
 ```bash
 npm install @putdotio/design
 ```
 
-Token sources live in [`tokens`](tokens), generated artifacts in
-[`dist`](dist), and package-safe brand assets in
-[`system/assets`](system/assets).
-
 ## Use
 
 Import the generated tokens first. Tier-1 web surfaces also import the
@@ -47,22 +39,22 @@ Component recipes consume semantic aliases such as `--field-*`, `--panel-*`,
 
 Package entrypoints, from `exports` in [package.json](package.json):
 
-| Subpath | File |
-| --- | --- |
-| `@putdotio/design/css` | [`dist/css/tokens.css`](dist/css/tokens.css) |
-| `@putdotio/design/components` | [`system/components.css`](system/components.css) |
-| `@putdotio/design/tokens` | [`dist/tokens.flat.json`](dist/tokens.flat.json) |
-| `@putdotio/design/tokens/meta` | [`dist/tokens.js`](dist/tokens.js), typed by [`dist/tokens.d.ts`](dist/tokens.d.ts) |
-| `@putdotio/design/tokens/dtcg` | [`dist/tokens.dtcg.json`](dist/tokens.dtcg.json) |
-| `@putdotio/design/tokens/figma` | [`dist/figma/putio.tokens.json`](dist/figma/putio.tokens.json) |
-| `@putdotio/design/assets/<file>` | [`system/assets`](system/assets) |
-| `@putdotio/design/design.md` | [`DESIGN.md`](DESIGN.md) |
+| Subpath                          | File                                                                                |
+| -------------------------------- | ----------------------------------------------------------------------------------- |
+| `@putdotio/design/css`           | [`dist/css/tokens.css`](dist/css/tokens.css)                                        |
+| `@putdotio/design/components`    | [`system/components.css`](system/components.css)                                    |
+| `@putdotio/design/tokens`        | [`dist/tokens.flat.json`](dist/tokens.flat.json)                                    |
+| `@putdotio/design/tokens/meta`   | [`dist/tokens.js`](dist/tokens.js), typed by [`dist/tokens.d.ts`](dist/tokens.d.ts) |
+| `@putdotio/design/tokens/dtcg`   | [`dist/tokens.dtcg.json`](dist/tokens.dtcg.json)                                    |
+| `@putdotio/design/tokens/figma`  | [`dist/figma/putio.tokens.json`](dist/figma/putio.tokens.json)                      |
+| `@putdotio/design/assets/<file>` | [`system/assets`](system/assets)                                                    |
+| `@putdotio/design/design.md`     | [`DESIGN.md`](DESIGN.md)                                                            |
 
 ## Docs
 
 - [Design contract](DESIGN.md)
 - [Design guide structure](system/README.md)
-- [Distribution](docs/DISTRIBUTION.md)
+- [Distribution](docs/distribution.md)
 - [Contributing](CONTRIBUTING.md)
 - [Security](https://github.com/putdotio/.github/blob/main/SECURITY.md)
 - [Agent guide](AGENTS.md)

package/dist/figma/putio.tokens.json

@@ -878,7 +878,7 @@
       "mono": {
         "$type": "fontFamily",
         "$value": "\"Berkeley Mono\", monospace",
-        "$description": "The single mono face: numerics, timestamps, file sizes, ETAs, counts, code, logs, magnet URIs, identifiers, and filenames. Web and mobile only — TV has no mono face."
+        "$description": "The single mono face: numerics, timestamps, file sizes, ETAs, counts, code, logs, magnet URIs, identifiers, and filenames. Web and mobile only. TV product UI has no mono face; a TV debug overlay may use the platform's system monospace."
       }
     },
     "fontSize": {

package/dist/tokens.dtcg.json

@@ -4749,7 +4749,7 @@
       "mono": {
         "$type": "fontFamily",
         "$value": "\"Berkeley Mono\", monospace",
-        "$description": "The single mono face: numerics, timestamps, file sizes, ETAs, counts, code, logs, magnet URIs, identifiers, and filenames. Web and mobile only — TV has no mono face.",
+        "$description": "The single mono face: numerics, timestamps, file sizes, ETAs, counts, code, logs, magnet URIs, identifiers, and filenames. Web and mobile only. TV product UI has no mono face; a TV debug overlay may use the platform's system monospace.",
         "$extensions": {
           "putio": {
             "cssName": "font-mono",

package/dist/tokens.flat.json

@@ -3225,7 +3225,7 @@
     "mode": "global",
     "value": "\"Berkeley Mono\", monospace",
     "originalValue": "\"Berkeley Mono\", monospace",
-    "description": "The single mono face: numerics, timestamps, file sizes, ETAs, counts, code, logs, magnet URIs, identifiers, and filenames. Web and mobile only — TV has no mono face."
+    "description": "The single mono face: numerics, timestamps, file sizes, ETAs, counts, code, logs, magnet URIs, identifiers, and filenames. Web and mobile only. TV product UI has no mono face; a TV debug overlay may use the platform's system monospace."
   },
   "typography.fontSize.xs": {
     "cssName": "--fs-xs",

package/dist/tokens.js

@@ -3227,7 +3227,7 @@ export const tokens = {
     "mode": "global",
     "value": "\"Berkeley Mono\", monospace",
     "originalValue": "\"Berkeley Mono\", monospace",
-    "description": "The single mono face: numerics, timestamps, file sizes, ETAs, counts, code, logs, magnet URIs, identifiers, and filenames. Web and mobile only — TV has no mono face."
+    "description": "The single mono face: numerics, timestamps, file sizes, ETAs, counts, code, logs, magnet URIs, identifiers, and filenames. Web and mobile only. TV product UI has no mono face; a TV debug overlay may use the platform's system monospace."
   },
   "typography.fontSize.xs": {
     "cssName": "--fs-xs",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@putdotio/design",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "description": "Public put.io design tokens, brand assets, and design-system guidance.",
   "license": "MIT",
   "type": "module",
@@ -68,24 +68,28 @@
     "dev": "node scripts/serve-system.ts",
     "tokens:build": "node scripts/build-tokens.ts",
     "tokens:check": "node scripts/build-tokens.ts && node scripts/check-component-css.ts && node scripts/verify-design-system.ts",
+    "artifact": "node scripts/build-artifact.ts && node scripts/build-canvases.ts",
     "test:config": "node --test tests/playwright-config.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",
     "html:check": "html-validate \"system/**/*.html\"",
+    "markdown:check": "oxfmt --check \"**/*.md\"",
     "e2e": "playwright test",
-    "verify": "pnpm typecheck:scripts && pnpm tokens:check && pnpm html:check",
+    "verify": "pnpm typecheck:scripts && pnpm tokens:check && pnpm artifact && pnpm html:check && pnpm markdown:check",
     "verify:full": "pnpm verify && pnpm test:config && pnpm e2e && npm pack --dry-run",
     "check": "pnpm verify",
     "deploy:production": "sst deploy --stage production"
   },
   "devDependencies": {
     "@axe-core/playwright": "^4.11.3",
+    "@phosphor-icons/web": "2.1.1",
     "@playwright/test": "^1.60.0",
     "@types/node": "^26.0.0",
     "html-validate": "^11.2.0",
+    "oxfmt": "0.73.0",
     "sst": "^4.14.3",
     "style-dictionary": "^5.4.1",
     "typescript": "^7.0.2",
     "yaml": "^2.9.0"
   },
-  "packageManager": "pnpm@12.4.2"
+  "packageManager": "pnpm@12.13.0"
 }

package/system/README.md

@@ -1,13 +1,15 @@
 # put.io design system
 
-This folder holds the generated site tokens, preview cards, and design-system index.
+The guide site: generated site tokens, component CSS, preview cards, and the
+design-system index.
 
 ## Layout
 
 - `index.html` redirects to `design-system.html`, the guide and preview-card
-  index. `design-system-light.html` is a legacy redirect to
+  index. `design-system-light.html` redirects to
   `design-system.html?theme=light`.
-- `tokens.css` is generated from `../tokens/**/*.tokens.json`; do not edit it.
+- `tokens.css` is generated from `../tokens/**/*.tokens.json`; edit the token
+  sources and rebuild.
 - `components.css` is the Tier-1 component layer (the web contract).
 - `tv.css` is the TV / 10-foot component CSS, scoped to `.tv` artboards.
 - `assets/` holds logos, favicons, retro marks, and app icons.
@@ -24,87 +26,84 @@ states, a spec strip, a don't block.
 ## Fonts
 
 Preview pages load the public put.io font CSS from `static.put.io`, the same
-source as the product. Do not commit font files here. Each HTML file links both
-families in `<head>`:
+source as the product; font licensing is in
+[Distribution](../docs/distribution.md#fonts-and-assets). Each preview links
+both families 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">
+<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: all mono text reads `--font-mono` (Berkeley Mono),
-whose tabular figures carry the numerics. Do not re-add the
-`gt-america/mono/font.css` load.
+Those two links are the full font set: mono text reads `--font-mono` (Berkeley
+Mono), whose tabular figures carry the numerics.
 
-Canonical weight mapping (matches the brand font host):
-`100 ultra-light · 200 thin · 300 light · 400 regular · 500 medium · 700 bold · 900 black`
+Weight names on the font host:
+`100 ultra-light · 200 thin · 300 light · 400 regular · 500 medium · 700 bold · 900 black`.
+The tokens use four of them through `--fw-regular`, `--fw-medium`, `--fw-bold`,
+and `--fw-black`.
 
 ## Using tokens
 
-For the static guide, pages in `system/` load the generated site stylesheet:
+Guide pages in `system/` load the generated site stylesheet:
 
 ```html
-<link rel="stylesheet" href="./tokens.css">
+<link rel="stylesheet" href="./tokens.css" />
 ```
 
 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 `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.
+the same source. Brand yellow is `var(--yellow-solid)`; its emitted hsl form is
+pinned in the [`../DESIGN.md`](../DESIGN.md) frontmatter, and the
+`--button-primary-bg-hover` derivation is in
+[Distribution](../docs/distribution.md#generated-files).
+
+Stacking, breakpoints, the root font-size, and the `@media` literal rule live
+in [Layout & Spacing](../DESIGN.md#layout--spacing) and
+[Typography](../DESIGN.md#typography).
 
 Package consumers import as in the [README](../README.md#use).
 
 For **TV preview cards**, also load `tv.css`, which adds the `.tv`, `.scr`,
 `.row`, solid surface tiers, and player chrome on top of the tokens, authored
 1:1 at 1920×1080 (a px in the file is a px on the TV). Every component selector
-is scoped under `.tv`, so the file is safe to bundle globally without bleeding
-into web components. Platform repos still implement TV components in their
-native UI stacks:
+is scoped under `.tv`, so the file can be bundled globally alongside web
+components. Platform repos implement TV components in their native UI stacks:
 
 ```html
-<link rel="stylesheet" href="./tokens.css">
-<link rel="stylesheet" href="./tv.css">
+<link rel="stylesheet" href="./tokens.css" /> <link rel="stylesheet" href="./tv.css" />
 ```
 
 TV material, focus, and the `tv` token group rules live in
-[`../DESIGN.md`](../DESIGN.md) (Components). Guide specifics: the `tv` group is
-`mode: "tv"` and read from `dist/tokens.flat.json`; only `--radius-tv` is
-global and reachable in CSS.
+[Components](../DESIGN.md#components). Guide specifics: the `tv` group is
+`mode: "tv"` and read from `dist/tokens.flat.json`; `--radius-tv` is the one
+`tv` value the token CSS emits, so `tv.css` declares the `--tv-*` properties
+its cards use itself.
 
 ## Core rules
 
-- **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%)`, a 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. 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, are in [`../DESIGN.md`](../DESIGN.md) (Components).
-- **Wordmarks are optically pre-centred.** All three logo SVGs carry built-in top padding in the viewBox (retro pair `0 -16 376 112`, `logo.svg` `0 -24.44 621.79 176.055`). Flex-centre as-is; never add a `translateY` nudge. Height-set placements size boxes at 7/6 of the ink height.
-- **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.
+- **Yellow** follows [Colors](../DESIGN.md#colors). Guide specifics: `--yellow-solid-hover` is the hover peer with one value in both modes, and button focus-visible rings use `--shadow-focus` (the yellow at 35% alpha, `--shadow-focus-color`). Form fields focus with the neutral `--field-ring` instead.
+- **Yellow as text on light** uses `--yellow-text-secondary` (≈5:1, AA); `--yellow-solid` is fill-only on light backgrounds.
+- **Labels on yellow** use `--primary-foreground`, a warm dark that passes AA on the yellow fill.
+- **One design, two modes.** Light and dark are the same markup and components with different token values. Toggle `.dark` on `<html>`; one page serves both modes. Components consume semantic tokens (`--bg`, `--text`, `--border`, `--accent`, …) instead of raw `#hex` or `hsl()`.
+- **Wordmarks are optically pre-centred.** All three logo SVGs carry built-in top padding in the viewBox (retro pair `0 -16 376 112`, `logo.svg` `0 -24.44 621.79 176.055`). Flex-centre them as-is, with no `translateY` nudge. Height-set placements size boxes at 7/6 of the ink height.
+
+Icons, fields and panels, and raw filenames follow the root
+[Components](../DESIGN.md#components) and
+[Content and Icons](../DESIGN.md#content-and-icons).
 
 ## Binding tiers
 
 Tier definitions, the Component/Element distinction, and the `preview/_tier.css`
-pairing rule live in [`../DESIGN.md`](../DESIGN.md) (Binding Tiers). Never read
-an Element card as a build-a-custom-control instruction.
+pairing rule live in [Binding Tiers](../DESIGN.md#binding-tiers). An Element
+card shows how a stock control receives tokens.
 
 Native cards are drawn 1:1 in their own unit (iPhone 393×852pt, iPad
 1024×768pt, Apple Watch 176×215pt, Android 412×915dp, TV 1920×1080px), so a
 number written on a card is the number in the HIG or the Material spec. Those
-metrics are Apple's and Google's; they are **not** put.io spacing tokens and
-must never be promoted into the graph. Device bezels and on-video chrome stay
-deliberately un-tokenised.
+metrics are Apple's and Google's and stay out of the put.io token graph. Device
+bezels and on-video chrome stay untokenised.
 
 ## Theme System
 
@@ -114,47 +113,46 @@ The guide (`design-system.html`) owns the theme toggle. It writes
 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, which is useful for screenshots.
+`?theme=dark`) overrides both, 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. A 10-foot
+Fixed-mode previews opt out with `<html data-theme-lock="dark">`, reserved for
+product mockups whose visual language is intrinsically one mode. A 10-foot
 screen, a native app mockup, and on-video player chrome are fixed-mode
 surfaces, so the `ios-*`, `android-*`, `androidtv-*`, `tvos-*`, `watchos-*`,
-`roku-*`, and `tv-*` cards plus `web-p06-player.html` are locked. Locked
-previews ignore both `localStorage` and parent broadcasts.
-New component previews should not use the lock; the tokens render them
-correctly in both modes.
+`roku-*`, `tv-*`, and `mobile-*` cards plus `web-p06-player.html` are locked.
+Locked previews ignore `localStorage`, parent broadcasts, and the URL query.
+New component previews stay unlocked, so the tokens render them in both modes.
 
 ## shadcn / Base UI interop
 
 The token layer aliases the canonical shadcn token names, so shadcn/ui blocks,
 Base UI components, and Tailwind presets resolve against put.io values without
-renaming. Always alias, never duplicate, so the two name systems cannot drift.
+renaming. Each shadcn name aliases a put.io token and carries no value of its
+own, so the two name systems cannot drift.
 
-| shadcn name | put.io target |
-| --- | --- |
-| `--primary` / `--primary-foreground` | `--yellow-solid` / `var(--primary-foreground)` (warm dark) |
+| 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.
-
-put.io components prefer the long descriptive names (`--component-bg-hover`,
+| `--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`                                          |
+
+A full `--input-*` set (`-bg`, `-border`, `-border-hover`, `-border-focus`,
+`-ring`, `-text`, `-placeholder`, `-radius`) aliases the matching `--field-*`
+tokens, so shadcn-shaped input code themes without renaming. **Author against
+`--field-*`;** the `--input-*` names are only the alias bridge.
+
+On a solid surface, read the foreground tokens (`--primary-foreground`,
+`--destructive-foreground`, `--success-foreground`), which encode the mode-safe
+inverse pair, instead of writing literal `#000` / `#fff`.
+
+put.io components use the long descriptive names (`--component-bg-hover`,
 `--yellow-text-secondary`) because they name the role exactly; shadcn-imported
 code keeps the short names.
 
@@ -162,31 +160,32 @@ code keeps the short names.
 
 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 `web-p00b-form-flows.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 with any controlling code and devtools show the state directly.
+on the DOM. put.io components target those same attribute values in CSS; see
+the wizard step bar in `web-p00b-form-flows.html`
+(`.step[data-state="completed"]`) and the menu/table cards. Express state with
+`data-state` rather than class flags (`.is-active`, `.on`, `.current`), so the
+same DOM contract works with any controlling code and devtools show the state
+directly.
 
 ### 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="card-title"`, and so on. put.io does the same on the folder picker
 (`data-slot="modal" / "modal-header" / "modal-body" / "modal-footer"`) and the
 auth cards in `web-p00c-auth-signin.html` and `web-p00d-auth-signup.html`
-(`data-slot="auth" / "auth-header" / "auth-body"`). This lets external CSS tweak one part without inventing
-nested class chains.
+(`data-slot="auth" / "auth-header" / "auth-body"`), so external CSS can target
+one part without nested class chains.
 
 ## Design variants
 
 Four documented type stacks; pick one per surface:
 
-| Variant | Stack | Use when |
-|---------|-------|----------|
-| Clean Modern | GT America | default app UI |
-| Monospace | Berkeley Mono | terminal, logs, technical dashboards |
-| Brutalist | GT America Black + Berkeley Mono | marketing punctuation |
-| Editorial | GT America Black 900 (tight tracking) + GT America | landing hero, about |
+| Variant      | Stack                                              | Use when                             |
+| ------------ | -------------------------------------------------- | ------------------------------------ |
+| Clean Modern | GT America                                         | default app UI                       |
+| Monospace    | Berkeley Mono                                      | terminal, logs, technical dashboards |
+| Brutalist    | GT America Black + Berkeley Mono                   | marketing punctuation                |
+| Editorial    | GT America Black 900 (tight tracking) + GT America | landing hero, about                  |
 
 ## Preview cards
 

package/tokens/primitives.tokens.json

@@ -123,7 +123,7 @@
       "mono": {
         "$type": "fontFamily",
         "$value": "\"Berkeley Mono\", monospace",
-        "$description": "The single mono face: numerics, timestamps, file sizes, ETAs, counts, code, logs, magnet URIs, identifiers, and filenames. Web and mobile only — TV has no mono face.",
+        "$description": "The single mono face: numerics, timestamps, file sizes, ETAs, counts, code, logs, magnet URIs, identifiers, and filenames. Web and mobile only. TV product UI has no mono face; a TV debug overlay may use the platform's system monospace.",
         "$extensions": {
           "putio": {
             "cssName": "font-mono",