@lifesg/react-design-system 4.0.0-alpha.13 → 4.0.0-alpha.14

package/skills/fds-build/evals/evals.json

@@ -0,0 +1,519 @@
+{
+    "skill_name": "fds-build",
+    "evals": [
+        {
+            "id": 0,
+            "prompt": "Build a registration form page using @lifesg/react-design-system v4. The form should collect: full name, email, phone number, and date of birth. Include field validation — all fields required, email must be valid format. Show an error summary at the top if submission fails. Show a success Alert after successful submission. Include Navbar and Footer.",
+            "expected_output": "A React component using ThemeProvider from @lifesg/react-design-system/theme, Navbar, Footer, Layout.Container type=grid, Form.Input for name/email/phone, Form.DateInput for DOB, Button.Default type=submit with loading+disabled during async, Alert type=error for summary, Alert type=success after submission. errorMessage only set after validation fails. No raw <input> elements. No styled-components. No Tailwind.",
+            "files": [],
+            "assertions": [
+                {
+                    "id": "uses-theme-provider",
+                    "description": "Wraps app in ThemeProvider from @lifesg/react-design-system/theme",
+                    "type": "contains",
+                    "value": "ThemeProvider"
+                },
+                {
+                    "id": "uses-form-input",
+                    "description": "Uses Form.Input not raw <input>",
+                    "type": "contains",
+                    "value": "Form.Input"
+                },
+                {
+                    "id": "no-raw-input",
+                    "description": "Does not use raw <input> elements",
+                    "type": "not_contains",
+                    "value": "<input"
+                },
+                {
+                    "id": "uses-form-date-input",
+                    "description": "Uses Form.DateInput for date of birth",
+                    "type": "contains",
+                    "value": "Form.DateInput"
+                },
+                {
+                    "id": "uses-alert-error",
+                    "description": "Uses Alert type=error for validation summary",
+                    "type": "contains",
+                    "value": "type=\"error\""
+                },
+                {
+                    "id": "uses-alert-success",
+                    "description": "Uses Alert type=success after submission",
+                    "type": "contains",
+                    "value": "type=\"success\""
+                },
+                {
+                    "id": "button-loading-disabled",
+                    "description": "Submit button uses both loading and disabled during async",
+                    "type": "contains",
+                    "value": "loading"
+                },
+                {
+                    "id": "uses-navbar",
+                    "description": "Page includes Navbar",
+                    "type": "contains",
+                    "value": "Navbar"
+                },
+                {
+                    "id": "uses-footer",
+                    "description": "Page includes Footer",
+                    "type": "contains",
+                    "value": "Footer"
+                },
+                {
+                    "id": "uses-layout-container",
+                    "description": "Uses Layout.Container for structure",
+                    "type": "contains",
+                    "value": "Layout.Container"
+                },
+                {
+                    "id": "no-styled-components",
+                    "description": "Does not import styled-components in v4",
+                    "type": "not_contains",
+                    "value": "from \"styled-components\""
+                },
+                {
+                    "id": "correct-form-import",
+                    "description": "Form imported from correct subpath",
+                    "type": "contains",
+                    "value": "@lifesg/react-design-system/form"
+                }
+            ]
+        },
+        {
+            "id": 1,
+            "prompt": "Build a service listing page using @lifesg/react-design-system v4. Show a hero banner with a title and a search bar (location input + category dropdown + Search button). Below the hero, show a filter sidebar on the left (sort by radio buttons, category checkboxes) and a results area on the right with a result count and 3 placeholder Card components. Include Navbar and Footer.",
+            "expected_output": "A React component with Navbar, a hero section, Layout.Container, a two-column layout with Filter component on the left and results on the right. Results area shows Typography.BodyMD for count and Card components. Uses Form.Input for location, Form.Select for category, RadioButton for sort, Filter.Checkbox or Checkbox for categories. No DataTable for citizen-facing results.",
+            "files": [],
+            "assertions": [
+                {
+                    "id": "uses-navbar-footer",
+                    "description": "Includes Navbar and Footer",
+                    "type": "contains",
+                    "value": "Navbar"
+                },
+                {
+                    "id": "uses-filter",
+                    "description": "Uses Filter component for sidebar",
+                    "type": "contains",
+                    "value": "Filter"
+                },
+                {
+                    "id": "uses-card-not-datatable",
+                    "description": "Uses Card for citizen-facing results, not DataTable",
+                    "type": "contains",
+                    "value": "Card"
+                },
+                {
+                    "id": "no-datatable",
+                    "description": "Does not use DataTable for citizen-facing listing",
+                    "type": "not_contains",
+                    "value": "DataTable"
+                },
+                {
+                    "id": "shows-result-count",
+                    "description": "Shows a result count using Typography",
+                    "type": "contains",
+                    "value": "result"
+                },
+                {
+                    "id": "uses-form-input-search",
+                    "description": "Search bar uses Form.Input",
+                    "type": "contains",
+                    "value": "Form.Input"
+                },
+                {
+                    "id": "uses-form-select",
+                    "description": "Category uses Form.Select not raw <select>",
+                    "type": "contains",
+                    "value": "Form.Select"
+                },
+                {
+                    "id": "no-raw-select",
+                    "description": "Does not use raw <select>",
+                    "type": "not_contains",
+                    "value": "<select"
+                },
+                {
+                    "id": "two-column-layout",
+                    "description": "Uses a two-column layout structure",
+                    "type": "contains",
+                    "value": "Layout.Container"
+                }
+            ]
+        },
+        {
+            "id": 2,
+            "prompt": "I need a delete confirmation modal using @lifesg/react-design-system v4. A button labelled 'Delete item' opens a modal. The modal has a title 'Delete this item?', a description 'This action cannot be undone.', a Cancel button and a red Confirm button. Clicking either closes the modal.",
+            "expected_output": "Uses Modal + Modal.Box with show controlled by useState. enableOverlayClick + onOverlayClick both call the same close handler. Modal.Box has showCloseButton and onClose. Direct child of Modal is not a Fragment. Confirm button uses danger prop. Both Cancel and Confirm call setShow(false).",
+            "files": [],
+            "assertions": [
+                {
+                    "id": "uses-modal",
+                    "description": "Uses Modal component",
+                    "type": "contains",
+                    "value": "Modal"
+                },
+                {
+                    "id": "uses-modal-box",
+                    "description": "Uses Modal.Box inside Modal",
+                    "type": "contains",
+                    "value": "Modal.Box"
+                },
+                {
+                    "id": "controlled-show",
+                    "description": "show prop controlled by state",
+                    "type": "contains",
+                    "value": "show="
+                },
+                {
+                    "id": "has-close-button",
+                    "description": "Modal.Box has showCloseButton",
+                    "type": "contains",
+                    "value": "showCloseButton"
+                },
+                {
+                    "id": "uses-danger",
+                    "description": "Confirm/delete button uses danger prop",
+                    "type": "contains",
+                    "value": "danger"
+                },
+                {
+                    "id": "no-fragment-child",
+                    "description": "Does not use Fragment as direct child of Modal",
+                    "type": "not_contains",
+                    "value": "<>"
+                },
+                {
+                    "id": "overlay-click-handled",
+                    "description": "Overlay click handled via enableOverlayClick + onOverlayClick",
+                    "type": "contains",
+                    "value": "onOverlayClick"
+                }
+            ]
+        },
+        {
+            "id": 3,
+            "prompt": "Build a dashboard page using @lifesg/react-design-system v4. Show 4 KPI metric cards in a responsive grid (2 columns on tablet, 4 on desktop). Each card shows a metric label, a large number value, and a percentage change badge. Below the cards, show a full-width section heading and a placeholder for a chart. Include Navbar and Footer.",
+            "expected_output": "Uses Layout.Container type=grid with Layout.ColDiv xsCols=8 mdCols=6 lgCols=3 for the 4-column responsive grid. Metric values use Typography.HeadingXL or similar large heading. Badge component for percentage change. Colour tokens used, not hardcoded hex. No Tailwind classes.",
+            "files": [],
+            "assertions": [
+                {
+                    "id": "uses-layout-grid",
+                    "description": "Uses Layout.Container type=grid",
+                    "type": "contains",
+                    "value": "type=\"grid\""
+                },
+                {
+                    "id": "responsive-cols",
+                    "description": "ColDiv uses xsCols for mobile stacking",
+                    "type": "contains",
+                    "value": "xsCols"
+                },
+                {
+                    "id": "uses-desktop-cols",
+                    "description": "ColDiv uses lgCols for 4-column desktop layout",
+                    "type": "contains",
+                    "value": "lgCols"
+                },
+                {
+                    "id": "uses-card",
+                    "description": "Metric cards use Card component",
+                    "type": "contains",
+                    "value": "Card"
+                },
+                {
+                    "id": "uses-badge",
+                    "description": "Percentage change uses Badge component",
+                    "type": "contains",
+                    "value": "Badge"
+                },
+                {
+                    "id": "uses-navbar-footer",
+                    "description": "Includes Navbar and Footer",
+                    "type": "contains",
+                    "value": "Navbar"
+                },
+                {
+                    "id": "no-hardcoded-hex",
+                    "description": "Does not hardcode hex colour values",
+                    "type": "not_contains",
+                    "value": "#"
+                },
+                {
+                    "id": "no-tailwind",
+                    "description": "Does not use Tailwind class names",
+                    "type": "not_contains",
+                    "value": "className=\"flex"
+                }
+            ]
+        },
+        {
+            "id": 4,
+            "prompt": "I need to show a 'no results found' state on my listing page using @lifesg/react-design-system. The search returned zero results. Show the appropriate empty state with a 'Clear filters' action button.",
+            "expected_output": "Uses ErrorDisplay component with type='no-item-found'. Imports from @lifesg/react-design-system/error-display. Provides actionButton prop with children='Clear filters' and onClick handler. Does not build a custom empty state with raw Typography + Button.",
+            "files": [],
+            "assertions": [
+                {
+                    "id": "uses-error-display",
+                    "description": "Uses ErrorDisplay component, not a custom empty state",
+                    "type": "contains",
+                    "value": "ErrorDisplay"
+                },
+                {
+                    "id": "correct-type",
+                    "description": "Uses type='no-item-found'",
+                    "type": "contains",
+                    "value": "no-item-found"
+                },
+                {
+                    "id": "correct-import",
+                    "description": "Imports from error-display subpath",
+                    "type": "contains",
+                    "value": "error-display"
+                },
+                {
+                    "id": "has-action-button",
+                    "description": "Includes actionButton prop for clear filters",
+                    "type": "contains",
+                    "value": "actionButton"
+                }
+            ]
+        },
+        {
+            "id": 5,
+            "prompt": "Add a loading state to my page. While data is fetching, show a full-page loading spinner centred in a card. Once loaded, show the content.",
+            "expected_output": "Uses LoadingSpinner imported from @lifesg/react-design-system/animations (not invented or from another library). Wrapped in a Card with centred layout. Conditional render based on isLoading state.",
+            "files": [],
+            "assertions": [
+                {
+                    "id": "uses-loading-spinner",
+                    "description": "Uses LoadingSpinner component",
+                    "type": "contains",
+                    "value": "LoadingSpinner"
+                },
+                {
+                    "id": "correct-import",
+                    "description": "LoadingSpinner imported from animations subpath",
+                    "type": "contains",
+                    "value": "@lifesg/react-design-system/animations"
+                },
+                {
+                    "id": "conditional-render",
+                    "description": "Loading state conditionally rendered",
+                    "type": "contains",
+                    "value": "isLoading"
+                },
+                {
+                    "id": "no-custom-spinner",
+                    "description": "Does not invent a custom spinner with raw CSS",
+                    "type": "not_contains",
+                    "value": "animation: spin"
+                }
+            ]
+        },
+        {
+            "id": 6,
+            "prompt": "Build a registration form using @lifesg/react-design-system v3. Collect full name, email, and a date of birth. On submit, show a success Toast. Include Navbar and Footer.",
+            "expected_output": "Uses StyleSheetManager + ThemeProvider with a theme object (e.g. LifeSGTheme) from @lifesg/react-design-system/theme. Uses styled-components for custom layout. Form.Input for name/email. Form.DateInput for DOB. Toast component for success feedback. No raw <input> elements. No plain CSS variables — tokens are interpolation functions inside styled templates.",
+            "files": [],
+            "assertions": [
+                {
+                    "id": "uses-stylesheet-manager",
+                    "description": "Wraps app in StyleSheetManager (v3 requirement)",
+                    "type": "contains",
+                    "value": "StyleSheetManager"
+                },
+                {
+                    "id": "theme-object-not-string",
+                    "description": "ThemeProvider receives a theme object, not a string",
+                    "type": "contains",
+                    "value": "LifeSGTheme"
+                },
+                {
+                    "id": "uses-form-input",
+                    "description": "Uses Form.Input for text fields",
+                    "type": "contains",
+                    "value": "Form.Input"
+                },
+                {
+                    "id": "uses-form-date-input",
+                    "description": "Uses Form.DateInput for date of birth",
+                    "type": "contains",
+                    "value": "Form.DateInput"
+                },
+                {
+                    "id": "uses-toast",
+                    "description": "Uses Toast for success feedback",
+                    "type": "contains",
+                    "value": "Toast"
+                },
+                {
+                    "id": "no-css-variable-strings",
+                    "description": "Does not use plain CSS variable strings (v4 pattern) in styled-components",
+                    "type": "not_contains",
+                    "value": "var(--fds-"
+                },
+                {
+                    "id": "uses-subpath-imports",
+                    "description": "Imports use subpath pattern",
+                    "type": "contains",
+                    "value": "@lifesg/react-design-system/form"
+                }
+            ]
+        },
+        {
+            "id": 7,
+            "prompt": "Build a Form.Select dropdown using @lifesg/react-design-system v4. The options are country objects: { value: 'sg', label: 'Singapore' }, { value: 'my', label: 'Malaysia' }. When the user selects an option, the closed selector should show the country name (e.g. 'Singapore'), not the code (e.g. 'sg').",
+            "expected_output": "Form.Select with options array, valueExtractor returning opt.value, listExtractor returning opt.label, and displayValueExtractor returning opt.label. Without displayValueExtractor the selector shows the raw value ('sg') instead of the label. All three extractors must be present.",
+            "files": [],
+            "assertions": [
+                {
+                    "id": "uses-form-select",
+                    "description": "Uses Form.Select component",
+                    "type": "contains",
+                    "value": "Form.Select"
+                },
+                {
+                    "id": "has-value-extractor",
+                    "description": "Provides valueExtractor",
+                    "type": "contains",
+                    "value": "valueExtractor"
+                },
+                {
+                    "id": "has-list-extractor",
+                    "description": "Provides listExtractor",
+                    "type": "contains",
+                    "value": "listExtractor"
+                },
+                {
+                    "id": "has-display-value-extractor",
+                    "description": "Provides displayValueExtractor to show label not raw value in closed selector",
+                    "type": "contains",
+                    "value": "displayValueExtractor"
+                },
+                {
+                    "id": "extractor-returns-label",
+                    "description": "displayValueExtractor returns the label field, not value",
+                    "type": "contains",
+                    "value": "opt.label"
+                }
+            ]
+        },
+        {
+            "id": 8,
+            "prompt": "I need a read-only summary table showing 3 rows of data: Name, Status, and Date. No sorting or row selection needed. Use @lifesg/react-design-system.",
+            "expected_output": "Uses Table.Container wrapping Table with Table.Head, Table.Body, Table.Row, Table.HeaderCell and Table.Cell sub-components. Imports from @lifesg/react-design-system/table. Does not use DataTable (overkill for read-only data). Does not use raw <table> HTML.",
+            "files": [],
+            "assertions": [
+                {
+                    "id": "uses-table-container",
+                    "description": "Wraps table in Table.Container for scroll behaviour",
+                    "type": "contains",
+                    "value": "Table.Container"
+                },
+                {
+                    "id": "uses-table-head",
+                    "description": "Uses Table.Head for header row",
+                    "type": "contains",
+                    "value": "Table.Head"
+                },
+                {
+                    "id": "uses-table-cell",
+                    "description": "Uses Table.Cell for data cells",
+                    "type": "contains",
+                    "value": "Table.Cell"
+                },
+                {
+                    "id": "correct-import",
+                    "description": "Imports Table from the table subpath",
+                    "type": "contains",
+                    "value": "@lifesg/react-design-system/table"
+                },
+                {
+                    "id": "no-datatable",
+                    "description": "Does not use DataTable for a simple read-only table",
+                    "type": "not_contains",
+                    "value": "DataTable"
+                },
+                {
+                    "id": "no-raw-table",
+                    "description": "Does not use raw <table> HTML elements",
+                    "type": "not_contains",
+                    "value": "<table"
+                }
+            ]
+        },
+        {
+            "id": 9,
+            "prompt": "Add a back arrow icon and a settings gear icon to a page header using @lifesg/react-design-system. The back arrow should be on the left, the gear on the right.",
+            "expected_output": "Imports icons from @lifesg/react-icons subpaths: ArrowLeftIcon from @lifesg/react-icons/arrow-left and GearIcon from @lifesg/react-icons/gear. Does not import from @lifesg/react-design-system directly for icons. Does not use MUI icons when react-icons has a suitable match. Icon component names end in 'Icon'.",
+            "files": [],
+            "assertions": [
+                {
+                    "id": "imports-from-react-icons",
+                    "description": "Imports from @lifesg/react-icons, not the main DS package",
+                    "type": "contains",
+                    "value": "@lifesg/react-icons"
+                },
+                {
+                    "id": "uses-arrow-icon",
+                    "description": "Uses a named arrow icon (not a custom SVG)",
+                    "type": "contains",
+                    "value": "ArrowLeft"
+                },
+                {
+                    "id": "uses-gear-icon",
+                    "description": "Uses GearIcon for settings",
+                    "type": "contains",
+                    "value": "Gear"
+                },
+                {
+                    "id": "icon-names-end-in-icon",
+                    "description": "Icon component names end in Icon suffix",
+                    "type": "contains",
+                    "value": "Icon"
+                },
+                {
+                    "id": "no-custom-svg",
+                    "description": "Does not inline a custom <svg> instead of using the package",
+                    "type": "not_contains",
+                    "value": "<svg"
+                }
+            ]
+        },
+        {
+            "id": 10,
+            "prompt": "I have a form with a Yes/No question 'Do you agree to the terms?' and a filter panel with a 'Remember me' tick-box. Which DS components should I use for each? Use @lifesg/react-design-system v4.",
+            "expected_output": "Yes/No question in a form: use Toggle with type='yes' and type='no' (not RadioButton, not Checkbox). Filter tick-box: use Checkbox (not Toggle). Toggle is for card-style form selections; Checkbox is for compact boolean filter/table use.",
+            "files": [],
+            "assertions": [
+                {
+                    "id": "uses-toggle-for-yes-no",
+                    "description": "Uses Toggle for the yes/no form question",
+                    "type": "contains",
+                    "value": "Toggle"
+                },
+                {
+                    "id": "toggle-type-yes",
+                    "description": "Toggle uses type='yes' and type='no'",
+                    "type": "contains",
+                    "value": "type=\"yes\""
+                },
+                {
+                    "id": "uses-checkbox-for-filter",
+                    "description": "Uses Checkbox for the compact filter tick-box",
+                    "type": "contains",
+                    "value": "Checkbox"
+                },
+                {
+                    "id": "no-radio-for-yes-no",
+                    "description": "Does not use RadioButton for the binary yes/no question",
+                    "type": "not_contains",
+                    "value": "RadioButton"
+                }
+            ]
+        }
+    ]
+}

package/skills/fds-build/resources/components/accordion.md

@@ -0,0 +1,128 @@
+# Accordion
+
+Import: `import { Accordion } from "@lifesg/react-design-system/accordion"`
+
+## When to use
+
+Use to reduce visual complexity when users don't need all content at once — FAQs, supplementary details, or grouped settings. Do not use when all content needs to be visible at the same time.
+
+## Composition
+
+```
+Accordion                    ← container, manages expand/collapse state
+├── Accordion.Item           ← expandable panel
+├── Accordion.Item
+└── Accordion.Item
+```
+
+All children must be `Accordion.Item`. Do not place other elements directly inside `Accordion`.
+
+## Variants
+
+| `type` on `Accordion.Item` | Usage                                |
+| -------------------------- | ------------------------------------ |
+| `"default"`                | Standard title size — default        |
+| `"small"`                  | Compact title size for dense layouts |
+
+## Usage
+
+```tsx
+import { Accordion } from "@lifesg/react-design-system/accordion";
+
+// Multiple items — all collapsed by default
+const FaqSection = () => (
+    <Accordion
+        title="Frequently asked questions"
+        headingLevel={2}
+        initialDisplay="collapse-all"
+        enableExpandAll
+    >
+        <Accordion.Item title="What is this service?">
+            <p>This service lets you manage your account settings.</p>
+        </Accordion.Item>
+        <Accordion.Item title="How do I reset my password?">
+            <p>Click "Forgot password" on the login page.</p>
+        </Accordion.Item>
+        {/* JSX in title must be wrapped in <span> — title renders inside <button> */}
+        <Accordion.Item
+            title={
+                <span>
+                    Can I use <strong>bold text</strong> in a title?
+                </span>
+            }
+        >
+            <p>Yes — wrap JSX title content in a span.</p>
+        </Accordion.Item>
+    </Accordion>
+);
+
+// Controlled item — force one item open regardless of Expand All state
+const ControlledExample = () => (
+    <Accordion initialDisplay="collapse-all">
+        <Accordion.Item title="Always expanded" expanded={true}>
+            <p>This item ignores the parent initialDisplay.</p>
+        </Accordion.Item>
+        <Accordion.Item title="Follows parent state">
+            <p>This item collapses with the rest.</p>
+        </Accordion.Item>
+    </Accordion>
+);
+```
+
+## Props — `AccordionProps`
+
+| Prop                     | Type                             | Default      | Description                                                                                                                                                                                                                                               |
+| ------------------------ | -------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `children` \*            | `JSX.Element \| JSX.Element[]`   | —            | —                                                                                                                                                                                                                                                         |
+| `title`                  | `string \| JSX.Element`          | —            | Section heading rendered above the item list. Visually hidden on mobile unless `showTitleInMobile` is true.                                                                                                                                               |
+| `enableExpandAll`        | `boolean`                        | true         | Renders the "Show all" / "Hide all" toggle button.                                                                                                                                                                                                        |
+| `initialDisplay`         | `"collapse-all" \| "expand-all"` | "expand-all" | Controls whether all items start expanded or collapsed.                                                                                                                                                                                                   |
+| `showTitleInMobile`      | `boolean`                        | false        | When `true`, the `title` remains visible on mobile viewports.                                                                                                                                                                                             |
+| `id`                     | `string`                         | —            | —                                                                                                                                                                                                                                                         |
+| `className`              | `string`                         | —            | —                                                                                                                                                                                                                                                         |
+| `headingLevel`           | `number`                         | 2            | The ARIA heading level for the accordion and item titles. Specify a custom value to reflect the component's hierarchy within a page. When a title is provided, the title level = n and the item title level = n + 1. Otherwise, the item title level = n. |
+| `onExpandCollapseChange` | `((expanded: boolean) => void)`  | —            | Called after the expand/collapse state changes.                                                                                                                                                                                                           |
+
+## Props — `AccordionItemProps`
+
+| Prop             | Type                            | Default | Description                                                                                                                                                                                                                                                                               |
+| ---------------- | ------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title` \*       | `string \| JSX.Element`         | —       | —                                                                                                                                                                                                                                                                                         |
+| `children` \*    | `JSX.Element \| JSX.Element[]`  | —       | —                                                                                                                                                                                                                                                                                         |
+| `expanded`       | `boolean`                       | —       | Controls the expanded state of this item. Omit (or pass `undefined`) to let the parent "Show all" / "Hide all" button manage the state. Pass an explicit boolean to take individual control of this item.                                                                                 |
+| `id`             | `string`                        | —       | —                                                                                                                                                                                                                                                                                         |
+| `className`      | `string`                        | —       | —                                                                                                                                                                                                                                                                                         |
+| `type`           | `AccordionItemType`             | —       | Visual size variant for the accordion item.                                                                                                                                                                                                                                               |
+| `collapsible`    | `boolean`                       | true    | When `false`, the item header is non-interactive and the content panel is always visible.                                                                                                                                                                                                 |
+| `onExpandChange` | `((expanded: boolean) => void)` | —       | Called when the user toggles this item or the parent "Show all" / "Hide all" button fires. When provided, the item enters **controlled mode** — the caller must update the `expanded` prop in response. Without this prop, the item manages its own state internally (uncontrolled mode). |
+
+## Props — `AccordionItemApi`
+
+| Prop            | Type            | Default | Description |
+| --------------- | --------------- | ------- | ----------- |
+| `expand` \*     | `() => void`    | —       | —           |
+| `collapse` \*   | `() => void`    | —       | —           |
+| `isExpanded` \* | `() => boolean` | —       | —           |
+
+## Props — `AccordionItemHandle`
+
+| Prop            | Type            | Default | Description |
+| --------------- | --------------- | ------- | ----------- |
+| `expand` \*     | `() => void`    | —       | —           |
+| `collapse` \*   | `() => void`    | —       | —           |
+| `isExpanded` \* | `() => boolean` | —       | —           |
+
+## Rules
+
+-   Always set `headingLevel` when `title` is provided — ensures correct heading hierarchy.
+-   Use `Accordion.Item` for all panels — do not place content directly in `Accordion`.
+-   Wrap custom JSX titles in `<span>` — item title renders inside a `<button>` and block elements are invalid inside it.
+-   Individual `expanded` on `Accordion.Item` overrides Expand All / Collapse All for that item.
+-   Use `initialDisplay="collapse-all"` when content is supplementary and users are unlikely to need it immediately.
+
+## Anti-patterns
+
+-   Placing content directly inside `Accordion` without `Accordion.Item` wrappers.
+-   Using Accordion when all content should be visible at once — use a plain layout instead.
+-   Using block elements (e.g. `<div>`) directly as `title` in `Accordion.Item` — wrap in `<span>`.
+-   Skipping `headingLevel` when `title` is set — this breaks heading hierarchy for screen readers.