@putdotio/design 2.0.1 → 3.0.0

package/system/README.md

@@ -6,16 +6,25 @@ This folder holds the generated site tokens, preview cards, and design-system in
 
 ```
 project root/
+├── platforms/               ← per-platform binding contracts (DESIGN.md each)
 └── system/
     ├── index.html           ← redirects to the design-system guide
     ├── design-system.html   ← guide and preview-card index
     ├── design-system-light.html ← legacy redirect to design-system.html?theme=light
     ├── tokens.css           ← generated from ../tokens/**/*.tokens.json
+    ├── components.css       ← the tier-1 component layer (the web contract)
+    ├── tv.css               ← TV / 10ft component CSS, scoped to .tv artboards
     ├── assets/              ← logos, favicons, retro marks, app icons
-    └── preview/             ← atomic review cards for foundations + components + brand + platforms
-        └── tv-shell.css     ← TV / 10ft component CSS, scoped to .tv artboards (preview-only)
+    └── preview/             ← specimen cards for foundations + every platform tier
+        └── _*.css, _resize.js ← card chrome only (frame, tier strip, HIG/M3/Roku shells)
 ```
 
+Cards are named `<platform>-<section><n>-<subject>.html` — section letter `f`
+foundations, `c` components, `e` elements, `p` patterns, `s` screens
+(`ios-e01-toggle.html`); the numbered `00-…13-…` files are the tier-0
+foundations. Element cards are a fixed 1120×580 viewport: one control, its
+states, a spec strip, a don't block.
+
 ## Fonts
 
 Preview pages load the public put.io font CSS from `static.put.io` (the same
@@ -65,15 +74,16 @@ 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`,
-`.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:
+For **TV preview cards**, also load `tv.css` — it 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:
 
 ```html
 <link rel="stylesheet" href="./tokens.css">
-<link rel="stylesheet" href="./preview/tv-shell.css">
+<link rel="stylesheet" href="./tv.css">
 ```
 
 TV surfaces are **solid token colors** — no `backdrop-filter`, no translucent
@@ -98,8 +108,35 @@ into the web scales: TV has no mono face, and TV orders `--tv-z-overlay` (300)
 - **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, 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.
 
+## Binding tiers
+
+ADR 0009 (putio-frontend `docs/decisions/0009-design-binding-tiers.md`): **a
+web-rendered mock is never a native spec**. Every specimen card declares its
+tier in a strip above the artboard (`preview/_tier.css` — the only place the
+tier text lives besides `../DESIGN.md`; change both in the same PR).
+
+| Tier | Surfaces | What binds |
+| --- | --- | --- |
+| 0 | Foundations | The token graph. Binds all tiers, values only |
+| 1 | www · app · auth | The full system — `components.css` recipes are the contract, here and only here |
+| 2 | iOS · iPadOS · tvOS · watchOS · Android · Android TV | Tokens only; every control from the platform HIG / Material 3 |
+| 3 | Roku | Tier-2 token inheritance + put.io conventions in custom SceneGraph components |
+| 4 | tv.put.io · Tizen · webOS | The web system, restrained to a 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; the card documents how it is
+tokenized). Never read an Element card as a build-a-custom-control instruction.
+
+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.
+
 ## Theme System
 
 The guide (`design-system.html`) owns the theme toggle. It writes
@@ -112,8 +149,10 @@ the parent broadcast when embedded. A URL query (`?theme=light` or
 
 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
-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.
+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.
 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.
@@ -158,7 +197,7 @@ they describe the role exactly. shadcn-imported code prefers 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 `components-form-layouts.html`
+wizard step bar in `web-p00-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
@@ -169,7 +208,7 @@ hand-written HTML, and so devtools can read the component's state at a glance.
 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 card in `web-p00-form-layouts.html` (`data-slot="auth" / "auth-header"
 / "auth-body"`). This lets external CSS tweak one part without inventing
 nested class chains.
 

package/system/components.css

@@ -358,7 +358,9 @@ input, textarea, select { text-transform: none; letter-spacing: normal; }
 .form-group .label-row a:hover { color: var(--text); }
 
 /* Floating-menu surface — one recipe for dropdowns, context menus,
-   submenus, and on-player popovers. Cards keep their item styles local. */
+   submenus, and on-player popovers. Cards keep their item styles local.
+   Consumed by web-c09-menu.html and web-p06-player.html — it looks unused
+   from this file alone, so do not delete it. */
 /* Reads the --menu-* aliases for surface, border, radius and shadow. The
    generic scale is close but not identical, and using it here would silently
    break --menu-* retheming for every consumer of this recipe. */