@hugocxl/design-system 0.0.0-stage → 0.1.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/DESIGN.md ADDED
@@ -0,0 +1,546 @@
1
+ ---
2
+ version: alpha
3
+ name: Design system
4
+ description: Text-led, technical design system. Large reading type, hairline figures, 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
+ dark:
17
+ canvas: "#111111"
18
+ ink: "#ededed"
19
+ muted: "#7d7d7d"
20
+ faint: "#737373"
21
+ rule: "#ededed24"
22
+ surface: "#1c1c1c"
23
+ accent-text: "#fe9369"
24
+ typography:
25
+ title:
26
+ fontFamily: Geist Sans
27
+ fontWeight: 500
28
+ lineHeight: 1.15
29
+ letterSpacing: -0.02em
30
+ reading:
31
+ fontFamily: Geist Sans
32
+ fontWeight: 300
33
+ lineHeight: 1.3
34
+ letterSpacing: -0.01em
35
+ heading:
36
+ fontFamily: Geist Sans
37
+ fontWeight: 400
38
+ lineHeight: 1.3
39
+ letterSpacing: -0.01em
40
+ small:
41
+ fontFamily: Geist Sans
42
+ fontWeight: 300
43
+ lineHeight: 1.4
44
+ control:
45
+ fontFamily: Geist Sans
46
+ fontSize: 16px
47
+ fontWeight: 400
48
+ letterSpacing: -0.01em
49
+ label:
50
+ fontFamily: Geist Mono
51
+ fontSize: 13px
52
+ fontWeight: 400
53
+ lineHeight: 1.5
54
+ letterSpacing: 0.08em
55
+ mono:
56
+ fontFamily: Geist Mono
57
+ fontSize: 15px
58
+ fontWeight: 400
59
+ lineHeight: 1.4
60
+ wordmark:
61
+ fontFamily: Geist Sans
62
+ fontSize: 18px
63
+ fontWeight: 600
64
+ letterSpacing: -0.055em
65
+ rounded:
66
+ control: 6px
67
+ media: 12px
68
+ pill: 999px
69
+ spacing:
70
+ space-1: 4px
71
+ space-2: 8px
72
+ space-3: 12px
73
+ space-4: 16px
74
+ space-5: 20px
75
+ space-6: 32px
76
+ space-7: 40px
77
+ space-8: 56px
78
+ space-9: 80px
79
+ space-10: 128px
80
+ paragraph: 20px
81
+ section: 40px
82
+ figure: 56px
83
+ target: 44px
84
+ measure: 30em
85
+ wide: 80rem
86
+ components:
87
+ button:
88
+ backgroundColor: "{colors.light.ink}"
89
+ textColor: "{colors.light.canvas}"
90
+ typography: "{typography.control}"
91
+ rounded: "{rounded.control}"
92
+ height: "{spacing.target}"
93
+ padding: "{spacing.space-5}"
94
+ button-dark:
95
+ backgroundColor: "{colors.dark.ink}"
96
+ textColor: "{colors.dark.canvas}"
97
+ typography: "{typography.control}"
98
+ rounded: "{rounded.control}"
99
+ media:
100
+ backgroundColor: "{colors.light.surface}"
101
+ rounded: "{rounded.media}"
102
+ media-dark:
103
+ backgroundColor: "{colors.dark.surface}"
104
+ rounded: "{rounded.media}"
105
+ code:
106
+ backgroundColor: "{colors.light.surface}"
107
+ textColor: "{colors.light.ink}"
108
+ typography: "{typography.mono}"
109
+ rounded: "{rounded.control}"
110
+ label:
111
+ textColor: "{colors.light.muted}"
112
+ typography: "{typography.label}"
113
+ label-dark:
114
+ textColor: "{colors.dark.muted}"
115
+ typography: "{typography.label}"
116
+ status-dot:
117
+ backgroundColor: "{colors.accent}"
118
+ rounded: "{rounded.pill}"
119
+ statement-accent:
120
+ textColor: "{colors.light.accent-text}"
121
+ typography: "{typography.title}"
122
+ statement-accent-dark:
123
+ textColor: "{colors.dark.accent-text}"
124
+ typography: "{typography.title}"
125
+ hairline:
126
+ backgroundColor: "{colors.light.rule}"
127
+ hairline-dark:
128
+ backgroundColor: "{colors.dark.rule}"
129
+ placeholder:
130
+ textColor: "{colors.light.faint}"
131
+ typography: "{typography.reading}"
132
+ placeholder-dark:
133
+ textColor: "{colors.dark.faint}"
134
+ typography: "{typography.reading}"
135
+ ---
136
+ ## Overview
137
+
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.
139
+
140
+ 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
+
142
+ 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.
144
+ 3. Check the result against [Do's and Don'ts](#dos-and-donts).
145
+
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`.
147
+
148
+ ```html
149
+ <!doctype html>
150
+ <html lang="en">
151
+ <head>
152
+ <meta charset="utf-8">
153
+ <meta name="viewport" content="width=device-width,initial-scale=1">
154
+ <title>Page title</title>
155
+ <link rel="stylesheet" href="system/p9.css">
156
+ <script src="system/theme.js"></script>
157
+ <script type="module" src="system/p9.js"></script>
158
+ </head>
159
+ <body class="p9" data-layout="plain">
160
+ <!-- masthead -->
161
+ <main>
162
+ <article class="p9-column p9-opening">
163
+ <!-- title, meta, sections, figures, form … in recipe order -->
164
+ </article>
165
+ </main>
166
+ <!-- footer -->
167
+ </body>
168
+ </html>
169
+ ```
170
+
171
+ ## Colors
172
+
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>`.
174
+
175
+ | Role | Light | Dark | Use |
176
+ | --- | --- | --- | --- |
177
+ | `canvas` | `#f5f5f4` | `#111111` | Page background |
178
+ | `ink` | `#171717` | `#ededed` | Text and the filled button |
179
+ | `muted` | `#6e6e6e` | `#7d7d7d` | Byline, section headings, labels, supporting sentences |
180
+ | `faint` | `#b3b3b3` | `#737373` | Placeholder text only |
181
+ | `rule` | `#1717171f` | `#ededed24` | Hairlines and borders |
182
+ | `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`) |
185
+
186
+ 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
+
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.
189
+
190
+ ## Typography
191
+
192
+ 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.
193
+
194
+ | Style | Size | Weight | Line height | Tracking | Use |
195
+ | --- | --- | --- | --- | --- | --- |
196
+ | title | `1.4 × reading` (≈ 29.7px at 1440) | 500 | 1.15 | −0.02em | `title`, `statement`. The largest text on any page. |
197
+ | reading | `min(1rem + 0.36vw, 1.54rem)` (≈ 21.2px at 1440) | 300 | 1.3 | −0.01em | Body text |
198
+ | heading | reading | 400, muted | 1.3 | −0.01em | Section `h2`, item `h3` (in ink) |
199
+ | small | `0.8 × reading` | 300 | 1.4 | −0.01em | Grid item text, table cells |
200
+ | label | 13px mono, uppercase | 400 | 1.5 | 0.08em | Dates, versions, figure captions, table headings |
201
+ | mono | 15px mono | 400 | 1.4 | 0 | Footer links |
202
+ | control | 16px | 400 | 1 | −0.01em | Button text |
203
+
204
+ Supporting sentences follow the main thought in the same paragraph, wrapped in `<span class="p9-muted">`. Write in sentence case.
205
+
206
+ ## Layout
207
+
208
+ Set the layout with `data-layout` on `<body class="p9">`. There are two layouts:
209
+
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.
212
+
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)`.
214
+
215
+ Use only these ten spacing steps:
216
+
217
+ | Token | Value | Role |
218
+ | --- | --- | --- |
219
+ | `space-1` | 4px | — |
220
+ | `space-2` | 8px | List items, label gaps, item title to text |
221
+ | `space-3` | 12px | Caption offset, table cell padding |
222
+ | `space-4` | 16px | Section heading to text |
223
+ | `space-5` | 20px | Between paragraphs |
224
+ | `space-6` | 32px | Title to meta, masthead top, grid gutter |
225
+ | `space-7` | 40px | Between sections, form top |
226
+ | `space-8` | 56px | Around wide figures, meta to lead |
227
+ | `space-9` | 80px | Above the footer |
228
+ | `space-10` | 128px | Largest opening |
229
+
230
+ ### Page recipes
231
+
232
+ 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.
233
+
234
+ | Recipe | Layout | Sequence |
235
+ | --- | --- | --- |
236
+ | `home` | field | `masthead statement meta? section (figure-wide \| figure-grid) section* (button \| form)? footer` |
237
+ | `article` | plain | `masthead title meta section figure-wide? section+ form? footer` |
238
+ | `docs` | plain | `masthead title meta? section (section \| figure-wide)* footer` |
239
+ | `changelog` | plain | `masthead title section? index footer` |
240
+ | `pricing` | plain | `masthead title section index table? section* button footer` |
241
+ | `contact` | plain | `masthead title section form footer` |
242
+
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.
244
+
245
+ ## Elevation & Depth
246
+
247
+ 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.
248
+
249
+ ## Shapes
250
+
251
+ 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.
252
+
253
+ ## Components
254
+
255
+ 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.
256
+
257
+ ### `masthead`
258
+
259
+ Wordmark, up to three text links, and the theme button. It is the first element in the body.
260
+
261
+ <!-- specimen:masthead -->
262
+ ```html
263
+ <header class="p9-masthead">
264
+ <a class="p9-wordmark" href="/">Fieldwork</a>
265
+ <a href="/changelog">Changelog</a>
266
+ <a href="/docs">Docs</a>
267
+ <button class="p9-theme" type="button" data-p9-theme aria-label="Switch theme">◐</button>
268
+ </header>
269
+ ```
270
+ <!-- /specimen -->
271
+
272
+ ### `title`
273
+
274
+ The page name in ink with a muted byline. Use it on every recipe except home. The heading fits on one line.
275
+
276
+ <!-- specimen:title -->
277
+ ```html
278
+ <hgroup class="p9-title">
279
+ <h1>Public testing is beginning</h1>
280
+ <p>Fieldwork team</p>
281
+ </hgroup>
282
+ ```
283
+ <!-- /specimen -->
284
+
285
+ ### `statement`
286
+
287
+ Home only: one sentence at title size, ending with an optional accent phrase of two or three words.
288
+
289
+ <!-- specimen:statement -->
290
+ ```html
291
+ <h1 class="p9-statement">Field notes for teams that ship <span class="p9-accent">every day.</span></h1>
292
+ ```
293
+ <!-- /specimen -->
294
+
295
+ ### `meta`
296
+
297
+ One to three mono labels: status, version, date. Only a status label takes `.p9-dot`, and it comes first. Dates use `<time datetime>`.
298
+
299
+ <!-- specimen:meta -->
300
+ ```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>
304
+ </ul>
305
+ ```
306
+ <!-- /specimen -->
307
+
308
+ ### `section`
309
+
310
+ 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.
311
+
312
+ <!-- specimen:section -->
313
+ ```html
314
+ <section class="p9-section" id="what-is-available">
315
+ <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>
317
+ <p>Read the <a href="/docs">documentation</a> for setup.</p>
318
+ </section>
319
+ ```
320
+ <!-- /specimen -->
321
+
322
+ ### `figure-wide`
323
+
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.
325
+
326
+ <!-- specimen:figure-wide -->
327
+ ```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>
331
+ </figure>
332
+ ```
333
+ <!-- /specimen -->
334
+
335
+ ### `figure-grid`
336
+
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.
338
+
339
+ <!-- specimen:figure-grid -->
340
+ ```html
341
+ <ul class="p9-grid p9-wide" data-columns="3">
342
+ <li>
343
+ <span class="p9-label">Fig 0.1</span>
344
+ <div data-figure="stack" aria-label="Stacked layers drawing"></div>
345
+ <h3>Purpose-built</h3>
346
+ <p>Shaped by the practices of teams who ship daily.</p>
347
+ </li>
348
+ <li>
349
+ <span class="p9-label">Fig 0.2</span>
350
+ <div data-figure="relay" aria-label="Relay drawing"></div>
351
+ <h3>Shared by people and agents</h3>
352
+ <p>From the first draft to the merged change.</p>
353
+ </li>
354
+ <li>
355
+ <span class="p9-label">Fig 0.3</span>
356
+ <div data-figure="terminal" aria-label="Terminal drawing"></div>
357
+ <h3>Designed for speed</h3>
358
+ <p>Less noise, more momentum, every release.</p>
359
+ </li>
360
+ </ul>
361
+ ```
362
+ <!-- /specimen -->
363
+
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
+
366
+ ### `index`
367
+
368
+ Rows divided by hairlines for changelogs, steps, plans and principles. The label is a number (`01`), a date or a price.
369
+
370
+ <!-- specimen:index -->
371
+ ```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>
375
+ </ol>
376
+ ```
377
+ <!-- /specimen -->
378
+
379
+ ### `table`
380
+
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.
382
+
383
+ <!-- specimen:table -->
384
+ ```html
385
+ <div class="p9-table-scroll" tabindex="0">
386
+ <table class="p9-table">
387
+ <thead><tr><th scope="col">Plan</th><th scope="col">Price</th><th scope="col">Hosts</th></tr></thead>
388
+ <tbody>
389
+ <tr><th scope="row">Personal</th><td>Free</td><td>3</td></tr>
390
+ <tr><th scope="row">Team</th><td>€12 per seat / month</td><td>Unlimited</td></tr>
391
+ </tbody>
392
+ </table>
393
+ </div>
394
+ ```
395
+ <!-- /specimen -->
396
+
397
+ ### `button`
398
+
399
+ 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.
400
+
401
+ <!-- specimen:button -->
402
+ ```html
403
+ <a class="p9-button" href="/download">Download for macOS</a>
404
+ ```
405
+ <!-- /specimen -->
406
+
407
+ ### `form`
408
+
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.
410
+
411
+ | State | Result |
412
+ | --- | --- |
413
+ | 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 |
419
+
420
+ <!-- specimen:form -->
421
+ ```html
422
+ <form class="p9-form" action="/waitlist" method="post">
423
+ <label for="waitlist-email">Sign up to secure your place in the waitlist</label>
424
+ <div class="p9-input">
425
+ <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>
427
+ </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>
430
+ </form>
431
+ ```
432
+ <!-- /specimen -->
433
+
434
+ ### `code`
435
+
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.
437
+
438
+ <!-- specimen:code -->
439
+ ```html
440
+ <div class="p9-code"><pre tabindex="0"><code>brew install fieldwork</code></pre><button type="button">Copy</button></div>
441
+ ```
442
+ <!-- /specimen -->
443
+
444
+ ### `footer`
445
+
446
+ Mono links at both ends with a hairline between them. It is the last element in the body, after `</main>`.
447
+
448
+ <!-- specimen:footer -->
449
+ ```html
450
+ <footer class="p9-footer">
451
+ <ul><li><a href="/press">Press kit</a></li></ul>
452
+ <ul><li><a href="/privacy">Privacy</a></li><li><a href="https://x.com/fieldwork">@fieldwork</a></li></ul>
453
+ </footer>
454
+ ```
455
+ <!-- /specimen -->
456
+
457
+ ## Icons and vectors
458
+
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.
460
+
461
+ ```sh
462
+ npm install @hugocxl/design-system @hugocxl/icons @hugocxl/vectors
463
+ ```
464
+
465
+ ### Icons
466
+
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.
468
+
469
+ ```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>
471
+ ```
472
+
473
+ ```jsx
474
+ import { BookOpenIcon } from '@hugocxl/icons/react/stroke';
475
+
476
+ <a href="/docs"><BookOpenIcon className="p9-icon" />Read the guide</a>
477
+ ```
478
+
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.
483
+
484
+ ### Vectors
485
+
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.
487
+
488
+ ```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>
492
+ </figure>
493
+ ```
494
+
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"`.
496
+
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`.
500
+ - Never crop a vector, color it with the accent or place it on the field.
501
+
502
+ ## Do's and Don'ts
503
+
504
+ ### Always
505
+
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.
509
+ - 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.
512
+ - Check the page at 320, 760, 761 and 1440px wide in both themes.
513
+
514
+ ### Never
515
+
516
+ - Never add a class, color, font, size, weight, radius or spacing value that is not a token.
517
+ - Never use the accent more than twice, or on body text, links, buttons, backgrounds, rules or figures.
518
+ - 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`.
520
+ - Never place two filled buttons on one page.
521
+ - Never center or justify text. Only the column itself is centered.
522
+ - Never invent copy, links, numbers, quotes or logos the brief does not supply. If a required input is missing, ask for it.
523
+
524
+ ### Brief an agent
525
+
526
+ 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.
527
+
528
+ ```json
529
+ {
530
+ "designRevision": "<design-system commit SHA>",
531
+ "recipe": "changelog",
532
+ "layout": "plain",
533
+ "blocks": [
534
+ { "component": "masthead", "wordmark": "Fieldwork", "links": [{ "label": "Docs", "href": "/docs" }] },
535
+ { "component": "title", "heading": "Changelog", "byline": "What shipped, newest first" },
536
+ { "component": "index", "items": [
537
+ { "label": "12 Nov 2026", "datetime": "2026-11-12", "title": "Persistent sessions", "text": "Sessions survive restarts." }
538
+ ] },
539
+ { "component": "footer", "start": [{ "label": "Press kit", "href": "/press" }], "end": [] }
540
+ ]
541
+ }
542
+ ```
543
+
544
+ ### Verify
545
+
546
+ `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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Hugo Corta
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,38 @@
1
- # Temporary Holding Version
1
+ # Design system
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ ### Words first. Everything else in their service.
4
+
5
+ A design system for **text-led websites**. Large reading type, hairline figures, mono labels and a single orange accent, defined so completely that a person or an agent can build a page that looks right the first time.
6
+
7
+ [Read the system](https://hugocxl.github.io/design-system/) · [Hand it to an agent](https://hugocxl.github.io/design-system/#agents) · [Visit the website](https://hugocxl.github.io/design-system/)
8
+
9
+ [![The design system's reference page](.github/preview.png)](https://hugocxl.github.io/design-system/)
10
+
11
+ ## Calm by default
12
+
13
+ Reading type carries every page, and nothing is set larger than the title. Line drawings explain instead of decorate. The orange accent appears at most twice, so when it shows up, it means something.
14
+
15
+ ## A closed vocabulary
16
+
17
+ Thirteen components and six page recipes cover a home page, articles, docs, changelogs, pricing and contact. Every color, size and space is a token, and every rule can be checked in a browser. What isn't in the system isn't part of it.
18
+
19
+ ## Made to feel at home
20
+
21
+ - **Ready for agents.** One file holds the whole definition, so an agent builds the same page from the same plan, every time.
22
+ - **Light and dark.** Every token has both, and pages follow the reader's preference.
23
+ - **Accessible from the start.** Readable contrast, keyboard-friendly controls and layouts that hold from a phone to a wide screen.
24
+ - **Free to use.** Open source, for personal and commercial work.
25
+
26
+ ## Part of a stack
27
+
28
+ Three libraries, designed to work as one.
29
+
30
+ - **[Icons](https://hugocxl.github.io/icons/)** label what people can do.
31
+ - **[Vectors](https://hugocxl.github.io/vectors/)** illustrate what you mean.
32
+ - **[Design system](https://hugocxl.github.io/design-system/)** gives them the type, color and space to live in.
33
+
34
+ ## License
35
+
36
+ The system is [MIT licensed](LICENSE). It ships the [Geist](https://vercel.com/font) typefaces under their [own license](system/fonts/Geist-LICENSE.txt) and the line drawings from [Hairline](https://github.com/lucasmarkes/hairline) under [theirs](system/figures/LICENSE). Its paper, orange and reading scale take after [Superlogical](https://www.superlogical.com/).
37
+
38
+ Made by [Hugo](https://github.com/hugocxl). Ideas and contributions are welcome: [open an issue](https://github.com/hugocxl/design-system/issues).
package/package.json CHANGED
@@ -1,6 +1,48 @@
1
1
  {
2
2
  "name": "@hugocxl/design-system",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "A text-led design system for websites: tokens, components, page recipes and rules.",
5
+ "type": "module",
6
+ "files": [
7
+ "system/p9.css",
8
+ "system/p9.js",
9
+ "system/theme.js",
10
+ "system/plan.schema.json",
11
+ "system/figures",
12
+ "system/fonts",
13
+ "system/images",
14
+ "DESIGN.md",
15
+ "LICENSE",
16
+ "README.md"
17
+ ],
18
+ "exports": {
19
+ "./p9.css": "./system/p9.css",
20
+ "./theme.js": "./system/theme.js",
21
+ "./p9.js": "./system/p9.js",
22
+ "./plan.schema.json": "./system/plan.schema.json",
23
+ "./DESIGN.md": "./DESIGN.md",
24
+ "./system/*": "./system/*",
25
+ "./package.json": "./package.json"
26
+ },
27
+ "style": "./system/p9.css",
28
+ "license": "MIT",
29
+ "homepage": "https://hugocxl.github.io/design-system/",
30
+ "repository": {
31
+ "type": "git",
32
+ "url": "https://github.com/hugocxl/design-system.git"
33
+ },
34
+ "publishConfig": {
35
+ "access": "public"
36
+ },
37
+ "scripts": {
38
+ "sync": "node scripts/sync-design.mjs",
39
+ "check": "design.md lint DESIGN.md && node scripts/sync-design.mjs --check",
40
+ "test": "npm run check && playwright test"
41
+ },
42
+ "devDependencies": {
43
+ "@axe-core/playwright": "4.14.0",
44
+ "@google/design.md": "0.4.0",
45
+ "@playwright/test": "1.65.1",
46
+ "yaml": "2.9.1"
47
+ }
48
+ }