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

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

@@ -31,10 +31,10 @@ Translate natural language UI descriptions into IDS (Iress Design System) compon
 | Select dropdown (static or async) | `IressField` + `IressSelect` | `<IressField label="Country"><IressSelect>...</IressSelect></IressField>` — supports static options and async loading via an `options` function |
 | Freetext input with suggestions  | `IressField` + `IressAutocomplete` | `<IressField label="Search"><IressAutocomplete /></IressField>` — allows any text input; suggestions are optional |
 | Currency input           | `IressField` + `IressInputCurrency` | `<IressField label="Amount"><IressInputCurrency /></IressField>`                                                               |
-| Checkbox                 | `IressCheckbox`                     | `<IressCheckbox label="I agree" />`                                                                                            |
-| Checkbox group           | `IressCheckboxGroup`                | `<IressCheckboxGroup label="Options"><IressCheckbox label="A" /><IressCheckbox label="B" /></IressCheckboxGroup>`              |
-| Radio buttons            | `IressRadioGroup` + `IressRadio`    | `<IressRadioGroup label="Choice"><IressRadio label="Yes" value="yes" /><IressRadio label="No" value="no" /></IressRadioGroup>` |
-| Toggle switch            | `IressToggle`                       | `<IressToggle label="Enable" />`                                                                                               |
+| Checkbox                 | `IressCheckbox`                     | `<IressCheckbox value="agree">I agree</IressCheckbox>`                                                                         |
+| Checkbox group           | `IressCheckboxGroup`                | `<IressField label="Options"><IressCheckboxGroup name="opts"><IressCheckbox value="a">A</IressCheckbox><IressCheckbox value="b">B</IressCheckbox></IressCheckboxGroup></IressField>` |
+| Radio buttons            | `IressRadioGroup` + `IressRadio`    | `<IressField label="Choice"><IressRadioGroup><IressRadio value="yes">Yes</IressRadio><IressRadio value="no">No</IressRadio></IressRadioGroup></IressField>` |
+| Toggle switch            | `IressToggle`                       | `<IressToggle>Enable</IressToggle>`                                                                                            |
 | Slider / range           | `IressSlider`                       | `<IressSlider min={0} max={100} />`                                                                                            |
 | Read-only display        | `IressReadonly`                     | `<IressReadonly label="Status" value="Active" />` — supports `actions` prop for inline action buttons (e.g. edit toggle). Use `variant="locked"` when the value is read-only due to permissions |
 
@@ -47,8 +47,8 @@ Translate natural language UI descriptions into IDS (Iress Design System) compon
 
 | Description                                  | IDS Component           | Example                                                                                   |
 | -------------------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------- |
-| Vertical stack (items stacked top-to-bottom) | `IressStack`            | `<IressStack gap="4">...</IressStack>`                                                    |
-| Horizontal row (items side-by-side)          | `IressInline`           | `<IressInline gap="2">...</IressInline>`                                                  |
+| Vertical stack (items stacked top-to-bottom) | `IressStack`            | `<IressStack gap="md">...</IressStack>`                                                    |
+| Horizontal row (items side-by-side)          | `IressInline`           | `<IressInline gap="sm">...</IressInline>`                                                  |
 | Grid columns                                 | `IressRow` + `IressCol` | `<IressRow><IressCol span={{ xs: 12, md: 6 }}>...</IressCol><IressCol span={{ xs: 12, md: 6 }}>...</IressCol></IressRow>` |
 | Container with max-width                     | `IressContainer`        | `<IressContainer>...</IressContainer>`                                                    |
 | Divider / separator                          | `IressDivider`          | `<IressDivider />`                                                                        |
@@ -60,14 +60,14 @@ Translate natural language UI descriptions into IDS (Iress Design System) compon
 | -------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------- |
 | Text / paragraph     | `IressText`                 | `<IressText>Body text</IressText>`                                                                          |
 | Heading              | `IressText element="h2"`    | `<IressText element="h2">Heading</IressText>`                                                               |
-| Card / panel         | `IressCard` or `IressPanel` | `<IressCard><IressCard.Header>Title</IressCard.Header><IressCard.Body>Content</IressCard.Body></IressCard>` |
+| Card / panel         | `IressCard` or `IressPanel` | `<IressCard heading={<h3>Title</h3>}>Content</IressCard>`                                   |
 | Alert / notification | `IressAlert`                | `<IressAlert status="success">Saved!</IressAlert>`                                                          |
 | Loading spinner      | `IressSpinner`              | `<IressSpinner />`                                                                                          |
 | Skeleton loader      | `IressSkeleton`             | `<IressSkeleton height="20px" width="200px" />`                                                             |
 | Progress bar         | `IressProgress`             | `<IressProgress value={75} max={100} />`                                                                    |
 | Image                | `IressImage`                | `<IressImage src="..." alt="..." />`                                                                        |
 | Icon                 | `IressIcon`                 | `<IressIcon name="settings" />`                                                                             |
-| Tag / badge          | `IressTag`                  | `<IressTag>New</IressTag>`                                                                                  |
+| Tag / badge          | `IressTag`                  | `<IressTag>New</IressTag>`; use `bordered` for visible-border style; use `element="button"` for clickable tag, `element="a"` for link tag; `onClick` alone also auto-renders as `<button>` |
 | Pill                 | `IressPill`                 | `<IressPill>Category</IressPill>`                                                                           |
 | Tooltip              | `IressTooltip`              | `<IressTooltip content="Help text"><IressButton>Hover me</IressButton></IressTooltip>`                      |
 
@@ -89,11 +89,11 @@ Translate natural language UI descriptions into IDS (Iress Design System) compon
 
 | Description | IDS Component | Example                                                                                                 |
 | ----------- | ------------- | ------------------------------------------------------------------------------------------------------- |
-| Data table  | `IressTable`  | `<IressTable><IressTable.Head>...</IressTable.Head><IressTable.Body>...</IressTable.Body></IressTable>` |
+| Data table  | `IressTable`  | `<IressTable caption="Users" rows={users} columns={columns} />` — data-driven via `rows` and `columns` props |
 3. **Verify component capabilities** — Before recommending a component, read its `.ai/components/<name>.md` doc (in `node_modules/@iress-oss/ids-components/.ai/components/`) to verify it supports the required features (async, filtering, validation, etc.)
-4. **Apply layout** — Wrap elements in `IressStack` (vertical), `IressInline` (horizontal), or `IressRow`/`IressCol` (grid). Always make grids responsive with `span={{ xs: 12, md: ... }}`
+4. **Apply layout** — Wrap elements in `IressStack` (vertical), `IressInline` (horizontal), or `IressRow`/`IressCol` (grid) only when needed. Check whether the parent component already provides layout (e.g. card footer, modal actions, button group) before adding wrappers. Never wrap a single child in a layout component. Always make grids responsive with `span={{ xs: 12, md: ... }}`
 5. **Add responsive behaviour** — Even if the description only mentions desktop, stack columns on mobile and relocate secondary content to `IressSlideout` or collapsible sections
-6. **Apply styling** — Use styling props for spacing, colour, and typography. Use spacing tokens (0–10) for `gap` props
+6. **Apply styling** — Use styling props for spacing, colour, and typography. Spacing tokens must include the category prefix: `gap="spacing.4"`, `p="spacing.6"`. Alias tokens (`"xs"`, `"sm"`, `"md"`, `"lg"`, `"xl"`) are also valid. Never use bare numbers like `gap="4"`.
 
 # Styling Props (IressCSSProps)
 
@@ -190,10 +190,10 @@ When you need to find the right IDS component for a UI element, read references/
 | Select dropdown (static or async) | `IressField` + `IressSelect` | `<IressField label="Country"><IressSelect>...</IressSelect></IressField>` — supports static options and async loading via an `options` function |
 | Freetext input with suggestions  | `IressField` + `IressAutocomplete` | `<IressField label="Search"><IressAutocomplete /></IressField>` — allows any text input; suggestions are optional |
 | Currency input           | `IressField` + `IressInputCurrency` | `<IressField label="Amount"><IressInputCurrency /></IressField>`                                                               |
-| Checkbox                 | `IressCheckbox`                     | `<IressCheckbox label="I agree" />`                                                                                            |
-| Checkbox group           | `IressCheckboxGroup`                | `<IressCheckboxGroup label="Options"><IressCheckbox label="A" /><IressCheckbox label="B" /></IressCheckboxGroup>`              |
-| Radio buttons            | `IressRadioGroup` + `IressRadio`    | `<IressRadioGroup label="Choice"><IressRadio label="Yes" value="yes" /><IressRadio label="No" value="no" /></IressRadioGroup>` |
-| Toggle switch            | `IressToggle`                       | `<IressToggle label="Enable" />`                                                                                               |
+| Checkbox                 | `IressCheckbox`                     | `<IressCheckbox value="agree">I agree</IressCheckbox>`                                                                         |
+| Checkbox group           | `IressCheckboxGroup`                | `<IressField label="Options"><IressCheckboxGroup name="opts"><IressCheckbox value="a">A</IressCheckbox><IressCheckbox value="b">B</IressCheckbox></IressCheckboxGroup></IressField>` |
+| Radio buttons            | `IressRadioGroup` + `IressRadio`    | `<IressField label="Choice"><IressRadioGroup><IressRadio value="yes">Yes</IressRadio><IressRadio value="no">No</IressRadio></IressRadioGroup></IressField>` |
+| Toggle switch            | `IressToggle`                       | `<IressToggle>Enable</IressToggle>`                                                                                            |
 | Slider / range           | `IressSlider`                       | `<IressSlider min={0} max={100} />`                                                                                            |
 | Read-only display        | `IressReadonly`                     | `<IressReadonly label="Status" value="Active" />` — supports `actions` prop for inline action buttons (e.g. edit toggle). Use `variant="locked"` when the value is read-only due to permissions |
 
@@ -206,8 +206,8 @@ When you need to find the right IDS component for a UI element, read references/
 
 | Description                                  | IDS Component           | Example                                                                                   |
 | -------------------------------------------- | ----------------------- | ----------------------------------------------------------------------------------------- |
-| Vertical stack (items stacked top-to-bottom) | `IressStack`            | `<IressStack gap="4">...</IressStack>`                                                    |
-| Horizontal row (items side-by-side)          | `IressInline`           | `<IressInline gap="2">...</IressInline>`                                                  |
+| Vertical stack (items stacked top-to-bottom) | `IressStack`            | `<IressStack gap="md">...</IressStack>`                                                    |
+| Horizontal row (items side-by-side)          | `IressInline`           | `<IressInline gap="sm">...</IressInline>`                                                  |
 | Grid columns                                 | `IressRow` + `IressCol` | `<IressRow><IressCol span={{ xs: 12, md: 6 }}>...</IressCol><IressCol span={{ xs: 12, md: 6 }}>...</IressCol></IressRow>` |
 | Container with max-width                     | `IressContainer`        | `<IressContainer>...</IressContainer>`                                                    |
 | Divider / separator                          | `IressDivider`          | `<IressDivider />`                                                                        |
@@ -219,14 +219,14 @@ When you need to find the right IDS component for a UI element, read references/
 | -------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------- |
 | Text / paragraph     | `IressText`                 | `<IressText>Body text</IressText>`                                                                          |
 | Heading              | `IressText element="h2"`    | `<IressText element="h2">Heading</IressText>`                                                               |
-| Card / panel         | `IressCard` or `IressPanel` | `<IressCard><IressCard.Header>Title</IressCard.Header><IressCard.Body>Content</IressCard.Body></IressCard>` |
+| Card / panel         | `IressCard` or `IressPanel` | `<IressCard heading={<h3>Title</h3>}>Content</IressCard>`                                   |
 | Alert / notification | `IressAlert`                | `<IressAlert status="success">Saved!</IressAlert>`                                                          |
 | Loading spinner      | `IressSpinner`              | `<IressSpinner />`                                                                                          |
 | Skeleton loader      | `IressSkeleton`             | `<IressSkeleton height="20px" width="200px" />`                                                             |
 | Progress bar         | `IressProgress`             | `<IressProgress value={75} max={100} />`                                                                    |
 | Image                | `IressImage`                | `<IressImage src="..." alt="..." />`                                                                        |
 | Icon                 | `IressIcon`                 | `<IressIcon name="settings" />`                                                                             |
-| Tag / badge          | `IressTag`                  | `<IressTag>New</IressTag>`                                                                                  |
+| Tag / badge          | `IressTag`                  | `<IressTag>New</IressTag>`; use `bordered` for visible-border style; use `element="button"` for clickable tag, `element="a"` for link tag; `onClick` alone also auto-renders as `<button>` |
 | Pill                 | `IressPill`                 | `<IressPill>Category</IressPill>`                                                                           |
 | Tooltip              | `IressTooltip`              | `<IressTooltip content="Help text"><IressButton>Hover me</IressButton></IressTooltip>`                      |
 
@@ -248,7 +248,7 @@ When you need to find the right IDS component for a UI element, read references/
 
 | Description | IDS Component | Example                                                                                                 |
 | ----------- | ------------- | ------------------------------------------------------------------------------------------------------- |
-| Data table  | `IressTable`  | `<IressTable><IressTable.Head>...</IressTable.Head><IressTable.Body>...</IressTable.Body></IressTable>` |
+| Data table  | `IressTable`  | `<IressTable caption="Users" rows={users} columns={columns} />` — data-driven via `rows` and `columns` props |
 
 ## Styling Props
 
@@ -355,7 +355,7 @@ import {
 
 function LoginForm() {
   return (
-    <IressStack gap="4">
+    <IressStack gap="md">
       <IressField label="Email" htmlFor="email" required>
         <IressInput id="email" type="email" placeholder="Enter your email" />
       </IressField>
@@ -377,30 +377,20 @@ function LoginForm() {
 ### "A card with a title, description, and two action buttons"
 
 ```tsx
-import {
-  IressCard,
-  IressButton,
-  IressInline,
-  IressText,
-} from '@iress-oss/ids-components';
+import { IressCard, IressButton, IressInline } from '@iress-oss/ids-components';
 
 function ActionCard() {
   return (
-    <IressCard>
-      <IressCard.Header>
-        <IressText element="h3">Card Title</IressText>
-      </IressCard.Header>
-      <IressCard.Body>
-        <IressText>
-          This is the card description with supporting details.
-        </IressText>
-      </IressCard.Body>
-      <IressCard.Footer>
-        <IressInline gap="2">
+    <IressCard
+      heading={<h3>Card Title</h3>}
+      footer={
+        <IressInline gap="sm">
           <IressButton mode="primary">Confirm</IressButton>
           <IressButton mode="secondary">Cancel</IressButton>
         </IressInline>
-      </IressCard.Footer>
+      }
+    >
+      This is the card description with supporting details.
     </IressCard>
   );
 }
@@ -417,19 +407,22 @@ import {
   IressButton,
   IressText,
   IressDivider,
+  IressField,
 } from '@iress-oss/ids-components';
 
 function SettingsPage() {
   return (
-    <IressStack gap="6">
+    <IressStack gap="lg">
       <IressText element="h2">Settings</IressText>
-      <IressToggle label="Enable notifications" />
+      <IressToggle>Enable notifications</IressToggle>
       <IressDivider />
-      <IressCheckboxGroup label="Notification types">
-        <IressCheckbox label="Email" value="email" />
-        <IressCheckbox label="SMS" value="sms" />
-        <IressCheckbox label="Push" value="push" />
-      </IressCheckboxGroup>
+      <IressField label="Notification types">
+        <IressCheckboxGroup name="notification-types">
+          <IressCheckbox value="email">Email</IressCheckbox>
+          <IressCheckbox value="sms">SMS</IressCheckbox>
+          <IressCheckbox value="push">Push</IressCheckbox>
+        </IressCheckboxGroup>
+      </IressField>
       <IressDivider />
       <IressButton mode="primary">Save settings</IressButton>
     </IressStack>
@@ -442,8 +435,8 @@ function SettingsPage() {
 Note: even though the description doesn't mention mobile, the sidebar is secondary content — on mobile it should move into a slideout so the main content gets focus.
 
 ```tsx
+import { useState } from 'react';
 import {
-  useState,
   IressRow,
   IressCol,
   IressStack,
@@ -460,18 +453,13 @@ function Dashboard() {
   const [navOpen, setNavOpen] = useState(false);
 
   const nav = (
-    <IressCard>
-      <IressCard.Body>
-        <IressStack gap="2">
-          <IressText weight="strong">Navigation</IressText>
-          <IressText>Menu items here</IressText>
-        </IressStack>
-      </IressCard.Body>
+    <IressCard heading={<h3>Navigation</h3>}>
+      Menu items here
     </IressCard>
   );
 
   return isMobile ? (
-    <IressStack gap="4">
+    <IressStack gap="md">
       <IressButton
         mode="secondary"
         icon="menu"
@@ -480,9 +468,7 @@ function Dashboard() {
         Menu
       </IressButton>
       <IressCard>
-        <IressCard.Body>
-          <IressText element="h2">Main Content</IressText>
-        </IressCard.Body>
+        <IressText element="h2">Main Content</IressText>
       </IressCard>
       <IressSlideout
         heading="Navigation"
@@ -497,9 +483,7 @@ function Dashboard() {
       <IressCol span={3}>{nav}</IressCol>
       <IressCol span={9}>
         <IressCard>
-          <IressCard.Body>
-            <IressText element="h2">Main Content</IressText>
-          </IressCard.Body>
+          <IressText element="h2">Main Content</IressText>
         </IressCard>
       </IressCol>
     </IressRow>
@@ -509,18 +493,60 @@ function Dashboard() {
 
 ## Best Practices
 
-1. **Always wrap in IressProvider** — Required at the root of your app for fonts and CSS variables. `IressProvider` already includes `IressModalProvider`, `IressSlideoutProvider`, `IressToasterProvider`, and `IressIconProvider` — do not add these separately. If using `IressShadow`, no additional providers are needed as it includes `IressProvider` internally.
-2. **Use IressField for all form inputs** — Provides consistent labels, hints, and validation display
-3. **Use IressStack/IressInline for layout** — Prefer these over custom CSS flex/grid
-4. **Use spacing tokens for gap** — Values 0–10 map to multiples of 4px
-5. **Use semantic button modes** — One `primary` per section, `secondary` for most actions
-6. **Always include labels** — All form inputs need accessible labels via `IressField`
-7. **Use status for feedback** — `IressAlert` for inline messages, `IressModal status="danger"` for confirmation dialogs, `status` prop on buttons for danger/success
-8. **Prefer IDS components** — Use `IressText` instead of raw `<p>`, `IressButton` instead of `<button>`
-9. **Native elements inside `IressText` are OK** — When rendering CMS content, markdown output, or other unstructured data sources, it is acceptable to nest native HTML elements (e.g. `<p>`, `<strong>`, `<a>`, `<ul>`) inside `IressText`. This lets `IressText` provide consistent typography while allowing flexible inner content structure.
-10. **Always make grid layouts responsive** — When using `IressRow`/`IressCol`, use responsive `span` values (e.g. `span={{ xs: 12, md: 6 }}`) so columns stack on mobile instead of overflowing
-11. **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 to achieve the layout. Every wrapper component should earn its place. Before adding `IressInline` or `IressStack`, check whether the parent component already handles the layout (e.g. `IressCard` has `heading` and `footer` props; `IressModal` has `actions`; `IressButtonGroup` handles horizontal button layout). See the "Unnecessary layout wrappers" section in Common Mistakes below.
+2. **Always wrap in IressProvider** — Required at the root of your app for fonts and CSS variables. `IressProvider` already includes `IressModalProvider`, `IressSlideoutProvider`, `IressToasterProvider`, and `IressIconProvider` — do not add these separately. If using `IressShadow`, no additional providers are needed as it includes `IressProvider` internally.
+3. **Use IressField for all form inputs** — Provides consistent labels, hints, and validation display
+4. **Use IressStack/IressInline only when needed** — Prefer these over custom CSS flex/grid, but don't add them when the parent already provides spacing or layout
+5. **Use correct spacing token format** — Always prefix with the token category: `gap="spacing.4"`, `p="spacing.6"`. Alias tokens (`"xs"`, `"sm"`, `"md"`, `"lg"`, `"xl"`) are also valid. Never use bare numbers like `gap="4"`.
+6. **Use semantic button modes** — One `primary` per section, `secondary` for most actions
+7. **Always include labels** — All form inputs need accessible labels via `IressField`
+8. **Use status for feedback** — `IressAlert` for inline messages, `IressModal status="danger"` for confirmation dialogs, `status` prop on buttons for danger/success
+9. **Prefer IDS components** — Use `IressText` instead of raw `<p>`, `IressButton` instead of `<button>`
+10. **Native elements inside `IressText` are OK** — When rendering CMS content, markdown output, or other unstructured data sources, it is acceptable to nest native HTML elements (e.g. `<p>`, `<strong>`, `<a>`, `<ul>`) inside `IressText`. This lets `IressText` provide consistent typography while allowing flexible inner content structure.
+11. **Always make grid layouts responsive** — When using `IressRow`/`IressCol`, use responsive `span` values (e.g. `span={{ xs: 12, md: 6 }}`) so columns stack on mobile instead of overflowing
+12. **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
+
+The most common mistake is wrapping children in `IressInline` or `IressStack` when it adds no value. Every wrapper must serve a purpose — if removing it produces the same result, remove it.
+
+```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>
+```
+
+```tsx
+// ❌ Wrapping content that's already a single block
+<IressStack gap="md">
+  <IressText element="h2">Title</IressText>
+</IressStack>
+
+// ✅ No wrapper needed for a single element
+<IressText element="h2">Title</IressText>
+```
+
+**When to use layout wrappers:**
+- `IressStack` — when you have 2+ block-level siblings that need vertical spacing between them
+- `IressInline` — when you have 2+ elements that need to sit side-by-side (e.g. buttons in a card `footer`, action bars)
+
+**When NOT to use them:**
+- The parent component already handles layout (modal `actions` prop, button group)
+- There's only one child — a wrapper around a single child adds nothing
+- You're nesting `IressInline` inside `IressInline` or `IressStack` inside `IressStack` without changing gap/alignment — flatten instead
+
+### 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).

package/README.md

@@ -10,11 +10,26 @@ This is the component library for the Iress Design System (IDS). You can use thi
 
 ## Set up the component library
 
-1. Install using: `yarn add @iress-oss/ids-components`
+1. Install using: `yarn add @iress-oss/ids-components@beta`
 2. Import the styles: `import '@iress-oss/ids-components/dist/style.css'`
 3. Import the components: `import { IressButton, IressText } from '@iress-oss/ids-components'`
 4. Use the components: `<IressButton>Click me</IressButton>`
 
+> **Note:** IDS v6 is currently in beta — install with the `@beta` tag as shown above.
+>
+> If you need to use design tokens directly in your application code (for custom CSS or inline styles), also install the tokens package:
+>
+> ```bash
+> yarn add @iress-oss/ids-tokens@beta
+> ```
+>
+> Then import the CSS variables stylesheet and use `cssVars` in your code:
+>
+> ```ts
+> import '@iress-oss/ids-tokens/build/css-vars.css';
+> import { cssVars } from '@iress-oss/ids-tokens';
+> ```
+
 ## Contributing
 
 The component library is part of the Iress Design System (IDS) monorepo. Please refer to the root [README](../../README.md) for more information on contributing to IDS.