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

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

@@ -0,0 +1,104 @@
+# Pagination
+
+Import: `import { Pagination } from "@lifesg/react-design-system/pagination"`
+
+## When to use
+
+Use below lists or tables when content is split across multiple pages.
+
+## Usage
+
+### Basic pagination (1-based indexing)
+
+```tsx
+import { useState } from "react";
+import { Pagination } from "@lifesg/react-design-system/pagination";
+
+const ResultsList = () => {
+    const totalItems = 243;
+    const pageSize = 10;
+    // activePage is 1-based: page 1 is the first page, not page 0
+    const [activePage, setActivePage] = useState(1);
+
+    return (
+        <>
+            <MyResultsTable
+                items={results.slice(
+                    (activePage - 1) * pageSize,
+                    activePage * pageSize
+                )}
+            />
+            <Pagination
+                totalItems={totalItems}
+                pageSize={pageSize}
+                activePage={activePage}
+                onPageChange={(page) => setActivePage(page)} // page is 1-based
+                showFirstAndLastNav
+            />
+        </>
+    );
+};
+```
+
+### With page size changer
+
+`onPageSizeChange` receives `(page, pageSize)` — reset to page 1 when size changes.
+
+```tsx
+const [activePage, setActivePage] = useState(1);
+const [pageSize, setPageSize] = useState(10);
+
+<Pagination
+    totalItems={500}
+    pageSize={pageSize}
+    activePage={activePage}
+    onPageChange={(page) => setActivePage(page)}
+    onPageSizeChange={(page, size) => {
+        setPageSize(size);
+        setActivePage(page); // component resets to page 1 on size change
+    }}
+    showFirstAndLastNav
+    showPageSizeChanger
+/>;
+```
+
+## Props — `PaginationProps`
+
+| Prop                  | Type                                         | Default             | Description                                                                                                   |
+| --------------------- | -------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `id`                  | `string`                                     | —                   | —                                                                                                             |
+| `className`           | `string`                                     | —                   | —                                                                                                             |
+| `variant`             | `"default" \| "full" \| "compact"`           | "default"           | Controls whether the pagination follows the responsive layout or always renders the full or compact layout.   |
+| `pageSize`            | `number`                                     | 10                  | Number of items displayed per page.                                                                           |
+| `totalItems` \*       | `number`                                     | —                   | Total number of items across all pages. Used to compute the total page count.                                 |
+| `activePage` \*       | `number`                                     | —                   | The currently active 1-based page number. This is a controlled prop; update it in response to `onPageChange`. |
+| `pageSizeOptions`     | `PageSizeItemProps[]`                        | 10, 20, 30 per page | Options listed in the page-size changer dropdown. Only relevant when `showPageSizeChanger` is `true`.         |
+| `showFirstAndLastNav` | `boolean`                                    | —                   | When `true`, renders first-page and last-page navigation buttons alongside the previous/next buttons.         |
+| `showPageSizeChanger` | `boolean`                                    | false               | When `true`, renders a dropdown in the full layout to change the `pageSize`.                                  |
+| `onPageChange`        | `((page: number) => void)`                   | —                   | Called when the user navigates to a different page.                                                           |
+| `onPageSizeChange`    | `((page: number, pageSize: number) => void)` | —                   | Called when the user selects a different page size from the dropdown and `showPageSizeChanger` is `true`.     |
+
+## Props — `PageSizeItemProps`
+
+| Prop       | Type     | Default | Description |
+| ---------- | -------- | ------- | ----------- |
+| `value` \* | `number` | —       | —           |
+| `label` \* | `string` | —       | —           |
+
+## Rules
+
+-   `activePage` is 1-based — the first page is `1`, not `0`.
+-   Always provide `onPageChange` to update `activePage` when the user changes page.
+-   Provide `onPageSizeChange` when `showPageSizeChanger` is enabled.
+-   Always center-align pagination below the results list.
+-   Place pagination below the results — never above.
+-   When total pages exceed 7, the component automatically shows an ellipsis — no additional props needed.
+-   The page size changer is only visible in the desktop viewport.
+-   The selected option in the page size changer takes precedence over `pageSize`.
+
+## Anti-patterns
+
+-   Do not use `showFirstAndLastNav` and `showPageSizeChanger` together unless the dataset is large enough to warrant both — avoid cluttering the interface with excessive controls.
+-   Do not left- or right-align pagination.
+-   Do not place pagination above the results.
+-   Do not use `pageSize` and a `pageSizeOptions` selection simultaneously without handling `onPageSizeChange` — the changer selection overrides `pageSize`.

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

@@ -0,0 +1,55 @@
+# Pill
+
+Import: `import { Pill } from "@lifesg/react-design-system/pill"`
+
+## When to use
+
+Use to communicate a status — application state, approval outcome, or processing stage. For categories, filters, or tagging, use Tag instead.
+
+## Variants
+
+| `type`      | Usage                                                    |
+| ----------- | -------------------------------------------------------- |
+| `"outline"` | Subtle, secondary label — default for most uses          |
+| `"solid"`   | Higher emphasis — use when the status needs to stand out |
+
+| `colorType` | Semantic use                  |
+| ----------- | ----------------------------- |
+| `"green"`   | Success, active, approved     |
+| `"red"`     | Error, rejected, danger       |
+| `"yellow"`  | Warning, pending, in progress |
+| `"blue"`    | Informational                 |
+| `"grey"`    | Neutral, inactive, draft      |
+| `"primary"` | Theme primary color           |
+| `"black"`   | Default, no semantic meaning  |
+
+## Usage
+
+```tsx
+import { Pill } from "@lifesg/react-design-system/pill";
+
+<Pill type="outline" colorType="green">
+    Approved
+</Pill>;
+```
+
+## Props — `PillProps`
+
+| Prop        | Type            | Default | Description                          |
+| ----------- | --------------- | ------- | ------------------------------------ |
+| `type` \*   | `PillType`      | —       | Visual style variant for the pill.   |
+| `colorType` | `PillColorType` | "black" | Color theme applied to the pill.     |
+| `icon`      | `JSX.Element`   | —       | Icon rendered before the label text. |
+
+## Rules
+
+-   Use color semantically — do not use `"red"` for non-error states.
+-   Use `"solid"` sparingly — reserve for statuses that need emphasis.
+-   Keep label text to 1–2 words — text does not wrap inside a pill.
+-   Pill is a static, non-interactive label — it does not accept `onClick`. Use Tag with `interactive` for clickable labels.
+
+## Anti-patterns
+
+-   Using Pill for categories or filters — use Tag instead.
+-   Using `"red"` for non-error states.
+-   Labels longer than 2–3 words — text overflow is not handled.

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

@@ -0,0 +1,80 @@
+# Popover
+
+Import: `import { Popover, withPopover } from "@lifesg/react-design-system/popover"`
+
+## When to use
+
+Use to show supplementary information when a user interacts with (clicks or hovers over) an element. On mobile, the popover renders as a bottom modal sheet.
+
+## Variants
+
+Two usage patterns are available:
+
+-   **`withPopover` HOC** — wraps an existing element to add popover behaviour.
+-   **`Popover` component** — a standalone popover that you control manually.
+
+## Usage
+
+```tsx
+import { withPopover } from "@lifesg/react-design-system/popover";
+import { Button } from "@lifesg/react-design-system/button";
+
+{
+    /* Preferred: HOC wraps an existing element */
+}
+{
+    withPopover(<Button styleType="link">What is this?</Button>, {
+        content: "This field requires your NRIC number.",
+        trigger: "click",
+    });
+}
+```
+
+## Props — `PopoverProps`
+
+| Prop            | Type                    | Default            | Description                                                                                                         |
+| --------------- | ----------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------- |
+| `children` \*   | `string \| JSX.Element` | —                  | Content displayed inside the popover. A plain string is automatically wrapped in a `Typography.BodyMD` element.     |
+| `visible`       | `boolean`               | false              | Controls whether the popover is visible.                                                                            |
+| `id`            | `string`                | —                  | —                                                                                                                   |
+| `className`     | `string`                | —                  | —                                                                                                                   |
+| `onMobileClose` | `(() => void)`          | —                  | Called when the user dismisses the popover on a mobile viewport, either by tapping the overlay or the close button. |
+| `ariaLabel`     | `string`                | "More information" | Accessible label for the `role="dialog"` element.                                                                   |
+| `overflow`      | `PopoverOverflowType`   | —                  | CSS `overflow` value applied to the popover card body.                                                              |
+| `maxHeight`     | `number`                | —                  | Maximum height of the popover card in pixels.                                                                       |
+
+## Props — `PopoverRenderProps`
+
+| Prop        | Type                  | Default | Description                                            |
+| ----------- | --------------------- | ------- | ------------------------------------------------------ |
+| `overflow`  | `PopoverOverflowType` | —       | CSS `overflow` value applied to the popover card body. |
+| `maxHeight` | `number`              | —       | Maximum height of the popover card in pixels.          |
+
+## Props — `PopoverTriggerProps`
+
+| Prop                | Type                                                                                 | Default            | Description                                                                                                                                                                     |
+| ------------------- | ------------------------------------------------------------------------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `children` \*       | `React.ReactNode`                                                                    | —                  | The trigger element rendered inside a focusable wrapper div.                                                                                                                    |
+| `popoverContent` \* | `\| string \| JSX.Element \| ((renderProps: PopoverRenderProps) => React.ReactNode)` | —                  | Content shown inside the popover panel. A string or JSX element is rendered inside the default `Popover`; a render function bypasses it for completely custom rendering.        |
+| `trigger`           | `PopoverTriggerType`                                                                 | "click"            | Interaction that opens the popover.                                                                                                                                             |
+| `position`          | `PopoverPosition`                                                                    | "top"              | Preferred placement of the popover relative to the trigger.                                                                                                                     |
+| `id`                | `string`                                                                             | —                  | —                                                                                                                                                                               |
+| `zIndex`            | `number`                                                                             | —                  | Overrides the stacking context z-index for the floating popover layer. Falls back to the inherited floating context z-index when omitted.                                       |
+| `className`         | `string`                                                                             | —                  | —                                                                                                                                                                               |
+| `rootNode`          | `RefObject<HTMLElement>`                                                             | document.body      | The root element that contains the popover element.                                                                                                                             |
+| `customOffset`      | `number`                                                                             | 16                 | Distance in pixels between the trigger element and the popover panel.                                                                                                           |
+| `delay`             | `\| { open?: number; close?: number }`                                               | —                  | Open and close delays in milliseconds. Only applies when `trigger` is `"hover"`.                                                                                                |
+| `enableFlip`        | `boolean`                                                                            | true               | Allows the popover to flip to the opposite side when the preferred position has insufficient viewport space.                                                                    |
+| `enableResize`      | `boolean`                                                                            | false              | Resizes the popover to fit the remaining vertical space in the viewport.                                                                                                        |
+| `overflow`          | `PopoverOverflowType`                                                                | "auto"             | CSS `overflow` value forwarded to the popover card when `enableResize` is active.                                                                                               |
+| `popoverAriaLabel`  | `string`                                                                             | "More information" | Accessible label for the popover dialog element.                                                                                                                                |
+| `triggerOnFocus`    | `boolean`                                                                            | false              | Also opens the popover when the trigger element receives focus.                                                                                                                 |
+| `isModal`           | `boolean`                                                                            | true               | When `true`, focus is trapped inside the popover until dismissed. When `false`, the popover closes automatically once the user tabs away from both the trigger and the popover. |
+| `onPopoverAppear`   | `(() => void)`                                                                       | —                  | Called when the popover becomes visible.                                                                                                                                        |
+| `onPopoverDismiss`  | `(() => void)`                                                                       | —                  | Called when the popover is dismissed.                                                                                                                                           |
+
+## Rules
+
+-   Use `withPopover` for most cases — it handles trigger logic automatically.
+-   Use the `Popover` component directly when you need full manual control over visibility.
+-   On mobile viewports the Popover renders as a bottom modal sheet — provide `onMobileClose` to handle dismissal.

package/skills/fds-build/resources/components/progress-indicator.md

@@ -0,0 +1,47 @@
+# ProgressIndicator
+
+Import: `import { ProgressIndicator } from "@lifesg/react-design-system/progress-indicator"`
+
+## When to use
+
+Use in multi-step forms or wizards to show the user's position within the flow.
+
+## Usage
+
+```tsx
+import { ProgressIndicator } from "@lifesg/react-design-system/progress-indicator";
+
+const steps = [
+    { label: "Personal details" },
+    { label: "Documents" },
+    { label: "Review" },
+];
+
+<ProgressIndicator
+    steps={steps}
+    currentIndex={1}
+    displayExtractor={(step) => step.label}
+/>;
+```
+
+## Props
+
+| Prop               | Type                    | Default | Description                                                                                              |
+| ------------------ | ----------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
+| `steps` \*         | `T[]`                   | —       | Ordered list of step items to render as progress bars and labels.                                        |
+| `currentIndex` \*  | `number`                | —       | Zero-based index of the current active step. All steps at or before this index are visually highlighted. |
+| `displayExtractor` | `((item: T) => string)` | —       | Derives the display label for a step item.                                                               |
+| `className`        | `string`                | —       | —                                                                                                        |
+| `id`               | `string`                | —       | —                                                                                                        |
+
+## Rules
+
+-   `currentIndex` is zero-based — the first step is `0`.
+-   Always provide `displayExtractor` when `steps` contains objects — without it, step labels will not render.
+-   Update `currentIndex` as the user moves between steps.
+-   Do not use `fadeColor` or `fadePosition` — these props are deprecated and have no effect in v3.
+
+## Anti-patterns
+
+-   Do not use ProgressIndicator on single-step pages.
+-   Do not use it as a general progress bar for loading states — use a loading spinner or skeleton instead.

package/skills/fds-build/resources/components/radio-button.md

@@ -0,0 +1,66 @@
+# RadioButton
+
+Import: `import { RadioButton } from "@lifesg/react-design-system/radio-button"`
+
+## When to use
+
+-   User must choose exactly one option from a small set (typically 2–5 options).
+-   Options are mutually exclusive.
+
+Prefer `Toggle` with `type="radio"` over bare `RadioButton` when building form inputs that need a visible card-style label container.
+
+## Variants
+
+| `displaySize` | When to use                    |
+| ------------- | ------------------------------ |
+| `"default"`   | Standard use                   |
+| `"small"`     | Dense layouts, inline controls |
+
+## Usage
+
+```tsx
+import { RadioButton } from "@lifesg/react-design-system/radio-button";
+
+<div role="radiogroup" aria-labelledby="group-label">
+    <label>
+        <RadioButton
+            name="plan"
+            value="basic"
+            checked={selected === "basic"}
+            onChange={(e) => {}}
+        />
+        Basic
+    </label>
+    <label>
+        <RadioButton
+            name="plan"
+            value="pro"
+            checked={selected === "pro"}
+            onChange={(e) => {}}
+        />
+        Pro
+    </label>
+</div>;
+```
+
+## Props — `RadioButtonProps`
+
+| Prop                    | Type              | Default   | Description                                                                                                             |
+| ----------------------- | ----------------- | --------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `checked`               | `boolean`         | —         | The selected state of the component                                                                                     |
+| `disabled`              | `boolean`         | —         | —                                                                                                                       |
+| `displaySize`           | `RadioButtonSize` | "default" | Visual size of the radio button icon.                                                                                   |
+| `focusableWhenDisabled` | `boolean`         | —         | When `true` and `disabled` is also `true`, the radio button remains keyboard-focusable. `onChange` is still suppressed. |
+
+## Rules
+
+-   Always wrap a group in `role="radiogroup"` with a visible group label (`aria-labelledby`).
+-   Always set the same `name` on all buttons in a group for native radio behaviour.
+-   Always pair each button with a visible label — wrap in `<label>` or use `aria-label`.
+-   Never render a single `RadioButton` in isolation — radio inputs only make sense in groups.
+
+## Anti-patterns
+
+-   Do not use `RadioButton` for binary yes/no questions in forms — use `Toggle` with `type="yes"` / `type="no"`.
+-   Do not use `RadioButton` when multiple selections are allowed — use `Checkbox` instead.
+-   Do not omit the `name` prop — without it, browsers cannot enforce mutual exclusivity natively.

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

@@ -0,0 +1,78 @@
+# Schedule
+
+Import: `import { Schedule } from "@lifesg/react-design-system/schedule"`
+
+## Sub-components
+
+-   `ScheduleEntityProps` — a service/resource row with its time slots
+-   `ScheduleSlotProps` — a single bookable timeslot cell
+-   `SchedulePopoverProps` — popover config for a slot
+
+## Props — `ScheduleEntityProps`
+
+| Prop       | Type                  | Default | Description                                                |
+| ---------- | --------------------- | ------- | ---------------------------------------------------------- |
+| `id` \*    | `string`              | —       | Unique identifier.                                         |
+| `name` \*  | `string`              | —       | Display name shown in the column header.                   |
+| `slots` \* | `ScheduleSlotProps[]` | —       | All time slots belonging to this service across all dates. |
+
+## Props — `SchedulePopoverProps`
+
+| Prop         | Type                                               | Default | Description                                                  |
+| ------------ | -------------------------------------------------- | ------- | ------------------------------------------------------------ |
+| `trigger` \* | `PopoverTriggerType`                               | —       | Interaction type that opens the popover.                     |
+| `content` \* | `string \| JSX.Element \| (() => React.ReactNode)` | —       | The popover body.                                            |
+| `delay`      | `{ open?: number; close?: number }`                | —       | Open and close delay in milliseconds.                        |
+| `offset`     | `number`                                           | —       | Distance in pixels between the slot element and the popover. |
+
+## Props — `ScheduleProps`
+
+| Prop                      | Type                                                          | Default | Description                                                                                                                |
+| ------------------------- | ------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `id`                      | `string`                                                      | —       | —                                                                                                                          |
+| `className`               | `string`                                                      | —       | —                                                                                                                          |
+| `view`                    | `ScheduleView`                                                | "day"   | The layout view.                                                                                                           |
+| `date` \*                 | `string`                                                      | —       | The currently displayed date in `YYYY-MM-DD` format. Slots are filtered to match this date in the day view.                |
+| `emptyContentMessage`     | `string`                                                      | —       | Message shown inside the empty-state illustration when `serviceData` is empty.                                             |
+| `serviceData` \*          | `ScheduleEntityProps[]`                                       | —       | Array of service entities to render. Each entity maps to a column in the week view, or to a carousel item in the day view. |
+| `loading`                 | `boolean`                                                     | false   | When `true` the schedule renders a loading animation in place of slot content.                                             |
+| `minTime`                 | `string`                                                      | "00:00" | Earliest time shown on the time axis, in `HH:mm` format.                                                                   |
+| `maxTime`                 | `string`                                                      | "23:59" | Latest time shown on the time axis, in `HH:mm` format.                                                                     |
+| `initialScrollTime`       | `string`                                                      | —       | Time the schedule scrolls to on first render, in `HH:mm` format.                                                           |
+| `minDate`                 | `string`                                                      | —       | Earliest selectable date in the calendar picker, in `YYYY-MM-DD` format.                                                   |
+| `maxDate`                 | `string`                                                      | —       | Latest selectable date in the calendar picker, in `YYYY-MM-DD` format.                                                     |
+| `onPreviousDayClick` \*   | `(currentDate: string) => void`                               | —       | Called when the user navigates to the previous day.                                                                        |
+| `onNextDayClick` \*       | `(currentDate: string) => void`                               | —       | Called when the user navigates to the next day.                                                                            |
+| `onCalendarDateSelect` \* | `(currentDate: string) => void`                               | —       | Called when the user picks a date from the calendar popover.                                                               |
+| `onTodayClick` \*         | `() => void`                                                  | —       | Called when the user clicks the "Today" button in the header.                                                              |
+| `onEmptySlotClick`        | `((slot: ScheduleEmptySlotProps) => void)`                    | —       | Called when the user clicks a cell without any time slots in the day view.                                                 |
+| `emptySlotPopover`        | `\| ((slot: ScheduleEmptySlotProps) => SchedulePopoverProps)` | —       | When provided, a popover is attached to each empty slot in the day view instead of calling `onEmptySlotClick` directly.    |
+| `blockedMessage`          | `string`                                                      | —       | Message displayed inside blocked slots.                                                                                    |
+| `onClickHiddenSlots`      | `((hiddenServices: string[]) => void)`                        | —       | Called in the week view when the user clicks a cell that contains hidden overflow slots.                                   |
+
+## Props — `ScheduleSlotProps`
+
+| Prop            | Type                                                          | Default | Description                                                |
+| --------------- | ------------------------------------------------------------- | ------- | ---------------------------------------------------------- |
+| `id` \*         | `string`                                                      | —       | Unique identifier for the slot.                            |
+| `startTime` \*  | `string`                                                      | —       | Slot start time in `HH:mm` format.                         |
+| `endTime` \*    | `string`                                                      | —       | Slot end time in `HH:mm` format.                           |
+| `status` \*     | `ScheduleCellType`                                            | —       | Visual state of the slot.                                  |
+| `capacity`      | `number`                                                      | —       | Total number of bookable places in this slot.              |
+| `date` \*       | `string`                                                      | —       | Date this slot belongs to in `YYYY-MM-DD` format.          |
+| `booked`        | `number`                                                      | —       | Number of confirmed bookings already made for this slot.   |
+| `customPopover` | `SchedulePopoverProps`                                        | —       | Attaches a popover to this slot with custom configuration. |
+| `onClick`       | `\| ((data: ScheduleSlotProps, e: React.MouseEvent) => void)` | —       | Called when the user clicks this slot.                     |
+
+## Props — `ScheduleEmptySlotProps`
+
+| Prop           | Type     | Default | Description                                     |
+| -------------- | -------- | ------- | ----------------------------------------------- |
+| `startTime` \* | `string` | —       | Slot start time in `HH:mm` format.              |
+| `endTime` \*   | `string` | —       | Slot end time in `HH:mm` format.                |
+| `name` \*      | `string` | —       | Name of the service this empty slot belongs to. |
+
+## Rules
+
+-   `date`, `serviceData`, `onPreviousDayClick`, and `onNextDayClick` are mandatory.
+-   Avoid combining a per-slot `onClick` with `customPopover` using `trigger: "click"` on the same slot — they conflict.

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

@@ -0,0 +1,183 @@
+# Sidenav
+
+Import: `import { Sidenav } from "@lifesg/react-design-system/sidenav"`
+
+## When to use
+
+Use for section-level navigation in admin dashboards or portals. The Sidenav sits fixed to the left and fills the full viewport height below the Navbar, which is always present at the top.
+
+Do not use for:
+
+-   Consumer-facing pages (use Navbar nav items or LocalNav instead)
+-   Simple single-section apps
+
+## Sub-components
+
+```
+Sidenav                          ← fixed sidebar container
+├── Sidenav.Group                ← logical section (optional separator)
+│   ├── Sidenav.Item             ← top-level nav link (no children)
+│   ├── Sidenav.DrawerItem       ← expandable item with sub-links
+│   │   ├── Sidenav.DrawerSubitem
+│   │   └── Sidenav.DrawerSubitem
+│   └── Sidenav.Item
+└── Sidenav.Group
+    └── Sidenav.Item
+```
+
+`Sidenav.Group` is the only valid direct child of `Sidenav`. Use `Sidenav.Item` for leaf links, `Sidenav.DrawerItem` when a nav entry has sub-items. `Sidenav.DrawerSubitem` can only nest inside `Sidenav.DrawerItem`.
+
+## Variants
+
+| Depth    | Components used                              |
+| -------- | -------------------------------------------- |
+| 1 level  | `Sidenav` → `Sidenav.Group` → `Sidenav.Item` |
+| 2 levels | + `Sidenav.DrawerItem`                       |
+| 3 levels | + `Sidenav.DrawerSubitem`                    |
+
+## Usage
+
+### 2-group, 3-item nav with full nesting
+
+```tsx
+import { CalendarIcon } from "@lifesg/react-icons/calendar";
+import { DocIcon } from "@lifesg/react-icons/doc";
+import { Square2x2Icon } from "@lifesg/react-icons/square-2x2";
+import { useState } from "react";
+import { Sidenav } from "@lifesg/react-design-system/sidenav";
+
+const AdminSidenav = () => {
+    const [selectedId, setSelectedId] = useState("dashboard");
+
+    return (
+        <Sidenav>
+            {/* Group 1 — top-level items with no sub-items: onClick fires */}
+            <Sidenav.Group separator>
+                <Sidenav.Item
+                    id="dashboard"
+                    title="Dashboard"
+                    icon={<Square2x2Icon />}
+                    selected={selectedId === "dashboard"}
+                    onClick={(id) => setSelectedId(id)}
+                />
+            </Sidenav.Group>
+
+            {/* Group 2 — Reports has sub-items so onClick is omitted;
+                clicking it opens the drawer instead */}
+            <Sidenav.Group>
+                <Sidenav.Item
+                    id="reports"
+                    title="Reports"
+                    icon={<DocIcon />}
+                    selected={
+                        selectedId === "monthly-reports" ||
+                        selectedId === "annual-reports"
+                    }
+                >
+                    {/* DrawerItem with no children: onClick fires */}
+                    <Sidenav.DrawerItem
+                        id="monthly-reports"
+                        title="Monthly reports"
+                        onClick={(id) => setSelectedId(id)}
+                    />
+                    {/* DrawerItem with children: onClick is omitted */}
+                    <Sidenav.DrawerItem
+                        id="annual-reports"
+                        title="Annual reports"
+                        selected={selectedId === "annual-reports"}
+                    >
+                        <Sidenav.DrawerSubitem
+                            id="annual-summary"
+                            title="Summary"
+                            onClick={(id) => setSelectedId(id)}
+                        />
+                        <Sidenav.DrawerSubitem
+                            id="annual-detail"
+                            title="Detailed breakdown"
+                            onClick={(id) => setSelectedId(id)}
+                        />
+                    </Sidenav.DrawerItem>
+                </Sidenav.Item>
+                <Sidenav.Item
+                    id="bookings"
+                    title="Bookings"
+                    icon={<CalendarIcon />}
+                    selected={selectedId === "bookings"}
+                    onClick={(id) => setSelectedId(id)}
+                />
+            </Sidenav.Group>
+        </Sidenav>
+    );
+};
+```
+
+Key wiring notes:
+
+-   `onClick` on `Sidenav.Item` is only attached when the item has **no** `children` — if children are present, clicking opens the drawer instead and `onClick` is ignored.
+-   The same rule applies to `Sidenav.DrawerItem`: omit `onClick` when it wraps `DrawerSubitem` children.
+-   Track `selectedId` in parent state; pass `selected={selectedId === id}` down to whichever level is active.
+-   `separator` on `Sidenav.Group` draws a dividing line below that group.
+
+## Props — `SidenavProps`
+
+| Prop          | Type              | Default   | Description                                                               |
+| ------------- | ----------------- | --------- | ------------------------------------------------------------------------- |
+| `fixed`       | `boolean`         | true      | Pins the sidebar to the left edge of the viewport while the page scrolls. |
+| `children` \* | `React.ReactNode` | —         | Navigation groups and items. Accepts `Sidenav.Group` elements.            |
+| `aria-label`  | `string`          | "Sidebar" | Accessible label announced for the sidebar navigation landmark.           |
+| `id`          | `string`          | —         | —                                                                         |
+| `className`   | `string`          | —         | —                                                                         |
+
+## Props — `SidenavGroupProps`
+
+| Prop          | Type              | Default | Description                                                         |
+| ------------- | ----------------- | ------- | ------------------------------------------------------------------- |
+| `separator`   | `boolean`         | —       | Renders a horizontal divider after the last item in the group.      |
+| `children` \* | `React.ReactNode` | —       | Navigation items within the group. Accepts `Sidenav.Item` elements. |
+| `aria-label`  | `string`          | —       | Accessible label for this navigation group.                         |
+| `id`          | `string`          | —       | —                                                                   |
+| `className`   | `string`          | —       | —                                                                   |
+
+## Props — `SidenavItemProps`
+
+| Prop        | Type                     | Default | Description                                                                                                                                              |
+| ----------- | ------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title` \*  | `string`                 | —       | Label displayed below the icon.                                                                                                                          |
+| `icon` \*   | `React.ReactNode`        | —       | Icon displayed above the title.                                                                                                                          |
+| `selected`  | `boolean`                | —       | Sets the item as initially selected on mount.                                                                                                            |
+| `onClick`   | `((id: string) => void)` | —       | Called when the item is activated and it has no drawer children. When `children` are provided, clicking opens the drawer without invoking this callback. |
+| `children`  | `React.ReactNode`        | —       | Drawer content displayed to the right of the sidebar when the item is active. Accepts `Sidenav.DrawerItem` elements.                                     |
+| `id`        | `string`                 | —       | —                                                                                                                                                        |
+| `className` | `string`                 | —       | —                                                                                                                                                        |
+
+## Props — `SidenavDrawerItemProps`
+
+| Prop        | Type                     | Default | Description                                                                                                                                                               |
+| ----------- | ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title` \*  | `string`                 | —       | The displayed label.                                                                                                                                                      |
+| `children`  | `React.ReactNode`        | —       | Sub-level entries for this section. Accepts `Sidenav.DrawerSubitem` elements. When provided, clicking toggles the collapsed/expanded state instead of invoking `onClick`. |
+| `onClick`   | `((id: string) => void)` | —       | Called when the item is activated and it has no sub-item children.                                                                                                        |
+| `id`        | `string`                 | —       | —                                                                                                                                                                         |
+| `className` | `string`                 | —       | —                                                                                                                                                                         |
+
+## Props — `SidenavDrawerSubitemProps`
+
+| Prop        | Type                     | Default | Description                            |
+| ----------- | ------------------------ | ------- | -------------------------------------- |
+| `title` \*  | `string`                 | —       | The displayed label.                   |
+| `onClick`   | `((id: string) => void)` | —       | Called when the sub-item is activated. |
+| `id`        | `string`                 | —       | —                                      |
+| `className` | `string`                 | —       | —                                      |
+
+## Rules
+
+-   Always provide `icon` on `Sidenav.Item` — it is required for the collapsed state.
+-   Maximum depth is 3 levels: `Item` → `DrawerItem` → `DrawerSubitem`.
+-   Use `Sidenav.Group` with `separator` to visually separate unrelated sections.
+-   `onClick` on `Sidenav.Item` and `Sidenav.DrawerItem` only fires when the item has no children — do not attach click handlers to items that have sub-items.
+
+## Anti-patterns
+
+-   Do not omit `icon` on `Sidenav.Item` — the component is designed around icon + label.
+-   Do not nest deeper than 3 levels.
+-   Do not use `Sidenav` on consumer-facing pages — it is suited to admin portals.

package/skills/fds-build/resources/components/singpass-button.md

@@ -0,0 +1,14 @@
+# SingpassButton
+
+Import: `import { SingpassButton } from "@lifesg/react-design-system/singpass-button"`
+
+## Props — `SingpassButtonProps`
+
+| Prop        | Type                      | Default        | Description                                                             |
+| ----------- | ------------------------- | -------------- | ----------------------------------------------------------------------- |
+| `styleType` | `SingpassButtonStyleType` | "white-filled" | Visual style variant controlling the button background and logo colour. |
+| `sizeType`  | `SingpassButtonSizeType`  | "default"      | Size variant of the button.                                             |
+
+## Rules
+
+-   Do not custom style — Singpass branding guidelines require using the component as-is.