@worldresources/wri-design-systems 2.194.5 → 2.195.0

package/README.md

@@ -70,6 +70,19 @@ Optional: run it against a specific path:
 ds setup-ai /path/to/your/project
 ```
 
+### Available Skills
+
+Copy the `SKILL.md` file you want into the matching skills folder in your own project:
+
+- Skills repo path: `agents/skills/<skill-name>/SKILL.md`
+- Copy the folder into the agent-specific skills directory your project uses.
+
+| Skill                                                     | What it does                                                                                  |
+| --------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| [`a11y-checker`](agents/skills/a11y-checker/SKILL.md)     | Reviews components, stories, and docs for accessibility issues and suggests or applies fixes. |
+| [`ds-ui-creator`](agents/skills/ds-ui-creator/SKILL.md)   | Guides UI creation with the WRI Design System first, Chakra UI second, and custom code last.  |
+| [`pr-description`](agents/skills/pr-description/SKILL.md) | Generates a PR description from the branch diff in a consistent markdown format.              |
+
 ### Create the Project Theme
 
 With this custom theme you can change the color scheme according to your Project Theme

package/agents/skills/a11y-checker/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: a11y-checker
+description: Reviews UI code (HTML, JSX, TSX, Vue, etc.) for accessibility (a11y) compliance across both library development (WRI Design System) and generic web applications, providing concrete guidelines and code-level fixes.
+---
+
+When running the accessibility checker on any codebase, follow this multi-tiered guide to ensure compliance with universal WCAG standards as well as library-specific rules.
+
+## 1. Universal Accessibility Standards (Any Web Project)
+
+Apply these rules to any kind of project (plain HTML, native React, Vue, Angular, or other UI libraries):
+
+### Accessible Names & Interactive Elements
+
+- **Discernible Text**: Every clickable control (buttons, links, inputs) must have a discernible text label.
+- **Icon-Only Actions**: If a button contains only an icon or image, it must receive an `aria-label` or `aria-labelledby` attribute (e.g., `<button aria-label="Close dialog">` or `<IconButton aria-label="Delete item" />`).
+- **Images and SVGs**:
+  - Standalone SVGs used as controls must have `role="img"` and an `aria-label`.
+  - Decorative icons or illustrations must have `aria-hidden="true"` or `alt=""` so they are ignored by screen readers.
+
+### Forms & Input Controls
+
+- **Explicit Associations**: Native HTML form controls must have a `<label>` explicitly linked using the `for` (or `htmlFor` in React) and `id` attributes.
+- **Accessible Placeholders**: A `placeholder` is not an accessible label. A proper visible label or `aria-label` must always be provided.
+- **Validation Signals**: Error states must never rely on color changes alone. Set `aria-invalid="true"` and programmatically link the input to its validation error message using `aria-describedby="error-message-id"`.
+
+### Layout & Landmark Structures
+
+- **Semantic HTML**: Use correct semantic tags (`<header>`, `<nav>`, `<main>`, `<footer>`, `<aside>`, `<section>`) instead of generic `<div>` wrappers.
+- **Multiple Landmarks**: If a page has multiple navigation regions, distinguish them using unique `aria-label` attributes (e.g., `<nav aria-label="Main navigation">` and `<nav aria-label="Footer navigation">`).
+
+### Keyboard Navigation & Focus Management
+
+- **Focus Path**: Every interactive element must be reachable using the `Tab` key. Custom non-interactive elements that trigger actions (e.g., a clickable `div`) must have `tabindex="0"`.
+- **Keyboard Triggers**: Custom interactive elements must handle `Enter` and `Space` key presses using keydown/keyup event handlers.
+- **Visible Focus**: Never suppress the browser's default focus outlines (`outline: none` or `outline: 0`) unless you are explicitly defining custom, highly-visible CSS focus indicator styles (e.g. using `:focus-visible`).
+- **Overlay Focus Traps**: Modals, slide-out panels, and dropdown menus must trap keyboard focus inside them while open, and must restore focus to the triggering element upon closure.
+
+### Data & Tabular Layouts
+
+- **Tables**: HTML tables must use correct semantic markup (`<table>`, `<thead>`, `<tbody>`, `<tr>`, `<th>`, `<td>`). Headers should use `scope="col"` or `scope="row"`. Provide a `<caption>` or an `aria-label` to summarize the table structure.
+- **Sortable Columns**: Header cells representing sortable columns must declare the current sort order via `aria-sort` (e.g. `aria-sort="ascending"` or `aria-sort="descending"`).
+
+---
+
+## 2. Project-Specific Rules
+
+### Context A: WRI Design System Library Contributor (`src/components/**`)
+
+When writing or updating components inside the `@worldresources/wri-design-systems` library:
+
+- **Expose ARIA Props**: Ensure TypeScript interfaces in `types.ts` explicitly declare standard `aria-*` props, and forward them directly to the underlying elements.
+- **Defaults**: Check the component documentation guidelines in `contributor-ai/a11y.instructions.md`.
+- **Test with Axe**: Write stories (`*.stories.tsx`) that demonstrate accessible configurations and include testing using `jest-axe` or Storybook's built-in a11y tools.
+
+### Context B: Consumer Apps using WRI Design System
+
+When consuming WRI DS components in external applications:
+
+- **Use Wrapper API**: Prefer built-in design system properties (e.g., `label` and `error` props on `TextInput` or `Select`) which automatically wire up proper markup, instead of manually writing custom ARIA glue.
+- **No Overrides**: Never add `tabIndex={-1}` or visual overrides that hide focus rings on standard DS buttons or inputs.
+
+---
+
+## 3. Auditing Process
+
+When checking a file, follow this flow:
+
+1. **Interactive Control Scan**: Locate all interactive controls (buttons, links, custom clickable elements). Verify that each has a discernible name (text, `aria-label`, or linked label).
+2. **Keyboard Path Audit**: Trace where focus moves. Ensure overlays/modals have trap-and-release focus management, and focus indicators are visible.
+3. **Form Wiring Verification**: Check that all input fields have valid labels, required states (`aria-required`), and connected error messages.
+4. **Markup Semantics Check**: Ensure landmarks exist and no inline SVG or icon lack proper `aria-hidden` or label states.
+
+---
+
+## 4. Code Examples (Common Fixes)
+
+### Custom Icon Buttons
+
+```tsx
+// ❌ HTML / Generic React Error (No accessible name, icon read as raw text or ignored)
+<button onClick={onClose}><CloseIcon /></button>
+
+// ✅ HTML / Generic React Fix
+<button aria-label="Close dialog" onClick={onClose}>
+  <CloseIcon aria-hidden="true" />
+</button>
+
+// ✅ WRI DS Fix
+<IconButton aria-label="Close dialog" icon={<CloseIcon aria-hidden="true" />} onClick={onClose} />
+```
+
+### Form Fields with Error States
+
+```tsx
+// ❌ Generic HTML Error (Color only, screen reader cannot read validation error connection)
+<input type="email" style={{ borderColor: 'red' }} />
+<span className="error">Invalid email address</span>
+
+// ✅ Generic HTML Fix
+<label htmlFor="email-input">Email Address</label>
+<input
+  id="email-input"
+  type="email"
+  aria-invalid="true"
+  aria-describedby="email-error-msg"
+/>
+<span id="email-error-msg" className="error">Invalid email address</span>
+
+// ✅ WRI DS Fix
+<TextInput
+  label="Email Address"
+  error="Invalid email address"
+  aria-invalid={true}
+  aria-describedby="email-error-msg"
+  id="email-input"
+/>
+```

package/agents/skills/ds-ui-creator/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: ds-ui-creator
+description: Guidelines for building user interfaces and components in applications consuming the WRI Design System, incorporating Level 1 (WRI DS), Level 2 (Chakra UI v3), and Level 3 (Custom CSS/HTML).
+---
+
+When building components and user interfaces in an application consuming the WRI Design System, developers and AI coding agents must follow these guidelines:
+
+## 1. Component Hierarchy (Golden Rule)
+
+Always evaluate and build UI elements using the following hierarchy. Never skip a level:
+
+```
+1. @worldresources/wri-design-systems (WRI DS) ← Always check first
+2. @chakra-ui/react (Chakra UI v3)             ← Fallback if no WRI DS equivalent
+3. Custom HTML + CSS / Styled Primitives       ← Last resort (requires reasoning tag)
+```
+
+### Level 1: WRI Design System (`@worldresources/wri-design-systems`)
+
+- **First Choice**: Check Storybook, Zeroheight style guide, or README files to verify if a component exists in the design system.
+- **Do Not Rebuild**: Never use raw elements (e.g. `<button>`, `<input>`, `<select>`) or raw Chakra equivalents when a WRI DS wrapper exists (e.g. `Button`, `IconButton`, `Select`, `TextInput`).
+- **No Style Overrides**: Do NOT use `sx`, `css`, `style`, or `className` to override design system component styles. Use them exactly as-is to preserve visual consistency.
+- **Query MCP**: Use the Storybook MCP server to check component listings (`mcp_wri-storybook_getComponentList`) and verify exact prop signatures (`mcp_wri-storybook_getComponentsProps`).
+
+### Level 2: Chakra UI v3 (`@chakra-ui/react`)
+
+- **Use as Fallback**: If there is no corresponding WRI DS component, use standard Chakra UI v3 primitives (e.g., `<Box>`, `<Flex>`, `<Grid>`).
+- **Chakra v3 API Only**: Do not use legacy Chakra v2 properties (like `colorScheme`, `isDisabled`, or `leftIcon`). Verify all props using the Chakra MCP server (`mcp_chakra-ui_get_component_props`).
+- **Theme Integration**: Apply styling using the themed token functions rather than passing raw non-token values.
+
+### Level 3: Custom Code (Last Resort)
+
+- **Required Marker**: If custom CSS or custom HTML is absolutely necessary because neither WRI DS nor Chakra v3 has the capabilities needed, comment it clearly with:
+  `// [CUSTOM COMPONENT] — <detailed reason explaining why Level 1 & 2 were bypassed>`
+- **No Hardcoding**: Custom components must still use design token functions for sizes, colors, margins, and borders. Never write raw hex colors, px, or rem.
+
+---
+
+## 2. Design Tokens & Theme API (Strict Token Enforcement)
+
+All values (colors, spacing, typography, borders, radii) must resolve through the design system token functions. Never hardcode literal values like `#2C7D6E`, `1rem`, `16px`, etc.
+
+### Token Helper Imports
+
+Import the themed helpers directly from the `@worldresources/wri-design-systems` package:
+
+```typescript
+import {
+  getThemedColor,
+  getThemedSpacing,
+  getThemedRadius,
+  getThemedBorderWidth,
+  getThemedFontSize,
+  getThemedLineHeight,
+} from '@worldresources/wri-design-systems'
+```
+
+### Reference Tables
+
+| Category         | Function                        | Valid Values / Steps / Tokens                                                                                                                                            | Example                                 |
+| :--------------- | :------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------- |
+| **Colors**       | `getThemedColor(variant, step)` | **Variants**: `neutral`, `primary`, `secondary`, `success`, `warning`, `error`, `accessible`<br>**Steps**: `100`, `200`, `300`, `400`, `500`, `600`, `700`, `800`, `900` | `getThemedColor('primary', 500)`        |
+| **Spacing**      | `getThemedSpacing(token)`       | `0`, `50`, `100`, `200`, `300`, `400`, `500`, `600`, `700`, `800`, `900`, `1000`, `1100`, `1200`, `1400`, `1600`, `2000`, `2400`, `2800`                                 | `getThemedSpacing(400)` (1rem)          |
+| **Radius**       | `getThemedRadius(token)`        | `100`, `200`, `300`, `400`, `500`, `600`, `700`, `800`, `900`                                                                                                            | `getThemedRadius(500)` (0.5rem)         |
+| **Border Width** | `getThemedBorderWidth(token)`   | `100`, `200`, `300`, `400`                                                                                                                                               | `getThemedBorderWidth(100)` (0.0625rem) |
+| **Font Size**    | `getThemedFontSize(token)`      | `200`, `300`, `400`, `500`, `600`, `700`, `800`, `900`, `1000`, `1100`                                                                                                   | `getThemedFontSize(700)` (1.5rem)       |
+| **Line Height**  | `getThemedLineHeight(token)`    | `300`, `400`, `500`, `600`, `700`, `800`, `900`, `1000`, `1100`, `1200`                                                                                                  | `getThemedLineHeight(400)` (1rem)       |
+
+### Code Examples
+
+```tsx
+// ❌ INCORRECT (Hardcoded visual values & bypassed tokens)
+<Box
+  p="1rem"
+  bg="#2C7D6E"
+  borderRadius="8px"
+  fontSize="16px"
+  border="1px solid #E2E8F0"
+/>
+
+// ✅ CORRECT (Tokens mapped using design system theme helper functions)
+<Box
+  p={getThemedSpacing(400)}
+  bg={getThemedColor('primary', 500)}
+  borderRadius={getThemedRadius(500)}
+  fontSize={getThemedFontSize(400)}
+  border={`${getThemedBorderWidth(100)} solid ${getThemedColor('neutral', 200)}`}
+/>
+```
+
+---
+
+## 3. Accessibility (A11y) Requirements
+
+Accessibility must be verified at every call site. Components provide internally sound accessible states, but they require proper configurations from developers:
+
+1. **Accessible Control Names**:
+   - Icon-only actions (like `IconButton`, `CloseButton`, or a text-free `Button`) must receive a localized, descriptive `aria-label`.
+   - Form fields must have labels. Prefer the built-in `label` prop. If no visible label is shown, provide `aria-label` or `aria-labelledby`.
+2. **Interactive States**:
+   - Toggle buttons must reflect state with `aria-pressed={isPressed}`.
+   - Elements that trigger collapsible panels or menus must use `aria-expanded={isOpen}` and `aria-controls="panel-id"`.
+3. **Form Validation & Error States**:
+   - When a field has validation errors, set `aria-invalid={true}` and use `aria-describedby` pointing to the error message container. Never signal an error state through color changes alone.
+4. **Layout Navigation Landmarks**:
+   - Multiple navigation regions must be distinguished with distinct labels (e.g. `<nav aria-label="Main navigation">` and `<nav aria-label="Footer">`).
+5. **Tabular Information**:
+   - Tables must have an `aria-label` or a `<caption>` child, and sortable headers must announce sorting state via `aria-sort` or its equivalent.
+6. **Focus Management**:
+   - Never suppress focus outlines (e.g., do not add `outline: none` or set `tabIndex={-1}` on interactive controls unless deliberately building focus-trap cycles).
+
+---
+
+## 4. Internationalization (i18n)
+
+All WRI DS components ship with English defaults. To localize UI strings for other languages, follow one of these patterns:
+
+- **Global/Provider Context**: Wrap the application with `DesignSystemLocaleProvider` to pass common translations (e.g., optional field suffixes, required markers, list expand/hide actions).
+
+  ```tsx
+  import { DesignSystemLocaleProvider, type DesignSystemLabels } from '@worldresources/wri-design-systems'
+
+  const labels: DesignSystemLabels = {
+    TextInput: {
+      optionalSuffix: t('common.optional'),
+      requiredSymbolLabel: t('common.required'),
+    },
+    CheckboxList: {
+      expandLabel: t('ds.expand'),
+      hideLabel: t('ds.hide'),
+    },
+  }
+
+  <DesignSystemLocaleProvider labels={labels}>
+    <App />
+  </DesignSystemLocaleProvider>
+  ```
+
+- **Component-Level Override**: Pass translated values directly to the component using its `labels` prop. Never hardcode English literals in the `labels` prop; always route strings through the translation framework.
+  ```tsx
+  <Password
+    labels={{
+      showLabel: t('password.show'),
+      hideLabel: t('password.hide'),
+    }}
+  />
+  ```
+
+---
+
+## 5. Forbidden Patterns
+
+- **Importing Raw Chakra Primitives when WRI DS Wrappers Exist**: Do not do `import { Button } from '@chakra-ui/react'` when WRI DS has `Button`.
+- **Applying Style Overrides on WRI DS Components**: Bypassing design consistency with `sx={{...}}`, `style={{...}}`, or inline style blocks is forbidden.
+- **Passing Raw Strings for Tokens**: Do not use `<Box bg="primary.500" />`. Use the exact helper call instead: `<Box bg={getThemedColor('primary', 500)} />`.
+- **Placeholder Labels**: Do not use `placeholder` in place of a proper visible label or `aria-label` attribute.

package/agents/skills/pr-description/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: pr-description
+description: Guidelines for writing PR description. Covers required content, formatting, and examples. Use when the user asks to summarize changes for a PR or create a PR description.
+---
+
+When writing a PR description:
+
+1. Run `git diff main...HEAD` to see all changes on this branch
+2. Write a description following this format, in markdown:
+
+## What
+
+One sentence explaining what this PR does.
+
+## Why
+
+Brief context on why this change is needed
+
+## Changes
+
+- Bullet points of specific changes made
+- Group related changes together
+- Mention any files deleted or renamed
+- Add some examples of before/after code where helpful