@hugocxl/design-system 0.0.0-stage → 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 ADDED
@@ -0,0 +1,686 @@
1
+ ---
2
+ version: alpha
3
+ name: Design system
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
+ colors:
6
+ primary: "#171717"
7
+ accent: "#fe9369"
8
+ light:
9
+ canvas: "#f5f5f4"
10
+ ink: "#171717"
11
+ muted: "#6e6e6e"
12
+ faint: "#b3b3b3"
13
+ rule: "#1717171f"
14
+ surface: "#ebebea"
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"
32
+ dark:
33
+ canvas: "#111111"
34
+ ink: "#ededed"
35
+ muted: "#7d7d7d"
36
+ faint: "#737373"
37
+ rule: "#ededed24"
38
+ surface: "#1c1c1c"
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"
56
+ typography:
57
+ title:
58
+ fontFamily: Geist Sans
59
+ fontWeight: 500
60
+ lineHeight: 1.15
61
+ letterSpacing: -0.02em
62
+ reading:
63
+ fontFamily: Geist Sans
64
+ fontWeight: 300
65
+ lineHeight: 1.3
66
+ letterSpacing: -0.01em
67
+ heading:
68
+ fontFamily: Geist Sans
69
+ fontWeight: 400
70
+ lineHeight: 1.3
71
+ letterSpacing: -0.01em
72
+ small:
73
+ fontFamily: Geist Sans
74
+ fontWeight: 300
75
+ lineHeight: 1.4
76
+ control:
77
+ fontFamily: Geist Sans
78
+ fontSize: 16px
79
+ fontWeight: 400
80
+ letterSpacing: -0.01em
81
+ label:
82
+ fontFamily: Geist Mono
83
+ fontSize: 13px
84
+ fontWeight: 400
85
+ lineHeight: 1.5
86
+ letterSpacing: 0.08em
87
+ mono:
88
+ fontFamily: Geist Mono
89
+ fontSize: 15px
90
+ fontWeight: 400
91
+ lineHeight: 1.4
92
+ wordmark:
93
+ fontFamily: Geist Sans
94
+ fontSize: 18px
95
+ fontWeight: 600
96
+ letterSpacing: -0.055em
97
+ rounded:
98
+ control: 6px
99
+ media: 12px
100
+ pill: 999px
101
+ spacing:
102
+ space-1: 4px
103
+ space-2: 8px
104
+ space-3: 12px
105
+ space-4: 16px
106
+ space-5: 20px
107
+ space-6: 32px
108
+ space-7: 40px
109
+ space-8: 56px
110
+ space-9: 80px
111
+ space-10: 128px
112
+ paragraph: 20px
113
+ section: 40px
114
+ figure: 56px
115
+ target: 44px
116
+ measure: 30em
117
+ wide: 80rem
118
+ components:
119
+ button:
120
+ backgroundColor: "{colors.light.ink}"
121
+ textColor: "{colors.light.canvas}"
122
+ typography: "{typography.control}"
123
+ rounded: "{rounded.control}"
124
+ height: "{spacing.target}"
125
+ padding: "{spacing.space-5}"
126
+ button-dark:
127
+ backgroundColor: "{colors.dark.ink}"
128
+ textColor: "{colors.dark.canvas}"
129
+ typography: "{typography.control}"
130
+ rounded: "{rounded.control}"
131
+ media:
132
+ backgroundColor: "{colors.light.surface}"
133
+ rounded: "{rounded.media}"
134
+ media-dark:
135
+ backgroundColor: "{colors.dark.surface}"
136
+ rounded: "{rounded.media}"
137
+ code:
138
+ backgroundColor: "{colors.light.surface}"
139
+ textColor: "{colors.light.ink}"
140
+ typography: "{typography.mono}"
141
+ rounded: "{rounded.control}"
142
+ label:
143
+ textColor: "{colors.light.muted}"
144
+ typography: "{typography.label}"
145
+ label-dark:
146
+ textColor: "{colors.dark.muted}"
147
+ typography: "{typography.label}"
148
+ status-dot:
149
+ backgroundColor: "{colors.accent}"
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}"
163
+ statement-accent:
164
+ textColor: "{colors.light.accent-text}"
165
+ typography: "{typography.title}"
166
+ statement-accent-dark:
167
+ textColor: "{colors.dark.accent-text}"
168
+ typography: "{typography.title}"
169
+ hairline:
170
+ backgroundColor: "{colors.light.rule}"
171
+ hairline-dark:
172
+ backgroundColor: "{colors.dark.rule}"
173
+ placeholder:
174
+ textColor: "{colors.light.faint}"
175
+ typography: "{typography.reading}"
176
+ placeholder-dark:
177
+ textColor: "{colors.dark.faint}"
178
+ typography: "{typography.reading}"
179
+ ---
180
+ ## Overview
181
+
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.
183
+
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:
185
+
186
+ 1. Pick a recipe from [Page recipes](#page-recipes). The recipe sets the layout and the order of components.
187
+ 2. For each block, copy the component markup from [Components](#components) exactly. Change only text, links, vector and icon names and IDs.
188
+ 3. Check the result against [Do's and Don'ts](#dos-and-donts).
189
+
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.
191
+
192
+ ```html
193
+ <!doctype html>
194
+ <html lang="en">
195
+ <head>
196
+ <meta charset="utf-8">
197
+ <meta name="viewport" content="width=device-width,initial-scale=1">
198
+ <title>Page title</title>
199
+ <link rel="stylesheet" href="system/ds.css">
200
+ <script src="system/theme.js"></script>
201
+ <script type="module" src="system/ds.js"></script>
202
+ </head>
203
+ <body class="ds" data-layout="plain">
204
+ <!-- masthead -->
205
+ <main>
206
+ <article class="ds-column ds-opening">
207
+ <!-- title, meta, sections, figures, form … in recipe order -->
208
+ </article>
209
+ </main>
210
+ <!-- footer -->
211
+ </body>
212
+ </html>
213
+ ```
214
+
215
+ ## Colors
216
+
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>`.
218
+
219
+ | Role | Light | Dark | Use |
220
+ | --- | --- | --- | --- |
221
+ | `canvas` | `#f5f5f4` | `#111111` | Page background |
222
+ | `ink` | `#171717` | `#ededed` | Text and the filled button |
223
+ | `muted` | `#6e6e6e` | `#7d7d7d` | Byline, section headings, labels, supporting sentences |
224
+ | `faint` | `#b3b3b3` | `#737373` | Placeholder text only |
225
+ | `rule` | `#1717171f` | `#ededed24` | Hairlines and borders |
226
+ | `surface` | `#ebebea` | `#1c1c1c` | Figure media and code backgrounds |
227
+ | `accent` | `#fe9369` | `#fe9369` | The status dot (`.ds-dot`) |
228
+ | `accent-text` | `#ce7755` | `#fe9369` | One phrase at title size (`.ds-accent`) |
229
+
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.
231
+
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.
285
+
286
+ ## Typography
287
+
288
+ Geist Sans for everything people read and Geist Mono for labels, dates and code. Both are bundled as variable WOFF2 files. Use three weights: 300 for reading, 400 for headings and controls, and 500 for the title and `<strong>`. The wordmark alone uses 600.
289
+
290
+ | Style | Size | Weight | Line height | Tracking | Use |
291
+ | --- | --- | --- | --- | --- | --- |
292
+ | title | `1.4 × reading` (≈ 29.7px at 1440) | 500 | 1.15 | −0.02em | `title`, `statement`. The largest text on any page. |
293
+ | reading | `min(1rem + 0.36vw, 1.54rem)` (≈ 21.2px at 1440) | 300 | 1.3 | −0.01em | Body text |
294
+ | heading | reading | 400, muted | 1.3 | −0.01em | Section `h2`, item `h3` (in ink) |
295
+ | small | `0.8 × reading` | 300 | 1.4 | −0.01em | Grid item text, table cells |
296
+ | label | 13px mono, uppercase | 400 | 1.5 | 0.08em | Dates, versions, figure captions, table headings |
297
+ | mono | 15px mono | 400 | 1.4 | 0 | Footer links |
298
+ | control | 16px | 400 | 1 | −0.01em | Button text |
299
+
300
+ Supporting sentences follow the main thought in the same paragraph, wrapped in `<span class="ds-muted">`. Write in sentence case.
301
+
302
+ ## Layout
303
+
304
+ Set the layout with `data-layout` on `<body class="ds">`. There are two layouts:
305
+
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.
308
+
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)`.
310
+
311
+ Use only these ten spacing steps:
312
+
313
+ | Token | Value | Role |
314
+ | --- | --- | --- |
315
+ | `space-1` | 4px | — |
316
+ | `space-2` | 8px | List items, label gaps, item title to text |
317
+ | `space-3` | 12px | Caption offset, table cell padding |
318
+ | `space-4` | 16px | Section heading to text |
319
+ | `space-5` | 20px | Between paragraphs |
320
+ | `space-6` | 32px | Title to meta, masthead top, grid gutter |
321
+ | `space-7` | 40px | Between sections, form top |
322
+ | `space-8` | 56px | Around wide figures, meta to lead |
323
+ | `space-9` | 80px | Above the footer |
324
+ | `space-10` | 128px | Largest opening |
325
+
326
+ ### Page recipes
327
+
328
+ A recipe fixes the layout and the component order. `?` means optional, `+` one or more, `*` zero or more and `|` one of. The first `section` after `title`, `statement` or `meta` has no heading and acts as the lead. Leave out an optional component when the brief has no content for it.
329
+
330
+ | Recipe | Layout | Sequence |
331
+ | --- | --- | --- |
332
+ | `home` | plain (field on a personal site) | `masthead statement meta? section (figure-wide \| figure-grid) section* (button \| form)? footer` |
333
+ | `article` | plain | `masthead title meta section figure-wide? section+ form? footer` |
334
+ | `docs` | plain | `masthead title meta? section (section \| figure-wide)* footer` |
335
+ | `changelog` | plain | `masthead title section? index footer` |
336
+ | `pricing` | plain | `masthead title section index table? section* button footer` |
337
+ | `contact` | plain | `masthead title section form footer` |
338
+
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.
340
+
341
+ ## Elevation & Depth
342
+
343
+ The system is flat. Group content with space and `rule` hairlines. The only fills are `surface` behind media and code, and `ink` behind the one button. Use no shadows, gradients or blur.
344
+
345
+ ## Shapes
346
+
347
+ Radii: 6px for the button, code blocks and table edges, 12px for media and the field, and a pill for the pager. Hairlines are 1px `rule`. Interactive targets are at least 44 × 44px. Focus is a 2px `ink` outline with a 3px offset.
348
+
349
+ ## Components
350
+
351
+ These thirteen components make up the whole vocabulary. Each markup block below is copied from the live specimen in `index.html` by `npm run sync`, so it is exactly what the reference renders. Keep every class and attribute.
352
+
353
+ ### `masthead`
354
+
355
+ Wordmark, up to three text links, and the theme button with the `contrast` icon. It is the first element in the body.
356
+
357
+ <!-- specimen:masthead -->
358
+ ```html
359
+ <header class="ds-masthead">
360
+ <a class="ds-wordmark" href="/">Fieldwork</a>
361
+ <a href="/changelog">Changelog</a>
362
+ <a href="/docs">Docs</a>
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>
364
+ </header>
365
+ ```
366
+ <!-- /specimen -->
367
+
368
+ ### `title`
369
+
370
+ The page name in ink with a muted byline. Use it on every recipe except home. The heading fits on one line.
371
+
372
+ <!-- specimen:title -->
373
+ ```html
374
+ <hgroup class="ds-title">
375
+ <h1>Public testing is beginning</h1>
376
+ <p>Fieldwork team</p>
377
+ </hgroup>
378
+ ```
379
+ <!-- /specimen -->
380
+
381
+ ### `statement`
382
+
383
+ Home only: one sentence at title size, ending with an optional accent phrase of two or three words.
384
+
385
+ <!-- specimen:statement -->
386
+ ```html
387
+ <h1 class="ds-statement">Field notes for teams that ship <span class="ds-accent">every day.</span></h1>
388
+ ```
389
+ <!-- /specimen -->
390
+
391
+ ### `meta`
392
+
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>`.
394
+
395
+ <!-- specimen:meta -->
396
+ ```html
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>
400
+ </ul>
401
+ ```
402
+ <!-- /specimen -->
403
+
404
+ ### `section`
405
+
406
+ A muted `h2` followed by paragraphs, lists, `code` or `table`. The lead section has no `h2`. Give a section an `id` when the page links to it.
407
+
408
+ <!-- specimen:section -->
409
+ ```html
410
+ <section class="ds-section" id="what-is-available">
411
+ <h2>What is available</h2>
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>
413
+ <p>Read the <a href="/docs">documentation</a> for setup.</p>
414
+ </section>
415
+ ```
416
+ <!-- /specimen -->
417
+
418
+ ### `figure-wide`
419
+
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.
421
+
422
+ <!-- specimen:figure-wide -->
423
+ ```html
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>
427
+ </figure>
428
+ ```
429
+ <!-- /specimen -->
430
+
431
+ ### `figure-grid`
432
+
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.
434
+
435
+ <!-- specimen:figure-grid -->
436
+ ```html
437
+ <ul class="ds-grid ds-wide" data-columns="3">
438
+ <li>
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>
441
+ <h3>Purpose-built</h3>
442
+ <p>Shaped by the practices of teams who ship daily.</p>
443
+ </li>
444
+ <li>
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>
447
+ <h3>Shared by people and agents</h3>
448
+ <p>From the first draft to the merged change.</p>
449
+ </li>
450
+ <li>
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>
453
+ <h3>Designed for speed</h3>
454
+ <p>Less noise, more momentum, every release.</p>
455
+ </li>
456
+ </ul>
457
+ ```
458
+ <!-- /specimen -->
459
+
460
+
461
+ ### `index`
462
+
463
+ Rows divided by hairlines for changelogs, steps, plans and principles. The label is a number (`01`), a date or a price.
464
+
465
+ <!-- specimen:index -->
466
+ ```html
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>
470
+ </ol>
471
+ ```
472
+ <!-- /specimen -->
473
+
474
+ ### `table`
475
+
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.
477
+
478
+ <!-- specimen:table -->
479
+ ```html
480
+ <div class="ds-table-scroll" tabindex="0">
481
+ <table class="ds-table">
482
+ <thead><tr><th scope="col">Plan</th><th scope="col">Price</th><th scope="col">Hosts</th></tr></thead>
483
+ <tbody>
484
+ <tr><th scope="row">Personal</th><td>Free</td><td>3</td></tr>
485
+ <tr><th scope="row">Team</th><td>€12 per seat / month</td><td>Unlimited</td></tr>
486
+ </tbody>
487
+ </table>
488
+ </div>
489
+ ```
490
+ <!-- /specimen -->
491
+
492
+ ### `button`
493
+
494
+ The single filled action on a page. Use `<a>` for navigation and `<button type="button">` for an in-place action. Every other action is an underlined text link.
495
+
496
+ <!-- specimen:button -->
497
+ ```html
498
+ <a class="ds-button" href="/download">Download for macOS</a>
499
+ ```
500
+ <!-- /specimen -->
501
+
502
+ ### `form`
503
+
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.
505
+
506
+ | State | Result |
507
+ | --- | --- |
508
+ | Idle | Placeholder in `faint`, feedback empty |
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`.
516
+
517
+ <!-- specimen:form -->
518
+ ```html
519
+ <form class="ds-form" action="/waitlist" method="post">
520
+ <label for="waitlist-email">Sign up to secure your place in the waitlist</label>
521
+ <div class="ds-input">
522
+ <input type="email" id="waitlist-email" name="email" placeholder="you@example.com" required autocomplete="email" aria-describedby="waitlist-help waitlist-feedback">
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>
524
+ </div>
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>
527
+ </form>
528
+ ```
529
+ <!-- /specimen -->
530
+
531
+ ### `code`
532
+
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.
534
+
535
+ <!-- specimen:code -->
536
+ ```html
537
+ <div class="ds-code"><pre tabindex="0"><code>brew install fieldwork</code></pre><button type="button">Copy</button></div>
538
+ ```
539
+ <!-- /specimen -->
540
+
541
+ ### `footer`
542
+
543
+ Mono links at both ends with a hairline between them. It is the last element in the body, after `</main>`.
544
+
545
+ <!-- specimen:footer -->
546
+ ```html
547
+ <footer class="ds-footer">
548
+ <ul><li><a href="/press">Press kit</a></li></ul>
549
+ <ul><li><a href="/privacy">Privacy</a></li><li><a href="https://x.com/fieldwork">@fieldwork</a></li></ul>
550
+ </footer>
551
+ ```
552
+ <!-- /specimen -->
553
+
554
+ ## Icons and vectors
555
+
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.
557
+
558
+ ```sh
559
+ npm install @hugocxl/design-system @hugocxl/icons @hugocxl/vectors
560
+ ```
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
+
564
+ ### Icons
565
+
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.
567
+
568
+ ```html
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>
576
+ ```
577
+
578
+ ```jsx
579
+ import { BookOpenIcon } from '@hugocxl/icons/react/stroke';
580
+
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>
610
+ ```
611
+
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.
617
+
618
+ ### Vectors
619
+
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.
621
+
622
+ ```html
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>
626
+ </figure>
627
+ ```
628
+
629
+ ```jsx
630
+ import { ModularDesignVector } from '@hugocxl/vectors/react/modular-design';
631
+
632
+ <div className="ds-media"><ModularDesignVector className="ds-vector" /></div>
633
+ ```
634
+
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.
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.
640
+
641
+ ## Do's and Don'ts
642
+
643
+ ### Always
644
+
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.
648
+ - Write in sentence case. Keep the title to one line and the statement to one sentence.
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.
651
+ - Check the page at 320, 760, 761 and 1440px wide in both themes.
652
+
653
+ ### Never
654
+
655
+ - Never add a class, color, font, size, weight, radius or spacing value that is not a token.
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.
658
+ - Never set text larger than the title or bolder than 500 (the wordmark is the exception).
659
+ - Never use shadows, gradients, emoji, stock photography, symbol characters as icons, or icons and illustrations from outside `@hugocxl/icons` and `@hugocxl/vectors`.
660
+ - Never place two filled buttons on one page.
661
+ - Never center or justify text. Only the column itself is centered.
662
+ - Never invent copy, links, numbers, quotes or logos the brief does not supply. If a required input is missing, ask for it.
663
+
664
+ ### Brief an agent
665
+
666
+ Give the agent this file at a pinned commit and a page plan. A page plan is JSON that validates against `system/plan.schema.json`. It names the recipe and layout and lists the blocks in order, with every slot filled. Validate the plan, check its sequence against the recipe, and then render each block from its component markup. The model's freedom stays in the plan, so the same plan and revision always produce the same page.
667
+
668
+ ```json
669
+ {
670
+ "designRevision": "<design-system commit SHA>",
671
+ "recipe": "changelog",
672
+ "layout": "plain",
673
+ "blocks": [
674
+ { "component": "masthead", "wordmark": "Fieldwork", "links": [{ "label": "Docs", "href": "/docs" }] },
675
+ { "component": "title", "heading": "Changelog", "byline": "What shipped, newest first" },
676
+ { "component": "index", "items": [
677
+ { "label": "12 Nov 2026", "datetime": "2026-11-12", "title": "Persistent sessions", "text": "Sessions survive restarts." }
678
+ ] },
679
+ { "component": "footer", "start": [{ "label": "Press kit", "href": "/press" }], "end": [] }
680
+ ]
681
+ }
682
+ ```
683
+
684
+ ### Verify
685
+
686
+ `npm test` lints this file, checks that its markup matches the specimens, and runs browser tests on the reference: computed tokens in both themes, column and figure geometry at 320, 760, 761 and 1440px, the accent budget, keyboard behavior and an axe WCAG 2.2 AA scan. For a generated page, check the same things plus the recipe order. To compare screenshots, fix the browser, viewport, scale, theme, locale and motion settings, and wait for fonts and figures to load.