Cn 165 design tokens storybook page #1658
Conversation
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive design tokens documentation to Storybook, providing guidance for designers and developers on how to use the three-tiered token system (foundation, semantic, and component tokens). The PR also includes cleanup of unused imports across several documentation files.
Key changes:
- New design tokens documentation page covering token tiers, usage priorities, modes, and integration with CSS and Figma
- Removal of unused
CustomBadgeimports from five MDX documentation files - Registration of the new design tokens page in Storybook's main configuration
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| projects/canopy/src/lib/docs/foundation/design-tokens.mdx | New comprehensive design tokens documentation with usage guidelines, best practices, and examples for both developers and designers |
| projects/canopy/src/lib/spacing/row-gap/docs/guide.mdx | Removed unused CustomBadge import |
| projects/canopy/src/lib/spacing/padding/docs/guide.mdx | Removed unused CustomBadge import |
| projects/canopy/src/lib/spacing/margin/docs/guide.mdx | Removed unused CustomBadge import |
| projects/canopy/src/lib/grid/docs/guide.mdx | Removed unused CustomBadge import |
| projects/canopy/src/lib/docs/foundation/layout-grid-and-spacing.mdx | Removed unused CustomBadge import |
| .storybook/main.js | Added design-tokens.mdx to Storybook stories configuration |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| * **Typography:** Productive and Expressive - these allow you to set the font face, weight and letter spacing of text | ||
| * **Component themes:** Neutral, Neutral inverse, Subtle and Bold - these allow you to set the colour tone of elements | ||
|
|
||
| For example, `--colour-surface-fill-1` has different values in “blue”, “green”, or “dark” modes, as well as in “Neutral”, “Neutral inverse”, “Subtle” and “Bold” |
There was a problem hiding this comment.
The example shows "dark" mode but the modes listed earlier in line 70 are "Blue, Green, Red and Yellow". The mention of "dark" mode is inconsistent with the documented modes. Either update the example to use one of the documented modes or add "dark" to the list of available modes.
| For example, `--colour-surface-fill-1` has different values in “blue”, “green”, or “dark” modes, as well as in “Neutral”, “Neutral inverse”, “Subtle” and “Bold” | |
| For example, `--colour-surface-fill-1` has different values in “blue”, “green”, or “yellow” modes, as well as in “Neutral”, “Neutral inverse”, “Subtle” and “Bold” |
| 3. **Apply a Variable (Token):** | ||
|
|
||
| For **colour:** | ||
| * Click the variable icon (hexagonal cog icon) next to Fill or Stroke. |
There was a problem hiding this comment.
The documentation refers to a "hexagonal cog icon" but the standard Figma UI uses a different icon for variables. Consider using more accurate terminology that matches the current Figma interface, such as "variable icon" or verifying the exact icon appearance in the current version of Figma.
| * Click the variable icon (hexagonal cog icon) next to Fill or Stroke. | |
| * Click the variable icon next to Fill or Stroke. |
| * **Component themes:** Neutral, Neutral inverse, Subtle and Bold - these allow you to set the colour tone of elements | ||
|
|
||
| For example, `--colour-surface-fill-1` has different values in “blue”, “green”, or “dark” modes, as well as in “Neutral”, “Neutral inverse”, “Subtle” and “Bold” |
There was a problem hiding this comment.
The term "colour tones" is mentioned here but the actual values listed are "Neutral, Neutral inverse, Subtle and Bold" which are described as "component themes". This inconsistency in terminology may confuse readers. Consider using consistent terminology throughout the document - either "colour tones" or "component themes".
|
|
||
| Design tokens encode design decisions—such as colours, typography, spacing, and more—into a format that can be used by both designers and developers. Tokens are defined according to https://design-tokens.github.io/community-group/format/ . We currently provide tokens in CSS format, with plans to support other formats (e.g., for native apps) in the future. | ||
|
|
||
| ## Who Should Use Design Tokens? |
There was a problem hiding this comment.
For all the other docs we use capital letter only on the very first letter, I think we should follow that pattern on this page too
| * **Developers:** If you’re not using the Angular components, need to add bespoke styling to your app or you’re contributing a new component to the design system, you should start with the design tokens | ||
| * **Anyone** involved in creating or maintaining UI components, patterns, or templates. | ||
|
|
||
| ## Recommended knowledge: |
There was a problem hiding this comment.
I would personally remove the : as it's not used in the other headings 🤔
|
|
||
| Our tokens are organised into three main tiers, each serving a specific purpose in the design system: | ||
|
|
||
| **Foundation Tokens** are the basic, raw values for colours, spacing, typography, and other atomic properties. |
There was a problem hiding this comment.
I wonder if it would be better to have each in their own heading, e.g.:
### Foundation tokens
The basic, raw values for colours, spacing, typography, and other atomic properties.
...
### Semantic tokens
They map foundation values to specific UI roles (e.g., containers, interactive components, inputs, and text).
...
### Component tokens
Tailored for specific components and should be your first choice when styling.
...
I think this way gives a bit more structure and it's better for accessibility (although a11y in Storybook generally is not great).
| * `--card-border-radius` | ||
| * `--nav-button-gap` | ||
|
|
||
| ## Usage Priority |
There was a problem hiding this comment.
Should this heading be a h3 ###? it's related to the one above, right? ## Token Tiers and Usage Order
Otherwise we could split it and have:
## Token tiers
...
## Usage priority
...
|
|
||
| * `--border-radius-5` is equivalent to 20px on SM and MD modes, but 24px on LG, XL and XXL modes. | ||
|
|
||
| ### How to Use Design Tokens in Code |
There was a problem hiding this comment.
I think this should be a h2 🤔 same as Using design tokens in Figma.
## How to use design tokens in code
...
### Referencing a Token in CSS
...
|
|
||
| * `--colour-surface-fill-1` will show a different colour depending on which of the blue/green/yellow modes has been selected (blue is default) | ||
|
|
||
| * `--font-family` is Nunito Sans when set to Productive mode and ABC Otto when set to Expressive mode. |
There was a problem hiding this comment.
I think my comment got lost in Confluence:
|
|
||
| ### How to Use Design Tokens in Code | ||
|
|
||
| Design tokens underpin all Canopy components, patterns, template libraries, and the Angular component library. |
There was a problem hiding this comment.
I think we can add our docs like this:
Design tokens underpin all Canopy components, patterns, template libraries, and the Angular component library.
If you're using the Canopy Angular library, the tokens are included automatically.
Otherwise, you'll need to install the package manually:
npm install @legal-and-general/canopy-design-tokens
To ensure everything works correctly, follow these steps:
- Setting up the GitHub registry -> external link to: http://github.com/Legal-and-General/canopy/blob/master/docs/USAGE.md#setting-up-the-github-registry
- Authenticating against the GitHub registry -> external link to: http://github.com/Legal-and-General/canopy/blob/master/docs/USAGE.md#setting-up-the-github-registry
Importing tokens (h3)
After installing the package, you can import the tokens by adding the necessary files to your build process.
Refer to the [Canopy Design Tokens repository to see which tokens are available](https://github.com/Legal-and-General/canopy-design-tokens/tree/master/build/css - external link).
Referencing a Token in CSS (h3)
...
There was a problem hiding this comment.
What's the content of the package? build/css? or just css? we should maybe add an example of where to find the tokens in the package within Importing tokens?
2 participants
Description
Add documentation in Storybook for the design tokens
Checklist: