@hugocxl/design-system 0.2.9 → 0.2.12
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/README.md +10 -5
- package/package.json +4 -3
- package/skills/design-system/SKILL.md +97 -0
package/README.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @hugocxl/design-system
|
|
2
2
|
|
|
3
3
|
### My signature, across everything I make.
|
|
4
4
|
|
|
@@ -26,11 +26,16 @@ 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
|
-
- **[
|
|
32
|
-
- **[
|
|
33
|
-
- **[
|
|
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/sounds](https://hugocxl.github.io/sounds/)** makes it feel like something.
|
|
34
|
+
- **[@hugocxl/design-system](https://hugocxl.github.io/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
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hugocxl/design-system",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.12",
|
|
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",
|
|
@@ -51,7 +52,7 @@
|
|
|
51
52
|
},
|
|
52
53
|
"scripts": {
|
|
53
54
|
"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
|
+
"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",
|
|
55
56
|
"test": "npm run check && playwright test",
|
|
56
57
|
"build": "node scripts/build-exports.mjs",
|
|
57
58
|
"prepack": "node scripts/build-exports.mjs --check"
|
|
@@ -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/design-system/
|