@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 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 `npm run sync`, so it is exactly what the reference renders. Keep every class and attribute.
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
- `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.
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
- [![The design system's reference page](.github/preview.png)](https://hugocxl.github.io/design-system/)
9
+ [![The design system's reference page](.github/preview.png)](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
- Three libraries, designed to work as one.
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/design-system](https://hugocxl.github.io/design-system/)** gives them the type, color and space to live in.
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/design-system/issues).
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.10",
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/design-system.git"
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": "npm run check && playwright 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": "^0.2.0",
63
- "@hugocxl/vectors": "^0.1.0",
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/
@@ -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",