@hugocxl/design-system 0.2.10 → 0.2.14
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 +4 -4
- package/README.md +12 -7
- package/package.json +10 -8
- package/skills/design-system/SKILL.md +97 -0
- package/system/plan.schema.json +1 -1
package/DESIGN.md
CHANGED
|
@@ -348,7 +348,7 @@ Radii: 6px for the button, code blocks and table edges, 12px for media and the f
|
|
|
348
348
|
|
|
349
349
|
## Components
|
|
350
350
|
|
|
351
|
-
These thirteen components make up the whole vocabulary. Each markup block below is copied from the live specimen in `index.html` by `
|
|
351
|
+
These thirteen components make up the whole vocabulary. Each markup block below is copied from the live specimen in `index.html` by `pnpm run sync`, so it is exactly what the reference renders. Keep every class and attribute.
|
|
352
352
|
|
|
353
353
|
### `masthead`
|
|
354
354
|
|
|
@@ -553,7 +553,7 @@ Mono links at both ends with a hairline between them. It is the last element in
|
|
|
553
553
|
|
|
554
554
|
## Icons and vectors
|
|
555
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.
|
|
556
|
+
Pages draw with two companion libraries and nothing else. [`@hugocxl/icons`](https://hugocxl.github.io/stack/icons/) label actions and [`@hugocxl/vectors`](https://hugocxl.github.io/stack/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
557
|
|
|
558
558
|
```sh
|
|
559
559
|
npm install @hugocxl/design-system @hugocxl/icons @hugocxl/vectors
|
|
@@ -632,7 +632,7 @@ import { ModularDesignVector } from '@hugocxl/vectors/react/modular-design';
|
|
|
632
632
|
<div className="ds-media"><ModularDesignVector className="ds-vector" /></div>
|
|
633
633
|
```
|
|
634
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.
|
|
635
|
+
- Choose a vector for what it means. The [vectors browser](https://hugocxl.github.io/stack/vectors/browse.html) lists all 2,000 by use case. Name it in the caption.
|
|
636
636
|
- Keep the SVG's `title` and `desc`: they are its accessible name.
|
|
637
637
|
- Use an `<img>` only for a screenshot of the product itself.
|
|
638
638
|
- Never crop a vector, color it with the accent or place it on the field.
|
|
@@ -683,4 +683,4 @@ Give the agent this file at a pinned commit and a page plan. A page plan is JSON
|
|
|
683
683
|
|
|
684
684
|
### Verify
|
|
685
685
|
|
|
686
|
-
`
|
|
686
|
+
`pnpm 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/README.md
CHANGED
|
@@ -4,9 +4,9 @@
|
|
|
4
4
|
|
|
5
5
|
The design system behind all my personal projects. Large reading type, quiet line vectors, rounded icons and a single orange accent, so every site I ship, from a product page to its docs, reads as part of the same body of work.
|
|
6
6
|
|
|
7
|
-
[Read the system](https://hugocxl.github.io/design-system/) · [See the icons and vectors in use](https://hugocxl.github.io/design-system/#stack) · [Visit the website](https://hugocxl.github.io/design-system/)
|
|
7
|
+
[Read the system](https://hugocxl.github.io/stack/design-system/) · [See the icons and vectors in use](https://hugocxl.github.io/stack/design-system/#stack) · [Visit the website](https://hugocxl.github.io/stack/design-system/)
|
|
8
8
|
|
|
9
|
-
[](https://hugocxl.github.io/design-system/)
|
|
9
|
+
[](https://hugocxl.github.io/stack/design-system/)
|
|
10
10
|
|
|
11
11
|
## Calm by default
|
|
12
12
|
|
|
@@ -26,14 +26,19 @@ Thirteen components and six page recipes cover a home page, articles, docs, chan
|
|
|
26
26
|
|
|
27
27
|
## Part of a stack
|
|
28
28
|
|
|
29
|
-
|
|
29
|
+
Four libraries, designed to work as one.
|
|
30
30
|
|
|
31
|
-
- **[@hugocxl/icons](https://hugocxl.github.io/icons/)** labels what people can do.
|
|
32
|
-
- **[@hugocxl/vectors](https://hugocxl.github.io/vectors/)** illustrates what you mean.
|
|
33
|
-
- **[@hugocxl/
|
|
31
|
+
- **[@hugocxl/icons](https://hugocxl.github.io/stack/icons/)** labels what people can do.
|
|
32
|
+
- **[@hugocxl/vectors](https://hugocxl.github.io/stack/vectors/)** illustrates what you mean.
|
|
33
|
+
- **[@hugocxl/sounds](https://hugocxl.github.io/stack/sounds/)** makes it feel like something.
|
|
34
|
+
- **[@hugocxl/design-system](https://hugocxl.github.io/stack/design-system/)** gives them the type, color and space to live in.
|
|
35
|
+
|
|
36
|
+
**Building with an AI agent?** The package ships an agent skill in `skills/design-system/`, and
|
|
37
|
+
[hugocxl/stack](https://github.com/hugocxl/stack) sets up any project so every agent uses the
|
|
38
|
+
four libraries the same way.
|
|
34
39
|
|
|
35
40
|
## License
|
|
36
41
|
|
|
37
42
|
The system is [MIT licensed](LICENSE). It ships the [Geist](https://vercel.com/font) typefaces under their [own license](system/fonts/Geist-LICENSE.txt). Its paper, orange and reading scale take after [Superlogical](https://www.superlogical.com/).
|
|
38
43
|
|
|
39
|
-
Made by [Hugo](https://github.com/hugocxl). Ideas and contributions are welcome: [open an issue](https://github.com/hugocxl/
|
|
44
|
+
Made by [Hugo](https://github.com/hugocxl). Ideas and contributions are welcome: [open an issue](https://github.com/hugocxl/stack/issues).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hugocxl/design-system",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.14",
|
|
4
4
|
"description": "The personal design system of @hugocxl: the signature across every project.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"files": [
|
|
@@ -14,7 +14,8 @@
|
|
|
14
14
|
"LICENSE",
|
|
15
15
|
"README.md",
|
|
16
16
|
"system/images",
|
|
17
|
-
"dist"
|
|
17
|
+
"dist",
|
|
18
|
+
"skills"
|
|
18
19
|
],
|
|
19
20
|
"exports": {
|
|
20
21
|
".": "./system/ds.css",
|
|
@@ -41,26 +42,27 @@
|
|
|
41
42
|
},
|
|
42
43
|
"style": "./system/ds.css",
|
|
43
44
|
"license": "MIT",
|
|
44
|
-
"homepage": "https://hugocxl.github.io/design-system/",
|
|
45
|
+
"homepage": "https://hugocxl.github.io/stack/design-system/",
|
|
45
46
|
"repository": {
|
|
46
47
|
"type": "git",
|
|
47
|
-
"url": "https://github.com/hugocxl/
|
|
48
|
+
"url": "https://github.com/hugocxl/stack.git",
|
|
49
|
+
"directory": "design-system"
|
|
48
50
|
},
|
|
49
51
|
"publishConfig": {
|
|
50
52
|
"access": "public"
|
|
51
53
|
},
|
|
52
54
|
"scripts": {
|
|
53
55
|
"sync": "node scripts/sync-assets.mjs && node scripts/sync-design.mjs",
|
|
54
|
-
"check": "design.md lint DESIGN.md && node scripts/sync-assets.mjs --check && node scripts/sync-design.mjs --check && node scripts/build-exports.mjs --check",
|
|
55
|
-
"test": "
|
|
56
|
+
"check": "design.md lint DESIGN.md && node scripts/sync-assets.mjs --check && node scripts/sync-design.mjs --check && node scripts/build-exports.mjs --check && node scripts/check-skill.mjs",
|
|
57
|
+
"test": "pnpm run check && playwright test",
|
|
56
58
|
"build": "node scripts/build-exports.mjs",
|
|
57
59
|
"prepack": "node scripts/build-exports.mjs --check"
|
|
58
60
|
},
|
|
59
61
|
"devDependencies": {
|
|
60
62
|
"@axe-core/playwright": "4.14.0",
|
|
61
63
|
"@google/design.md": "0.4.0",
|
|
62
|
-
"@hugocxl/icons": "
|
|
63
|
-
"@hugocxl/vectors": "
|
|
64
|
+
"@hugocxl/icons": "0.2.0",
|
|
65
|
+
"@hugocxl/vectors": "0.1.0",
|
|
64
66
|
"@playwright/test": "1.65.1",
|
|
65
67
|
"yaml": "2.9.1"
|
|
66
68
|
}
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: design-system
|
|
3
|
+
description: Use @hugocxl/design-system for the look of every @hugocxl website, page and interface — type, color, spacing, layout, page recipes and the thirteen components. Covers reading the full definition (DESIGN.md), planning a page, rendering components exactly, and using the tokens from plain HTML, Tailwind, CSS, Sass or JavaScript. Use it whenever you create, style or review a page, a screen or a component.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# @hugocxl/design-system
|
|
7
|
+
|
|
8
|
+
The signature shared by every @hugocxl project: large reading type in Geist, quiet line
|
|
9
|
+
vectors, rounded Stroke icons, monospaced labels and one scarce orange accent. Flat, light and
|
|
10
|
+
dark, accessible by default.
|
|
11
|
+
|
|
12
|
+
## Read the definition first
|
|
13
|
+
|
|
14
|
+
`DESIGN.md` defines the system completely; anything it does not describe is not part of the
|
|
15
|
+
system. Read it before building or changing any page. It ships in the package:
|
|
16
|
+
|
|
17
|
+
- In a project: `node_modules/@hugocxl/design-system/DESIGN.md`
|
|
18
|
+
- Otherwise: `../../DESIGN.md` from this skill's directory
|
|
19
|
+
|
|
20
|
+
Its YAML front matter holds every token value. Its body holds the colors, type scale, layout,
|
|
21
|
+
page recipes, the markup of each component, and the rules.
|
|
22
|
+
|
|
23
|
+
## Build a page
|
|
24
|
+
|
|
25
|
+
1. **Pick a recipe** (`home`, `article`, `docs`, `changelog`, `pricing`, `contact`). It fixes
|
|
26
|
+
the layout and the order of components.
|
|
27
|
+
2. **Write a page plan** for anything beyond a trivial page: JSON that validates against
|
|
28
|
+
`@hugocxl/design-system/plan.schema.json`, naming the recipe, the layout and every block
|
|
29
|
+
with its content. Check the block order against the recipe.
|
|
30
|
+
3. **Render each block** by copying the component's markup from DESIGN.md exactly. Change only
|
|
31
|
+
text, links, IDs and the names of vectors and icons.
|
|
32
|
+
4. **Fill figures and icons** from `@hugocxl/vectors` and `@hugocxl/icons` (see their skills),
|
|
33
|
+
never from anything else.
|
|
34
|
+
5. **Verify** at 320, 760, 761 and 1440 px wide in both themes.
|
|
35
|
+
|
|
36
|
+
Never invent copy, links, numbers, quotes or logos the brief does not supply. If a required
|
|
37
|
+
input is missing, ask for it.
|
|
38
|
+
|
|
39
|
+
## Install
|
|
40
|
+
|
|
41
|
+
```sh
|
|
42
|
+
npm install @hugocxl/design-system @hugocxl/icons @hugocxl/vectors
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
| Stack | Use |
|
|
46
|
+
| --- | --- |
|
|
47
|
+
| Static HTML (the reference) | Serve `system/` from the package. Load `system/ds.css` and `system/theme.js` in the head and `system/ds.js` as a module. Body: `class="ds"` and the recipe's `data-layout`. |
|
|
48
|
+
| Tailwind v4 | `@import "@hugocxl/design-system/tailwind";` |
|
|
49
|
+
| Tailwind v3 | `presets: [require('@hugocxl/design-system/tailwind-preset')]` |
|
|
50
|
+
| Plain CSS | `@hugocxl/design-system/fonts.css` and `@hugocxl/design-system/tokens.css` (custom properties `--ds-<role>`) |
|
|
51
|
+
| Sass | `@use "pkg:@hugocxl/design-system/scss";` |
|
|
52
|
+
| JavaScript | `import { tokens } from '@hugocxl/design-system/tokens'` or `@hugocxl/design-system/tokens.json` |
|
|
53
|
+
|
|
54
|
+
In Tailwind, use only the token utilities (`bg-canvas`, `text-ink`, `text-muted`,
|
|
55
|
+
`text-reading`, `p-space-5`, `rounded-media`, `max-w-measure`…). Never Tailwind's default
|
|
56
|
+
palette, font sizes, spacing or radii (`bg-blue-500`, `text-xl`, `p-4`, `rounded-lg`).
|
|
57
|
+
|
|
58
|
+
The theme follows the reader's preference and switches with `data-theme="light|dark"` on
|
|
59
|
+
`<html>`; `system/theme.js` sets it before the first paint.
|
|
60
|
+
|
|
61
|
+
## Rules that matter most
|
|
62
|
+
|
|
63
|
+
The full list is in DESIGN.md under "Do's and Don'ts". The ones agents break most often:
|
|
64
|
+
|
|
65
|
+
- **Tokens only.** No color, font, size, weight, radius or spacing value that is not a token.
|
|
66
|
+
No hex values in components.
|
|
67
|
+
- **Accent at most twice per page:** the status dot (`.ds-dot`) and one phrase at title size
|
|
68
|
+
(`.ds-accent`). Never on body text, links, buttons, backgrounds, rules, icons or figures.
|
|
69
|
+
- **Hue and status colors only on icons and dots**, and the words beside them always say what
|
|
70
|
+
the color means.
|
|
71
|
+
- **Nothing larger than the title**, nothing bolder than 500. Sentence case. Left-aligned text;
|
|
72
|
+
only the column is centered.
|
|
73
|
+
- **Flat.** No shadows, gradients, blur, emoji or stock imagery.
|
|
74
|
+
- **One filled button per page.**
|
|
75
|
+
- **Icons** use the Stroke style, sit only in links, the button, meta labels and icon buttons,
|
|
76
|
+
and never replace words.
|
|
77
|
+
- **Figures** are vectors from `@hugocxl/vectors` in `figure-wide` or `figure-grid`, chosen for
|
|
78
|
+
their meaning and named in the caption.
|
|
79
|
+
- **Accessible:** every icon button has an `aria-label`, every field a visible label, every
|
|
80
|
+
image `alt` text, and every vector keeps its `title`.
|
|
81
|
+
|
|
82
|
+
## App screens and other stacks
|
|
83
|
+
|
|
84
|
+
For an app screen, a component library or anything that is not one of the six page recipes,
|
|
85
|
+
use the same tokens and rules: the reading scale, the spacing steps, the color roles, flat
|
|
86
|
+
surfaces with `rule` hairlines, Stroke icons and the accent budget. Reuse a component's
|
|
87
|
+
markup and classes from DESIGN.md wherever one fits instead of inventing a new one.
|
|
88
|
+
|
|
89
|
+
## Check your work
|
|
90
|
+
|
|
91
|
+
- The page follows its recipe's component order, and every component's markup matches DESIGN.md.
|
|
92
|
+
- No value outside the tokens, no Tailwind default palette or scale.
|
|
93
|
+
- The accent appears at most twice; no shadow, gradient or emoji.
|
|
94
|
+
- Icons come from `@hugocxl/icons` (Stroke) and figures from `@hugocxl/vectors`.
|
|
95
|
+
- The page works at 320, 760, 761 and 1440 px in light and dark.
|
|
96
|
+
|
|
97
|
+
Reference page: https://hugocxl.github.io/stack/design-system/
|
package/system/plan.schema.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
-
"$id": "https://hugocxl.github.io/design-system/system/plan.schema.json",
|
|
3
|
+
"$id": "https://hugocxl.github.io/stack/design-system/system/plan.schema.json",
|
|
4
4
|
"title": "Design system page plan",
|
|
5
5
|
"description": "One page as data. Render each block by copying its component markup from DESIGN.md and replacing only the slot values.",
|
|
6
6
|
"type": "object",
|