@putdotio/design 5.1.0 → 5.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -47,28 +47,15 @@ keeps the token file's element styles below utilities:
47
47
  ```
48
48
 
49
49
  Utilities then read the tokens: `bg-bg` is `var(--bg)`, `rounded-sm` is
50
- `var(--radius-sm)`, `text-lg` is `var(--fs-lg)`. The full mapping:
50
+ `var(--radius-sm)`, `text-lg` is `var(--fs-lg)`. Theme rules:
51
51
  [Tailwind v4 theme](system/README.md#tailwind-v4-theme).
52
52
 
53
- Package entrypoints, from `exports` in [package.json](package.json):
54
-
55
- | Subpath | File |
56
- | -------------------------------- | ----------------------------------------------------------------------------------- |
57
- | `@putdotio/design/css` | [`dist/css/tokens.css`](dist/css/tokens.css) |
58
- | `@putdotio/design/components` | [`system/components.css`](system/components.css) |
59
- | `@putdotio/design/tailwind` | [`dist/css/tailwind.css`](dist/css/tailwind.css) |
60
- | `@putdotio/design/tokens` | [`dist/tokens.flat.json`](dist/tokens.flat.json) |
61
- | `@putdotio/design/tokens/meta` | [`dist/tokens.js`](dist/tokens.js), typed by [`dist/tokens.d.ts`](dist/tokens.d.ts) |
62
- | `@putdotio/design/tokens/dtcg` | [`dist/tokens.dtcg.json`](dist/tokens.dtcg.json) |
63
- | `@putdotio/design/tokens/figma` | [`dist/figma/putio.tokens.json`](dist/figma/putio.tokens.json) |
64
- | `@putdotio/design/assets/<file>` | [`system/assets`](system/assets) |
65
- | `@putdotio/design/design.md` | [`DESIGN.md`](DESIGN.md) |
53
+ Every entrypoint is listed under `exports` in [package.json](package.json).
66
54
 
67
55
  ## Docs
68
56
 
69
57
  - [Design contract](DESIGN.md)
70
- - [Design guide structure](system/README.md)
71
- - [Distribution](docs/distribution.md)
58
+ - [Design guide](system/README.md)
72
59
  - [Contributing](CONTRIBUTING.md)
73
60
  - [Security](https://github.com/putdotio/.github/blob/main/SECURITY.md)
74
61
  - [Agent guide](AGENTS.md)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@putdotio/design",
3
- "version": "5.1.0",
3
+ "version": "5.2.0",
4
4
  "description": "Public put.io design tokens, brand assets, and design-system guidance.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -93,5 +93,5 @@
93
93
  "typescript": "^7.0.2",
94
94
  "yaml": "^2.9.0"
95
95
  },
96
- "packageManager": "pnpm@12.14.0"
96
+ "packageManager": "pnpm@12.15.0"
97
97
  }
package/system/README.md CHANGED
@@ -1,228 +1,76 @@
1
1
  # put.io design system
2
2
 
3
- The guide site: generated site tokens, component CSS, preview cards, and the
4
- design-system index.
3
+ The guide site and the package's component and Tailwind layers. The design
4
+ rules live in [DESIGN.md](../DESIGN.md).
5
5
 
6
- ## Layout
7
-
8
- - `index.html` redirects to `design-system.html`, the guide and preview-card
9
- index. `design-system-light.html` redirects to
10
- `design-system.html?theme=light`.
11
- - `tokens.css` is generated from `../tokens/**/*.tokens.json`; edit the token
12
- sources and rebuild.
13
- - `components.css` is the Tier-1 component layer (the web contract).
14
- - `tv.css` is the TV / 10-foot component CSS, scoped to `.tv` artboards.
15
- - `assets/` holds logos, favicons, retro marks, and app icons.
16
- - `preview/` holds specimen cards for the foundations and every platform tier.
17
- Its `_`-prefixed files are card chrome only (frame, tier strip, HIG, M3, and
18
- Roku shells, resize and password-toggle helpers).
19
-
20
- Cards are named `<platform>-<section><n>-<subject>.html` with section letter `f`
21
- foundations, `c` components, `e` elements, `p` patterns, or `s` screens
22
- (`ios-e01-toggle.html`); the numbered `00-…13-…` files are the tier-0
23
- foundations. Element cards are a fixed 1120×580 viewport: one control, its
24
- states, a spec strip, a don't block.
25
-
26
- ## Fonts
27
-
28
- Preview pages load the public put.io font CSS from `static.put.io`, the same
29
- source as the product; font licensing is in
30
- [Distribution](../docs/distribution.md#fonts-and-assets). Each preview links
31
- both families in `<head>`:
32
-
33
- ```html
34
- <link rel="stylesheet" href="https://static.put.io/fonts/gt-america/standard/font.css" />
35
- <link rel="stylesheet" href="https://static.put.io/fonts/berkeley-mono/variable/font.css" />
36
- ```
37
-
38
- Those two links are the full font set: mono text reads `--font-mono` (Berkeley
39
- Mono), whose tabular figures carry the numerics.
40
-
41
- Weight names on the font host:
42
- `100 ultra-light · 200 thin · 300 light · 400 regular · 500 medium · 700 bold · 900 black`.
43
- The tokens use four of them through `--fw-regular`, `--fw-medium`, `--fw-bold`,
44
- and `--fw-black`.
45
-
46
- ## Using tokens
47
-
48
- Guide pages in `system/` load the generated site stylesheet:
49
-
50
- ```html
51
- <link rel="stylesheet" href="./tokens.css" />
52
- ```
53
-
54
- The canonical source is DTCG-compatible JSON in [`../tokens`](../tokens). This
55
- site stylesheet (`system/tokens.css`) and the package stylesheet
56
- (`dist/css/tokens.css`, exported as `@putdotio/design/css`) are generated from
57
- the same source. Brand yellow is `var(--yellow-solid)`; its emitted hsl form is
58
- pinned in the [`../DESIGN.md`](../DESIGN.md) frontmatter, and the
59
- `--button-primary-bg-hover` derivation is in
60
- [Distribution](../docs/distribution.md#generated-files).
61
-
62
- Stacking, breakpoints, the root font-size, and the `@media` literal rule live
63
- in [Layout & Spacing](../DESIGN.md#layout--spacing) and
64
- [Typography](../DESIGN.md#typography).
65
-
66
- Package consumers import as in the [README](../README.md#use).
67
-
68
- For **TV preview cards**, also load `tv.css`, which adds the `.tv`, `.scr`,
69
- `.row`, solid surface tiers, and player chrome on top of the tokens, authored
70
- 1:1 at 1920×1080 (a px in the file is a px on the TV). Every component selector
71
- is scoped under `.tv`, so the file can be bundled globally alongside web
72
- components. Platform repos implement TV components in their native UI stacks:
73
-
74
- ```html
75
- <link rel="stylesheet" href="./tokens.css" /> <link rel="stylesheet" href="./tv.css" />
76
- ```
77
-
78
- TV material, focus, and the `tv` token group rules live in
79
- [Components](../DESIGN.md#components). Guide specifics: the `tv` group is
80
- `mode: "tv"` and read from `dist/tokens.flat.json`; `--radius-tv` is the one
81
- `tv` value the token CSS emits, so `tv.css` declares the `--tv-*` properties
82
- its cards use itself.
83
-
84
- ## Core rules
85
-
86
- - **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`: a 2px `--bg` gap, then a 2px `--solid-hover` ring, at least 3:1 against the page and panels. `--shadow-focus-color` (the yellow at 35% alpha) stays only as shadcn's `--ring`. Form fields focus with `--field-ring` instead.
87
- - **Yellow as text on light** uses `--yellow-text-secondary` (≈5:1, AA); `--yellow-solid` is fill-only on light backgrounds.
88
- - **Labels on yellow** use `--primary-foreground`, a warm dark that passes AA on the yellow fill.
89
- - **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()`.
90
- - **Text sizes are tokens.** The guide, the web previews, and their shared CSS (`_tier.css`, `_frame.css`, `_element.css`) set text with a role (`--fs-ui`, `--fs-body`, `--fs-caption`, `--fs-field`) or a heading step, per [Typography](../DESIGN.md#typography). Icon glyphs keep px, rules under `.tv` keep the TV grid, and native and TV previews keep platform px. `pnpm verify` fails on any other literal font size.
91
- - **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.
92
-
93
- Icons, fields and panels, and raw filenames follow the root
94
- [Components](../DESIGN.md#components) and
95
- [Content and Icons](../DESIGN.md#content-and-icons).
96
-
97
- ## Binding tiers
6
+ ## Preview cards
98
7
 
99
- Tier definitions, the Component/Element distinction, and the `preview/_tier.css`
100
- pairing rule live in [Binding Tiers](../DESIGN.md#binding-tiers). An Element
101
- card shows how a stock control receives tokens.
8
+ `design-system.html` indexes every card. Each card renders one concept against
9
+ the real tokens; read it as a spec.
102
10
 
103
- Native cards are drawn 1:1 in their own unit (iPhone 393×852pt, iPad
104
- 1024×768pt, Apple Watch 176×215pt, Android 412×915dp, TV 1920×1080px), so a
105
- number written on a card is the number in the HIG or the Material spec. Those
106
- metrics are Apple's and Google's and stay out of the put.io token graph. Device
107
- bezels and on-video chrome stay untokenised.
11
+ - Name cards `<platform>-<section><n>-<subject>.html`, with section `f`
12
+ foundations, `c` components, `e` elements, `p` patterns, or `s` screens
13
+ (`ios-e01-toggle.html`). The numbered `00-…13-…` files are tier-0
14
+ foundations. `pnpm verify` rejects other names.
15
+ - Element cards are a fixed 1120×580 viewport: one control, its states, a spec
16
+ strip, a don't block.
17
+ - Native cards are drawn 1:1 in their own unit (iPhone 393×852pt, iPad
18
+ 1024×768pt, Apple Watch 176×215pt, Android 412×915dp, TV 1920×1080px), so a
19
+ number on a card is the number in the HIG or the Material spec. Those
20
+ metrics, device bezels, and on-video chrome stay out of the token graph.
21
+ - Each card links the public font CSS from `static.put.io`; these two links are
22
+ the full font set:
23
+
24
+ ```html
25
+ <link rel="stylesheet" href="https://static.put.io/fonts/gt-america/standard/font.css" />
26
+ <link rel="stylesheet" href="https://static.put.io/fonts/berkeley-mono/variable/font.css" />
27
+ ```
28
+
29
+ - TV cards also load `tv.css`, authored 1:1 at 1920×1080 and scoped under
30
+ `.tv`. It declares the `--tv-*` properties its cards use, because the token
31
+ CSS emits only `--radius-tv` from the `tv` group.
32
+ - Wordmark SVGs carry their optical centring in the viewBox. Flex-centre them
33
+ as is, with no `translateY` nudge.
108
34
 
109
35
  ## Theme System
110
36
 
111
- The guide (`design-system.html`) owns the theme toggle. It writes
112
- `putio-ds-theme` to `localStorage`, updates `html.dark`, and broadcasts
113
- `{type:'__theme', theme}` to every embedded preview iframe via `postMessage`,
114
- so embeds flip live without reloading. Each preview's inline bootstrap reads
115
- the same storage key on standalone open, and `preview/_resize.js` listens for
116
- the parent broadcast when embedded. A URL query (`?theme=light` or
117
- `?theme=dark`) overrides both, for screenshots.
37
+ Light and dark are the same markup with different token values: toggle `.dark`
38
+ on `<html>`. The guide stores the choice in `localStorage` and broadcasts it to
39
+ embedded cards; `?theme=light` or `?theme=dark` overrides both, for
40
+ screenshots.
118
41
 
119
- Fixed-mode previews opt out with `<html data-theme-lock="dark">`, reserved for
120
- product mockups whose visual language is intrinsically one mode. A 10-foot
121
- screen, a native app mockup, and on-video player chrome are fixed-mode
122
- surfaces, so the `ios-*`, `android-*`, `androidtv-*`, `tvos-*`, `watchos-*`,
123
- `roku-*`, `tv-*`, and `mobile-*` cards plus `web-p06-player.html` are locked.
124
- Locked previews ignore `localStorage`, parent broadcasts, and the URL query.
125
- New component previews stay unlocked, so the tokens render them in both modes.
42
+ Native, TV, and on-video player cards are fixed-mode product mockups and set
43
+ `<html data-theme-lock="dark">`, which ignores the toggle and the query. Every
44
+ other card stays unlocked, and the e2e suite checks it in both modes.
126
45
 
127
46
  ## shadcn / Base UI interop
128
47
 
129
- The token layer aliases the canonical shadcn token names, so shadcn/ui blocks,
130
- Base UI components, and Tailwind presets resolve against put.io values without
131
- renaming. Each shadcn name aliases a put.io token and carries no value of its
132
- own, so the two name systems cannot drift.
133
-
134
- | shadcn name | put.io target |
135
- | -------------------------------------------- | ---------------------------------------------------------- |
136
- | `--primary` / `--primary-foreground` | `--yellow-solid` / `var(--primary-foreground)` (warm dark) |
137
- | `--destructive` / `--destructive-foreground` | `--red-solid` / `var(--destructive-foreground)` (= `#fff`) |
138
- | `--success` / `--success-foreground` | `--green-solid` / `var(--success-foreground)` (= `#fff`) |
139
- | `--muted` / `--muted-foreground` | `--bg-secondary` / `--text-secondary` |
140
- | `--accent` / `--accent-foreground` | `--component-bg` / `--text` |
141
- | `--card` / `--card-foreground` | `--component-bg` / `--text` |
142
- | `--popover` / `--popover-foreground` | `--component-bg` / `--text` |
143
- | `--input` | `--field-border` |
144
- | `--ring` | `--shadow-focus-color` |
145
- | `--background` / `--foreground` | `--bg` / `--text` |
146
-
147
- The `--input-*` set (`-bg`, `-border`, `-border-hover`, `-border-focus`,
148
- `-ring`, `-text`, `-placeholder`, `-radius`) and `--foreground-muted` are
149
- [deprecated](../docs/distribution.md#deprecated-tokens): shadcn itself names
150
- only `--input` and `--muted-foreground`. Each deprecated name aliases its
151
- replacement; **author against `--field-*` and `--text-secondary`.**
48
+ The token layer defines the shadcn names (`--primary`, `--muted-foreground`,
49
+ `--input`, `--ring`, …) as aliases of put.io tokens, so shadcn/ui blocks and
50
+ Base UI components resolve against put.io values without renaming.
152
51
 
153
- On a solid surface, read the foreground tokens (`--primary-foreground`,
154
- `--destructive-foreground`, `--success-foreground`), which encode the mode-safe
155
- inverse pair, instead of writing literal `#000` / `#fff`.
156
-
157
- put.io components use the long descriptive names (`--component-bg-hover`,
158
- `--yellow-text-secondary`) because they name the role exactly; shadcn-imported
159
- code keeps the short names.
52
+ - Author against `--field-*` and `--text-secondary`. The `--input-*` set and
53
+ `--foreground-muted` are deprecated aliases.
54
+ - On a solid fill, read `--primary-foreground`, `--destructive-foreground`, or
55
+ `--success-foreground` instead of literal `#000` or `#fff`.
56
+ - Express state with `data-state` (`open`, `checked`, `completed`, …), the
57
+ attribute headless primitives set, not class flags such as `.is-active`.
58
+ - Mark compound parts with `data-slot` (`modal-header`, `card-title`, …) so
59
+ external CSS can target one part without nested class chains.
160
60
 
161
61
  ### Tailwind v4 theme
162
62
 
163
63
  `@putdotio/design/tailwind` ([`dist/css/tailwind.css`](../dist/css/tailwind.css))
164
- maps the tokens into Tailwind v4 theme keys. The build derives each key from the
165
- token's type and CSS name, so new tokens join their namespace without a hand
166
- list. Import it after `tailwindcss` and `@putdotio/design/css`; the
167
- [README](../README.md#use) shows the import lines.
168
-
169
- | Tailwind key | put.io token | Example utilities |
170
- | ------------------------- | ---------------------------------------------------------- | ----------------------------------------------- |
171
- | `--color-<name>` | every color token `--<name>` | `bg-bg`, `text-muted-foreground` |
172
- | `--font-*` | `--font-*` | `font-sans`, `font-mono` |
173
- | `--font-weight-*` | `--fw-*` | `font-regular`, `font-bold` |
174
- | `--text-*` | `--fs-*` | `text-sm`, `text-display` |
175
- | `--leading-*` | `--lh-*` | `leading-tight` |
176
- | `--tracking-*` | `--tracking-*`, `--button-tracking*` | `tracking-tight`, `tracking-button` |
177
- | `--radius`, `--radius-*` | `--radius`, `--radius-*`, `--<component>-radius` | `rounded`, `rounded-sm`, `rounded-panel` |
178
- | `--shadow-*` | `--shadow-*`, `--<component>-shadow`, `--<component>-ring` | `shadow-sm`, `shadow-menu`, `shadow-field-ring` |
179
- | `--ease-*` | `--ease-*` | `ease-out` |
180
- | `--transition-duration-*` | `--dur-*` | `duration-base` |
181
-
182
- - The block is `@theme inline reference`. Utilities read the put.io custom
183
- property where they apply, so `.dark` works. Tailwind declares none of the
184
- keys, so `--radius-sm` or `--font-sans` stays the token instead of a
185
- self-reference. In custom CSS, read the put.io name (`var(--bg)`), not
186
- `var(--color-bg)`.
187
- - shadcn class names such as `bg-primary`, `border-input`, and
188
- `text-muted-foreground` resolve through the aliases above.
189
- - `text-*` sizes set no line height; the document's `--lh-normal` applies until
190
- a `leading-*` utility sets one.
191
- - TV tokens, z-indexes and breakpoints stay out. Deprecated tokens stay in until a major release removes them.
192
- - `--spacing` is `var(--space-1)`, so `p-4` is 16px at any root size and equals
193
- `--space-4`. Tailwind defaults that put.io does not define, such as
194
- `rounded-xl`, stay available.
195
-
196
- ### State via `data-state`, not class flags
197
-
198
- Base UI / headless primitives set
199
- `data-state="open|closed|checked|unchecked|active|completed|pending|loading"`
200
- on the DOM. put.io components target those same attribute values in CSS; see
201
- the wizard step bar in `web-p00b-form-flows.html`
202
- (`.step[data-state="completed"]`) and the menu/table cards. Express state with
203
- `data-state` rather than class flags (`.is-active`, `.on`, `.current`), so the
204
- same DOM contract works with any controlling code and devtools show the state
205
- directly.
206
-
207
- ### Compound parts via `data-slot`
208
-
209
- shadcn marks parts of compound components with `data-slot="card-header"`,
210
- `data-slot="card-title"`, and so on. put.io does the same on the folder picker
211
- (`data-slot="modal" / "modal-header" / "modal-body" / "modal-footer"`), so
212
- external CSS can target one part without nested class chains.
213
-
214
- ## Design variants
215
-
216
- Four documented type stacks; pick one per surface:
217
-
218
- | Variant | Stack | Use when |
219
- | ------------ | -------------------------------------------------- | ------------------------------------ |
220
- | Clean Modern | GT America | default app UI |
221
- | Monospace | Berkeley Mono | terminal, logs, technical dashboards |
222
- | Brutalist | GT America Black + Berkeley Mono | marketing punctuation |
223
- | Editorial | GT America Black 900 (tight tracking) + GT America | landing hero, about |
224
-
225
- ## Preview cards
226
-
227
- `design-system.html` is the full index. Each card renders one concept against
228
- the real tokens; read it as a spec.
64
+ maps the tokens into Tailwind v4 theme keys: `bg-bg`, `rounded-panel`,
65
+ `text-display`, `duration-base`. Import it after `tailwindcss` and
66
+ `@putdotio/design/css`, as in the [README](../README.md#use).
67
+
68
+ - The block is `@theme inline reference`: utilities read the put.io custom
69
+ property, so `.dark` works. In custom CSS, read the put.io name (`var(--bg)`),
70
+ not `var(--color-bg)`.
71
+ - `text-*` sizes set no line height; `--lh-normal` applies until a `leading-*`
72
+ utility sets one.
73
+ - `--spacing` is `var(--space-1)`, so `p-4` is 16px and equals `--space-4`.
74
+ - z-indexes, breakpoints, and the `tv` group except `--radius-tv` stay out.
75
+ Tailwind defaults that put.io does not define, such as `rounded-xl`, stay
76
+ available.
@@ -0,0 +1,9 @@
1
+ <!--
2
+ 108dp adaptive-icon grid, at the colour icon's scale (its 1024 master fills
3
+ the 72dp centre). Paths carry no fill: the platform tints them.
4
+ -->
5
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 108 108">
6
+ <path fill-rule="evenodd" d="M34.594 44.508H35.651V40.289H36.709V38.18H37.766V37.125H38.823V36.07H39.881V33.961H41.996V32.906H43.053V31.852H45.168V30.797H47.283V29.742L58.915 29.742V30.797H61.029V31.852H63.144V32.906H65.259V33.961H66.316V35.016H67.374V36.07H68.431V38.18H69.489V40.289H70.546V42.398H71.604V52.945H70.546V56.109H69.489V58.219H68.431V59.273H67.374V60.328H66.316V61.383H65.259V62.438H64.202V63.492H62.087V64.547H59.972V65.602H55.742V66.656H45.168V67.711H44.111V72.984H43.053V74.039H41.996V75.094H36.709V74.039H35.651V72.984H34.594L34.594 44.508ZM46.225 44.508V42.398H47.283V41.344H49.397V40.289H51.512V39.234H54.685V40.289H57.857V41.344H58.914V42.398H59.972V44.508H61.029V50.836H59.972V51.891H58.914V52.945H57.857V54H56.8V55.055H49.397V54H48.34V52.945H47.283V51.891H46.225V49.781H45.168V44.508H46.225Z"/>
7
+ <path d="M50.455 43.453H48.34V45.562H47.283V48.727H48.34V50.836H49.398V48.727H50.455V46.617H51.513V45.562H53.627V44.508H55.742V43.453H56.8V42.398H53.627V41.344H52.57V42.398H50.455V43.453Z"/>
8
+ <path d="M74.776 44.508H73.719V54H72.662V57.164H71.604V59.273H70.546V60.328H69.489V61.383H68.432V62.438H67.374V63.492H66.317V64.547H65.259V65.602H63.145V66.656H61.03V67.711H56.8V68.766H46.226L46.226 74.039H45.168V75.094H44.111V76.148H43.053V77.203H39.881V78.258H40.939V79.312H46.226V78.258H47.283V77.203H48.341V71.93H49.398V70.875H59.972V69.82H64.202V68.766H66.317V67.711H68.432V66.656H69.489V65.602H70.546V64.547H71.604V63.492H72.662V62.438H73.719V60.328H74.776V57.164H75.834V46.617H74.776V44.508Z"/>
9
+ </svg>