@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 +546 -0
- package/LICENSE +21 -0
- package/README.md +37 -2
- package/package.json +46 -4
- package/system/figures/LICENSE +21 -0
- package/system/figures/index.js +5950 -0
- package/system/fonts/Geist-LICENSE.txt +92 -0
- package/system/fonts/Geist-Variable.woff2 +0 -0
- package/system/fonts/GeistMono-Variable.woff2 +0 -0
- package/system/images/gray-folds.png +0 -0
- package/system/p9.css +240 -0
- package/system/p9.js +30 -0
- package/system/plan.schema.json +196 -0
- package/system/theme.js +13 -0
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
|
-
#
|
|
1
|
+
# Design system
|
|
2
2
|
|
|
3
|
-
|
|
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
|
+
[](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.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
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
|
+
}
|