@hugocxl/design-system 0.1.0 → 0.2.7

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/DESIGN.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  version: alpha
3
3
  name: Design system
4
- description: Text-led, technical design system. Large reading type, hairline figures, mono labels and one scarce orange accent.
4
+ description: The personal design system of @hugocxl, the signature shared by every @hugocxl project. Large reading type, vectors and icons from the @hugocxl stack, mono labels and one scarce orange accent.
5
5
  colors:
6
6
  primary: "#171717"
7
7
  accent: "#fe9369"
@@ -13,6 +13,22 @@ colors:
13
13
  rule: "#1717171f"
14
14
  surface: "#ebebea"
15
15
  accent-text: "#ce7755"
16
+ red: "#c43d3d"
17
+ orange: "#bb702f"
18
+ yellow: "#a08005"
19
+ green: "#419445"
20
+ teal: "#378f99"
21
+ sky: "#388cb0"
22
+ blue: "#3f83ce"
23
+ violet: "#633cc7"
24
+ purple: "#993ab8"
25
+ pink: "#c23b62"
26
+ brown: "#8f6d53"
27
+ success: "#419445"
28
+ warning: "#a08005"
29
+ error: "#c43d3d"
30
+ info: "#3f83ce"
31
+ neutral: "#6e6e6e"
16
32
  dark:
17
33
  canvas: "#111111"
18
34
  ink: "#ededed"
@@ -21,6 +37,22 @@ colors:
21
37
  rule: "#ededed24"
22
38
  surface: "#1c1c1c"
23
39
  accent-text: "#fe9369"
40
+ red: "#c43d3d"
41
+ orange: "#c77b3b"
42
+ yellow: "#ceab3c"
43
+ green: "#4b9d4e"
44
+ teal: "#4da3ad"
45
+ sky: "#4c9fc3"
46
+ blue: "#3f83ce"
47
+ violet: "#7350dc"
48
+ purple: "#9e3fbd"
49
+ pink: "#c23b62"
50
+ brown: "#8f6d53"
51
+ success: "#4b9d4e"
52
+ warning: "#ceab3c"
53
+ error: "#c43d3d"
54
+ info: "#3f83ce"
55
+ neutral: "#7d7d7d"
24
56
  typography:
25
57
  title:
26
58
  fontFamily: Geist Sans
@@ -116,6 +148,18 @@ components:
116
148
  status-dot:
117
149
  backgroundColor: "{colors.accent}"
118
150
  rounded: "{rounded.pill}"
151
+ status-dot-success:
152
+ backgroundColor: "{colors.light.success}"
153
+ rounded: "{rounded.pill}"
154
+ status-dot-warning:
155
+ backgroundColor: "{colors.light.warning}"
156
+ rounded: "{rounded.pill}"
157
+ status-dot-error:
158
+ backgroundColor: "{colors.light.error}"
159
+ rounded: "{rounded.pill}"
160
+ status-dot-info:
161
+ backgroundColor: "{colors.light.info}"
162
+ rounded: "{rounded.pill}"
119
163
  statement-accent:
120
164
  textColor: "{colors.light.accent-text}"
121
165
  typography: "{typography.title}"
@@ -135,15 +179,15 @@ components:
135
179
  ---
136
180
  ## Overview
137
181
 
138
- This is the @hugocxl design system for text-led technical websites. Large reading type leads every page. Hairline drawings and monospaced labels make it feel engineered, and a single orange accent appears at most twice per page. The visual reference is Superlogical: its paper and orange, its 21 px reading size, its centered or left-aligned column with a textured field, and its mono footer.
182
+ This is the personal design system of @hugocxl: the signature shared by every @hugocxl project, so each one reads as part of the same body of work. Large reading type leads every page. Line vectors from `@hugocxl/vectors`, icons from `@hugocxl/icons` and monospaced labels make it feel engineered, and a single orange accent appears at most twice per page. The visual reference is Superlogical: its paper and orange, its 21 px reading size, its centered or left-aligned column with a textured field, and its mono footer.
139
183
 
140
184
  This file and [index.html](index.html) define the system completely. Anything not described here is not part of the system. When you build a page:
141
185
 
142
186
  1. Pick a recipe from [Page recipes](#page-recipes). The recipe sets the layout and the order of components.
143
- 2. For each block, copy the component markup from [Components](#components) exactly. Change only text, links, figure names and IDs.
187
+ 2. For each block, copy the component markup from [Components](#components) exactly. Change only text, links, vector and icon names and IDs.
144
188
  3. Check the result against [Do's and Don'ts](#dos-and-donts).
145
189
 
146
- Files: `system/p9.css` (all styles), `system/theme.js` (theme, loaded in the head), `system/p9.js` (figures and copy buttons, loaded as a module), `system/figures/` (33 hairline drawings, or [vectors](#vectors) from `@hugocxl/vectors`), `system/fonts/`, `system/images/gray-folds.png` (field texture) and `system/plan.schema.json` (page plan schema). They ship together in the npm package `@hugocxl/design-system`.
190
+ Files: `system/ds.css` (all styles), `system/theme.js` (theme, loaded in the head), `system/ds.js` (copy buttons, loaded as a module), `system/fonts/`, `system/images/gray-folds.png` (field texture) and `system/plan.schema.json` (page plan schema). They ship together in the npm package `@hugocxl/design-system`. The package also ships the tokens alone for other stacks, generated from `system/ds.css`: `@hugocxl/design-system/tailwind` (Tailwind v4), `/tailwind-preset` (Tailwind v3), `/tokens.css` and `/fonts.css` (plain CSS), `pkg:@hugocxl/design-system/scss` (Sass) and `/tokens` or `/tokens.json` (JavaScript). In Tailwind, use the token utilities (`bg-canvas`, `text-ink`, `text-reading`, `p-space-5`, `rounded-media`, `max-w-measure`) and never Tailwind's default palette, sizes or radii. Figures come from [`@hugocxl/vectors`](#vectors) and icons from [`@hugocxl/icons`](#icons); no other artwork is part of the system.
147
191
 
148
192
  ```html
149
193
  <!doctype html>
@@ -152,14 +196,14 @@ Files: `system/p9.css` (all styles), `system/theme.js` (theme, loaded in the hea
152
196
  <meta charset="utf-8">
153
197
  <meta name="viewport" content="width=device-width,initial-scale=1">
154
198
  <title>Page title</title>
155
- <link rel="stylesheet" href="system/p9.css">
199
+ <link rel="stylesheet" href="system/ds.css">
156
200
  <script src="system/theme.js"></script>
157
- <script type="module" src="system/p9.js"></script>
201
+ <script type="module" src="system/ds.js"></script>
158
202
  </head>
159
- <body class="p9" data-layout="plain">
203
+ <body class="ds" data-layout="plain">
160
204
  <!-- masthead -->
161
205
  <main>
162
- <article class="p9-column p9-opening">
206
+ <article class="ds-column ds-opening">
163
207
  <!-- title, meta, sections, figures, form … in recipe order -->
164
208
  </article>
165
209
  </main>
@@ -170,7 +214,7 @@ Files: `system/p9.css` (all styles), `system/theme.js` (theme, loaded in the hea
170
214
 
171
215
  ## Colors
172
216
 
173
- The paper and orange come from Superlogical, and the greys are neutral. Use colors only through these roles. The CSS custom property is `--p9-<role>`, and each one switches with `data-theme` on `<html>`.
217
+ The paper and orange come from Superlogical, and the greys are neutral. Use colors only through these roles. The CSS custom property is `--ds-<role>`, and each one switches with `data-theme` on `<html>`.
174
218
 
175
219
  | Role | Light | Dark | Use |
176
220
  | --- | --- | --- | --- |
@@ -180,12 +224,64 @@ The paper and orange come from Superlogical, and the greys are neutral. Use colo
180
224
  | `faint` | `#b3b3b3` | `#737373` | Placeholder text only |
181
225
  | `rule` | `#1717171f` | `#ededed24` | Hairlines and borders |
182
226
  | `surface` | `#ebebea` | `#1c1c1c` | Figure media and code backgrounds |
183
- | `accent` | `#fe9369` | `#fe9369` | The status dot (`.p9-dot`) |
184
- | `accent-text` | `#ce7755` | `#fe9369` | One phrase at title size (`.p9-accent`) |
227
+ | `accent` | `#fe9369` | `#fe9369` | The status dot (`.ds-dot`) |
228
+ | `accent-text` | `#ce7755` | `#fe9369` | One phrase at title size (`.ds-accent`) |
185
229
 
186
230
  The system keeps Superlogical's warm paper and orange but uses neutral greys instead of its green-tinted ink and muted tones. Superlogical's muted grey `#b3b3b3` fails WCAG AA for text, so it survives only as the light `faint` for placeholders, and `muted` is set to reach 4.5:1. The orange reaches 3:1 on paper only at title size, which is why `accent-text` exists and is used only there.
187
231
 
188
- **Accent budget:** at most two accent elements per page. That is one `.p9-accent` phrase of two or three words at the end of the `statement`, and one `.p9-dot` before a status label in `meta`. The accent never colors body text, links, buttons, backgrounds, rules or figures.
232
+ **Accent budget:** at most two accent elements per page. That is one `.ds-accent` phrase of two or three words at the end of the `statement`, and one `.ds-dot` before a status label in `meta`. The accent never colors body text, links, buttons, backgrounds, rules or figures.
233
+
234
+ ### Hues
235
+
236
+ Eleven hues color marks: [colored icons](#colored-icons) and status dots. They take after the [diffs.com icon palette](https://diffs.com/icons). The dark values are the reference's own, with violet and purple lifted to reach contrast. The light values are deepened along the same hue. Every hue reaches 3:1, the WCAG minimum for non-text marks, on both `canvas` and `surface` in its theme. The CSS custom property is `--ds-<hue>`.
237
+
238
+ | Hue | Light | Dark | For example |
239
+ | --- | --- | --- | --- |
240
+ | `red` | `#c43d3d` | `#c43d3d` | npm, Ruby, YAML, errors |
241
+ | `orange` | `#bb702f` | `#c77b3b` | HTML, Rust, Swift, RSS |
242
+ | `yellow` | `#a08005` | `#ceab3c` | JavaScript, folders, archives, warnings |
243
+ | `green` | `#419445` | `#4b9d4e` | Shell, tables, Vue, success |
244
+ | `teal` | `#378f99` | `#4da3ad` | Prettier, formatters |
245
+ | `sky` | `#388cb0` | `#4c9fc3` | Go, React, servers, layers |
246
+ | `blue` | `#3f83ce` | `#3f83ce` | TypeScript, C, Docker, code, information |
247
+ | `violet` | `#633cc7` | `#7350dc` | CSS, ESLint, Bootstrap, WebAssembly |
248
+ | `purple` | `#993ab8` | `#9e3fbd` | Vite, Astro, fonts, MCP |
249
+ | `pink` | `#c23b62` | `#c23b62` | GraphQL, Sass, images |
250
+ | `brown` | `#8f6d53` | `#8f6d53` | Bun |
251
+
252
+ Grey is not a hue: an uncolored icon takes the text color, and `neutral` covers the grey status.
253
+
254
+ - Hues color marks only: an icon (`.ds-icon`) or a dot (`.ds-dot`). Never text, links, buttons, backgrounds, rules, figures or vectors.
255
+ - A hue names a kind of thing, the same one everywhere: a language, a tool, a file type or a brand. Never pick a hue for decoration or variety.
256
+ - The hues are not the accent. `orange` is a file-type color, and it never replaces `accent`. Hues do not count toward the accent budget.
257
+
258
+ ### Status
259
+
260
+ Five roles give a hue a meaning. Each is an alias, `--ds-<role>`, so it follows the theme.
261
+
262
+ | Role | Hue | Light | Dark | Means |
263
+ | --- | --- | --- | --- | --- |
264
+ | `success` | `green` | `#419445` | `#4b9d4e` | Done, live, passing, confirmed |
265
+ | `warning` | `yellow` | `#a08005` | `#ceab3c` | Needs attention soon but still works |
266
+ | `error` | `red` | `#c43d3d` | `#c43d3d` | Failed, down, invalid, blocked |
267
+ | `info` | `blue` | `#3f83ce` | `#3f83ce` | Scheduled, planned, worth knowing |
268
+ | `neutral` | `muted` | `#6e6e6e` | `#7d7d7d` | Inactive: draft, paused, archived |
269
+
270
+ Set `data-status` on a `.ds-dot`, a `.ds-icon` or the form's `.ds-feedback` and it takes the role's color. A `.ds-dot` without `data-status` stays the accent.
271
+
272
+ | Status label | Role | Mark |
273
+ | --- | --- | --- |
274
+ | Live, Stable, Operational, Shipped, Paid, Sent | `success` | dot, or `circle-check` |
275
+ | Degraded, Deprecated, Expiring, Limited | `warning` | dot, or `triangle-alert` |
276
+ | Down, Failed, Removed, Overdue, Invalid | `error` | dot, or `circle-x` |
277
+ | Planned, Scheduled, Maintenance, Preview | `info` | dot, or `circle-info` |
278
+ | Draft, Paused, Archived, Unlisted | `neutral` | dot |
279
+ | Beta, New (the page's own status in `meta`) | accent | `.ds-dot` without `data-status` |
280
+
281
+ - Color never carries a status alone. The words always name it, and the dot or icon goes before them.
282
+ - Status text stays `ink`, or `muted` where the component already uses it. Only the mark takes the color.
283
+ - One status per element and one mark per status: a dot or an icon, never both.
284
+ - A status mark goes where a status label goes: a `meta` label, an `index` label, a table cell or the form feedback line.
189
285
 
190
286
  ## Typography
191
287
 
@@ -201,16 +297,16 @@ Geist Sans for everything people read and Geist Mono for labels, dates and code.
201
297
  | mono | 15px mono | 400 | 1.4 | 0 | Footer links |
202
298
  | control | 16px | 400 | 1 | −0.01em | Button text |
203
299
 
204
- Supporting sentences follow the main thought in the same paragraph, wrapped in `<span class="p9-muted">`. Write in sentence case.
300
+ Supporting sentences follow the main thought in the same paragraph, wrapped in `<span class="ds-muted">`. Write in sentence case.
205
301
 
206
302
  ## Layout
207
303
 
208
- Set the layout with `data-layout` on `<body class="p9">`. There are two layouts:
304
+ Set the layout with `data-layout` on `<body class="ds">`. There are two layouts:
209
305
 
210
- - **`field`** is for home only. The column aligns to the left gutter. A fixed textured panel fills the right side at `clamp(30vw, 100vw − 2 × gutter − 47.6rem, 40vw)`, inset 12px with a 12px radius. At 760px and below the field becomes a 12px strip.
211
- - **`plain`** is for every other recipe. The column is centered, and wide figures are centered on the column.
306
+ - **`plain`** is the default for every page, home included. The column is centered, and wide figures are centered on the column. Nothing sits beside the content.
307
+ - **`field`** is an optional signature for a personal home page, such as hugocxl.me, and nowhere else. The column aligns to the left gutter and a fixed textured panel fills the right side at `clamp(30vw, 100vw − 2 × gutter − 47.6rem, 40vw)`, inset 12px with a 12px radius. At 760px and below the field becomes a 12px strip. Never use it on product, library or documentation sites.
212
308
 
213
- The column (`.p9-column`) is 30em of reading type, about 65 characters. `.p9-wide` elements (figures and grids) extend to `min(main width, 80rem)`. The gutter is `clamp(1.25rem, 4.5vw, 4rem)`. The opening padding is `clamp(80px, 8vw, 128px)`.
309
+ The column (`.ds-column`) is 30em of reading type, about 65 characters. `.ds-wide` elements (figures and grids) extend to `min(main width, 80rem)`. The gutter is `clamp(1.25rem, 4.5vw, 4rem)`. The opening padding is `clamp(80px, 8vw, 128px)`.
214
310
 
215
311
  Use only these ten spacing steps:
216
312
 
@@ -233,14 +329,14 @@ A recipe fixes the layout and the component order. `?` means optional, `+` one o
233
329
 
234
330
  | Recipe | Layout | Sequence |
235
331
  | --- | --- | --- |
236
- | `home` | field | `masthead statement meta? section (figure-wide \| figure-grid) section* (button \| form)? footer` |
332
+ | `home` | plain (field on a personal site) | `masthead statement meta? section (figure-wide \| figure-grid) section* (button \| form)? footer` |
237
333
  | `article` | plain | `masthead title meta section figure-wide? section+ form? footer` |
238
334
  | `docs` | plain | `masthead title meta? section (section \| figure-wide)* footer` |
239
335
  | `changelog` | plain | `masthead title section? index footer` |
240
336
  | `pricing` | plain | `masthead title section index table? section* button footer` |
241
337
  | `contact` | plain | `masthead title section form footer` |
242
338
 
243
- `masthead` goes before `<main>` and `footer` after it. All other components go inside `<article class="p9-column p9-opening">`, in order. The example home page in [index.html](index.html#recipes) is the reference output.
339
+ `masthead` goes before `<main>` and `footer` after it. All other components go inside `<article class="ds-column ds-opening">`, in order. The example home page in [index.html](index.html#recipes) is the reference output.
244
340
 
245
341
  ## Elevation & Depth
246
342
 
@@ -256,15 +352,15 @@ These thirteen components make up the whole vocabulary. Each markup block below
256
352
 
257
353
  ### `masthead`
258
354
 
259
- Wordmark, up to three text links, and the theme button. It is the first element in the body.
355
+ Wordmark, up to three text links, and the theme button with the `contrast` icon. It is the first element in the body.
260
356
 
261
357
  <!-- specimen:masthead -->
262
358
  ```html
263
- <header class="p9-masthead">
264
- <a class="p9-wordmark" href="/">Fieldwork</a>
359
+ <header class="ds-masthead">
360
+ <a class="ds-wordmark" href="/">Fieldwork</a>
265
361
  <a href="/changelog">Changelog</a>
266
362
  <a href="/docs">Docs</a>
267
- <button class="p9-theme" type="button" data-p9-theme aria-label="Switch theme">◐</button>
363
+ <button class="ds-theme" type="button" data-ds-theme aria-label="Switch theme"><svg class="ds-icon" data-icon="contrast" viewBox="0 0 16 16" fill="none" aria-hidden="true"><!-- paths from @hugocxl/icons --></svg></button>
268
364
  </header>
269
365
  ```
270
366
  <!-- /specimen -->
@@ -275,7 +371,7 @@ The page name in ink with a muted byline. Use it on every recipe except home. Th
275
371
 
276
372
  <!-- specimen:title -->
277
373
  ```html
278
- <hgroup class="p9-title">
374
+ <hgroup class="ds-title">
279
375
  <h1>Public testing is beginning</h1>
280
376
  <p>Fieldwork team</p>
281
377
  </hgroup>
@@ -288,19 +384,19 @@ Home only: one sentence at title size, ending with an optional accent phrase of
288
384
 
289
385
  <!-- specimen:statement -->
290
386
  ```html
291
- <h1 class="p9-statement">Field notes for teams that ship <span class="p9-accent">every day.</span></h1>
387
+ <h1 class="ds-statement">Field notes for teams that ship <span class="ds-accent">every day.</span></h1>
292
388
  ```
293
389
  <!-- /specimen -->
294
390
 
295
391
  ### `meta`
296
392
 
297
- One to three mono labels: status, version, date. Only a status label takes `.p9-dot`, and it comes first. Dates use `<time datetime>`.
393
+ One to three mono labels: status, version, date. Only a status label takes `.ds-dot`, and it comes first. The page's own status (Beta, New) uses the accent dot. A state from [Status](#status) sets `data-status` on the dot, as in `<span class="ds-dot" data-status="success" aria-hidden="true"></span>Operational`. Dates use `<time datetime>`.
298
394
 
299
395
  <!-- specimen:meta -->
300
396
  ```html
301
- <ul class="p9-meta">
302
- <li class="p9-label"><span class="p9-dot" aria-hidden="true"></span>Beta</li>
303
- <li class="p9-label"><time datetime="2026-10-05">5 October 2026</time></li>
397
+ <ul class="ds-meta">
398
+ <li class="ds-label"><span class="ds-dot" aria-hidden="true"></span>Beta</li>
399
+ <li class="ds-label"><time datetime="2026-10-05">5 October 2026</time></li>
304
400
  </ul>
305
401
  ```
306
402
  <!-- /specimen -->
@@ -311,9 +407,9 @@ A muted `h2` followed by paragraphs, lists, `code` or `table`. The lead section
311
407
 
312
408
  <!-- specimen:section -->
313
409
  ```html
314
- <section class="p9-section" id="what-is-available">
410
+ <section class="ds-section" id="what-is-available">
315
411
  <h2>What is available</h2>
316
- <p>Initially, testing is limited to the macOS application. <span class="p9-muted">Linux and Windows follow once the first wave is stable.</span></p>
412
+ <p>Initially, testing is limited to the macOS application. <span class="ds-muted">Linux and Windows follow once the first wave is stable.</span></p>
317
413
  <p>Read the <a href="/docs">documentation</a> for setup.</p>
318
414
  </section>
319
415
  ```
@@ -321,39 +417,39 @@ A muted `h2` followed by paragraphs, lists, `code` or `table`. The lead section
321
417
 
322
418
  ### `figure-wide`
323
419
 
324
- One drawing (`data-figure`) or `<img>` on the surface at 3:2, with a caption that reads `Fig. NN / Name`. A drawing needs an `aria-label` and an image needs `alt`. Add the pager only when the figure cycles.
420
+ One [vector](#vectors) or, for a product screenshot, an `<img>` on the surface at 3:2, with a caption that reads `Fig. NN / Name`. A vector keeps its `title`; an image needs `alt`. Add the pager, with `arrow-left` and `arrow-right` icons, only when the figure cycles.
325
421
 
326
422
  <!-- specimen:figure-wide -->
327
423
  ```html
328
- <figure class="p9-wide">
329
- <div class="p9-media"><div data-figure="terrain" aria-label="Isometric terrain drawing"></div></div>
330
- <figcaption class="p9-caption"><span class="p9-label">Fig. 01 / Terrain</span></figcaption>
424
+ <figure class="ds-wide">
425
+ <div class="ds-media"><svg class="ds-vector" data-vector="how-it-works" viewBox="0 0 480 360" role="img" fill="none" stroke="currentColor" stroke-width="1.05" stroke-linecap="round" stroke-linejoin="round"><title>How it works</title><!-- paths from @hugocxl/vectors --></svg></div>
426
+ <figcaption class="ds-caption"><span class="ds-label">Fig. 01 / How it works</span></figcaption>
331
427
  </figure>
332
428
  ```
333
429
  <!-- /specimen -->
334
430
 
335
431
  ### `figure-grid`
336
432
 
337
- Two to four drawings separated by hairlines. Each has a `Fig 0.N` label, a title of up to four words and one sentence. Set `data-columns` to the item count. The grid stacks when its container is narrower than 34rem.
433
+ Two to four [vectors](#vectors) separated by hairlines. Each has a `Fig 0.N` label, a title of up to four words and one sentence. Set `data-columns` to the item count. The grid stacks when its container is narrower than 34rem.
338
434
 
339
435
  <!-- specimen:figure-grid -->
340
436
  ```html
341
- <ul class="p9-grid p9-wide" data-columns="3">
437
+ <ul class="ds-grid ds-wide" data-columns="3">
342
438
  <li>
343
- <span class="p9-label">Fig 0.1</span>
344
- <div data-figure="stack" aria-label="Stacked layers drawing"></div>
439
+ <span class="ds-label">Fig 0.1</span>
440
+ <svg class="ds-vector" data-vector="modular-design" viewBox="0 0 480 360" role="img" fill="none" stroke="currentColor" stroke-width="1.05" stroke-linecap="round" stroke-linejoin="round"><title>Modular design</title><!-- paths from @hugocxl/vectors --></svg>
345
441
  <h3>Purpose-built</h3>
346
442
  <p>Shaped by the practices of teams who ship daily.</p>
347
443
  </li>
348
444
  <li>
349
- <span class="p9-label">Fig 0.2</span>
350
- <div data-figure="relay" aria-label="Relay drawing"></div>
445
+ <span class="ds-label">Fig 0.2</span>
446
+ <svg class="ds-vector" data-vector="handoff" viewBox="0 0 480 360" role="img" fill="none" stroke="currentColor" stroke-width="1.05" stroke-linecap="round" stroke-linejoin="round"><title>Handoff</title><!-- paths from @hugocxl/vectors --></svg>
351
447
  <h3>Shared by people and agents</h3>
352
448
  <p>From the first draft to the merged change.</p>
353
449
  </li>
354
450
  <li>
355
- <span class="p9-label">Fig 0.3</span>
356
- <div data-figure="terminal" aria-label="Terminal drawing"></div>
451
+ <span class="ds-label">Fig 0.3</span>
452
+ <svg class="ds-vector" data-vector="fast-performance" viewBox="0 0 480 360" role="img" fill="none" stroke="currentColor" stroke-width="1.05" stroke-linecap="round" stroke-linejoin="round"><title>Fast performance</title><!-- paths from @hugocxl/vectors --></svg>
357
453
  <h3>Designed for speed</h3>
358
454
  <p>Less noise, more momentum, every release.</p>
359
455
  </li>
@@ -361,7 +457,6 @@ Two to four drawings separated by hairlines. Each has a `Fig 0.N` label, a title
361
457
  ```
362
458
  <!-- /specimen -->
363
459
 
364
- Figure names: `basket`, `branches`, `cabinet`, `dish`, `drawer`, `elevator`, `exploded`, `format`, `hub`, `keyboard`, `laptop`, `lockers`, `loupe`, `padlock`, `patch`, `phone`, `phosphor`, `plot`, `plug`, `query`, `rail`, `rebuild`, `relay`, `riffle`, `router`, `settle`, `sieve`, `slow`, `stack`, `terminal`, `terrain`, `turntable`, `vault`.
365
460
 
366
461
  ### `index`
367
462
 
@@ -369,21 +464,21 @@ Rows divided by hairlines for changelogs, steps, plans and principles. The label
369
464
 
370
465
  <!-- specimen:index -->
371
466
  ```html
372
- <ol class="p9-index">
373
- <li><span class="p9-label"><time datetime="2026-11-12">12 Nov 2026</time></span><div><h3>Persistent sessions</h3><p>Sessions survive restarts and reconnect where you left them.</p></div></li>
374
- <li><span class="p9-label"><time datetime="2026-10-28">28 Oct 2026</time></span><div><h3>Remote hosts</h3><p>Connect to any machine running the server.</p></div></li>
467
+ <ol class="ds-index">
468
+ <li><span class="ds-label"><time datetime="2026-11-12">12 Nov 2026</time></span><div><h3>Persistent sessions</h3><p>Sessions survive restarts and reconnect where you left them.</p></div></li>
469
+ <li><span class="ds-label"><time datetime="2026-10-28">28 Oct 2026</time></span><div><h3>Remote hosts</h3><p>Connect to any machine running the server.</p></div></li>
375
470
  </ol>
376
471
  ```
377
472
  <!-- /specimen -->
378
473
 
379
474
  ### `table`
380
475
 
381
- Comparisons and specifications. Column headings use `scope="col"` and row headings use `scope="row"`. Always wrap the table in `.p9-table-scroll` with `tabindex="0"` so it can be scrolled by keyboard.
476
+ Comparisons and specifications. Column headings use `scope="col"` and row headings use `scope="row"`. Always wrap the table in `.ds-table-scroll` with `tabindex="0"` so it can be scrolled by keyboard.
382
477
 
383
478
  <!-- specimen:table -->
384
479
  ```html
385
- <div class="p9-table-scroll" tabindex="0">
386
- <table class="p9-table">
480
+ <div class="ds-table-scroll" tabindex="0">
481
+ <table class="ds-table">
387
482
  <thead><tr><th scope="col">Plan</th><th scope="col">Price</th><th scope="col">Hosts</th></tr></thead>
388
483
  <tbody>
389
484
  <tr><th scope="row">Personal</th><td>Free</td><td>3</td></tr>
@@ -400,44 +495,46 @@ The single filled action on a page. Use `<a>` for navigation and `<button type="
400
495
 
401
496
  <!-- specimen:button -->
402
497
  ```html
403
- <a class="p9-button" href="/download">Download for macOS</a>
498
+ <a class="ds-button" href="/download">Download for macOS</a>
404
499
  ```
405
500
  <!-- /specimen -->
406
501
 
407
502
  ### `form`
408
503
 
409
- A visible label, an underlined input with an icon submit button (`↩` or `→`, with an `aria-label`), optional help text and a live feedback line.
504
+ A visible label, an underlined input with an icon submit button (`corner-down-left` to send or `arrow-right` to go, with an `aria-label`), optional help text and a live feedback line.
410
505
 
411
506
  | State | Result |
412
507
  | --- | --- |
413
508
  | Idle | Placeholder in `faint`, feedback empty |
414
- | Invalid submit | Value kept, `aria-invalid="true"` on the input, the fix written in the feedback line |
415
- | Editing after an error | `aria-invalid` removed, feedback cleared |
416
- | Pending | Submit disabled, feedback reads “Sending…” |
417
- | Success | Feedback confirms in one sentence. Focus stays on the input. |
418
- | Failure | Value kept, feedback explains the failure and how to retry |
509
+ | Invalid submit | Value kept, `aria-invalid="true"` on the input (a wavy `error` underline), `data-status="error"` on the feedback, the fix written in the feedback line |
510
+ | Editing after an error | `aria-invalid` and `data-status` removed, feedback cleared |
511
+ | Pending | Submit disabled, no `data-status`, feedback reads “Sending…” |
512
+ | Success | `data-status="success"` on the feedback, which confirms in one sentence. Focus stays on the input. |
513
+ | Failure | Value kept, `data-status="error"` on the feedback, which explains the failure and how to retry |
514
+
515
+ With `data-status`, the feedback line starts with a dot in the status color. Its text stays `ink`.
419
516
 
420
517
  <!-- specimen:form -->
421
518
  ```html
422
- <form class="p9-form" action="/waitlist" method="post">
519
+ <form class="ds-form" action="/waitlist" method="post">
423
520
  <label for="waitlist-email">Sign up to secure your place in the waitlist</label>
424
- <div class="p9-input">
521
+ <div class="ds-input">
425
522
  <input type="email" id="waitlist-email" name="email" placeholder="you@example.com" required autocomplete="email" aria-describedby="waitlist-help waitlist-feedback">
426
- <button type="submit" aria-label="Join the waitlist">↩</button>
523
+ <button type="submit" aria-label="Join the waitlist"><svg class="ds-icon" data-icon="corner-down-left" viewBox="0 0 16 16" fill="none" aria-hidden="true"><!-- paths from @hugocxl/icons --></svg></button>
427
524
  </div>
428
- <p class="p9-help" id="waitlist-help">We’ll let you know when the beta is available.</p>
429
- <output class="p9-feedback" id="waitlist-feedback" aria-live="polite"></output>
525
+ <p class="ds-help" id="waitlist-help">We’ll let you know when the beta is available.</p>
526
+ <output class="ds-feedback" id="waitlist-feedback" aria-live="polite"></output>
430
527
  </form>
431
528
  ```
432
529
  <!-- /specimen -->
433
530
 
434
531
  ### `code`
435
532
 
436
- A command or snippet on the surface with a Copy button. `system/p9.js` handles the copy. `tabindex="0"` on `pre` keeps long lines scrollable by keyboard.
533
+ A command or snippet on the surface with a Copy button. `system/ds.js` handles the copy. `tabindex="0"` on `pre` keeps long lines scrollable by keyboard.
437
534
 
438
535
  <!-- specimen:code -->
439
536
  ```html
440
- <div class="p9-code"><pre tabindex="0"><code>brew install fieldwork</code></pre><button type="button">Copy</button></div>
537
+ <div class="ds-code"><pre tabindex="0"><code>brew install fieldwork</code></pre><button type="button">Copy</button></div>
441
538
  ```
442
539
  <!-- /specimen -->
443
540
 
@@ -447,7 +544,7 @@ Mono links at both ends with a hairline between them. It is the last element in
447
544
 
448
545
  <!-- specimen:footer -->
449
546
  ```html
450
- <footer class="p9-footer">
547
+ <footer class="ds-footer">
451
548
  <ul><li><a href="/press">Press kit</a></li></ul>
452
549
  <ul><li><a href="/privacy">Privacy</a></li><li><a href="https://x.com/fieldwork">@fieldwork</a></li></ul>
453
550
  </footer>
@@ -456,67 +553,110 @@ Mono links at both ends with a hairline between them. It is the last element in
456
553
 
457
554
  ## Icons and vectors
458
555
 
459
- Two companion libraries complete the system, and they are the only icons and illustrations a page may use. [Icons](https://hugocxl.github.io/icons/) label actions and [Vectors](https://hugocxl.github.io/vectors/) illustrate ideas. Both draw in `currentColor`, so they follow the theme and never touch the accent.
556
+ Pages draw with two companion libraries and nothing else. [`@hugocxl/icons`](https://hugocxl.github.io/icons/) label actions and [`@hugocxl/vectors`](https://hugocxl.github.io/vectors/) illustrate ideas. Both draw in `currentColor`, so they follow the theme and never touch the accent. Only an icon may take a color, from the [hues](#hues) or the [status roles](#status). No other icon set, illustration, emoji or symbol character may stand in for them.
460
557
 
461
558
  ```sh
462
559
  npm install @hugocxl/design-system @hugocxl/icons @hugocxl/vectors
463
560
  ```
464
561
 
562
+ In the markup above, `<!-- paths from @hugocxl/icons -->` and `<!-- paths from @hugocxl/vectors -->` mark where the SVG's own content goes. Copy it from the package: the JavaScript export of each name is the SVG as a string, and the React components render it directly.
563
+
465
564
  ### Icons
466
565
 
467
- Use the **Stroke** style from `@hugocxl/icons`, inline before the words of a link, the `button` or a `meta` label. Give the SVG `class="p9-icon"`: it sizes to `1em`, takes the text color and keeps `space-2` before the words.
566
+ Use the **Stroke** style. An icon either goes before the words of a link, the `button` or a `meta` label, or it is the whole content of an icon button that has an `aria-label`. Give the SVG `class="ds-icon"` and `data-icon` with its name: it sizes to `1em`, takes the text color and keeps `space-2` before the words. Inside an icon button the gap is removed.
468
567
 
469
568
  ```html
470
- <a href="/docs"><svg class="p9-icon" viewBox="0 0 16 16" fill="none" aria-hidden="true"><!-- paths from @hugocxl/icons, Stroke --></svg>Read the guide</a>
569
+ <!-- Before words -->
570
+ <a href="/docs"><svg class="ds-icon" data-icon="book-open" viewBox="0 0 16 16" fill="none" aria-hidden="true"><!-- paths from @hugocxl/icons --></svg>Read the guide</a>
571
+ <a class="ds-button" href="/browse"><svg class="ds-icon" data-icon="search" viewBox="0 0 16 16" fill="none" aria-hidden="true"><!-- paths from @hugocxl/icons --></svg>Browse icons</a>
572
+ <li class="ds-label"><svg class="ds-icon" data-icon="calendar" viewBox="0 0 16 16" fill="none" aria-hidden="true"><!-- paths from @hugocxl/icons --></svg><time datetime="2026-11-18">18 November 2026</time></li>
573
+
574
+ <!-- Alone, in an icon button -->
575
+ <button class="ds-theme" type="button" data-ds-theme aria-label="Switch theme"><svg class="ds-icon" data-icon="contrast" viewBox="0 0 16 16" fill="none" aria-hidden="true"><!-- paths from @hugocxl/icons --></svg></button>
471
576
  ```
472
577
 
473
578
  ```jsx
474
579
  import { BookOpenIcon } from '@hugocxl/icons/react/stroke';
475
580
 
476
- <a href="/docs"><BookOpenIcon className="p9-icon" />Read the guide</a>
581
+ <a href="/docs"><BookOpenIcon className="ds-icon" />Read the guide</a>
582
+ ```
583
+
584
+ | Place | Icon |
585
+ | --- | --- |
586
+ | Theme button | `contrast` |
587
+ | Pager | `arrow-left`, `arrow-right` |
588
+ | Form submit | `corner-down-left` to send, `arrow-right` to go |
589
+ | Search | `search` |
590
+ | External link | `arrow-up-right` |
591
+
592
+ - One icon per element. Before words it never replaces a word; alone it needs an `aria-label`.
593
+ - Only in links, the button, meta labels and icon buttons, plus [colored icons](#colored-icons) in index labels and table cells. Never in headings, the statement, body sentences or the footer.
594
+ - Icons carry `aria-hidden="true"`. The React components add it unless they receive an `aria-label`.
595
+ - Never in the accent color, and never draw arrows, ◐ or other symbols as text instead.
596
+
597
+ ### Colored icons
598
+
599
+ An icon takes a color only when the color carries meaning, in one of two ways:
600
+
601
+ - **Kind.** `data-color="<hue>"` marks what a thing is: a language, a tool, a file type or a brand, such as `folder` in `yellow` or `terminal` in `green`. Use the hue the icon library assigns to the icon, so the same thing has the same color everywhere. These icons label items in a list, an `index` label or a table cell.
602
+ - **Status.** `data-status="<role>"` marks a state, before the words that name it: `circle-check` for `success`, `triangle-alert` for `warning`, `circle-x` for `error`, `circle-info` for `info`.
603
+
604
+ ```html
605
+ <!-- Kind: what the item is -->
606
+ <td><svg class="ds-icon" data-icon="folder" data-color="yellow" viewBox="0 0 16 16" fill="none" aria-hidden="true"><!-- paths from @hugocxl/icons --></svg>components</td>
607
+
608
+ <!-- Status: the state, named by the words after it -->
609
+ <li class="ds-label"><svg class="ds-icon" data-icon="circle-check" data-status="success" viewBox="0 0 16 16" fill="none" aria-hidden="true"><!-- paths from @hugocxl/icons --></svg>Operational</li>
477
610
  ```
478
611
 
479
- - One icon per element, before its words. An icon never replaces a word; arrows and ◐ stay as text characters.
480
- - Only in links, the button and meta labels. Never in headings, the statement, body sentences, the masthead or the footer.
481
- - Decorative icons carry `aria-hidden="true"`. The React components add it unless they receive an `aria-label`.
482
- - Never in the accent color and never on a filled shape.
612
+ Colored icons can use the Duotone style, whose second layer is the same color at lower opacity, as well as Stroke. Everything else follows the icon rules above.
613
+
614
+ - Action icons, such as those in links, the button and icon buttons, are never colored. They take the text color.
615
+ - One color per icon, from the tokens. Never a hex value, a gradient or the accent.
616
+ - The words beside a colored icon always say what it means. Color alone never does.
483
617
 
484
618
  ### Vectors
485
619
 
486
- A vector from `@hugocxl/vectors` takes the place of a drawing in `figure-wide` or a `figure-grid` item. Inline the SVG, replace its root `xmlns` attribute with `class="p9-vector"` and remove its `color` attribute. It then draws in ink on the surface at its own 4:3 proportions.
620
+ Every figure is a vector from `@hugocxl/vectors`. It fills `figure-wide` and each `figure-grid` item, drawn in ink on the surface at its own 4:3 proportions. Inline the SVG, replace its root `xmlns` attribute with `class="ds-vector"` and `data-vector` with its name, and remove its `color` attribute.
487
621
 
488
622
  ```html
489
- <figure class="p9-wide">
490
- <div class="p9-media"><svg class="p9-vector" viewBox="0 0 480 360" role="img" fill="none" stroke="currentColor"><title>Modular design</title><desc>…</desc><!-- paths --></svg></div>
491
- <figcaption class="p9-caption"><span class="p9-label">Fig. 02 / Modular design</span></figcaption>
623
+ <figure class="ds-wide">
624
+ <div class="ds-media"><svg class="ds-vector" data-vector="modular-design" viewBox="0 0 480 360" role="img" fill="none" stroke="currentColor" stroke-width="1.05" stroke-linecap="round" stroke-linejoin="round"><title>Modular design</title><!-- paths from @hugocxl/vectors --></svg></div>
625
+ <figcaption class="ds-caption"><span class="ds-label">Fig. 02 / Modular design</span></figcaption>
492
626
  </figure>
493
627
  ```
494
628
 
495
- In a `figure-grid` item the vector replaces the `data-figure` element, between the label and the `h3`. In React, render the component with `className="p9-vector"`.
629
+ ```jsx
630
+ import { ModularDesignVector } from '@hugocxl/vectors/react/modular-design';
631
+
632
+ <div className="ds-media"><ModularDesignVector className="ds-vector" /></div>
633
+ ```
496
634
 
497
- - Choose a vector for what it means. The [vectors browser](https://hugocxl.github.io/vectors/browse.html) lists every one by use case. Name it in the caption.
498
- - Use one family of figures on a page: vectors or the built-in drawings, not both.
499
- - Keep the SVG's `title` and `desc`, or give it an `aria-label`.
635
+ - Choose a vector for what it means. The [vectors browser](https://hugocxl.github.io/vectors/browse.html) lists all 2,000 by use case. Name it in the caption.
636
+ - Keep the SVG's `title` and `desc`: they are its accessible name.
637
+ - Use an `<img>` only for a screenshot of the product itself.
500
638
  - Never crop a vector, color it with the accent or place it on the field.
639
+ - Use the `field` layout only on a personal home page.
501
640
 
502
641
  ## Do's and Don'ts
503
642
 
504
643
  ### Always
505
644
 
506
- - Load `system/p9.css` and `system/theme.js` in the head and `system/p9.js` as a module.
507
- - Set `class="p9"` and the recipe's `data-layout` on the body.
508
- - Follow the recipe's component order. Copy component markup exactly and change only text, links, figure names and IDs.
645
+ - Load `system/ds.css` and `system/theme.js` in the head and `system/ds.js` as a module.
646
+ - Set `class="ds"` and the recipe's `data-layout` on the body.
647
+ - Follow the recipe's component order. Copy component markup exactly and change only text, links, vector and icon names and IDs.
509
648
  - Write in sentence case. Keep the title to one line and the statement to one sentence.
510
- - Put supporting sentences in `.p9-muted`, inline after the main thought. Text on `surface` is always `ink`, because muted falls below 4.5:1 there.
511
- - Give every drawing an `aria-label`, every image `alt` text and every field a visible label.
649
+ - Put supporting sentences in `.ds-muted`, inline after the main thought. Text on `surface` is always `ink`, because muted falls below 4.5:1 there.
650
+ - Keep every vector's `title`, give every icon button an `aria-label`, every image `alt` text and every field a visible label.
512
651
  - Check the page at 320, 760, 761 and 1440px wide in both themes.
513
652
 
514
653
  ### Never
515
654
 
516
655
  - Never add a class, color, font, size, weight, radius or spacing value that is not a token.
517
656
  - Never use the accent more than twice, or on body text, links, buttons, backgrounds, rules or figures.
657
+ - Never use a hue or status color on anything but an icon or a dot, or let color alone say what something is or what state it is in.
518
658
  - Never set text larger than the title or bolder than 500 (the wordmark is the exception).
519
- - Never use shadows, gradients, emoji, stock photography, or icons and illustrations from outside `@hugocxl/icons` and `@hugocxl/vectors`.
659
+ - Never use shadows, gradients, emoji, stock photography, symbol characters as icons, or icons and illustrations from outside `@hugocxl/icons` and `@hugocxl/vectors`.
520
660
  - Never place two filled buttons on one page.
521
661
  - Never center or justify text. Only the column itself is centered.
522
662
  - Never invent copy, links, numbers, quotes or logos the brief does not supply. If a required input is missing, ask for it.