@iress-oss/ids-components 6.0.0-beta.2 → 6.0.0-beta.4

package/.ai/components/tag.md

@@ -63,12 +63,46 @@ Use semantic status values (`danger`, `info`, `success`, `warning`) when tags ne
 
 [View "Status" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-tag--status)
 
+### Bordered tags
+
+Set `bordered` to render a tag with a visible border using the tag's current
+colour, without altering its background. This enhances visibility and makes tags
+look more interactive — useful for dropdown filter tags or any context where
+tags need to stand out.
+
+```tsx
+<IressInline gap="sm">
+<IressTag bordered>
+No mode
+</IressTag>
+{BADGE_MODES.map((mode) => (
+<IressTag key={mode} mode={mode} bordered>
+{mode}
+</IressTag>
+))}
+{STATUSES.map((status) => (
+<IressTag key={status} mode={status} bordered>
+{status}
+</IressTag>
+))}
+</IressInline>
+```
+
+[View "Bordered" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_components-tag--bordered)
+
 ### Clickable tags
 
-Tags can be made clickable by passing an `onClick` handler. This will apply hover styles to the tag to indicate it is clickable.
+Tags can be made clickable by setting `element="button"`. This is the
+recommended, explicit API and renders the tag as a `<button>` with hover
+styles to indicate it is clickable.
+
+For backwards compatibility, passing `onClick` without setting `element` is
+also supported and will automatically render the tag as a `<button>`.
+
+Use `element="a"` to render the tag as a link.
 
 ```tsx
-<IressTag>
+<IressTag bordered>
   Tag
 </IressTag>
 ```
@@ -124,12 +158,18 @@ Query tags by their text content:
 const tag = screen.getByText('Category');
 ```
 
-When `onClick` is provided, the tag renders as a `<button>`:
+When `element="button"` is set, the tag renders as a `<button>`:
 
 ```tsx
 const tag = screen.getByRole('button', { name: 'Category' });
 ```
 
+When `element="a"` is set, the tag renders as a link:
+
+```tsx
+const tag = screen.getByRole('link', { name: 'Category' });
+```
+
 For deletable tags, query the delete button:
 
 ```tsx

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

@@ -4,18 +4,60 @@
 
 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:
 >
 > ```bash
 > npm install @iress-oss/ids-components@beta
+> npm install @iress-oss/ids-tokens@beta  # if using tokens directly (e.g. cssVars or CSS vars import)
 > ```
 
 ## Figma → IDS Mapping
@@ -48,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"`                 |                            |
@@ -64,8 +106,8 @@ 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      |
-| Tag                | `IressTag`                                   | clickable variant          |
+| 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`                               |                            |
 | Icon               | `IressIcon name="..."`                       | Material Symbols name      |
@@ -131,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.
 
@@ -175,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" />
@@ -255,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.
@@ -350,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';
@@ -367,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"
@@ -424,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.