@hugocxl/design-system 0.2.10 → 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 CHANGED
@@ -26,12 +26,17 @@ Thirteen components and six page recipes cover a home page, articles, docs, chan
26
26
 
27
27
  ## Part of a stack
28
28
 
29
- Three libraries, designed to work as one.
29
+ Four libraries, designed to work as one.
30
30
 
31
31
  - **[@hugocxl/icons](https://hugocxl.github.io/icons/)** labels what people can do.
32
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.
33
34
  - **[@hugocxl/design-system](https://hugocxl.github.io/design-system/)** gives them the type, color and space to live in.
34
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.
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/).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hugocxl/design-system",
3
- "version": "0.2.10",
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/