@putdotio/design 0.1.0-alpha.0

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@putdotio/design",
+  "version": "0.1.0-alpha.0",
+  "description": "Public put.io design tokens, generated token artifacts, and design-system guidance.",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://design.put.io",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/putdotio/putio-design.git"
+  },
+  "bugs": {
+    "url": "https://github.com/putdotio/putio-design/issues"
+  },
+  "keywords": [
+    "putio",
+    "design-system",
+    "design-tokens",
+    "dtcg"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "DESIGN.md",
+    "dist",
+    "tokens",
+    "system/README.md"
+  ],
+  "exports": {
+    "./css": "./dist/css/tokens.css",
+    "./tokens": "./dist/tokens.flat.json",
+    "./tokens/meta": {
+      "types": "./dist/tokens.d.ts",
+      "default": "./dist/tokens.js"
+    },
+    "./tokens/dtcg": "./dist/tokens.dtcg.json",
+    "./tokens/figma": "./dist/figma/putio.tokens.json",
+    "./design.md": "./DESIGN.md"
+  },
+  "scripts": {
+    "dev": "node scripts/serve-system.ts",
+    "tokens:build": "node scripts/build-tokens.ts",
+    "tokens:check": "pnpm tokens:build && node scripts/verify-design-system.ts && git diff --exit-code -- DESIGN.md dist system/tokens.css",
+    "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:full": "pnpm verify && pnpm e2e && npm pack --dry-run",
+    "check": "pnpm verify",
+    "deploy:production": "sst deploy --stage production"
+  },
+  "devDependencies": {
+    "@axe-core/playwright": "^4.11.3",
+    "@playwright/test": "^1.60.0",
+    "@types/node": "^25.9.1",
+    "html-validate": "^11.2.0",
+    "sst": "^4.14.3",
+    "style-dictionary": "^5.4.1",
+    "typescript": "^6.0.2",
+    "yaml": "^2.9.0"
+  },
+  "packageManager": "pnpm@11.2.2"
+}

package/system/README.md

@@ -0,0 +1,84 @@
+# put.io design system
+
+This is the `system/` folder inside [`putdotio/putio-design`](https://github.com/putdotio/putio-design). It holds the **tokens**, **preview cards**, and an **index** of the design system.
+
+## Layout
+
+```
+project root/
+└── 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
+    ├── 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)
+```
+
+## Fonts
+
+Fonts are loaded directly from `static.put.io`, so the design system uses the same public type families as put.io product surfaces. 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 `putdotio/putio-static`):
+`100 ultra-light · 200 thin · 300 light · 400 regular · 500 medium · 700 bold · 900 black`
+
+## Using tokens
+
+```html
+<link rel="stylesheet" href="system/tokens.css">
+```
+
+The canonical source is DTCG-compatible JSON in [`../tokens`](../tokens). This
+CSS file is generated for the design site and package consumers. Everything else
+is a variable. The only hard-coded value you should ever write is `#FDCE45` —
+and even that is exposed as `var(--yellow-solid)`.
+
+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:
+
+```html
+<link rel="stylesheet" href="system/tokens.css">
+<link rel="stylesheet" href="system/preview/tv-shell.css">
+```
+
+## Core rules
+
+- **Yellow `#FDCE45` is sacred.** Never gradient, tint, or replace. Primary CTAs, folder icons, focus rings (at 35% alpha), progress bars. `--yellow-solid` is the brand value; for yellow text on light backgrounds use `--yellow-text-secondary` instead.
+- **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.
+- **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.
+
+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.
+
+## 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 |
+
+## Preview cards
+
+Open `system/design-system.html` for the full index. Each card renders a single concept against the actual tokens — read it like a spec.
+
+See the root [`AGENTS.md`](../AGENTS.md) for naming conventions and the rules agents must follow.

package/tokens/components.tokens.json

@@ -0,0 +1,229 @@
+{
+  "$description": "Component-level aliases. Platform repos may map these to native controls, but this repo only emits generic tokens.",
+  "component": {
+    "button": {
+      "primary": {
+        "background": {
+          "$type": "color",
+          "$value": "{color.brand.yellow}",
+          "$description": "Primary command background.",
+          "$extensions": {
+            "putio": {
+              "cssName": "button-primary-bg",
+              "mode": "global"
+            }
+          }
+        },
+        "foreground": {
+          "$type": "color",
+          "$value": "#0A0A0A",
+          "$description": "Text or icon color on the yellow primary button.",
+          "$extensions": {
+            "putio": {
+              "cssName": "button-primary-fg",
+              "mode": "global"
+            }
+          }
+        },
+        "radius": {
+          "$type": "dimension",
+          "$value": "{radius.default}",
+          "$extensions": {
+            "putio": {
+              "cssName": "button-radius",
+              "mode": "global"
+            }
+          }
+        }
+      },
+      "secondary": {
+        "background": {
+          "$type": "color",
+          "$value": "{color.neutral.light.componentBg}",
+          "$extensions": {
+            "putio": {
+              "cssName": "button-secondary-bg",
+              "mode": "light"
+            }
+          }
+        },
+        "backgroundDark": {
+          "$type": "color",
+          "$value": "{color.neutral.dark.componentBg}",
+          "$extensions": {
+            "putio": {
+              "cssName": "button-secondary-bg",
+              "mode": "dark"
+            }
+          }
+        },
+        "foreground": {
+          "$type": "color",
+          "$value": "{color.neutral.light.text}",
+          "$extensions": {
+            "putio": {
+              "cssName": "button-secondary-fg",
+              "mode": "light"
+            }
+          }
+        },
+        "foregroundDark": {
+          "$type": "color",
+          "$value": "{color.neutral.dark.text}",
+          "$extensions": {
+            "putio": {
+              "cssName": "button-secondary-fg",
+              "mode": "dark"
+            }
+          }
+        }
+      }
+    },
+    "input": {
+      "background": {
+        "$type": "color",
+        "$value": "{surface.light.appBg}",
+        "$extensions": {
+          "putio": {
+            "cssName": "input-bg",
+            "mode": "light"
+          }
+        }
+      },
+      "backgroundDark": {
+        "$type": "color",
+        "$value": "{color.neutral.dark.componentBg}",
+        "$extensions": {
+          "putio": {
+            "cssName": "input-bg",
+            "mode": "dark"
+          }
+        }
+      },
+      "border": {
+        "$type": "color",
+        "$value": "{color.neutral.light.border}",
+        "$extensions": {
+          "putio": {
+            "cssName": "input-border",
+            "mode": "light"
+          }
+        }
+      },
+      "borderDark": {
+        "$type": "color",
+        "$value": "{color.neutral.dark.border}",
+        "$extensions": {
+          "putio": {
+            "cssName": "input-border",
+            "mode": "dark"
+          }
+        }
+      },
+      "radius": {
+        "$type": "dimension",
+        "$value": "{radius.default}",
+        "$extensions": {
+          "putio": {
+            "cssName": "input-radius",
+            "mode": "global"
+          }
+        }
+      }
+    },
+    "fileRow": {
+      "background": {
+        "$type": "color",
+        "$value": "{surface.light.listItemBg}",
+        "$extensions": {
+          "putio": {
+            "cssName": "file-row-bg",
+            "mode": "light"
+          }
+        }
+      },
+      "backgroundDark": {
+        "$type": "color",
+        "$value": "{surface.dark.listItemBg}",
+        "$extensions": {
+          "putio": {
+            "cssName": "file-row-bg",
+            "mode": "dark"
+          }
+        }
+      },
+      "hoverBackground": {
+        "$type": "color",
+        "$value": "{surface.light.listItemBgHover}",
+        "$extensions": {
+          "putio": {
+            "cssName": "file-row-bg-hover",
+            "mode": "light"
+          }
+        }
+      },
+      "hoverBackgroundDark": {
+        "$type": "color",
+        "$value": "{surface.dark.listItemBgHover}",
+        "$extensions": {
+          "putio": {
+            "cssName": "file-row-bg-hover",
+            "mode": "dark"
+          }
+        }
+      },
+      "icon": {
+        "$type": "color",
+        "$value": "{color.brand.yellow}",
+        "$extensions": {
+          "putio": {
+            "cssName": "file-row-icon",
+            "mode": "global"
+          }
+        }
+      }
+    },
+    "notification": {
+      "infoBackground": {
+        "$type": "color",
+        "$value": "{color.neutral.light.bgSecondary}",
+        "$extensions": {
+          "putio": {
+            "cssName": "notification-info-bg",
+            "mode": "light"
+          }
+        }
+      },
+      "infoBackgroundDark": {
+        "$type": "color",
+        "$value": "{color.neutral.dark.componentBg}",
+        "$extensions": {
+          "putio": {
+            "cssName": "notification-info-bg",
+            "mode": "dark"
+          }
+        }
+      },
+      "dangerBackground": {
+        "$type": "color",
+        "$value": "{color.red.light.componentBg}",
+        "$extensions": {
+          "putio": {
+            "cssName": "notification-danger-bg",
+            "mode": "light"
+          }
+        }
+      },
+      "dangerBackgroundDark": {
+        "$type": "color",
+        "$value": "{color.red.dark.componentBg}",
+        "$extensions": {
+          "putio": {
+            "cssName": "notification-danger-bg",
+            "mode": "dark"
+          }
+        }
+      }
+    }
+  }
+}

package/tokens/context.tokens.json

@@ -0,0 +1,155 @@
+{
+  "$description": "Shared TV context tokens. Consuming TV repos generate their own platform artifacts from these values.",
+  "context": {
+    "tv": {
+      "surface": {
+        "0": {
+          "$type": "color",
+          "$value": "#000",
+          "$extensions": {
+            "putio": {
+              "cssName": "surf-0",
+              "mode": "tv"
+            }
+          }
+        },
+        "1": {
+          "$type": "color",
+          "$value": "#0a0a0a",
+          "$extensions": {
+            "putio": {
+              "cssName": "surf-1",
+              "mode": "tv"
+            }
+          }
+        },
+        "2": {
+          "$type": "color",
+          "$value": "#161616",
+          "$extensions": {
+            "putio": {
+              "cssName": "surf-2",
+              "mode": "tv"
+            }
+          }
+        },
+        "3": {
+          "$type": "color",
+          "$value": "#1f1f1f",
+          "$extensions": {
+            "putio": {
+              "cssName": "surf-3",
+              "mode": "tv"
+            }
+          }
+        }
+      },
+      "text": {
+        "primary": {
+          "$type": "color",
+          "$value": "#f4f4f4",
+          "$extensions": {
+            "putio": {
+              "cssName": "text-1",
+              "mode": "tv"
+            }
+          }
+        },
+        "secondary": {
+          "$type": "color",
+          "$value": "rgba(244,244,244,0.62)",
+          "$extensions": {
+            "putio": {
+              "cssName": "text-2",
+              "mode": "tv"
+            }
+          }
+        },
+        "tertiary": {
+          "$type": "color",
+          "$value": "rgba(244,244,244,0.38)",
+          "$extensions": {
+            "putio": {
+              "cssName": "text-3",
+              "mode": "tv"
+            }
+          }
+        }
+      },
+      "glass": {
+        "1": {
+          "$type": "color",
+          "$value": "rgba(255,255,255,0.06)",
+          "$extensions": {
+            "putio": {
+              "cssName": "glass-1-bg",
+              "mode": "tv"
+            }
+          }
+        },
+        "2": {
+          "$type": "color",
+          "$value": "rgba(255,255,255,0.10)",
+          "$extensions": {
+            "putio": {
+              "cssName": "glass-2-bg",
+              "mode": "tv"
+            }
+          }
+        },
+        "3": {
+          "$type": "color",
+          "$value": "rgba(255,255,255,0.14)",
+          "$extensions": {
+            "putio": {
+              "cssName": "glass-3-bg",
+              "mode": "tv"
+            }
+          }
+        },
+        "border": {
+          "$type": "color",
+          "$value": "rgba(255,255,255,0.12)",
+          "$extensions": {
+            "putio": {
+              "cssName": "glass-border",
+              "mode": "tv"
+            }
+          }
+        },
+        "borderStrong": {
+          "$type": "color",
+          "$value": "rgba(255,255,255,0.22)",
+          "$extensions": {
+            "putio": {
+              "cssName": "glass-border-strong",
+              "mode": "tv"
+            }
+          }
+        }
+      },
+      "focus": {
+        "ring": {
+          "$type": "color",
+          "$value": "rgba(253,206,69,0.18)",
+          "$extensions": {
+            "putio": {
+              "cssName": "focus-ring",
+              "mode": "tv"
+            }
+          }
+        },
+        "liftShadow": {
+          "$type": "string",
+          "$value": "0 14px 30px rgba(0,0,0,0.45)",
+          "$extensions": {
+            "putio": {
+              "cssName": "focus-shadow",
+              "mode": "tv"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/tokens/foundation.css

@@ -0,0 +1,133 @@
+/* -- Document base ------------------------------------------------- */
+html {
+  background: var(--html-bg);
+  color: var(--text);
+  font-family: var(--font-sans);
+  font-size: 15px;        /* 14–15 responsive base, per app convention */
+  line-height: var(--lh-normal);
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  text-rendering: optimizeLegibility;
+}
+body {
+  background: var(--app-bg);
+  color: var(--text);
+  margin: 0;
+}
+
+/* -- Semantic type ------------------------------------------------- */
+
+.h-display, h1.display {
+  font-family: var(--font-display);
+  font-size: var(--fs-display);
+  font-weight: var(--fw-black);
+  line-height: 0.95;
+  letter-spacing: var(--tracking-tight);
+  text-transform: uppercase;
+  margin: 0;
+}
+
+/* Numeric / tabular UI text — transfer speeds, storage sizes, timestamps */
+.num, .tabular {
+  font-family: var(--font-ui-mono);
+  font-variant-numeric: tabular-nums;
+  font-feature-settings: "tnum";
+}
+
+h1, .h1 {
+  font-family: var(--font-sans);
+  font-size: var(--fs-3xl);
+  font-weight: var(--fw-bold);
+  line-height: var(--lh-tight);
+  letter-spacing: var(--tracking-tight);
+  margin: 0 0 var(--space-3);
+}
+
+h2, .h2 {
+  font-family: var(--font-sans);
+  font-size: var(--fs-2xl);
+  font-weight: var(--fw-bold);
+  line-height: var(--lh-tight);
+  margin: 0 0 var(--space-3);
+}
+
+h3, .h3 {
+  font-family: var(--font-sans);
+  font-size: var(--fs-xl);
+  font-weight: var(--fw-medium);
+  line-height: var(--lh-snug);
+  margin: 0 0 var(--space-2);
+}
+
+h4, .h4 {
+  font-family: var(--font-sans);
+  font-size: var(--fs-lg);
+  font-weight: var(--fw-medium);
+  line-height: var(--lh-snug);
+  margin: 0 0 var(--space-2);
+}
+
+.subheading {
+  font-size: var(--fs-md);
+  font-weight: var(--fw-medium);
+  color: var(--text);
+}
+
+p, .body {
+  font-family: var(--font-sans);
+  font-size: var(--fs-base);
+  font-weight: var(--fw-regular);
+  line-height: var(--lh-normal);
+  margin: 0 0 var(--space-3);
+}
+
+.lead {
+  font-size: var(--fs-lg);
+  font-weight: var(--fw-regular);
+  line-height: var(--lh-normal);
+  color: var(--text-secondary);
+}
+
+small, .caption {
+  font-size: var(--fs-xs);
+  color: var(--text-secondary);
+}
+
+.label {
+  font-size: var(--fs-sm);
+  font-weight: var(--fw-medium);
+  color: var(--text);
+}
+
+.button-text {
+  font-weight: var(--fw-medium);
+  font-size: var(--fs-base);
+  letter-spacing: 0;
+}
+
+code, kbd, .mono {
+  font-family: var(--font-mono);
+  font-size: 0.92em;
+}
+
+a {
+  color: inherit;
+  text-decoration: underline;
+  text-underline-offset: 2px;
+  text-decoration-thickness: 1px;
+  text-decoration-color: var(--border-hover);
+  transition: text-decoration-color var(--dur-fast) var(--ease-out);
+}
+a:hover { text-decoration-color: currentColor; }
+
+/* -- Utility classes ---------------------------------------------- */
+.fg-1      { color: var(--text); }
+.fg-2      { color: var(--text-secondary); }
+.fg-yellow { color: var(--yellow-text-secondary); }
+.fg-green  { color: var(--green-text-secondary); }
+.fg-red    { color: var(--red-text-secondary); }
+
+.bg-1           { background: var(--bg); }
+.bg-2           { background: var(--bg-secondary); }
+.bg-component   { background: var(--component-bg); }
+.bg-yellow      { background: var(--yellow-solid); color: #000; }