@bcgov/design-tokens 5.0.0-pr921 → 5.0.0-pr929
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 +50 -13
- package/package.json +1 -1
package/AGENTS.md
CHANGED
|
@@ -1,30 +1,67 @@
|
|
|
1
|
-
# B.C. Design System Design Tokens
|
|
1
|
+
# B.C. Design System Design Tokens
|
|
2
2
|
|
|
3
3
|
## Library context
|
|
4
4
|
|
|
5
|
-
- This design tokens library is part of the [B.C. Design System](https://gov.bc.ca/designsystem)
|
|
6
|
-
-
|
|
7
|
-
-
|
|
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
8
|
|
|
9
|
-
|
|
9
|
+
### Installation
|
|
10
10
|
|
|
11
|
-
- Install the design tokens package
|
|
12
|
-
-
|
|
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
|
|
13
47
|
- Reference design tokens directly when styling UI
|
|
14
|
-
- The full list of available tokens is in `node_modules/@bcgov/design-tokens/dist`
|
|
15
48
|
- Always use the semantic variable names
|
|
16
49
|
- Never guess or assume token names
|
|
17
50
|
- Never hard-code or modify token values
|
|
18
|
-
- Hard-coding token values will cause design drift when the tokens library is updated
|
|
19
51
|
|
|
20
|
-
###
|
|
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
|
|
21
58
|
|
|
59
|
+
### Colour
|
|
22
60
|
- Prefer using semantically-named colour tokens (for example, `--theme-primary-gold`) instead of generic scale points like `--theme-gold-100`
|
|
23
|
-
- Ensure that colour combinations meet the contrast requirements for WCAG 2.
|
|
61
|
+
- Ensure that colour combinations meet the contrast requirements for WCAG 2.2 Level AA
|
|
24
62
|
|
|
25
63
|
### Typography
|
|
26
|
-
|
|
27
64
|
- Typography tokens use the BC Sans typeface
|
|
28
65
|
- Ensure that [@bcgov/bc-sans](https://www.npmjs.com/package/@bcgov/bc-sans) is installed and configured before use
|
|
29
66
|
- Composite typography tokens map to the CSS `font` shorthand
|
|
30
|
-
- Use these instead of setting individual font properties
|
|
67
|
+
- Use these instead of setting individual font properties
|