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

package/skills/fds-build/resources/components/data-table.md

@@ -0,0 +1,142 @@
+# DataTable
+
+Import: `import { DataTable } from "@lifesg/react-design-system/data-table"`
+
+## When to use
+
+-   Displaying tabular data with optional sorting, row selection, and custom cell rendering.
+-   Use `enableMultiSelect` + `enableSelectAll` when users need to act on multiple rows at once.
+
+## Usage
+
+### Column definitions, sorting, selection, and custom cell rendering
+
+```tsx
+import { useState, useMemo } from "react";
+import {
+    DataTable,
+    SortIndicatorsProps,
+} from "@lifesg/react-design-system/data-table";
+import { Pill } from "@lifesg/react-design-system/pill";
+
+const rows = [
+    { id: "1", name: "Alice", status: "active", score: 90 },
+    { id: "2", name: "Bob", status: "inactive", score: 72 },
+    { id: "3", name: "Carol", status: "active", score: 85 },
+];
+
+const Example = () => {
+    const [selectedIds, setSelectedIds] = useState<string[]>([]);
+    const [sortState, setSortState] = useState<SortIndicatorsProps>({
+        score: "desc",
+    });
+
+    // onSelect: toggle a single row id
+    const handleSelect = (rowId: string, isSelected: boolean) => {
+        setSelectedIds((prev) =>
+            isSelected ? [...prev, rowId] : prev.filter((id) => id !== rowId)
+        );
+    };
+
+    // onSelectAll: isAllSelected=true means "clear all"; false means "select all"
+    const handleSelectAll = (isAllSelected: boolean) => {
+        setSelectedIds(isAllSelected ? [] : rows.map((r) => r.id));
+    };
+
+    const handleHeaderClick = (fieldKey: string) => {
+        if (fieldKey === "score") {
+            setSortState({ score: sortState.score === "asc" ? "desc" : "asc" });
+        }
+    };
+
+    const sorted = useMemo(
+        () =>
+            [...rows].sort((a, b) =>
+                sortState.score === "asc"
+                    ? a.score - b.score
+                    : b.score - a.score
+            ),
+        [sortState]
+    );
+
+    return (
+        <DataTable
+            headers={[
+                { fieldKey: "name", label: "Name", keyColumn: true },
+                { fieldKey: "status", label: "Status" },
+                { fieldKey: "score", label: "Score", clickable: true },
+            ]}
+            rows={sorted.map((row) => ({
+                ...row,
+                // custom cell: render status as a Pill
+                status: <Pill type="outline">{row.status}</Pill>,
+            }))}
+            selectedIds={selectedIds}
+            disabledIds={["2"]}
+            sortIndicators={sortState}
+            enableMultiSelect
+            enableSelectAll
+            onSelect={handleSelect}
+            onSelectAll={handleSelectAll}
+            onHeaderClick={handleHeaderClick}
+        />
+    );
+};
+```
+
+## HeaderItemProps
+
+| Prop          | Type                        | Default | Description                                                            |
+| ------------- | --------------------------- | ------- | ---------------------------------------------------------------------- |
+| `fieldKey` \* | `string`                    | —       | Key name in the row item object                                        |
+| `label` \*    | `string \| React.ReactNode` | —       | Display label for the column header                                    |
+| `clickable`   | `boolean`                   | —       | If true, `onHeaderClick` is called when the cell is clicked            |
+| `style`       | `CSSProperties`             | —       | Custom styles for the column header cell                               |
+| `keyColumn`   | `boolean`                   | —       | Marks this column as descriptive for screen reader row checkbox labels |
+
+## Props — `DataTableProps`
+
+| Prop                              | Type                                             | Default   | Description                                                                                                                                                                                   |
+| --------------------------------- | ------------------------------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`                              | `string`                                         | —         | —                                                                                                                                                                                             |
+| `headers` \*                      | `HeaderProps[]`                                  | —         | Column definitions that determine the rendered headers and the `fieldKey` used to read values from each `RowProps` entry.                                                                     |
+| `rows`                            | `RowProps[]`                                     | —         | Row data to render. When omitted or empty the empty state is shown.                                                                                                                           |
+| `className`                       | `string`                                         | —         | —                                                                                                                                                                                             |
+| `selectedIds`                     | `string[]`                                       | —         | The ids of selected items. If undefined, the Select All checkbox remains enabled when rows are non-empty.                                                                                     |
+| `disabledIds`                     | `string[]`                                       | —         | Row IDs whose checkboxes are rendered in a disabled state; the rows remain visible.                                                                                                           |
+| `enableMultiSelect`               | `boolean`                                        | —         | Renders a checkbox column as the first column of each row to support row selection.                                                                                                           |
+| `enableSelectAll`                 | `boolean`                                        | —         | Renders a select-all checkbox in the header checkbox column. Requires `enableMultiSelect`.                                                                                                    |
+| `enableActionBar`                 | `boolean`                                        | —         | Shows the action bar whenever one or more rows are selected.                                                                                                                                  |
+| `enableActionBarWithoutSelection` | `boolean`                                        | —         | Shows the action bar even when no rows are selected. Requires `enableActionBar`.                                                                                                              |
+| `enableStickyHeader`              | `boolean`                                        | —         | Keeps the header row visible as the user scrolls down through the table.                                                                                                                      |
+| `actionBarContent`                | `ReactNode`                                      | —         | Additional content rendered inside the action bar.                                                                                                                                            |
+| `loadState`                       | `LoadStateType`                                  | "success" | Controls whether the table body renders data rows or a loading indicator.                                                                                                                     |
+| `onSelect`                        | `((rowId: string, isSelected: boolean) => void)` | —         | Called when a row's checkbox is toggled; receives the row ID and the new selected state.                                                                                                      |
+| `onSelectAll`                     | `((isAllSelected: boolean) => void)`             | —         | Called when the select-all checkbox is toggled.                                                                                                                                               |
+| `onHeaderClick`                   | `((fieldKey: string) => void)`                   | —         | Called when a header cell is clicked; receives the `fieldKey` of the clicked column.                                                                                                          |
+| `onClearSelectionClick`           | `(() => void)`                                   | —         | Called when the "Clear selection" button inside the action bar is clicked.                                                                                                                    |
+| `sortIndicators`                  | `SortIndicatorsProps`                            | —         | Maps each `fieldKey` to its current sort direction. A key present in this map causes the corresponding header to render a directional arrow and expose sort controls to assistive technology. |
+| `alternatingRows`                 | `boolean`                                        | —         | Applies an alternate background colour to every odd-indexed row.                                                                                                                              |
+| `emptyView`                       | `ErrorDisplayAttributes`                         | —         | Overrides the title and description shown in the built-in empty state. Ignored when `renderCustomEmptyView` is provided.                                                                      |
+| `renderCustomEmptyView`           | `(() => ReactNode)`                              | —         | Renders a fully custom empty state in place of the default `ErrorDisplay`.                                                                                                                    |
+
+## Props — `RowProps`
+
+| Prop    | Type               | Default | Description                                                                                   |
+| ------- | ------------------ | ------- | --------------------------------------------------------------------------------------------- |
+| `id` \* | `string \| number` | —       | Unique identifier for the row; used as the key and referenced by `selectedIds`/`disabledIds`. |
+
+## Rules
+
+-   Each row object must have a unique `id: string` field.
+-   `selectedIds` and `disabledIds` are arrays of row `id` strings — manage them in external state.
+-   `onSelect(rowId, isSelected)` fires per row; toggle the id into/out of your `selectedIds` array.
+-   `onSelectAll(isAllSelected)` fires when the header checkbox is clicked; `isAllSelected` is `true` when the action should clear all selections (the parameter name is inverted — see example).
+-   For sortable columns, set `clickable: true` on the header and handle `onHeaderClick(fieldKey)`.
+-   Custom cell rendering: set a row field to a `ReactNode` or a render function `(row, renderProps) => ReactNode`.
+
+## Anti-patterns
+
+-   Do not derive `selectedIds` from row data alone without external state — the table is uncontrolled for selection without it.
+-   Do not omit `id` on row objects — selection and disabled logic will break silently.
+-   Do not add `clickable: true` to a header without wiring `onHeaderClick` — clicks will silently do nothing.

package/skills/fds-build/resources/components/date-navigator.md

@@ -0,0 +1,25 @@
+# DateNavigator
+
+Import: `import { DateNavigator } from "@lifesg/react-design-system/date-navigator"`
+
+## Props
+
+| Prop                     | Type                              | Default       | Description                                                                                                                                                                        |
+| ------------------------ | --------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`                     | `string`                          | —             | —                                                                                                                                                                                  |
+| `className`              | `string`                          | —             | —                                                                                                                                                                                  |
+| `selectedDate` \*        | `string`                          | —             | The currently displayed date in `YYYY-MM-DD` format.                                                                                                                               |
+| `minDate`                | `string`                          | —             | The earliest selectable date in `YYYY-MM-DD` format. The left arrow is disabled when `selectedDate` reaches this boundary.                                                         |
+| `maxDate`                | `string`                          | —             | The latest selectable date in `YYYY-MM-DD` format. The right arrow is disabled when `selectedDate` reaches this boundary.                                                          |
+| `loading`                | `boolean`                         | —             | When `true`, both navigation arrows and the calendar trigger are disabled.                                                                                                         |
+| `showDateAsShortForm`    | `boolean`                         | —             | When `true`, formats the displayed date using abbreviated month and day names (e.g. `"3 Jul 2025, Wed"` instead of `"3 July 2025, Wednesday"`).                                    |
+| `showCurrentDateAsToday` | `boolean`                         | —             | When `true`, replaces the day-of-week label with `"Today"` if `selectedDate` matches the current calendar date.                                                                    |
+| `view`                   | `"day" \| "week"`                 | "day"         | Controls whether navigation steps by a single day or by a full week. In `"week"` mode the label shows the Sunday–Saturday range that contains `selectedDate`.                      |
+| `onLeftArrowClick` \*    | `(currentDate: string) => void`   | —             | Called with the current `selectedDate` value when the left arrow is clicked.                                                                                                       |
+| `onRightArrowClick` \*   | `(currentDate: string) => void`   | —             | Called with the current `selectedDate` value when the right arrow is clicked.                                                                                                      |
+| `onCalendarDateSelect`   | `((currentDate: string) => void)` | —             | Called with the chosen date string when the user selects a date from the calendar dropdown. When omitted the date label is non-interactive and the calendar dropdown is not shown. |
+| `dropdownRootNode`       | `RefObject<HTMLElement>`          | document.body | The root element that contains the dropdown element.                                                                                                                               |
+
+## Rules
+
+-   Only override `dropdownRootNode` if you need the dropdown to share a stacking context with a scroll container — may cause z-index issues.

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

@@ -0,0 +1,23 @@
+# Divider
+
+Import: `import { Divider } from "@lifesg/react-design-system/divider"`
+
+## Props — `DividerProps`
+
+| Prop         | Type                   | Default          | Description                                                                                                                                                                                                                                                      |
+| ------------ | ---------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `thickness`  | `number`               | 1                | Thickness of the line in pixels.                                                                                                                                                                                                                                 |
+| `lineStyle`  | `DividerLineStyleType` | "solid"          | Visual style of the line.                                                                                                                                                                                                                                        |
+| `layoutType` | `DividerLayoutType`    | "flex"           | Controls how the divider is rendered relative to its parent layout. Use `"flex"` when the divider is a direct child of a flex container. Use `"grid"` to wrap the line in a `ColDiv`, enabling responsive column-span control via the `xxsCols`–`xxlCols` props. |
+| `color`      | `string`               | Colour["border"] | Color of the line. Accepts a design-system colour token or any valid CSS color value.                                                                                                                                                                            |
+| `xxlCols`    | `ColSpan`              | —                | Column span at the `xxl` breakpoint.                                                                                                                                                                                                                             |
+| `xlCols`     | `ColSpan`              | —                | Column span at the `xl` breakpoint.                                                                                                                                                                                                                              |
+| `lgCols`     | `ColSpan`              | —                | Column span at the `lg` breakpoint.                                                                                                                                                                                                                              |
+| `mdCols`     | `ColSpan`              | —                | Column span at the `md` breakpoint.                                                                                                                                                                                                                              |
+| `smCols`     | `ColSpan`              | —                | Column span at the `sm` breakpoint.                                                                                                                                                                                                                              |
+| `xsCols`     | `ColSpan`              | —                | Column span at the `xs` breakpoint.                                                                                                                                                                                                                              |
+| `xxsCols`    | `ColSpan`              | —                | Column span at the `xxs` (smallest) breakpoint. Acts as the base value. All larger breakpoints fall back to this when their own prop is not set.                                                                                                                 |
+
+## Rules
+
+-   `mobileCols`, `tabletCols`, `desktopCols` follow the same semantics as `Layout.ColDiv` — see ColDiv docs for details.

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

@@ -0,0 +1,78 @@
+# Drawer
+
+Import: `import { Drawer } from "@lifesg/react-design-system/drawer"`
+
+## When to use
+
+Use to show supplementary content or actions without navigating away from the current page — for example, filter panels or detail views.
+
+Do not use for:
+
+-   Primary forms that require focused attention
+-   Flows that need the full viewport
+
+## Usage
+
+```tsx
+import { useState } from "react";
+import { Drawer } from "@lifesg/react-design-system/drawer";
+import { Button } from "@lifesg/react-design-system/button";
+import { Typography } from "@lifesg/react-design-system/typography";
+
+const FilterDrawer = () => {
+    const [show, setShow] = useState(false);
+
+    const handleClose = () => setShow(false);
+
+    return (
+        <>
+            <Button onClick={() => setShow(true)}>Open filters</Button>
+
+            <Drawer
+                show={show}
+                heading="Filter options"
+                onClose={handleClose}
+                onOverlayClick={handleClose}
+            >
+                <div style={{ padding: "1.5rem" }}>
+                    <Typography.HeadingMD style={{ marginBottom: "0.75rem" }}>
+                        Category
+                    </Typography.HeadingMD>
+                    <Typography.BodyBL style={{ marginBottom: "2rem" }}>
+                        Filter content goes here.
+                    </Typography.BodyBL>
+                    <Button styleType="secondary" onClick={handleClose}>
+                        Close
+                    </Button>
+                </div>
+            </Drawer>
+        </>
+    );
+};
+```
+
+## Props
+
+| Prop                 | Type              | Default | Description                                                                                                                                                                    |
+| -------------------- | ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `children`           | `React.ReactNode` | —       | —                                                                                                                                                                              |
+| `className`          | `string`          | —       | —                                                                                                                                                                              |
+| `id`                 | `string`          | —       | —                                                                                                                                                                              |
+| `heading`            | `string`          | —       | Text rendered as the drawer title and used as the accessible label for the dialog.                                                                                             |
+| `show`               | `boolean`         | —       | Controls whether the drawer is visible.                                                                                                                                        |
+| `onClose`            | `(() => void)`    | —       | Called when the user requests to close the drawer via the close button or the Escape key.                                                                                      |
+| `onOverlayClick`     | `(() => void)`    | —       | Called when the user clicks the background overlay.                                                                                                                            |
+| `customCallToAction` | `React.ReactNode` | —       | Optional element rendered in the header, e.g. a link or button. Sits beside the title on wider drawers, and wraps onto its own line below the title once the drawer is narrow. |
+
+## Rules
+
+-   Always provide `onClose` so users can dismiss the panel via the close button.
+-   Provide `onOverlayClick` to allow dismissal by clicking outside the panel; set it to the same handler as `onClose` unless the overlay should not close the panel.
+-   Use `heading` to give the drawer a descriptive title for the user and for screen readers.
+-   The drawer slides in from the right edge of the viewport.
+-   Content scrolls independently within the panel when it exceeds the panel height.
+
+## Anti-patterns
+
+-   Do not use the Drawer for full forms — use a dedicated page or ModalV2 instead.
+-   Do not omit `onClose` — users must have a way to dismiss the panel.

package/skills/fds-build/resources/components/error-display.md

@@ -0,0 +1,137 @@
+# ErrorDisplay
+
+Import: `import { ErrorDisplay } from "@lifesg/react-design-system/error-display"`
+
+## When to use
+
+Use for full-page or full-section states where the primary content cannot be shown — HTTP errors, empty results, session states, and system messages. It handles illustration, title, description, and action button as a unit.
+
+Do not build custom error pages with raw Typography + Button — always use `ErrorDisplay` so illustrations and copy stay consistent across products.
+
+## Variants
+
+| `type`                          | When to use                                                      |
+| ------------------------------- | ---------------------------------------------------------------- |
+| `"no-item-found"`               | Search or filter returned no results                             |
+| `"404"`                         | Page not found                                                   |
+| `"403"`                         | Access denied / permission error                                 |
+| `"500"`                         | Internal server error                                            |
+| `"400"`                         | Bad request                                                      |
+| `"408"`                         | Request timeout                                                  |
+| `"502"`                         | Bad gateway                                                      |
+| `"503"`                         | Service unavailable                                              |
+| `"504"`                         | Gateway timeout                                                  |
+| `"maintenance"`                 | Planned downtime — requires `additionalProps.dateString`         |
+| `"inactivity"`                  | Session timeout warning — requires `additionalProps.secondsLeft` |
+| `"logout"`                      | User has been logged out                                         |
+| `"warning"`                     | General warning state                                            |
+| `"confirmation"`                | Action confirmed (e.g. submission complete)                      |
+| `"link-error"`                  | Broken or expired link                                           |
+| `"insufficient-credits"`        | User lacks credits to proceed                                    |
+| `"payment-unsuccessful"`        | Payment failed                                                   |
+| `"transfer-unsuccessful"`       | Transfer failed                                                  |
+| `"unsupported-browser"`         | Browser not supported                                            |
+| `"partially-supported-browser"` | Browser partially supported                                      |
+
+## Usage
+
+```tsx
+import { ErrorDisplay } from "@lifesg/react-design-system/error-display";
+
+{
+    /* No search results */
+}
+<ErrorDisplay
+    type="no-item-found"
+    title="No results found"
+    description="Try adjusting your search or filters."
+    actionButton={{ children: "Clear filters", onClick: handleClear }}
+/>;
+
+{
+    /* Page not found */
+}
+<ErrorDisplay type="404" />;
+
+{
+    /* Maintenance with scheduled date */
+}
+<ErrorDisplay
+    type="maintenance"
+    additionalProps={{ dateString: "1 Jan 2025, 8:00am to 10:00am" }}
+/>;
+
+{
+    /* Session inactivity warning */
+}
+<ErrorDisplay
+    type="inactivity"
+    additionalProps={{ secondsLeft: 60, reminderInterval: 30 }}
+/>;
+```
+
+## MaintenanceAdditionalAttributes
+
+| Prop            | Type     | Default | Description                            |
+| --------------- | -------- | ------- | -------------------------------------- |
+| `dateString` \* | `string` | —       | Date display for the maintenance error |
+
+## InactivityAdditionalAttributes
+
+| Prop             | Type     | Default | Description                                          |
+| ---------------- | -------- | ------- | ---------------------------------------------------- |
+| `secondsLeft` \* | `number` | —       | Time remaining in seconds for the inactivity display |
+
+## Props — `MaintenanceAdditionalAttributes`
+
+| Prop            | Type     | Default | Description                                                      |
+| --------------- | -------- | ------- | ---------------------------------------------------------------- |
+| `dateString` \* | `string` | —       | Date string rendered inside the default maintenance description. |
+
+## Props — `InactivityAdditionalAttributes`
+
+| Prop               | Type     | Default | Description                                                                       |
+| ------------------ | -------- | ------- | --------------------------------------------------------------------------------- |
+| `secondsLeft` \*   | `number` | —       | Remaining seconds before the session expires, used to render the countdown timer. |
+| `reminderInterval` | `number` | —       | Interval (in seconds) for announcing remaining time via screen readers.           |
+
+## Props — `ErrorDisplayAttributes`
+
+| Prop                 | Type                                                                   | Default | Description                                                                                                                                                                         |
+| -------------------- | ---------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `img`                | `React.ImgHTMLAttributes<HTMLImageElement>`                            | —       | Overrides the default illustration for the selected `type`.                                                                                                                         |
+| `title`              | `string \| JSX.Element`                                                | —       | Overrides the default title for the selected `type`.                                                                                                                                |
+| `description`        | `string \| JSX.Element`                                                | —       | Overrides the default description for the selected `type`. When `additionalProps` is also provided for `"maintenance"` or `"inactivity"` types, `additionalProps` takes precedence. |
+| `actionButton`       | `ButtonProps`                                                          | —       | Action button rendered below the description. Defaults to a "Proceed" label when `children` is omitted.                                                                             |
+| `additionalProps`    | `\| MaintenanceAdditionalAttributes \| InactivityAdditionalAttributes` | —       | Type-specific attributes that inject dynamic content into the default description.                                                                                                  |
+| `imageOnly`          | `boolean`                                                              | false   | Renders only the illustration, hiding the title, description, and action button.                                                                                                    |
+| `illustrationScheme` | `ThemeType`                                                            | —       | Selects the illustration resource scheme to use.                                                                                                                                    |
+
+## Props — `ErrorDisplayProps`
+
+| Prop                 | Type                                                                   | Default | Description                                                                                                                                                                         |
+| -------------------- | ---------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type` \*            | `ErrorDisplayType`                                                     | —       | Determines the default illustration assets and copy to display.                                                                                                                     |
+| `img`                | `React.ImgHTMLAttributes<HTMLImageElement>`                            | —       | Overrides the default illustration for the selected `type`.                                                                                                                         |
+| `title`              | `string \| JSX.Element`                                                | —       | Overrides the default title for the selected `type`.                                                                                                                                |
+| `description`        | `string \| JSX.Element`                                                | —       | Overrides the default description for the selected `type`. When `additionalProps` is also provided for `"maintenance"` or `"inactivity"` types, `additionalProps` takes precedence. |
+| `actionButton`       | `ButtonProps`                                                          | —       | Action button rendered below the description. Defaults to a "Proceed" label when `children` is omitted.                                                                             |
+| `additionalProps`    | `\| MaintenanceAdditionalAttributes \| InactivityAdditionalAttributes` | —       | Type-specific attributes that inject dynamic content into the default description.                                                                                                  |
+| `imageOnly`          | `boolean`                                                              | false   | Renders only the illustration, hiding the title, description, and action button.                                                                                                    |
+| `illustrationScheme` | `ThemeType`                                                            | —       | Selects the illustration resource scheme to use.                                                                                                                                    |
+
+## Rules
+
+-   Always use `ErrorDisplay` for error/empty states — never build custom error pages with raw components.
+-   `type` is required — it determines the default illustration, title, and description.
+-   Override `title` and `description` only when the defaults don't fit your context.
+-   `actionButton` accepts standard `ButtonProps` — label and `onClick` are the common fields.
+-   `"maintenance"` requires `additionalProps.dateString` to render the scheduled date in the description.
+-   `"inactivity"` requires `additionalProps.secondsLeft` for the countdown display.
+-   For listing pages use `type="no-item-found"` — it has the correct "empty results" illustration.
+
+## Anti-patterns
+
+-   Do not use `imageOnly` unless rendering inside a constrained space where text would overflow.
+-   Do not hardcode error page titles/descriptions that duplicate what `ErrorDisplay` already provides by default.
+-   Do not use `type="warning"` as a generic placeholder — it implies a system-level warning, not a validation message (use `Alert` for that).

package/skills/fds-build/resources/components/feedback-rating.md

@@ -0,0 +1,61 @@
+# FeedbackRating
+
+Import: `import { FeedbackRating } from "@lifesg/react-design-system/feedback-rating"`
+
+## When to use
+
+Use at the end of a flow or session to collect a star rating and an optional submission action from the user.
+
+## Usage
+
+### Complete controlled pattern
+
+```tsx
+import { useState } from "react";
+import { FeedbackRating } from "@lifesg/react-design-system/feedback-rating";
+
+const RatingWidget = () => {
+    // Track rating separately — onSubmit does NOT receive it
+    const [rating, setRating] = useState(0);
+
+    const handleSubmit = () => {
+        // Read from state, not from onSubmit arguments (there are none)
+        submitFeedback({ stars: rating });
+    };
+
+    return (
+        <FeedbackRating
+            rating={rating}
+            onRatingChange={(value) => setRating(value)}
+            onSubmit={handleSubmit}
+            description="How was your experience?"
+            buttonLabel="Send feedback"
+        />
+    );
+};
+```
+
+**Key gotcha:** `onSubmit` has the signature `() => void` — it carries no payload. The rating value is only available through the `rating` state you control via `onRatingChange`.
+
+## Props
+
+| Prop                | Type                      | Default                | Description                                                                                                                                                               |
+| ------------------- | ------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `imgSrc`            | `string`                  | —                      | URL of the banner image displayed above the star rating. Falls back to the default Life SG feedback banner when omitted. Hidden automatically if the image fails to load. |
+| `description`       | `string`                  | "Rate your experience" | Heading text displayed above the star rating.                                                                                                                             |
+| `buttonLabel`       | `string`                  | "Submit"               | Label for the submit button.                                                                                                                                              |
+| `className`         | `string`                  | —                      | —                                                                                                                                                                         |
+| `id`                | `string`                  | —                      | —                                                                                                                                                                         |
+| `rating` \*         | `number`                  | —                      | The currently selected star rating (1–5).                                                                                                                                 |
+| `onRatingChange` \* | `(value: number) => void` | —                      | Called when the user selects a star.                                                                                                                                      |
+| `onSubmit` \*       | `() => void`              | —                      | Called when the user clicks the submit button.                                                                                                                            |
+
+## Rules
+
+-   All three props — `rating`, `onRatingChange`, `onSubmit` — are required.
+-   `onSubmit` does **not** receive the rating value. Track the rating separately via `onRatingChange` state and read it inside `onSubmit`.
+-   `rating` must be controlled state; the component does not manage selection internally.
+
+## Anti-patterns
+
+-   Do not try to read the rating from inside `onSubmit`'s arguments — it receives none. Always use the state value set by `onRatingChange`.

package/skills/fds-build/resources/components/file-download.md

@@ -0,0 +1,54 @@
+# FileDownload
+
+Import: `import { FileDownload } from "@lifesg/react-design-system/file-download"`
+
+## Sub-components
+
+-   `FileItemProps` — shape of each item in `fileItems`
+
+## FileItemProps
+
+| Prop                    | Type                        | Default | Description                                   |
+| ----------------------- | --------------------------- | ------- | --------------------------------------------- |
+| `id` \*                 | `string`                    | —       | The unique identifier of the file             |
+| `name` \*               | `string`                    | —       | The name of the file                          |
+| `mimeType` \*           | `string`                    | —       | The MIME type of the file                     |
+| `filePath` \*           | `string`                    | —       | The remote path of the file                   |
+| `size`                  | `number`                    | —       | The size of the file in bytes                 |
+| `errorMessage`          | `string \| React.ReactNode` | —       | Custom error message when file download fails |
+| `thumbnailImageDataUrl` | `string`                    | —       | The thumbnail of the file                     |
+| `truncateText`          | `boolean`                   | `true`  | Indicates if text should be truncated         |
+| `ready`                 | `boolean`                   | `true`  | Indicates if the file is ready for download   |
+
+## Props — `FileItemDownloadProps`
+
+| Prop                    | Type                        | Default       | Description                                                                                                                           |
+| ----------------------- | --------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `id` \*                 | `string`                    | —             | —                                                                                                                                     |
+| `name` \*               | `string`                    | —             | The display name of the file.                                                                                                         |
+| `mimeType` \*           | `string`                    | —             | The MIME type of the file (e.g. `"application/pdf"`).                                                                                 |
+| `size`                  | `number`                    | —             | The size of the file in bytes. Displayed as formatted text when provided.                                                             |
+| `filePath` \*           | `string`                    | —             | The remote path or URL used to fetch the file for download.                                                                           |
+| `errorMessage`          | `string \| React.ReactNode` | —             | Error message shown on the file item to indicate a download failure. Accepts a plain string or a React node for richer error display. |
+| `thumbnailImageDataUrl` | `string`                    | —             | URL or data URL for a thumbnail image shown alongside the file entry.                                                                 |
+| `truncateText`          | `boolean`                   | true          | Truncates long file names with an ellipsis when `true`.                                                                               |
+| `ready`                 | `boolean`                   | true          | Indicates the file is available and ready to be downloaded.                                                                           |
+| `clickLabel`            | `string`                    | the file name | Name for the card, used when `FileDownload` is given an `onClick`.                                                                    |
+
+## Props — `FileDownloadProps`
+
+| Prop            | Type                                                     | Default    | Description                                                                                                                                                                                                                                                                             |
+| --------------- | -------------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title`         | `string \| JSX.Element`                                  | —          | Optional heading rendered above the file list. Accepts a plain string or a JSX element for rich content.                                                                                                                                                                                |
+| `description`   | `string \| JSX.Element`                                  | —          | Optional text rendered beneath the title. Accepts a plain string or a JSX element for rich content.                                                                                                                                                                                     |
+| `fileItems` \*  | `FileItemDownloadProps[]`                                | —          | The list of file items to display. When empty, no file cards are rendered.                                                                                                                                                                                                              |
+| `styleType`     | `FileDownloadStyle`                                      | "bordered" | Controls whether the component is wrapped in a dashed border.                                                                                                                                                                                                                           |
+| `className`     | `string`                                                 | —          | —                                                                                                                                                                                                                                                                                       |
+| `id`            | `string`                                                 | —          | —                                                                                                                                                                                                                                                                                       |
+| `onDownload` \* | `(file: FileItemDownloadProps) => void \| Promise<void>` | —          | Called when the user triggers a download for an individual file item. May return a `Promise` to handle async download logic; the component awaits resolution. If the callback throws or the promise rejects, the item is marked as failed and the error UI is shown for that file card. |
+| `onClick`       | `((file: FileItemDownloadProps) => void)`                | —          | Called when a file card itself is activated, as opposed to its download button. When omitted, activating the card triggers `onDownload` instead.                                                                                                                                        |
+
+## Rules
+
+-   `fileItems` and `onDownload` are required.
+-   On `FileItemProps`: `id`, `name`, `mimeType`, and `filePath` are required.