@worldresources/wri-design-systems 2.191.20 → 2.191.21

package/README.md

@@ -38,6 +38,8 @@ npm i @chakra-ui/react @emotion/react
 
 Run the DS CLI to set up AI tooling for this design system in your project root (the directory where you run the command).
 
+For the full setup guide see [docs/ai-tooling.md](docs/ai-tooling.md).
+
 ```
 ds setup-ai
 ```

package/agents/AGENTS.md

@@ -37,6 +37,7 @@ Key rules (full details in the instructions file):
 3. **No style overrides** — do not use `sx`, `css`, or inline styles to override WRI DS component styles.
 4. **Tokens only** — use `getThemed*` from `@worldresources/wri-design-systems`. No hardcoded `#hex`, `rem`, `px`.
 5. **No Chakra v2 API** — v3 has breaking changes. Verify props via Chakra MCP.
+6. **Accessibility first** — always provide `aria-*` props (like `aria-label` or `aria-describedby`), explicit `role` attributes, and ensure keyboard focus navigation context when consuming components.
 
 ## Design Tokens — Source of Truth
 
@@ -68,10 +69,3 @@ Full token tables: `agents/spacing.md`, `agents/radius.md`, `agents/border-width
 
 - **Storybook MCP** — WRI DS components, props, and usage patterns
 - **Chakra UI MCP** — Chakra v3 component props and migration guidance
-
-## MCP Session Caveat
-
-The setup command writes IDE-specific MCP config files such as `.vscode/mcp.json` and `.cursor/mcp.json`.
-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.
-
-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/a11y.instructions.md

@@ -0,0 +1,68 @@
+---
+description: 'Accessibility rules for WRI DS consumers. Auto-attached when editing .tsx files. Covers required aria props, per-component type rules, and common mistakes.'
+applyTo: '**/*.tsx'
+---
+
+# WRI DS — Accessibility for Consumers
+
+When using `@worldresources/wri-design-systems`, always pass the required accessibility props.
+The components handle ARIA roles, focus management, and keyboard interactions internally —
+but only if you provide the right props at the call site.
+
+## Core Rules
+
+1. **Icon-only actions always need `aria-label`** — `IconButton`, `CloseButton`, and any `Button` with no visible text must receive `aria-label`.
+2. **Form fields always need a label** — pass the `label` prop, or provide `aria-label`/`aria-labelledby` if no visible label is shown.
+3. **Error states need two signals** — set `aria-invalid` and wire `aria-describedby` to the error message in addition to any color change.
+4. **Never suppress focus** — do not add `tabIndex={-1}` or `outline: none` to interactive WRI DS components.
+5. **Navigation regions need `aria-label`** — when using `Navbar` or any `<nav>` wrapper, pass `aria-label` to distinguish multiple nav landmarks on the page.
+
+## Per-Component Quick Reference
+
+| Component type                                       | What you must provide at the call site                                                                                     |
+| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `IconButton`, `CloseButton`                          | `aria-label` (required — no default)                                                                                       |
+| `Button` with no visible text                        | `aria-label`                                                                                                               |
+| Toggle `Button`                                      | `aria-pressed={isPressed}`                                                                                                 |
+| `Button` that opens a panel / menu                   | `aria-expanded={isOpen}` + `aria-controls="<panel-id>"`                                                                    |
+| `TextInput`, `Select`, `Checkbox`, `Radio`, `Switch` | `label` prop or `aria-label`/`aria-labelledby`; `aria-required` for required fields                                        |
+| Fields with validation errors                        | `aria-invalid={true}` + `aria-describedby="<error-id>"`                                                                    |
+| `Modal`, `Panel`, `Sheet`                            | `title` prop (maps to `aria-labelledby`) or `aria-label` when no visible title                                             |
+| `Navbar`, `Footer`, nav wrappers                     | `aria-label` to distinguish landmarks (e.g. `"Main navigation"`, `"Footer"`)                                               |
+| `Table`                                              | `aria-label` or a `<caption>` child; `aria-sort` on sortable column headers                                                |
+| `AlertBanner`, `Toast`, `InlineMessage`              | Ensure `role="alert"` (critical) or `role="status"` (informational) — check the component's default and override if needed |
+
+## Common Mistakes
+
+```tsx
+// ❌ Icon-only button with no accessible name
+<IconButton icon={<DeleteIcon />} onClick={fn} />
+
+// ✅
+<IconButton icon={<DeleteIcon aria-hidden="true" />} aria-label="Delete item" onClick={fn} />
+
+// ❌ Form field with no label — placeholder is not an accessible label
+<TextInput placeholder="Search..." />
+
+// ✅
+<TextInput label="Search" placeholder="Search..." />
+
+// ❌ Error state using only color — screen readers won't know it's invalid
+<TextInput label="Email" style={{ borderColor: 'red' }} />
+
+// ✅
+<TextInput
+  label="Email"
+  error="Enter a valid email address"
+  aria-invalid={true}
+  aria-describedby="email-error"
+/>
+
+// ❌ Multiple nav regions with no distinguishing label
+<Navbar />
+<nav>{footerLinks}</nav>
+
+// ✅
+<Navbar aria-label="Main navigation" />
+<nav aria-label="Footer">{footerLinks}</nav>
+```

package/agents/wri-ds.instructions.md

@@ -12,6 +12,41 @@ applyTo: '**/*.tsx'
 3. **No style overrides** — do not use `sx`, `css`, `style`, or `className` to override WRI DS component styles.
 4. **Tokens only** — all values via `getThemed*` from `@worldresources/wri-design-systems`. No hardcoded `#hex`, `rem`, `px`.
 5. **No Chakra v2 API** — verify props via Chakra MCP before using any Chakra component.
+6. **Accessibility check** — confirm that necessary `aria-*` props, roles, and keyboard navigation considerations are explicitly added.
+
+## Accessibility (A11y) — Mandatory
+
+When consuming WRI DS components, always ensure that accessibility context is preserved and passed correctly.
+
+1. **Name every control:** If a control has no visible text label (icon-only, or label is visually hidden), you **must** provide an accessible name via `aria-label` (or `aria-labelledby`).
+2. **Connect helper/error text:** When there is helper text or validation errors, connect it using `aria-describedby` (and `aria-errormessage` if the component supports it). Prefer the component’s built-in props for this (verify via Storybook MCP) instead of custom DOM glue.
+3. **State must be announced:** For toggles/menus/expanders, reflect state with `aria-expanded`, `aria-controls`, `aria-pressed`, `aria-selected` as appropriate (again: verify the DS component API first).
+4. **Keyboard support is non‑negotiable:** Any custom wrapper around DS components must preserve focusability and keyboard activation (Enter/Space for buttons; Arrow keys where applicable). Do not remove focus outlines.
+5. **Tables and lists:** Provide structure (`caption`, correct header cells, sort state announcements like `aria-sort`) when using tabular components. If you can’t confirm the right props, stop and query Storybook MCP.
+
+### A11y Defaults When Using Common DS Components
+
+These rules apply when consuming components; **do not invent prop names**—verify each component’s actual a11y-related props with Storybook MCP.
+
+- **`Button`, `IconButton`, `CloseButton`**
+  - Icon-only actions: require `aria-label` (localized).
+  - Destructive actions: ensure the visible label is explicit (“Delete”, “Remove”, etc.) and confirm focus/disabled states still announce correctly.
+- **`Tooltip`**
+  - Tooltip is not a label replacement. Keep `aria-label`/visible label on the trigger when the action is otherwise unlabeled.
+- **`Menu` (trigger + items)**
+  - Icon-only trigger: require `aria-label`.
+  - If the trigger opens/closes, ensure state is represented (often `aria-expanded` is handled by the component—verify).
+- **`Modal` / `Sheet`**
+  - Provide a clear, unique title and ensure it is announced (typically via `aria-labelledby` or a `title` prop depending on the DS API).
+  - Ensure close action is reachable and labeled (`aria-label` on close icon buttons).
+- **Form controls (`TextInput`, `Select`, `Textarea`, `Checkbox`, `Radio`, etc.)**
+  - Prefer the DS `label` prop (or label slot) for accessible naming.
+  - If a field is required/invalid/disabled, ensure the correct state is exposed via props (verify which props exist).
+- **`Table`**
+  - Sortable headers must communicate sort state (`aria-sort` or DS equivalent). Do not rely on icon color alone.
+  - Provide row selection announcements where selection exists.
+- **`Toast`, `InlineMessage`, `AlertBanner`**
+  - Status messages must be announced appropriately (`role="status"` / `role="alert"` behavior). Prefer DS defaults; if composing custom status UI, add the correct roles and `aria-live` semantics.
 
 ## Component Hierarchy (never skip a level)