@worldresources/wri-design-systems 2.191.17 → 2.191.18
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/AGENTS.md +43 -236
- package/agents/setup-ai.mjs +10 -2
- package/agents/wri-ds.instructions.md +93 -0
- package/package.json +1 -1
package/agents/AGENTS.md
CHANGED
|
@@ -1,270 +1,77 @@
|
|
|
1
|
-
#
|
|
1
|
+
# WRI Design System — AI Context
|
|
2
2
|
|
|
3
3
|
This file provides context for AI coding agents working on WRI projects.
|
|
4
|
-
|
|
5
|
-
The setup script distributes this file to the correct location for each IDE.
|
|
4
|
+
`@worldresources/wri-design-systems` is the **standard component library for all World Resources Institute products**, built on Chakra UI v3.
|
|
6
5
|
|
|
7
|
-
|
|
6
|
+
> If your editor supports per-file instructions (e.g. VS Code Copilot), detailed usage rules
|
|
7
|
+
> live in `.github/instructions/wri-ds.instructions.md` and auto-attach when you edit `.tsx` files.
|
|
8
|
+
> Read that file before using any WRI DS component.
|
|
8
9
|
|
|
9
10
|
## What is the WRI Design System?
|
|
10
11
|
|
|
11
|
-
`@worldresources/wri-design-systems` is
|
|
12
|
+
`@worldresources/wri-design-systems` is built on Chakra UI v3 and provides WRI-branded components shared across WRI products. **Do not override component styles** — visual consistency depends on using the library as-is.
|
|
12
13
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
|
16
|
-
|
|
|
17
|
-
|
|
|
18
|
-
| GitHub repo | https://github.com/wri/wri-design-systems |
|
|
19
|
-
| GitHub README | https://github.com/wri/wri-design-systems#readme |
|
|
20
|
-
| Component READMEs | `src/components/<Category>/<ComponentName>/README.md` in the GitHub repo |
|
|
21
|
-
| npm | https://www.npmjs.com/package/@worldresources/wri-design-systems |
|
|
22
|
-
| Style guide | https://zeroheight.com/4221801da |
|
|
23
|
-
|
|
24
|
-
---
|
|
25
|
-
|
|
26
|
-
## MCP Servers
|
|
27
|
-
|
|
28
|
-
Two MCP servers are configured for this project. **Query them before writing any component code** — never assume props or token names from memory.
|
|
29
|
-
|
|
30
|
-
### Storybook MCP
|
|
31
|
-
|
|
32
|
-
Exposes WRI DS component stories, props, and usage patterns directly from the hosted Storybook.
|
|
33
|
-
Use it to verify: which WRI DS components exist, their props, and documented usage examples.
|
|
34
|
-
|
|
35
|
-
```json
|
|
36
|
-
{
|
|
37
|
-
"mcpServers": {
|
|
38
|
-
"wri-storybook": {
|
|
39
|
-
"command": "npx",
|
|
40
|
-
"args": ["-y", "storybook-mcp@latest"],
|
|
41
|
-
"env": {
|
|
42
|
-
"STORYBOOK_URL": "https://wri.github.io/wri-design-systems/index.json"
|
|
43
|
-
}
|
|
44
|
-
}
|
|
45
|
-
}
|
|
46
|
-
}
|
|
47
|
-
```
|
|
48
|
-
|
|
49
|
-
### Chakra UI MCP
|
|
50
|
-
|
|
51
|
-
Exposes Chakra UI v3 component props, design tokens, and migration guidance.
|
|
52
|
-
Use it as fallback when a component is not in the WRI DS.
|
|
53
|
-
|
|
54
|
-
```json
|
|
55
|
-
{
|
|
56
|
-
"mcpServers": {
|
|
57
|
-
"chakra-ui": {
|
|
58
|
-
"command": "npx",
|
|
59
|
-
"args": ["-y", "@chakra-ui/react-mcp"]
|
|
60
|
-
}
|
|
61
|
-
}
|
|
62
|
-
}
|
|
63
|
-
```
|
|
64
|
-
|
|
65
|
-
> **Note:** The project setup script configures both MCP servers automatically.
|
|
66
|
-
> Run it once after cloning — see the README for instructions.
|
|
67
|
-
|
|
68
|
-
---
|
|
14
|
+
| Resource | URL |
|
|
15
|
+
| ----------- | ---------------------------------------------------------------- |
|
|
16
|
+
| Storybook | https://wri.github.io/wri-design-systems/ |
|
|
17
|
+
| npm | https://www.npmjs.com/package/@worldresources/wri-design-systems |
|
|
18
|
+
| Style guide | https://zeroheight.com/4221801da |
|
|
69
19
|
|
|
70
20
|
## Component Hierarchy — Never Skip a Level
|
|
71
21
|
|
|
72
22
|
```
|
|
73
|
-
1. @worldresources/wri-design-systems
|
|
74
|
-
2. @chakra-ui/react
|
|
75
|
-
3. Custom code
|
|
76
|
-
```
|
|
77
|
-
|
|
78
|
-
## Component APIs — Do Not Invent Props or Options
|
|
79
|
-
|
|
80
|
-
When using any WRI DS or Chakra component, you must **confirm** the component’s API (types, props, valid options, variants, sizes, etc.) from a trusted source before coding. **Never** guess or invent prop names or allowed values.
|
|
81
|
-
|
|
82
|
-
Use one (or more) of the following, in order:
|
|
83
|
-
|
|
84
|
-
1. **Library `index.d.ts`** — check the exported types first (source of truth for public APIs).
|
|
85
|
-
2. **Storybook MCP** — preferred for WRI DS components (authoritative props + usage patterns).
|
|
86
|
-
3. **Component README** — `src/components/<Category>/<ComponentName>/README.md` for WRI DS details.
|
|
87
|
-
4. **TypeScript types in this repo** — rely on exported types and TS errors as the source of truth.
|
|
88
|
-
5. **Chakra MCP** — preferred for Chakra-only components and Chakra v3 migration-safe props.
|
|
89
|
-
|
|
90
|
-
If you can’t confirm an API, stop and ask for clarification rather than guessing.
|
|
91
|
-
|
|
92
|
-
### Level 1 — WRI Design System
|
|
93
|
-
|
|
94
|
-
Check the [Storybook](https://wri.github.io/wri-design-systems/) or query the Storybook MCP first. For detailed props and usage notes, also check the component's individual README in the [GitHub repo](https://github.com/wri/wri-design-systems) at `src/components/<Category>/<ComponentName>/README.md` — for example: [`Panel/README.md`](https://github.com/wri/wri-design-systems/blob/main/src/components/Containers/Panel/README.md).
|
|
95
|
-
|
|
96
|
-
```tsx
|
|
97
|
-
// ✅ Correct
|
|
98
|
-
import { Button } from '@worldresources/wri-design-systems'
|
|
99
|
-
;<Button variant='primary'>Save</Button>
|
|
100
|
-
```
|
|
101
|
-
|
|
102
|
-
### Level 2 — Chakra UI (fallback only)
|
|
103
|
-
|
|
104
|
-
Only use Chakra directly if there is **no WRI DS equivalent**. Use the Chakra MCP to verify props — do not rely on memory. Chakra v3 has breaking changes from v2.
|
|
105
|
-
|
|
106
|
-
```tsx
|
|
107
|
-
// ✅ Acceptable — no WRI DS equivalent exists
|
|
108
|
-
import { Skeleton } from '@chakra-ui/react'
|
|
109
|
-
```
|
|
110
|
-
|
|
111
|
-
### Level 3 — Custom Code (last resort)
|
|
112
|
-
|
|
113
|
-
When neither the WRI DS nor Chakra covers the use case, you **must**:
|
|
114
|
-
|
|
115
|
-
1. Add a `// [CUSTOM COMPONENT]` comment on the line above the definition.
|
|
116
|
-
This is a searchable marker — find all custom components with "Find in Files" → `[CUSTOM COMPONENT]`.
|
|
117
|
-
2. Add a brief justification explaining why no DS or Chakra component was used.
|
|
118
|
-
|
|
119
|
-
```tsx
|
|
120
|
-
// [CUSTOM COMPONENT] — No WRI DS or Chakra equivalent for map tooltip overlay
|
|
121
|
-
const MapTooltip = ({ lat, lng, children }: MapTooltipProps) => {
|
|
122
|
-
...
|
|
123
|
-
}
|
|
124
|
-
```
|
|
125
|
-
|
|
126
|
-
---
|
|
127
|
-
|
|
128
|
-
## Design Tokens
|
|
129
|
-
|
|
130
|
-
WRI DS tokens are defined as Chakra semantic tokens. **Never hardcode values** that have a token equivalent.
|
|
131
|
-
|
|
132
|
-
```tsx
|
|
133
|
-
// ❌ Wrong — hardcoded colour
|
|
134
|
-
<Box bg="#2C7D6E" />
|
|
135
|
-
|
|
136
|
-
// ✅ Correct — semantic token
|
|
137
|
-
<Box bg="brand.primary" />
|
|
138
|
-
```
|
|
139
|
-
|
|
140
|
-
If unsure what tokens exist, use the Chakra MCP (`get_theme`) or check the [style guide](https://zeroheight.com/4221801da).
|
|
141
|
-
|
|
142
|
-
### Color Palette — Authoritative Source
|
|
143
|
-
|
|
144
|
-
The project's `ChakraProvider` in `src/components/Providers/index.tsx` is the **single source of truth for all color overrides** in this project. Before suggesting or using any color token, read that file to see which palette scales are defined and what values they map to.
|
|
145
|
-
|
|
146
|
-
**Do not invent, assume, or guess color token names or values.** The provider only extends the following palette scales:
|
|
147
|
-
|
|
148
|
-
| Scale | Defined steps / tokens | Notes |
|
|
149
|
-
| ------------ | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
|
|
150
|
-
| `neutral` | 100, 200, 300, 400, 500, 600, 700, 800, 900 | Overrides Chakra defaults |
|
|
151
|
-
| `primary` | 100, 200, 300, 400, 500, 600, 700, 800, 900 | Overrides Chakra defaults |
|
|
152
|
-
| `secondary` | 100, 200, 300, 400, 500, 600, 700, 800, 900 | Overrides Chakra defaults |
|
|
153
|
-
| `success` | 100, 200, 300, 500, 900 | Falls back to WRI DS `designSystemStyles` |
|
|
154
|
-
| `warning` | 100, 200, 300, 500, 900 | Falls back to WRI DS `designSystemStyles` |
|
|
155
|
-
| `error` | 100, 200, 300, 500, 900 | Falls back to WRI DS `designSystemStyles` |
|
|
156
|
-
| `accessible` | 'text-on-primary-mids', 'text-on-secondary-mids', 'controls-on-neutral-lights', 'controls-on-neutral-darks' | Use repo-defined keys (for example `text-on-primary-mids`) from WRI DS `designSystemStyles` |
|
|
157
|
-
|
|
158
|
-
For scales not overridden, and for named token sets such as `accessible`, values come from the WRI DS `designSystemStyles` system context — **do not guess these values**. Query the Storybook MCP to verify what values are available. In particular, do not call `getThemedColor('accessible', 100)`; use the actual string token key defined by the design system.
|
|
159
|
-
|
|
160
|
-
### How to Use Color Tokens — `getThemedColor`
|
|
161
|
-
|
|
162
|
-
Colors must always be accessed via `getThemedColor` exported from `@worldresources/wri-design-systems`. **Never use raw token strings as JSX prop values.**
|
|
163
|
-
|
|
164
|
-
```tsx
|
|
165
|
-
import { getThemedColor } from "@worldresources/wri-design-systems";
|
|
166
|
-
|
|
167
|
-
// ❌ Wrong — raw token string
|
|
168
|
-
<Box bg="primary.500" />
|
|
169
|
-
|
|
170
|
-
// ✅ Correct — use getThemedColor
|
|
171
|
-
<Box bg={getThemedColor('primary', 500)} />
|
|
172
|
-
<Box color={getThemedColor('neutral', 300)} />
|
|
173
|
-
<Box borderColor={getThemedColor('success', 500)} />
|
|
23
|
+
1. @worldresources/wri-design-systems ← always check first (Storybook MCP)
|
|
24
|
+
2. @chakra-ui/react ← fallback if no WRI DS equivalent
|
|
25
|
+
3. Custom code ← last resort; add // [CUSTOM COMPONENT] comment
|
|
174
26
|
```
|
|
175
27
|
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
```typescript
|
|
179
|
-
getThemedColor(
|
|
180
|
-
variant: "neutral" | "primary" | "secondary" | "success" | "warning" | "error" | "accessible",
|
|
181
|
-
index:
|
|
182
|
-
| 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900
|
|
183
|
-
| "text-on-primary-mids"
|
|
184
|
-
| "text-on-secondary-mids"
|
|
185
|
-
| "controls-on-neutral-lights"
|
|
186
|
-
| "controls-on-neutral-darks"
|
|
187
|
-
): string
|
|
188
|
-
```
|
|
28
|
+
## Component Rules — Read Before Implementing Anything
|
|
189
29
|
|
|
190
|
-
**
|
|
30
|
+
**Before writing any component code, read `.github/instructions/wri-ds.instructions.md`.**
|
|
31
|
+
It contains the mandatory pre-implementation checklist, API verification steps, token rules, and forbidden patterns.
|
|
191
32
|
|
|
192
|
-
|
|
193
|
-
- For overridden scales (`neutral`, `primary`, `secondary`), valid steps are listed in the table above.
|
|
194
|
-
- For non-overridden scales (`success`, `warning`, `error`, `accessible`), query the Storybook MCP before using any step — do not assume which steps are defined.
|
|
33
|
+
Key rules (full details in the instructions file):
|
|
195
34
|
|
|
196
|
-
|
|
35
|
+
1. **Query MCP before coding** — use Storybook MCP to confirm which WRI DS components exist and their props. Never guess.
|
|
36
|
+
2. **WRI DS first** — if a WRI DS component exists, use it. Never use the raw Chakra equivalent.
|
|
37
|
+
3. **No style overrides** — do not use `sx`, `css`, or inline styles to override WRI DS component styles.
|
|
38
|
+
4. **Tokens only** — use `getThemed*` from `@worldresources/wri-design-systems`. No hardcoded `#hex`, `rem`, `px`.
|
|
39
|
+
5. **No Chakra v2 API** — v3 has breaking changes. Verify props via Chakra MCP.
|
|
197
40
|
|
|
198
|
-
|
|
41
|
+
## Design Tokens — Source of Truth
|
|
199
42
|
|
|
200
|
-
|
|
201
|
-
- **Radius:** `getThemedRadius(token)` (Tokens: `100`, `200`, `300`, `400`, `500`, `600`, `700`, `800`, `900`)
|
|
202
|
-
- **Border Width:** `getThemedBorderWidth(token)` (Tokens: `100`, `200`, `300`, `400`)
|
|
203
|
-
- **Font Size:** `getThemedFontSize(token)` (Tokens: `200`, `300`, `400`, `500`, `600`, `700`, `800`, `900`, `1000`, `1100`)
|
|
204
|
-
- **Line Height:** `getThemedLineHeight(token)` (Tokens: `300`, `400`, `500`, `600`, `700`, `800`, `900`, `1000`, `1100`, `1200`)
|
|
43
|
+
All token functions are imported from the **package**:
|
|
205
44
|
|
|
206
|
-
```
|
|
45
|
+
```ts
|
|
207
46
|
import {
|
|
47
|
+
getThemedColor,
|
|
208
48
|
getThemedSpacing,
|
|
209
49
|
getThemedRadius,
|
|
210
50
|
getThemedBorderWidth,
|
|
211
51
|
getThemedFontSize,
|
|
212
52
|
getThemedLineHeight,
|
|
213
53
|
} from '@worldresources/wri-design-systems'
|
|
214
|
-
|
|
215
|
-
// ✅ Correct
|
|
216
|
-
;<Box
|
|
217
|
-
p={getThemedSpacing(400)}
|
|
218
|
-
borderRadius={getThemedRadius(500)}
|
|
219
|
-
border={`${getThemedBorderWidth(100)} solid ${getThemedColor('neutral', 300)}`}
|
|
220
|
-
>
|
|
221
|
-
<Text fontSize={getThemedFontSize(500)} lineHeight={getThemedLineHeight(600)}>
|
|
222
|
-
Label
|
|
223
|
-
</Text>
|
|
224
|
-
</Box>
|
|
225
54
|
```
|
|
226
55
|
|
|
227
|
-
|
|
56
|
+
| Function | Tokens |
|
|
57
|
+
| ------------------------------- | ---------------------------------------------------------------------------------------- |
|
|
58
|
+
| `getThemedColor(variant, step)` | variants: `neutral primary secondary success warning error accessible`; steps: `100–900` |
|
|
59
|
+
| `getThemedSpacing(token)` | `0 50 100 200 300 400 500 600 700 800 900 1000…` |
|
|
60
|
+
| `getThemedRadius(token)` | `100 200 300 400 500 600 700 800 900` |
|
|
61
|
+
| `getThemedBorderWidth(token)` | `100 200 300 400` |
|
|
62
|
+
| `getThemedFontSize(token)` | `200 300 400 500 600 700 800 900 1000 1100` |
|
|
63
|
+
| `getThemedLineHeight(token)` | `300 400 500 600 700 800 900 1000 1100 1200` |
|
|
228
64
|
|
|
229
|
-
|
|
65
|
+
Full token tables: `agents/spacing.md`, `agents/radius.md`, `agents/border-width.md`, `agents/typography.md`.
|
|
230
66
|
|
|
231
|
-
##
|
|
67
|
+
## MCP Servers (configured automatically by `npx ds setup-ai`)
|
|
232
68
|
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
import { Button } from "@chakra-ui/react" // → use WRI DS Button
|
|
236
|
-
|
|
237
|
-
// ❌ Do not override WRI DS styles
|
|
238
|
-
<Button sx={{ backgroundColor: "red" }}>Delete</Button>
|
|
239
|
-
|
|
240
|
-
// ❌ Do not hardcode design values or use raw strings for spacing, radius, etc.
|
|
241
|
-
<Text fontSize="14px" color="#333333">Label</Text> // → use getThemedFontSize, getThemedColor
|
|
242
|
-
<Box p="1rem" borderRadius="8px" /> // → use getThemedSpacing, getThemedRadius
|
|
243
|
-
|
|
244
|
-
// ❌ Do not use raw token strings as styling props — always use getThemed* functions
|
|
245
|
-
<Box bg="primary.500" /> // → use getThemedColor('primary', 500)
|
|
246
|
-
|
|
247
|
-
// ❌ Do not create custom components without the searchable marker
|
|
248
|
-
const MyButton = () => <button style={{ background: "blue" }}>Click</button>
|
|
249
|
-
|
|
250
|
-
// ❌ Do not skip the hierarchy — always check WRI DS and Chakra before going custom
|
|
251
|
-
|
|
252
|
-
// ❌ Do not use Chakra v2 API — v3 has breaking changes (e.g. colorScheme is removed)
|
|
253
|
-
// Always verify props via the Chakra MCP
|
|
254
|
-
```
|
|
69
|
+
- **Storybook MCP** — WRI DS components, props, and usage patterns
|
|
70
|
+
- **Chakra UI MCP** — Chakra v3 component props and migration guidance
|
|
255
71
|
|
|
256
|
-
|
|
72
|
+
## MCP Session Caveat
|
|
257
73
|
|
|
258
|
-
|
|
74
|
+
The setup command writes IDE-specific MCP config files such as `.vscode/mcp.json` and `.cursor/mcp.json`.
|
|
75
|
+
Those files help supported editors attach MCP servers, but they do **not** guarantee that every agent runtime or terminal session will automatically inherit those tools.
|
|
259
76
|
|
|
260
|
-
|
|
261
|
-
| --------------------------------------------- | ------------------------------------------------------------------------- |
|
|
262
|
-
| Does a WRI DS component exist? | [Storybook](https://wri.github.io/wri-design-systems/) or Storybook MCP |
|
|
263
|
-
| Detailed props / usage for a WRI DS component | Component README in GitHub: `src/components/<Category>/<Name>/README.md` |
|
|
264
|
-
| What props does a Chakra component accept? | Chakra MCP → `get_component_props` |
|
|
265
|
-
| What design tokens are available? | `agents/*.md` files, Chakra MCP → `get_theme`, or Zeroheight |
|
|
266
|
-
| Which color scales/steps are overridden here? | Read `src/components/Providers/index.tsx` — that is the source of truth |
|
|
267
|
-
| Which steps exist for non-overridden scales? | Query Storybook MCP — do not guess |
|
|
268
|
-
| How do I use a color in JSX? | `getThemedColor('scale', step)` from `@worldresources/wri-design-systems` |
|
|
269
|
-
| How do I use spacing/radius/fonts in JSX? | `getThemedSpacing`, `getThemedRadius`, `getThemedFontSize`, etc. |
|
|
270
|
-
| Where are all custom components in this repo? | "Find in Files" → `[CUSTOM COMPONENT]` |
|
|
77
|
+
If an agent cannot access Figma or Storybook in a given session, verify the MCP tools are actually exposed in that session before assuming the repo config is broken.
|
package/agents/setup-ai.mjs
CHANGED
|
@@ -18,6 +18,7 @@ import { fileURLToPath } from 'url'
|
|
|
18
18
|
|
|
19
19
|
const __dirname = dirname(fileURLToPath(import.meta.url))
|
|
20
20
|
const SOURCE = join(__dirname, 'AGENTS.md')
|
|
21
|
+
const SOURCE_COMPONENT_INSTRUCTIONS = join(__dirname, 'wri-ds.instructions.md')
|
|
21
22
|
// Where we write the setup files.
|
|
22
23
|
// Default is the repo root you're currently in when you run the CLI.
|
|
23
24
|
// You can optionally pass a target directory as argv[2].
|
|
@@ -37,9 +38,9 @@ if (!existsSync(SOURCE)) {
|
|
|
37
38
|
|
|
38
39
|
// ── Helpers ──────────────────────────────────────────────────────
|
|
39
40
|
|
|
40
|
-
function installFile(dest, label) {
|
|
41
|
+
function installFile(dest, label, src = SOURCE) {
|
|
41
42
|
mkdirSync(dirname(dest), { recursive: true })
|
|
42
|
-
copyFileSync(
|
|
43
|
+
copyFileSync(src, dest)
|
|
43
44
|
installed.push(`${label} → ${relative(ROOT, dest)}`)
|
|
44
45
|
}
|
|
45
46
|
|
|
@@ -184,6 +185,13 @@ if (hasVSCode) {
|
|
|
184
185
|
join(ROOT, '.github', 'copilot-instructions.md'),
|
|
185
186
|
'GitHub Copilot',
|
|
186
187
|
)
|
|
188
|
+
if (existsSync(SOURCE_COMPONENT_INSTRUCTIONS)) {
|
|
189
|
+
installFile(
|
|
190
|
+
join(ROOT, '.github', 'instructions', 'wri-ds.instructions.md'),
|
|
191
|
+
'GitHub Copilot (component instructions)',
|
|
192
|
+
SOURCE_COMPONENT_INSTRUCTIONS,
|
|
193
|
+
)
|
|
194
|
+
}
|
|
187
195
|
writeJSON(join(ROOT, '.vscode', 'mcp.json'), 'VS Code MCP config', mcpVSCode)
|
|
188
196
|
} else {
|
|
189
197
|
skipped.push('GitHub Copilot / VS Code (not detected)')
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: 'Use when importing or using @worldresources/wri-design-systems components, tokens, or utilities. Covers component hierarchy, API verification, design tokens, and forbidden patterns.'
|
|
3
|
+
applyTo: '**/*.tsx'
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# WRI Design System — Usage Rules
|
|
7
|
+
|
|
8
|
+
## Pre-Implementation Checklist (MANDATORY — run before writing any JSX)
|
|
9
|
+
|
|
10
|
+
1. **Query Storybook MCP first** — call `mcp_wri-storybook_getComponentList` then `mcp_wri-storybook_getComponentsProps` to confirm the component exists and its exact prop API. Never guess props.
|
|
11
|
+
2. **WRI DS first** — if it exists in the library, use it. Never use the raw Chakra equivalent when WRI DS already wraps it.
|
|
12
|
+
3. **No style overrides** — do not use `sx`, `css`, `style`, or `className` to override WRI DS component styles.
|
|
13
|
+
4. **Tokens only** — all values via `getThemed*` from `@worldresources/wri-design-systems`. No hardcoded `#hex`, `rem`, `px`.
|
|
14
|
+
5. **No Chakra v2 API** — verify props via Chakra MCP before using any Chakra component.
|
|
15
|
+
|
|
16
|
+
## Component Hierarchy (never skip a level)
|
|
17
|
+
|
|
18
|
+
```
|
|
19
|
+
1. @worldresources/wri-design-systems ← always check first
|
|
20
|
+
2. @chakra-ui/react ← fallback if no WRI DS equivalent exists
|
|
21
|
+
3. Custom code ← last resort; add // [CUSTOM COMPONENT] — <reason>
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
```tsx
|
|
25
|
+
// ❌ Raw Chakra when WRI DS already wraps it
|
|
26
|
+
import { Button } from '@chakra-ui/react'
|
|
27
|
+
|
|
28
|
+
// ✅ WRI DS component
|
|
29
|
+
import { Button } from '@worldresources/wri-design-systems'
|
|
30
|
+
;<Button variant='primary'>Save</Button>
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Custom components that have no WRI DS or Chakra equivalent must be marked:
|
|
34
|
+
|
|
35
|
+
```tsx
|
|
36
|
+
// [CUSTOM COMPONENT] — no WRI DS or Chakra equivalent for X
|
|
37
|
+
const MyThing = () => { ... }
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## API Verification — Never Guess
|
|
41
|
+
|
|
42
|
+
Confirm props, variants, and valid values from a trusted source before writing code:
|
|
43
|
+
|
|
44
|
+
1. **Storybook MCP** → `mcp_wri-storybook_getComponentsProps` (preferred for WRI DS)
|
|
45
|
+
2. **Component README** → GitHub `src/components/<Category>/<Name>/README.md`
|
|
46
|
+
3. **Chakra MCP** → `mcp_chakra-ui_get_component_props` (for Chakra-only components)
|
|
47
|
+
|
|
48
|
+
If you cannot confirm an API, ask the user rather than inventing props.
|
|
49
|
+
|
|
50
|
+
## Design Tokens
|
|
51
|
+
|
|
52
|
+
```ts
|
|
53
|
+
import {
|
|
54
|
+
getThemedColor,
|
|
55
|
+
getThemedSpacing,
|
|
56
|
+
getThemedRadius,
|
|
57
|
+
getThemedBorderWidth,
|
|
58
|
+
getThemedFontSize,
|
|
59
|
+
getThemedLineHeight,
|
|
60
|
+
} from '@worldresources/wri-design-systems'
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
| Function | Tokens |
|
|
64
|
+
| ------------------------------- | ---------------------------------------------------------------------------------------- |
|
|
65
|
+
| `getThemedColor(variant, step)` | variants: `neutral primary secondary success warning error accessible`; steps: `100–900` |
|
|
66
|
+
| `getThemedSpacing(token)` | `0 50 100 200 300 400 500 600 700 800 900 1000 1100 1200 1400 1600 2000 2400 2800` |
|
|
67
|
+
| `getThemedRadius(token)` | `100 200 300 400 500 600 700 800 900` |
|
|
68
|
+
| `getThemedBorderWidth(token)` | `100 200 300 400` |
|
|
69
|
+
| `getThemedFontSize(token)` | `200 300 400 500 600 700 800 900 1000 1100` |
|
|
70
|
+
| `getThemedLineHeight(token)` | `300 400 500 600 700 800 900 1000 1100 1200` |
|
|
71
|
+
|
|
72
|
+
```tsx
|
|
73
|
+
// ❌ Hardcoded value
|
|
74
|
+
<Box p="1rem" bg="#2C7D6E" borderRadius="8px" />
|
|
75
|
+
|
|
76
|
+
// ✅ Design tokens
|
|
77
|
+
<Box
|
|
78
|
+
p={getThemedSpacing(400)}
|
|
79
|
+
bg={getThemedColor('primary', 500)}
|
|
80
|
+
borderRadius={getThemedRadius(300)}
|
|
81
|
+
/>
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## Forbidden Patterns
|
|
85
|
+
|
|
86
|
+
| Pattern | Correct alternative |
|
|
87
|
+
| -------------------------------------------------------------------- | ------------------------------------------------------------- |
|
|
88
|
+
| `import { Button } from '@chakra-ui/react'` when WRI DS has `Button` | `import { Button } from '@worldresources/wri-design-systems'` |
|
|
89
|
+
| `<Button sx={{ ... }}>` overriding WRI DS styles | Remove style override |
|
|
90
|
+
| Hardcoded `#hex`, `rem`, `px` | `getThemed*` tokens |
|
|
91
|
+
| Raw token strings: `<Box bg="primary.500" />` | `getThemedColor('primary', 500)` |
|
|
92
|
+
| Inventing prop names without checking MCP | Query Storybook MCP first |
|
|
93
|
+
| Chakra v2 API (`colorScheme`, `variant` on v2 components) | Verify via Chakra MCP |
|