@iress-oss/ids-components 6.0.0-beta.3 → 6.0.0-beta.5

package/.ai/components/popover.md

@@ -173,6 +173,29 @@ This will be the case when you are rendering into its parent container, which is
 
 [View "ParentContainer" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-popover--parent-container)
 
+### Using the `IressPopoverProvider`
+
+You can use the `IressPopoverProvider` to set a shared container for
+all nested popovers. This is useful when you want all popovers in a
+section of your application to render into the same DOM node, similar
+to how `IressModalProvider` and `IressSlideoutProvider` work.
+
+Individual popovers can still override the provider's container by
+setting their own `container` prop.
+
+> **Note:** If you are already using `IressProvider` or `IressShadow`,
+> you do not need to add `IressPopoverProvider` separately — it is
+> already included. To set a shared container for popovers through
+> `IressProvider`, use the `popoverContainer` prop. You can also set
+> `popoverContainer="container"` to reuse the same container that
+> modals, slideouts and toasts render into.
+
+```tsx
+<AppWithPopoverProvider />
+```
+
+[View "Provider" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-provider--provider)
+
 ## `IressInputPopover`
 
 If you need a popover that is triggered by input changes, you can use the `IressInputPopover` component. This component has an additional `minLength` prop that allows you to specify the minimum number of characters required before the popover is shown.

package/.ai/components/provider.md

@@ -19,10 +19,11 @@ The design system provider automates some set-up tasks for you, including:
 
 - Adding the icon fonts and CSS variables to the document head
 - Consistent container handling for providers, if you need the modals, slideouts and toasts rendered in a specific area (common with micro frontends)
+- Optional separate container for popovers via the `popoverContainer` prop
 
 In most cases, you should wrap the entire application with the `IressProvider` component. This will ensure that the design system is set up correctly and consistently across the application.
 
-> **Note:** `IressProvider` already includes `IressModalProvider`, `IressSlideoutProvider`, `IressToasterProvider`, and `IressIconProvider`. You do not need to add these providers separately when using `IressProvider`. Similarly, `IressShadow` includes `IressProvider` internally, so you do not need any additional providers when using `IressShadow`.
+> **Note:** `IressProvider` already includes `IressModalProvider`, `IressSlideoutProvider`, `IressToasterProvider`, `IressPopoverProvider`, and `IressIconProvider`. You do not need to add these providers separately when using `IressProvider`. Similarly, `IressShadow` includes `IressProvider` internally, so you do not need any additional providers when using `IressShadow`.
 
 ```tsx
 import { IressProvider } from '@iress-oss/ids-components';

package/.ai/skills/figma-to-ids.md

@@ -4,12 +4,53 @@
 
 Translate Figma design properties and structures into IDS (Iress Design System) component implementations. This skill helps AI agents interpret Figma design metadata (from tools like Figma MCP or exported design specs) and produce accurate IDS code.
 
+## Figma MCP Setup
+
+AI agents need a Figma MCP server to read Figma files directly. Without one, you can still use this skill by pasting exported design specs or Figma component descriptions manually.
+
+### Setup
+
+1. **Get a Figma personal access token** — In Figma, go to *Settings → Account → Personal access tokens* and create a token with **File content (Read-only)** scope.
+
+2. **Add the MCP server to your agent config.** The exact location depends on your tool:
+
+   | Tool | Config file |
+   | --- | --- |
+   | **Kiro CLI** | `~/.kiro/settings/mcp.json` (global) or `.kiro/settings/mcp.json` (workspace) |
+   | **Cursor** | `.cursor/mcp.json` |
+   | **Claude Code** | `.claude/mcp.json` or `~/.claude/mcp.json` |
+   | **VS Code (GitHub Copilot)** | `.vscode/mcp.json` |
+
+   Example configuration (using the community [`figma-developer-mcp`](https://github.com/nicholasgriffintn/figma-developer-mcp) server):
+
+   ```json
+   {
+     "mcpServers": {
+       "Figma": {
+         "command": "npx",
+         "args": ["-y", "figma-developer-mcp", "--stdio"],
+         "env": {
+           "FIGMA_API_KEY": "<your-figma-token>"
+         }
+       }
+     }
+   }
+   ```
+
+   For Kiro CLI, you can also add it via the command line:
+
+   ```bash
+   kiro-cli mcp add --name Figma --command npx --args "-y figma-developer-mcp --stdio" --env "FIGMA_API_KEY=<your-figma-token>"
+   ```
+
+3. **Verify** — Ask your agent to fetch data from a Figma file URL. It should return frame and component information.
+
 ## Process
 
 1. **Analyse Figma structure** — Identify frames, auto-layout, and component instances
 2. **Map components** — Match Figma component names/variants to IDS components
 3. **Extract tokens** — Convert Figma design values to IDS design token references
-4. **Generate code** — Produce clean React/TypeScript with proper IDS imports
+4. **Generate code** — Produce clean, minimal React/TypeScript with proper IDS imports. Use the fewest components possible — check whether parent components already handle layout before adding `IressInline`/`IressStack` wrappers. Never wrap a single child in a layout component.
 5. **Verify output** — Check that all imports resolve, no raw HTML is used where IDS components exist, grid layouts use responsive `span` values, and no common anti-patterns are present (disabled buttons, slot attributes, redundant textStyle)
 
 > **Important:** IDS v6 is currently in beta. Install with the `@beta` tag:
@@ -49,11 +90,11 @@ When mapping Figma components to IDS, read references/component-mapping.md for t
 | Input / Text       | `IressField` + `IressInput`                  | label, placeholder         |
 | Input / Currency   | `IressField` + `IressInputCurrency`          | label                      |
 | Select / Dropdown  | `IressField` + `IressSelect`                 | label, options             |
-| Checkbox           | `IressCheckbox`                              | label                      |
-| Checkbox Group     | `IressCheckboxGroup` + `IressCheckbox`s      | label                      |
-| Radio Group        | `IressRadioGroup` + `IressRadio`s            | label                      |
-| Toggle             | `IressToggle`                                | label                      |
-| Card               | `IressCard`                                  | Header, Body, Footer slots |
+| Checkbox           | `IressCheckbox`                              | `children` for label       |
+| Checkbox Group     | `IressCheckboxGroup` + `IressCheckbox`s      | Wrap in `IressField` for label |
+| Radio Group        | `IressRadioGroup` + `IressRadio`s            | Wrap in `IressField` for label |
+| Toggle             | `IressToggle`                                | `children` for label       |
+| Card               | `IressCard`                                  | `heading`, `footer` props; `children` for body |
 | Panel              | `IressPanel`                                 |                            |
 | Alert / Success    | `IressAlert status="success"`                |                            |
 | Alert / Danger     | `IressAlert status="danger"`                 |                            |
@@ -65,7 +106,7 @@ When mapping Figma components to IDS, read references/component-mapping.md for t
 | Modal / Warning    | `IressModal status="warning"`                | actions, size sm/md only   |
 | Slideout / Drawer  | `IressSlideout`                              |                            |
 | Tabs               | `IressTabSet` + `IressTab`                   |                            |
-| Table              | `IressTable`                                 | Head, Body, Row, Cell      |
+| Table              | `IressTable`                                 | Data-driven: `rows`, `columns`, `caption` props |
 | Tag                | `IressTag`                                   | `bordered` for visible border; `element="button"` for clickable, `element="a"` for link; `onClick` alone also auto-renders as button |
 | Pill               | `IressPill`                                  |                            |
 | Tooltip            | `IressTooltip`                               |                            |
@@ -132,19 +173,23 @@ IDS base spacing unit = 4px (0.25rem). Map Figma pixel values:
 
 ## Typography
 
-| Figma Text Style                   | IDS Token                    | Component                               |
-| ---------------------------------- | ---------------------------- | --------------------------------------- |
-| Heading / H1 (Ubuntu 24px/500)     | `typography.heading.1`       | `<IressText element="h1">`              |
-| Heading / H2 (Ubuntu 20px/500)     | `typography.heading.2`       | `<IressText element="h2">`              |
-| Heading / H3 (Ubuntu 18px/500)     | `typography.heading.3`       | `<IressText element="h3">`              |
-| Heading / H4 (Ubuntu 16px/500)     | `typography.heading.4`       | `<IressText element="h4">`              |
-| Heading / H5 (Ubuntu 16px/400)     | `typography.heading.5`       | `<IressText element="h5">`              |
-| Body / MD Regular (Inter 14px/400) | `typography.body.md.regular` | `<IressText>` (default)                 |
-| Body / MD Medium (Inter 14px/500)  | `typography.body.md.medium`  | `<IressText weight="medium">`           |
-| Body / MD Strong (Inter 14px/600)  | `typography.body.md.strong`  | `<IressText weight="strong">`           |
-| Body / SM Regular (Inter 12px/400) | `typography.body.sm.regular` | `<IressText size="sm">`                 |
-| Body / SM Strong (Inter 12px/600)  | `typography.body.sm.strong`  | `<IressText size="sm" weight="strong">` |
-| Code (Space 16px/400)              | `typography.code`            | `<IressText element="code">`            |
+Prefer semantic HTML elements via the `element` prop — they convey meaning to screen readers. Only fall back to `textStyle` when no semantic element matches the visual treatment.
+
+| Figma Text Style                   | IDS Token                    | Component                                                                                         |
+| ---------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------- |
+| Heading / H1 (Ubuntu 24px/500)     | `typography.heading.1`       | `<IressText element="h1">`                                                                        |
+| Heading / H2 (Ubuntu 20px/500)     | `typography.heading.2`       | `<IressText element="h2">`                                                                        |
+| Heading / H3 (Ubuntu 18px/500)     | `typography.heading.3`       | `<IressText element="h3">`                                                                        |
+| Heading / H4 (Ubuntu 16px/500)     | `typography.heading.4`       | `<IressText element="h4">`                                                                        |
+| Heading / H5 (Ubuntu 16px/400)     | `typography.heading.5`       | `<IressText element="h5">`                                                                        |
+| Body / MD Regular (Inter 14px/400) | `typography.body.md.regular` | `<IressText>` (default) or `<IressText element="p">` for paragraph semantics                      |
+| Body / MD Medium (Inter 14px/500)  | `typography.body.md.medium`  | `<IressText textStyle="typography.body.md.medium">` — use `textStyle` because there is no semantic medium element |
+| Body / MD Strong (Inter 14px/600)  | `typography.body.md.strong`  | `<IressText element="strong">` — conveys emphasis to screen readers                               |
+| Body / SM Regular (Inter 12px/400) | `typography.body.sm`         | `<IressText element="small">` — conveys fine print / secondary text                               |
+| Body / SM Strong (Inter 12px/600)  | `typography.body.sm.strong`  | `<IressText element="small"><strong>...</strong></IressText>`                                     |
+| Code (Space 16px/400)              | `typography.code`            | `<IressText element="code">`                                                                      |
+
+> **When to use `textStyle`:** Only when you need to visually override the default styling of a semantic element — e.g. making an `h2` look like an `h4` for visual hierarchy while keeping the correct heading level for accessibility: `<IressText element="h2" textStyle="typography.heading.4">`.
 
 > **Tip:** When translating Figma frames that contain mixed or unstructured text (e.g. CMS content, markdown, rich text blocks), wrap the content in `IressText` and nest native HTML elements (`<p>`, `<strong>`, `<a>`, `<ul>`, etc.) inside it. This is an allowed pattern that lets `IressText` apply consistent typography while preserving the original content structure.
 
@@ -176,8 +221,8 @@ import {
 
 function LoginForm() {
   return (
-    <IressCard p="6">
-      <IressStack gap="4">
+    <IressCard p="lg">
+      <IressStack gap="md">
         <IressText element="h2">Log In</IressText>
         <IressField label="Email" htmlFor="email" required>
           <IressInput id="email" type="email" />
@@ -256,39 +301,41 @@ import { IressModal } from '@iress-oss/ids-components';
 
 ```tsx
 import { IressTable, IressTag, IressButton } from '@iress-oss/ids-components';
+import type { TableColumn } from '@iress-oss/ids-components';
 
-function UsersTable({ users }) {
-  return (
-    <IressTable>
-      <IressTable.Head>
-        <IressTable.Row>
-          <IressTable.HeaderCell>Name</IressTable.HeaderCell>
-          <IressTable.HeaderCell>Email</IressTable.HeaderCell>
-          <IressTable.HeaderCell>Status</IressTable.HeaderCell>
-          <IressTable.HeaderCell>Actions</IressTable.HeaderCell>
-        </IressTable.Row>
-      </IressTable.Head>
-      <IressTable.Body>
-        {users.map((user) => (
-          <IressTable.Row key={user.id}>
-            <IressTable.Cell>{user.name}</IressTable.Cell>
-            <IressTable.Cell>{user.email}</IressTable.Cell>
-            <IressTable.Cell>
-              <IressTag>{user.status}</IressTag>
-            </IressTable.Cell>
-            <IressTable.Cell>
-              <IressButton mode="tertiary" icon="edit">
-                Edit
-              </IressButton>
-            </IressTable.Cell>
-          </IressTable.Row>
-        ))}
-      </IressTable.Body>
-    </IressTable>
-  );
+interface User {
+  name: string;
+  email: string;
+  status: string;
+  id: string;
+}
+
+const columns: TableColumn<User>[] = [
+  { key: 'name', label: 'Name' },
+  { key: 'email', label: 'Email' },
+  {
+    key: 'status',
+    label: 'Status',
+    format: (value) => <IressTag>{value}</IressTag>,
+  },
+  {
+    key: 'actions',
+    label: 'Actions',
+    format: (_, row) => (
+      <IressButton mode="tertiary" icon="edit">
+        Edit
+      </IressButton>
+    ),
+  },
+];
+
+function UsersTable({ users }: { users: User[] }) {
+  return <IressTable caption="Users" rows={users} columns={columns} />;
 }
 ```
 
+> **Key insight:** `IressTable` is data-driven — pass `rows` and `columns` props instead of composing sub-components. Use the `format` function on columns to render custom cell content like tags or buttons.
+
 ## Responsive Layout
 
 **Always produce responsive output**, even when Figma only provides a single desktop frame. IDS uses a 12-column grid with 6 breakpoints — every translation should consider how the layout adapts to smaller screens.
@@ -351,10 +398,12 @@ When Figma provides separate mobile and desktop frames for the same layout:
 When Figma only provides a desktop frame with a sidebar + main content area, infer the mobile layout:
 
 ```tsx
+import { useState } from 'react';
 import {
   useBreakpoint,
   IressSlideout,
   IressButton,
+  IressStack,
   IressRow,
   IressCol,
 } from '@iress-oss/ids-components';
@@ -368,7 +417,7 @@ function Page() {
     <>
       {isMobile ? (
         // Mobile: primary content first, secondary content in slideout
-        <IressStack gap="4">
+        <IressStack gap="md">
           <IressButton
             mode="secondary"
             icon="filter_list"
@@ -425,17 +474,42 @@ function Navigation() {
 
 ## Best Practices
 
-1. **Use IDS components, not raw elements** — IDS components encapsulate correct spacing, colours, border radius, and accessibility
-2. **Don't recreate component internals** — If Figma shows a button with specific padding/radius, use `IressButton` with the right `mode` — the styling is built in
-3. **Map Figma gap/padding to spacing tokens** — Divide pixel value by 4 to get the token number
-4. **Prefer semantic props over manual styling** — Use `status="danger"` instead of `bg="colour.system.danger.fill"`
-5. **Use IressField for all form inputs** — It provides the label, hint, and validation layout
-6. **Respect responsive patterns** — Use `hideFrom`/`hideBelow` props or the `useBreakpoint` hook for responsive visibility; use responsive `span` on `IressCol` for adaptive grid layouts
-7. **Always make grid layouts responsive** — When translating Figma multi-column layouts, use responsive `span` values (e.g. `span={{ xs: 12, md: 6 }}`) so columns stack on mobile
-8. **Check the component docs** — Read the specific component doc for detailed props and patterns (`node_modules/@iress-oss/ids-components/.ai/components/`)
+1. **Minimise component nesting** — Use the fewest components possible. Every wrapper must earn its place. Before adding `IressInline` or `IressStack`, check whether the parent already handles layout (e.g. `IressCard` has `heading` and `footer` props; `IressModal` has `actions`; `IressButtonGroup` handles horizontal button layout). Don't wrap a single child in a layout component.
+2. **Use IDS components, not raw elements** — IDS components encapsulate correct spacing, colours, border radius, and accessibility
+3. **Don't recreate component internals** — If Figma shows a button with specific padding/radius, use `IressButton` with the right `mode` — the styling is built in
+4. **Map Figma gap/padding to spacing tokens** — Divide pixel value by 4 to get the token number, then use the full token: 16px → `"spacing.4"`, 24px → `"spacing.6"`. Alias tokens (`"xs"`, `"sm"`, `"md"`, `"lg"`, `"xl"`) are also valid. Never use bare numbers like `gap="4"`.
+5. **Prefer semantic props over manual styling** — Use `status="danger"` instead of `bg="colour.system.danger.fill"`
+6. **Use IressField for all form inputs** — It provides the label, hint, and validation layout
+7. **Respect responsive patterns** — Use `hideFrom`/`hideBelow` props or the `useBreakpoint` hook for responsive visibility; use responsive `span` on `IressCol` for adaptive grid layouts
+8. **Always make grid layouts responsive** — When translating Figma multi-column layouts, use responsive `span` values (e.g. `span={{ xs: 12, md: 6 }}`) so columns stack on mobile
+9. **Check the component docs** — Read the specific component doc for detailed props and patterns (`node_modules/@iress-oss/ids-components/.ai/components/`)
 
 ## Common Mistakes
 
+### Unnecessary layout wrappers
+
+Don't add `IressInline` or `IressStack` when it adds no value. Every Figma auto-layout frame does NOT need its own layout wrapper — check the IDS component first.
+
+```tsx
+// ❌ Unnecessary nesting — IressStack wrapping a single child
+<IressStack gap="md">
+  <IressInline gap="sm">
+    <IressButton mode="primary">Save</IressButton>
+    <IressButton mode="secondary">Cancel</IressButton>
+  </IressInline>
+</IressStack>
+
+// ✅ Single group of buttons only needs IressInline
+<IressInline gap="sm">
+  <IressButton mode="primary">Save</IressButton>
+  <IressButton mode="secondary">Cancel</IressButton>
+</IressInline>
+```
+
+**Rule of thumb:** When Figma shows an auto-layout frame, check if the corresponding IDS component already provides that layout before adding a wrapper. Components like `IressModal` (with `actions`) and `IressButtonGroup` already handle their internal layout. For `IressCard`, use the `heading` and `footer` props to structure content — but note the `footer` slot does not auto-layout its children, so use `IressInline` inside `footer` when you need horizontal button layout.
+
+### Other common anti-patterns
+
 For the full list of common anti-patterns (disabled buttons, redundant textStyle, legacy slot attributes, raw HTML, hardcoded values), read the Common Mistakes guide at `node_modules/@iress-oss/ids-components/.ai/guides/foundations-common-mistakes.md` (requires `@iress-oss/ids-components` to be installed).
 
 **Figma-specific addition:** When Figma shows named content areas ("prepend", "append", "footer"), map them to the corresponding **React prop**, not to a `slot` attribute. When Figma shows a greyed-out or disabled button state, do not use `disabled` — see the guide for alternatives.

package/.ai/skills/ui-doctor.md

@@ -1812,7 +1812,7 @@ Not every raw HTML element is a violation. The following are **acceptable except
 
 #### a. Provider & CSS Setup
 
-- **IressProvider must wrap the application root** — Required for fonts, CSS variables, and theming. `IressProvider` already includes `IressModalProvider`, `IressSlideoutProvider`, `IressToasterProvider`, and `IressIconProvider` — these should not be added separately. Similarly, `IressShadow` includes `IressProvider` internally, so no additional providers are needed when using `IressShadow`.
+- **IressProvider must wrap the application root** — Required for fonts, CSS variables, and theming. `IressProvider` already includes `IressModalProvider`, `IressSlideoutProvider`, `IressToasterProvider`, `IressPopoverProvider`, and `IressIconProvider` — these should not be added separately. Similarly, `IressShadow` includes `IressProvider` internally, so no additional providers are needed when using `IressShadow`.
 - **The IDS component CSS must be imported** — `@iress-oss/ids-components/dist/style.css` contains all component styles
 - Users only need to install `@iress-oss/ids-components@beta` — the tokens are bundled within the component library and do not need to be installed separately. **IDS v6 is currently in beta**, so the `@beta` tag is required (e.g. `npm install @iress-oss/ids-components@beta`)
 - **CSP must allowlist IDS external origins** — If the app enforces a Content Security Policy, `fonts.googleapis.com` and `fonts.gstatic.com` must be in `style-src`/`font-src`. Add `cdn.iress.com` if using legacy Font Awesome icons or `IressTheme`. If using `IressShadow` and inline styles are blocked, add `<meta name="csp-nonce" content="...">` in `<head>`. See the CSP Guide at `node_modules/@iress-oss/ids-components/.ai/guides/get-started-content-security-policy.md` for details (requires `@iress-oss/ids-components` to be installed).