UNPKG

@atlaskit/tokens

Version:

Design tokens are the single source of truth to name and store design decisions.

atlassian.design/components/tokens

59 lines (44 loc) • 4.68 kB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
# Token Docs and Examples When you add a new public token, you must update the **hand-authored** docs and examples in addition to the generated artifacts. Generated docs _data_ alone (see below) does not make a token visible or well-documented for humans. ## Generated docs data vs. hand-authored docs | Kind | Location | How it's produced | Your action | | ---------------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------- | | Generated docs data | `platform/packages/design-system/tokens/token-metadata.codegen.tsx` and other `@codegen`/`SignedSource` files | `yarn build tokens` (full build) | Do **not** hand-edit; regenerate from source. Feeds `@atlaskit/ads-mcp` and the hosted `llms-tokens.txt`. | | Hosted reference table | `atlassian.design/components/tokens` (external) | Published from token metadata | Nothing to edit in-repo. `docs/1-tokens-reference.tsx` is just a stub linking here. | | Hand-authored examples | `platform/packages/design-system/tokens/examples/*` | Written by contributors | **Add/update** an example demonstrating the new token. | | Hand-authored usage guidance | `platform/packages/design-system/tokens/docs/ai/*` | Written by contributors | **Update** the matching per-category instruction file. | ## Examples to update by token category The `tokens/examples/` directory contains numbered example modules. Match the new token to the most relevant one (and any matching VR example): | Token category | Example file(s) | | ---------------------------------------------- | ----------------------------------------------------------------- | | Elevation / surface (incl. interaction states) | `examples/2-elevations.tsx`, `examples/10-current-surface-vr.tsx` | | Color roles (text, background, border) | `examples/0-color-roles.tsx`, `examples/3-color-pairs.tsx` | | Color accents | `examples/1-color-accents.tsx` | | Spacing | `examples/4-spacing-vr.tsx` | | Typography | `examples/20-typography.tsx`, `examples/5-typography-vr.tsx` | | Shape / radius | `examples/8-shape-vr.tsx` | Notes: - Files ending in `-vr.tsx` are **visual-regression** examples. Adding or changing a token's visual appearance usually means updating one of these so VR coverage includes the new token. - Examples import the real token via `token('<token.name>')` from `@atlaskit/tokens`, so they only work after the source token exists and codegen has run. - If no existing example fits the new token, extend the closest example rather than leaving the token undemonstrated. ## Usage guidance to update by category `tokens/docs/ai/` holds per-category usage instructions consumed by AI tooling and contributors: - `color-instructions.md` — color tokens (text, background, border, accents, surfaces). - `spacing-instructions.md` — spacing tokens. - `border-radius-instructions.md` — radius/shape tokens. When the new token belongs to one of these categories, add a short, token-specific note describing intended use and when **not** to use it. Avoid copying the generic boilerplate `usage` string from a sibling token — guidance should be specific to the new token's role (e.g. container hover vs. press surfaces). ## Checklist - [ ] New token is demonstrated in a relevant `tokens/examples/*` file. - [ ] A VR example covers the token if it has a distinct visual appearance. - [ ] Per-category `docs/ai/*` guidance updated with token-specific (not boilerplate) usage notes. - [ ] Generated docs data (`token-metadata.codegen.tsx`) regenerated via the full `yarn build tokens`, not hand-edited.