@putdotio/design 1.3.0 → 1.4.0

package/system/README.md

@@ -18,8 +18,18 @@ 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. Each HTML file links three 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/gt-america/mono/font.css">
+<link rel="stylesheet" href="https://static.put.io/fonts/berkeley-mono/variable/font.css">
+```
+
+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 +43,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,7 +61,7 @@ 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`, `.topnav`, `.scr`, glass 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">
@@ -53,24 +70,81 @@ For **TV preview cards**, also load `preview/tv-shell.css` — it adds the `.tv`
 
 ## 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 — TV's
+translucent glass material and on-video player chrome can't render on a light
+surface, 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` |
+
+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 +159,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.

package/tokens/components.tokens.json

@@ -215,6 +215,28 @@
         }
       },
       "info": {
+        "background": {
+          "$type": "color",
+          "$value": "{color.neutral.light.solid}",
+          "$description": "Neutral solid command background in light mode.",
+          "$extensions": {
+            "putio": {
+              "cssName": "button-info-bg",
+              "mode": "light"
+            }
+          }
+        },
+        "backgroundDark": {
+          "$type": "color",
+          "$value": "{color.neutral.dark.solid}",
+          "$description": "Neutral solid command background in dark mode.",
+          "$extensions": {
+            "putio": {
+              "cssName": "button-info-bg",
+              "mode": "dark"
+            }
+          }
+        },
         "backgroundHover": {
           "$type": "color",
           "$value": "{color.neutral.light.solidHover}",
@@ -236,6 +258,96 @@
               "mode": "dark"
             }
           }
+        },
+        "foreground": {
+          "$type": "color",
+          "$value": "{component.alias.solidForeground}",
+          "$description": "Label on the neutral solid — mode-aware for AA contrast on the gray fill.",
+          "$extensions": {
+            "putio": {
+              "cssName": "button-info-fg",
+              "mode": "light"
+            }
+          }
+        },
+        "foregroundDark": {
+          "$type": "color",
+          "$value": "{component.alias.solidForegroundDark}",
+          "$description": "Label on the neutral solid in dark mode.",
+          "$extensions": {
+            "putio": {
+              "cssName": "button-info-fg",
+              "mode": "dark"
+            }
+          }
+        }
+      },
+      "default": {
+        "background": {
+          "$type": "color",
+          "$value": "{color.neutral.light.componentBg}",
+          "$description": "Quiet default button fill in light mode.",
+          "$extensions": {
+            "putio": {
+              "cssName": "button-default-bg",
+              "mode": "light"
+            }
+          }
+        },
+        "backgroundDark": {
+          "$type": "color",
+          "$value": "{color.neutral.dark.componentBg}",
+          "$description": "Quiet default button fill in dark mode.",
+          "$extensions": {
+            "putio": {
+              "cssName": "button-default-bg",
+              "mode": "dark"
+            }
+          }
+        },
+        "backgroundHover": {
+          "$type": "color",
+          "$value": "{color.neutral.light.componentBgHover}",
+          "$description": "Default button hover fill in light mode.",
+          "$extensions": {
+            "putio": {
+              "cssName": "button-default-bg-hover",
+              "mode": "light"
+            }
+          }
+        },
+        "backgroundHoverDark": {
+          "$type": "color",
+          "$value": "{color.neutral.dark.componentBgHover}",
+          "$description": "Default button hover fill in dark mode.",
+          "$extensions": {
+            "putio": {
+              "cssName": "button-default-bg-hover",
+              "mode": "dark"
+            }
+          }
+        },
+        "foreground": {
+          "$type": "color",
+          "$value": "{color.neutral.light.text}",
+          "$description": "Default button label in light mode.",
+          "$extensions": {
+            "putio": {
+              "cssName": "button-default-fg",
+              "mode": "light"
+            }
+          }
+        },
+        "foregroundDark": {
+          "$type": "color",
+          "$value": "{color.neutral.dark.text}",
+          "$description": "Default button label in dark mode.",
+          "$extensions": {
+            "putio": {
+              "cssName": "button-default-fg",
+              "mode": "dark"
+            }
+          }
         }
       }
     },

package/tokens/foundation.css

@@ -3,7 +3,7 @@ html {
   background: var(--html-bg);
   color: var(--text);
   font-family: var(--font-sans);
-  font-size: 15px;        /* 14–15 responsive base, per app convention */
+  font-size: 14px;  /* app.put.io root: fontSize ["14px","14px","15px"] — 15px at ≥ --bp-lg (media query below) */
   line-height: var(--lh-normal);
   -webkit-font-smoothing: antialiased;
   -moz-osx-font-smoothing: grayscale;
@@ -15,6 +15,13 @@ body {
   margin: 0;
 }
 
+/* Root steps up on desktop, matching app.put.io's responsive base.
+   14px/15px literals must stay in sync with --bp-lg (media queries
+   can't read custom properties). */
+@media (min-width: 1280px) {
+  html { font-size: 15px; }
+}
+
 /* -- Semantic type ------------------------------------------------- */
 
 .h-display, h1.display {
@@ -36,7 +43,7 @@ body {
 
 h1, .h1 {
   font-family: var(--font-sans);
-  font-size: var(--fs-3xl);
+  font-size: var(--fs-xl);
   font-weight: var(--fw-bold);
   line-height: var(--lh-tight);
   letter-spacing: var(--tracking-tight);
@@ -45,7 +52,7 @@ h1, .h1 {
 
 h2, .h2 {
   font-family: var(--font-sans);
-  font-size: var(--fs-2xl);
+  font-size: var(--fs-lg);
   font-weight: var(--fw-bold);
   line-height: var(--lh-tight);
   margin: 0 0 var(--space-3);
@@ -53,7 +60,7 @@ h2, .h2 {
 
 h3, .h3 {
   font-family: var(--font-sans);
-  font-size: var(--fs-xl);
+  font-size: var(--fs-md);
   font-weight: var(--fw-medium);
   line-height: var(--lh-snug);
   margin: 0 0 var(--space-2);
@@ -61,7 +68,7 @@ h3, .h3 {
 
 h4, .h4 {
   font-family: var(--font-sans);
-  font-size: var(--fs-lg);
+  font-size: var(--fs-base);
   font-weight: var(--fw-medium);
   line-height: var(--lh-snug);
   margin: 0 0 var(--space-2);
@@ -82,26 +89,26 @@ p, .body {
 }
 
 .lead {
-  font-size: var(--fs-lg);
+  font-size: var(--fs-md);
   font-weight: var(--fw-regular);
   line-height: var(--lh-normal);
   color: var(--text-secondary);
 }
 
 small, .caption {
-  font-size: var(--fs-xs);
+  font-size: var(--fs-sm);  /* production caption = fontSize 0 */
   color: var(--text-secondary);
 }
 
 .label {
-  font-size: var(--fs-sm);
+  font-size: var(--fs-base);  /* production label = fontSize 1, medium */
   font-weight: var(--fw-medium);
   color: var(--text);
 }
 
 .button-text {
   font-weight: var(--fw-medium);
-  font-size: var(--fs-base);
+  font-size: var(--fs-sm);  /* production button = fontSize 0 */
   letter-spacing: 0;
 }
 
@@ -120,16 +127,6 @@ a {
 }
 a:hover { text-decoration-color: currentColor; }
 
-/* -- Component-role aliases --------------------------------------- */
-/* Button default + info variants — live aliases; the DTCG layer doesn't define these two. */
-:root {
-  --button-default-bg:        var(--component-bg);
-  --button-default-bg-hover:  var(--component-bg-hover);
-  --button-default-fg:        var(--text);
-  --button-info-bg:           var(--solid);
-  --button-info-fg:           var(--solid-foreground);
-}
-
 /* -- Utility classes ---------------------------------------------- */
 .fg-1      { color: var(--text); }
 .fg-2      { color: var(--text-secondary); }
@@ -141,3 +138,16 @@ a:hover { text-decoration-color: currentColor; }
 .bg-2           { background: var(--bg-secondary); }
 .bg-component   { background: var(--component-bg); }
 .bg-yellow      { background: var(--yellow-solid); color: var(--primary-foreground); }
+
+/* -- Reduced motion ------------------------------------------------ */
+/* Honor the OS "reduce motion" setting: collapse transitions/animations
+   to near-instant and stop looping/auto-scrolling effects. Components
+   should not rely on motion to convey state. */
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}

package/tokens/primitives.tokens.json

@@ -30,7 +30,8 @@
     },
     "color": {
       "$type": "color",
-      "$value": "hsl(0, 0%, 78.0%)",
+      "$value": "{elevation.shadowColor}",
+      "$description": "Compat name kept for existing web consumers — alias of elevation.shadowColor so the two can never drift.",
       "$extensions": {
         "putio": {
           "cssName": "shadow",
@@ -110,7 +111,7 @@
       },
       "display": {
         "$type": "fontFamily",
-        "$value": "\"GT America\", sans-serif",
+        "$value": "{typography.fontFamily.sans}",
         "$extensions": {
           "putio": {
             "cssName": "font-display",
@@ -132,7 +133,7 @@
       },
       "mono": {
         "$type": "fontFamily",
-        "$value": "\"Berkeley Mono\", \"GT America Mono\", monospace",
+        "$value": "\"Berkeley Mono\", {typography.fontFamily.uiMono}",
         "$extensions": {
           "putio": {
             "cssName": "font-mono",
@@ -156,7 +157,8 @@
       },
       "sm": {
         "$type": "dimension",
-        "$value": "0.8125rem",
+        "$value": "0.875rem",
+        "$description": "Caption and button labels — production fontSize 0.",
         "$extensions": {
           "putio": {
             "cssName": "fs-sm",
@@ -167,7 +169,8 @@
       },
       "base": {
         "$type": "dimension",
-        "$value": "0.875rem",
+        "$value": "1rem",
+        "$description": "Body, labels, inputs — production fontSize 1; equals the responsive root (14px, 15px at >= breakpoint.lg).",
         "$extensions": {
           "putio": {
             "cssName": "fs-base",
@@ -178,7 +181,8 @@
       },
       "md": {
         "$type": "dimension",
-        "$value": "1rem",
+        "$value": "1.125rem",
+        "$description": "Subheading.",
         "$extensions": {
           "putio": {
             "cssName": "fs-md",
@@ -189,7 +193,8 @@
       },
       "lg": {
         "$type": "dimension",
-        "$value": "1.125rem",
+        "$value": "1.5rem",
+        "$description": "Heading.",
         "$extensions": {
           "putio": {
             "cssName": "fs-lg",
@@ -200,7 +205,8 @@
       },
       "xl": {
         "$type": "dimension",
-        "$value": "1.5rem",
+        "$value": "2rem",
+        "$description": "Page title.",
         "$extensions": {
           "putio": {
             "cssName": "fs-xl",
@@ -211,7 +217,8 @@
       },
       "2xl": {
         "$type": "dimension",
-        "$value": "2rem",
+        "$value": "48px",
+        "$description": "Fixed display tier — does not scale with the responsive root.",
         "$extensions": {
           "putio": {
             "cssName": "fs-2xl",
@@ -222,7 +229,8 @@
       },
       "3xl": {
         "$type": "dimension",
-        "$value": "3rem",
+        "$value": "64px",
+        "$description": "Fixed display tier — does not scale with the responsive root.",
         "$extensions": {
           "putio": {
             "cssName": "fs-3xl",
@@ -233,7 +241,8 @@
       },
       "4xl": {
         "$type": "dimension",
-        "$value": "4rem",
+        "$value": "{typography.fontSize.3xl}",
+        "$description": "Compatibility alias for the former 4xl tier; new surfaces should use fontSize.3xl or fontSize.display.",
         "$extensions": {
           "putio": {
             "cssName": "fs-4xl",
@@ -244,7 +253,8 @@
       },
       "display": {
         "$type": "dimension",
-        "$value": "6rem",
+        "$value": "96px",
+        "$description": "Fixed display tier for brand display moments.",
         "$extensions": {
           "putio": {
             "cssName": "fs-display",
@@ -624,5 +634,108 @@
         }
       }
     }
+  },
+  "z": {
+    "$description": "Stacking scale. Gapped for platform chrome — never invent z-index numbers in apps.",
+    "dropdown": {
+      "$type": "number",
+      "$value": 1000,
+      "$extensions": {
+        "putio": {
+          "cssName": "z-dropdown",
+          "mode": "global",
+          "category": "other",
+          "figma": false
+        }
+      }
+    },
+    "sticky": {
+      "$type": "number",
+      "$value": 1100,
+      "$extensions": {
+        "putio": {
+          "cssName": "z-sticky",
+          "mode": "global",
+          "category": "other",
+          "figma": false
+        }
+      }
+    },
+    "modal": {
+      "$type": "number",
+      "$value": 1300,
+      "$extensions": {
+        "putio": {
+          "cssName": "z-modal",
+          "mode": "global",
+          "category": "other",
+          "figma": false
+        }
+      }
+    },
+    "notification": {
+      "$type": "number",
+      "$value": 1400,
+      "$extensions": {
+        "putio": {
+          "cssName": "z-notification",
+          "mode": "global",
+          "category": "other",
+          "figma": false
+        }
+      }
+    },
+    "tooltip": {
+      "$type": "number",
+      "$value": 1500,
+      "$extensions": {
+        "putio": {
+          "cssName": "z-tooltip",
+          "mode": "global",
+          "category": "other",
+          "figma": false
+        }
+      }
+    }
+  },
+  "breakpoint": {
+    "$description": "Responsive breakpoints, lifted from app.put.io's BREAKPOINTS. Generator-facing: CSS media queries cannot read custom properties, so emitters bind these as Tailwind screens, StyleX consts, or documented literals.",
+    "sm": {
+      "$type": "dimension",
+      "$value": "640px",
+      "$extensions": {
+        "putio": {
+          "cssName": "bp-sm",
+          "mode": "global",
+          "category": "other",
+          "figma": false
+        }
+      }
+    },
+    "md": {
+      "$type": "dimension",
+      "$value": "768px",
+      "$extensions": {
+        "putio": {
+          "cssName": "bp-md",
+          "mode": "global",
+          "category": "other",
+          "figma": false
+        }
+      }
+    },
+    "lg": {
+      "$type": "dimension",
+      "$value": "1280px",
+      "$description": "The root font-size steps from 14px to 15px at this width.",
+      "$extensions": {
+        "putio": {
+          "cssName": "bp-lg",
+          "mode": "global",
+          "category": "other",
+          "figma": false
+        }
+      }
+    }
   }
 }