@bcgov/design-tokens 5.0.0 → 5.1.0-pr911
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/AGENTS.md +67 -0
- package/README.md +8 -0
- package/package.json +1 -1
package/AGENTS.md
ADDED
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# B.C. Design System Design Tokens
|
|
2
|
+
|
|
3
|
+
## Library context
|
|
4
|
+
|
|
5
|
+
- This design tokens library (`@bcgov/design-tokens`) is part of the [B.C. Design System](https://gov.bc.ca/designsystem)
|
|
6
|
+
- Tokens are the single source of truth for colours, typography, spacing/shadows and icons in B.C. government UI
|
|
7
|
+
- Tokens are available as CSS, SCSS and JavaScript (ESM and CommonJS) variables
|
|
8
|
+
|
|
9
|
+
### Installation
|
|
10
|
+
|
|
11
|
+
- Install the design tokens package: `npm i @bcgov/design-tokens`
|
|
12
|
+
- Also install [@bcgov/bc-sans](https://www.npmjs.com/package/@bcgov/bc-sans)
|
|
13
|
+
|
|
14
|
+
## Choosing a format
|
|
15
|
+
| Use case | Import | Notes |
|
|
16
|
+
| --- | --- | --- |
|
|
17
|
+
| JS/TS (try first) | `import * as tokens from "@bcgov/design-tokens/js"` | ESM with TypeScript definitions for autocomplete |
|
|
18
|
+
| JS/TS, name collisions | `@bcgov/design-tokens/js-prefixed` | All exports prefixed with `bcds` (ex: `bcdsThemeBlue100`) |
|
|
19
|
+
| CommonJS | `require("@bcgov/design-tokens/cjs")` | TypeScript definitions included |
|
|
20
|
+
| CommonJS, name collisions | `require("@bcgov/design-tokens/cjs-prefixed")` | Exports prefixed with `bcds` |
|
|
21
|
+
| Static CSS | `import "@bcgov/design-tokens/css/variables.css"` | All tokens as custom properties on `:root` |
|
|
22
|
+
| Static CSS, name collisions | `@bcgov/design-tokens/css-prefixed/variables.css` | Custom properties prefixed with `--bcds-` |
|
|
23
|
+
| SCSS | `@use "@bcgov/design-tokens/scss/variables";` | SCSS `$variables` |
|
|
24
|
+
|
|
25
|
+
- Verify imports against files in `node_modules/@bcgov/design-tokens/`
|
|
26
|
+
- Do not guess import paths
|
|
27
|
+
|
|
28
|
+
## Token naming
|
|
29
|
+
- Token names follow the token's semantic path: `theme.blue.100` becomes:
|
|
30
|
+
- CSS: `--theme-blue-100`
|
|
31
|
+
- SCSS: `$theme-blue-100`
|
|
32
|
+
- JavaScript: `themeBlue100`
|
|
33
|
+
- Prefixed JavaScript: `bcdsThemeBlue100`
|
|
34
|
+
- Available token categories:
|
|
35
|
+
- `icons`
|
|
36
|
+
- `layout`
|
|
37
|
+
- `support`
|
|
38
|
+
- `surface`
|
|
39
|
+
- `theme`
|
|
40
|
+
- `typography`
|
|
41
|
+
- To discover exact token names, check `js/index.d.ts` (JS) or `css/variables.css` (CSS) in the installed package
|
|
42
|
+
- Always use the semantic variable names as written in those files
|
|
43
|
+
- Never guess, invent, or abbreviate token names
|
|
44
|
+
- Never hard-code or modify token values
|
|
45
|
+
|
|
46
|
+
## Using tokens
|
|
47
|
+
- Reference design tokens directly when styling UI
|
|
48
|
+
- Always use the semantic variable names
|
|
49
|
+
- Never guess or assume token names
|
|
50
|
+
- Never hard-code or modify token values
|
|
51
|
+
|
|
52
|
+
### Layout
|
|
53
|
+
- `layout.padding.*` and `layout.margin.*` tokens are for spacing *within* and *between* individual UI components inside a container
|
|
54
|
+
- For example: padding inside a card, gap between a button and its label, margin between list items
|
|
55
|
+
- There is no token category for page-level layout (page grid, column widths, breakpoints, major section spacing)
|
|
56
|
+
- Use plain CSS (grid/flexbox) or the host framework's layout system with unitless/relative values
|
|
57
|
+
- Do not stretch `layout.padding.*` or `layout.margin.*` tokens to fill this gap
|
|
58
|
+
|
|
59
|
+
### Colour
|
|
60
|
+
- Prefer using semantically-named colour tokens (for example, `--theme-primary-gold`) instead of generic scale points like `--theme-gold-100`
|
|
61
|
+
- Ensure that colour combinations meet the contrast requirements for WCAG 2.2 Level AA
|
|
62
|
+
|
|
63
|
+
### Typography
|
|
64
|
+
- Typography tokens use the BC Sans typeface
|
|
65
|
+
- Ensure that [@bcgov/bc-sans](https://www.npmjs.com/package/@bcgov/bc-sans) is installed and configured before use
|
|
66
|
+
- Composite typography tokens map to the CSS `font` shorthand
|
|
67
|
+
- Use these instead of setting individual font properties
|
package/README.md
CHANGED
|
@@ -12,6 +12,14 @@ To use, install this package (`npm i @bcgov/design-tokens`) and import the desig
|
|
|
12
12
|
|
|
13
13
|
This package includes tokens in JavaScript (ECMAScript Module and CommonJS), CSS and SCSS formats.
|
|
14
14
|
|
|
15
|
+
### Using this library with LLMs
|
|
16
|
+
|
|
17
|
+
Instructions for AI agents are shipped with this library (`/node_modules/@bcgov/design-tokens/AGENTS.md`).
|
|
18
|
+
|
|
19
|
+
Add the B.C. Design System boilerplate from [AGENTS.example.md](https://github.com/bcgov/design-system/blob/main/AGENTS.example.md) to an `AGENTS.md` file at the root of your project. This directs agents to load the library-specific instructions.
|
|
20
|
+
|
|
21
|
+
Run `/context` to confirm that your agent has loaded the instructions into its context window.
|
|
22
|
+
|
|
15
23
|
### JavaScript (ECMAScript Module)
|
|
16
24
|
|
|
17
25
|
> **Try this first!** Using JavaScript variables can give you a better developer experience with autocomplete.
|