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

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

@@ -0,0 +1,123 @@
+# Timetable
+
+Import: `import { Timetable } from "@lifesg/react-design-system/timetable"`
+
+## TimeTableRowData
+
+| Prop                    | Type                                                       | Default   | Description                                               |
+| ----------------------- | ---------------------------------------------------------- | --------- | --------------------------------------------------------- |
+| `name` \*               | `string`                                                   | —         | Row header name                                           |
+| `rowCells` \*           | `TimeTableRowCellData[]`                                   | —         | Array of row cells; sorted by start time automatically    |
+| `id`                    | `string`                                                   | —         | Row identifier; passed to `onRowNameClick`                |
+| `subtitle`              | `string \| JSX.Element`                                    | —         | Row header subtitle                                       |
+| `rowHeaderPopover`      | `TimeTablePopoverProps`                                    | —         | Custom popover for the row header                         |
+| `outOfRangeCellPopover` | `TimeTablePopoverProps`                                    | —         | Custom popover for auto-filled blocked cells              |
+| `rowMinTime`            | `string`                                                   | `minTime` | Row start time; blocked cells are auto-filled before this |
+| `rowMaxTime`            | `string`                                                   | `maxTime` | Row end time; blocked cells are auto-filled after this    |
+| `onRowNameClick`        | `(rowData: TimeTableRowData, e: React.MouseEvent) => void` | —         | Called when the row header name is clicked                |
+
+## TimeTableRowCellData
+
+| Prop                  | Type                                                            | Default | Description                                                        |
+| --------------------- | --------------------------------------------------------------- | ------- | ------------------------------------------------------------------ |
+| `startTime` \*        | `string`                                                        | —       | Cell start time in `HH:mm` (duration must be a multiple of 15 min) |
+| `endTime` \*          | `string`                                                        | —       | Cell end time in `HH:mm` (duration must be a multiple of 15 min)   |
+| `id`                  | `string`                                                        | —       | Cell identifier; passed to `onClick`                               |
+| `status`              | `"filled" \| "blocked" \| "default" \| "pending" \| "disabled"` | —       | Cell status, determines rendering style                            |
+| `title`               | `string`                                                        | —       | Title shown for this cell                                          |
+| `subtitle`            | `string`                                                        | —       | Subtitle shown for this cell                                       |
+| `customPopover`       | `TimeTablePopoverProps`                                         | —       | Custom popover for the cell                                        |
+| `cellStyleAttributes` | `TimeTableCellStyleAttributes`                                  | —       | Custom style attributes; falls back to default row bar colors      |
+| `onClick`             | `(data: TimeTableRowCellData, e: React.MouseEvent) => void`     | —       | Called when the cell is clicked                                    |
+
+## TimeTableCellStyleAttributes
+
+| Prop                      | Type                                           | Description                                                                      |
+| ------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------- |
+| `backgroundColor`         | `string \| (props: ThemeStyleProps) => string` | Main background color                                                            |
+| `altBackgroundColor`      | `string \| (props: ThemeStyleProps) => string` | Alternate background color for striped displays                                  |
+| `hoverBackgroundColor`    | `string \| (props: ThemeStyleProps) => string` | Background on hover                                                              |
+| `altHoverBackgroundColor` | `string \| (props: ThemeStyleProps) => string` | Alternate background on hover                                                    |
+| `styleType`               | `"default" \| "solid" \| "stripes"`            | Display style; defaults to cell type (blocked/pending = striped, others = solid) |
+
+## Props — `TimeTableCellStyleAttributes`
+
+| Prop                      | Type                     | Default   | Description                                                                |
+| ------------------------- | ------------------------ | --------- | -------------------------------------------------------------------------- |
+| `backgroundColor`         | `string`                 | —         | Main background color for the cell.                                        |
+| `altBackgroundColor`      | `string`                 | —         | Alternate background color used for the second stripe in striped patterns. |
+| `hoverBackgroundColor`    | `string`                 | —         | Background color applied on hover.                                         |
+| `altHoverBackgroundColor` | `string`                 | —         | Alternate background color applied on hover for striped patterns.          |
+| `styleType`               | `TimeTableCellStyleType` | "default" | Cell background pattern.                                                   |
+
+## Props — `TimeTableRef`
+
+| Prop             | Type         | Default | Description                                                                                   |
+| ---------------- | ------------ | ------- | --------------------------------------------------------------------------------------------- |
+| `resetScroll` \* | `() => void` | —       | Scrolls the timetable back to `initialScrollTime`. No-op when `initialScrollTime` is not set. |
+
+## Props — `TimeTableRowData`
+
+| Prop                    | Type                                                            | Default | Description                                                                                                     |
+| ----------------------- | --------------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------- |
+| `id`                    | `string`                                                        | —       | Unique identifier for the row.                                                                                  |
+| `name` \*               | `string`                                                        | —       | Display name shown in the row header.                                                                           |
+| `rowCells` \*           | `TimeTableRowCellData[]`                                        | —       | Cells occupying time slots within this row.                                                                     |
+| `subtitle`              | `string \| JSX.Element`                                         | —       | Secondary text or element rendered beneath the row name in the header.                                          |
+| `rowHeaderPopover`      | `TimeTablePopoverProps`                                         | —       | Popover attached to the row header label.                                                                       |
+| `outOfRangeCellPopover` | `TimeTablePopoverProps`                                         | —       | Popover shown when the user interacts with cells outside the active time range.                                 |
+| `rowMinTime`            | `string`                                                        | —       | Earliest time this row is active, in `HH:mm` format. Time slots before this value are rendered as out-of-range. |
+| `rowMaxTime`            | `string`                                                        | —       | Latest time this row is active, in `HH:mm` format. Time slots after this value are rendered as out-of-range.    |
+| `onRowNameClick`        | `\| ((rowData: TimeTableRowData, e: React.MouseEvent) => void)` | —       | Called when the row header name is clicked.                                                                     |
+
+## Props — `TimeTablePopoverProps`
+
+| Prop         | Type                                               | Default | Description                                                                                                    |
+| ------------ | -------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------- |
+| `trigger` \* | `PopoverTriggerType`                               | —       | Interaction that opens the popover                                                                             |
+| `content` \* | `string \| JSX.Element \| (() => React.ReactNode)` | —       | Content rendered inside the popover.                                                                           |
+| `delay`      | `\| { open?: number; close?: number }`             | —       | Open and close delays in milliseconds. Useful for hover popovers to avoid flickering on quick mouse movements. |
+| `offset`     | `number`                                           | —       | Distance in pixels between the popover and its trigger element.                                                |
+
+## Props — `TimeTableProps`
+
+| Prop                     | Type                              | Default | Description                                                                                                                             |
+| ------------------------ | --------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`                     | `string`                          | —       | —                                                                                                                                       |
+| `className`              | `string`                          | —       | —                                                                                                                                       |
+| `date` \*                | `string`                          | —       | The date currently displayed.                                                                                                           |
+| `emptyContentMessage`    | `string`                          | —       | Text shown in the empty state when `rowData` is empty or `totalRecords` is `0`.                                                         |
+| `rowData` \*             | `TimeTableRowData[]`              | —       | Rows to render in the timetable grid.                                                                                                   |
+| `loading`                | `boolean`                         | —       | When `true`, replaces row content with a loading spinner.                                                                               |
+| `minTime`                | `string`                          | "00:00" | Earliest hour column displayed, in `HH:mm` format. Rounded to the nearest full hour internally.                                         |
+| `maxTime`                | `string`                          | "23:00" | Latest hour column displayed, in `HH:mm` format. Rounded up to the nearest full hour internally.                                        |
+| `initialScrollTime`      | `string`                          | —       | Time to scroll to on mount in `HH:mm` format (e.g. `"09:00"`).                                                                          |
+| `minDate`                | `string`                          | —       | Earliest date the user can navigate to in the date picker.                                                                              |
+| `maxDate`                | `string`                          | —       | Latest date the user can navigate to in the date picker                                                                                 |
+| `totalRecords`           | `number`                          | —       | Total number of records across all pages. When `0`, the empty state is shown regardless of `rowData`.                                   |
+| `showCurrentDateAsToday` | `boolean`                         | —       | When `true`, the date header displays `"Today"` instead of the formatted date string when `date` matches the current calendar day.      |
+| `showDateAsShortForm`    | `boolean`                         | —       | When `true`, the date header uses an abbreviated date format.                                                                           |
+| `roundInitialScrollTime` | `boolean`                         | true    | When `true`, `initialScrollTime` is snapped to the nearest time interval (e.g. `"06:30"` snaps to `"06:00"` with a 60-minute interval). |
+| `onRefresh`              | `(() => void)`                    | —       | Called when the user clicks the refresh button in the header.                                                                           |
+| `onPage`                 | `(() => void)`                    | —       | Called when the timetable needs to load the next page of rows.                                                                          |
+| `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 selects a date from the calendar picker.                                                                           |
+
+## Props — `TimeTableRowCellData`
+
+| Prop                  | Type                                                             | Default | Description                                             |
+| --------------------- | ---------------------------------------------------------------- | ------- | ------------------------------------------------------- |
+| `id`                  | `string`                                                         | —       | Unique identifier for the cell.                         |
+| `startTime` \*        | `string`                                                         | —       | Start time of the cell in `HH:mm` format.               |
+| `endTime` \*          | `string`                                                         | —       | End time of the cell in `HH:mm` format.                 |
+| `status` \*           | `TimeTableCellType`                                              | —       | Visual and interaction state of the cell.               |
+| `title`               | `string`                                                         | —       | Primary label rendered inside the cell.                 |
+| `subtitle`            | `string`                                                         | —       | Secondary label rendered below `title` inside the cell. |
+| `customPopover`       | `TimeTablePopoverProps`                                          | —       | Popover shown when the user interacts with this cell.   |
+| `cellStyleAttributes` | `TimeTableCellStyleAttributes`                                   | —       | Color and pattern overrides for this cell.              |
+| `onClick`             | `\| ((data: TimeTableRowCellData, e: React.MouseEvent) => void)` | —       | Called when the user clicks this cell.                  |
+
+## Rules
+
+-   Do not combine `onClick` on a cell with a `trigger="click"` popover on the same cell — they conflict.

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

@@ -0,0 +1,72 @@
+# Toast
+
+Import: `import { Toast } from "@lifesg/react-design-system/toast"`
+
+## When to use
+
+Use for brief, non-blocking feedback on system or user actions — "Changes saved", "Upload complete", "Request failed". Does not replace persistent callouts — use Alert for section-specific notices.
+
+## Sub-components
+
+### ActionButtonProps
+
+| Prop      | Type         | Default | Description                                         |
+| --------- | ------------ | ------- | --------------------------------------------------- |
+| `label`   | `string`     | —       | Label of the action button — required               |
+| `onClick` | `() => void` | —       | Called when the action button is clicked — required |
+
+## Variants
+
+| `type`      | When to use                   |
+| ----------- | ----------------------------- |
+| `"success"` | Action completed successfully |
+| `"error"`   | Action failed or system error |
+| `"warning"` | Completed with caution        |
+| `"info"`    | Neutral status update         |
+
+## Usage
+
+```tsx
+import { Toast } from "@lifesg/react-design-system/toast";
+
+<Toast
+    type="success"
+    label="Changes saved successfully."
+    autoDismiss
+    onDismiss={() => {}}
+/>;
+```
+
+## Props — `ToastActionButtonProps`
+
+| Prop         | Type         | Default | Description                              |
+| ------------ | ------------ | ------- | ---------------------------------------- |
+| `label` \*   | `string`     | —       | The label of the action button           |
+| `onClick` \* | `() => void` | —       | Called when the action button is clicked |
+
+## Props — `ToastProps`
+
+| Prop              | Type                        | Default   | Description                                                                                                                           |
+| ----------------- | --------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `type` \*         | `ToastType`                 | "success" | Visual variant controlling the icon and color treatment.                                                                              |
+| `label` \*        | `string \| React.ReactNode` | —         | Main text content of the toast. When `title` is also provided, rendered as a supporting description using a smaller typography style. |
+| `title`           | `string \| React.ReactNode` | —         | Optional heading displayed above `label`.                                                                                             |
+| `autoDismiss`     | `boolean`                   | —         | When `true`, the toast dismisses itself automatically after `autoDismissTime` milliseconds.                                           |
+| `autoDismissTime` | `number`                    | 4000      | Duration in milliseconds before the toast auto-dismisses. Only takes effect when `autoDismiss` is `true`.                             |
+| `onDismiss`       | `(() => void)`              | —         | Called after the dismissal animation completes.                                                                                       |
+| `fixed`           | `boolean`                   | true      | Pins the toast in a fixed position at the top of the viewport.                                                                        |
+| `actionButton`    | `ToastActionButtonProps`    | —         | Optional action button rendered alongside the toast content.                                                                          |
+
+## Rules
+
+-   `autoDismissTime` only takes effect when `autoDismiss` is `true`.
+-   Use `autoDismiss` for non-critical updates — keep visible for errors that require user action.
+-   Use `actionButton` for recoverable errors (retry, undo).
+-   Use `title` + `label` together when the toast message has a heading and a description.
+-   Do not use Toast for persistent notices — use Alert or NotificationBanner instead.
+
+## Anti-patterns
+
+-   Using Toast for errors that require user action without providing an `actionButton`.
+-   Setting `autoDismiss` on error toasts — errors should remain visible until the user dismisses them.
+-   Replacing Alert with Toast for section-specific inline messages.

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

@@ -0,0 +1,119 @@
+# Toggle
+
+Import: `import { Toggle } from "@lifesg/react-design-system/toggle"`
+
+## When to use
+
+-   Form inputs for boolean choices, single/multi-option selection, and yes/no questions.
+-   Preferred over bare `Checkbox` and `RadioButton` when building form inputs that need a card-style visible label container.
+
+## Variants
+
+| `type`       | When to use                                                  |
+| ------------ | ------------------------------------------------------------ |
+| `"checkbox"` | Multiple options can be selected or deselected independently |
+| `"radio"`    | Exactly one option must be selected — cannot be deselected   |
+| `"yes"`      | Binary yes answer — use with a paired `type="no"` Toggle     |
+| `"no"`       | Binary no answer — use with a paired `type="yes"` Toggle     |
+
+| `styleType`   | When to use                                                  |
+| ------------- | ------------------------------------------------------------ |
+| `"default"`   | Standard bordered card                                       |
+| `"no-border"` | Borderless — for contexts where the border is visually noisy |
+
+| `type`       | Behaviour                            |
+| ------------ | ------------------------------------ |
+| `"checkbox"` | Allows deselection — standard toggle |
+| `"radio"`    | No deselection — radio-style         |
+| `"yes"`      | No deselection — tick indicator      |
+| `"no"`       | No deselection — cross indicator     |
+
+## Usage
+
+```tsx
+import { Toggle } from "@lifesg/react-design-system/toggle";
+import { Form } from "@lifesg/react-design-system/form";
+
+{/* Checkbox group */}
+<Form.Label>Select your preferences</Form.Label>
+<Toggle type="checkbox" indicator checked={emailChecked} onChange={(e) => {}}>
+  Email notifications
+</Toggle>
+<Toggle type="checkbox" indicator checked={smsChecked} onChange={(e) => {}}>
+  SMS notifications
+</Toggle>
+```
+
+## Props — `ToggleProps`
+
+| Prop                    | Type                                                         | Default    | Description                                                                                                                                                                                                                                                             |
+| ----------------------- | ------------------------------------------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type`                  | `ToggleType`                                                 | "checkbox" | Determines selection behavior and the indicator icon style.                                                                                                                                                                                                             |
+| `indicator`             | `boolean`                                                    | —          | Whether to render the selection indicator icon inside the toggle. The icon shape depends on `type`: - `"checkbox"` renders a tick box. - `"radio"` renders a filled circle. - `"yes"` renders a tick. - `"no"` renders a cross.                                         |
+| `checked`               | `boolean`                                                    | —          | Controlled checked state of the toggle.                                                                                                                                                                                                                                 |
+| `styleType`             | `ToggleStyleType`                                            | "default"  | Visual presentation of the toggle container.                                                                                                                                                                                                                            |
+| `children` \*           | `React.ReactNode`                                            | —          | Label content for the toggle.                                                                                                                                                                                                                                           |
+| `childrenMaxLines`      | `\| { mobile?: number; desktop?: number; tablet?: number; }` | —          | Maximum number of visible label lines at each breakpoint. Lines beyond the limit are truncated with an ellipsis. Omit a breakpoint key to leave that viewport unconstrained.                                                                                            |
+| `subLabel`              | `(() => JSX.Element) \| JSX.Element \| string`               | —          | Secondary content rendered below the main label.                                                                                                                                                                                                                        |
+| `disabled`              | `boolean`                                                    | —          | —                                                                                                                                                                                                                                                                       |
+| `error`                 | `boolean`                                                    | —          | Renders the input in an error state.                                                                                                                                                                                                                                    |
+| `className`             | `string`                                                     | —          | —                                                                                                                                                                                                                                                                       |
+| `name`                  | `string`                                                     | —          | —                                                                                                                                                                                                                                                                       |
+| `id`                    | `string`                                                     | —          | —                                                                                                                                                                                                                                                                       |
+| `onChange`              | `\| ((event: React.ChangeEvent<HTMLInputElement>) => void)`  | —          | Called when the toggle selection state changes. When provided, the caller is responsible for reflecting the new value back via `checked`.                                                                                                                               |
+| `compositeSection`      | `ToggleCompositeSectionProps`                                | —          | Optional collapsible body section rendered below the toggle label. The section automatically expands when the toggle becomes selected.                                                                                                                                  |
+| `removable`             | `boolean`                                                    | —          | Renders a "Remove" button alongside the label. Clicking the button calls `onRemove` when the toggle is not disabled.                                                                                                                                                    |
+| `onRemove`              | `(() => void)`                                               | —          | Called when the remove button is clicked and the toggle is not disabled.                                                                                                                                                                                                |
+| `useContentWidth`       | `boolean`                                                    | —          | Constrains the toggle width to its content rather than filling the container.                                                                                                                                                                                           |
+| `focusableWhenDisabled` | `boolean`                                                    | —          | Keeps the toggle keyboard-focusable when `disabled` is `true`. When set alongside `disabled`, the native `disabled` attribute is omitted in favor of `aria-disabled="true"` and `tabIndex={0}`, keeping the element keyboard-reachable. `onChange` is still suppressed. |
+
+## Props — `ToggleCompositeSectionProps`
+
+| Prop              | Type                      | Default | Description                                                                                                                                                                                          |
+| ----------------- | ------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `children` \*     | `React.ReactNode`         | —       | Content rendered inside the composite section body.                                                                                                                                                  |
+| `collapsible`     | `boolean`                 | true    | Whether the section can be collapsed and expanded by the user.                                                                                                                                       |
+| `initialExpanded` | `boolean`                 | false   | Whether the composite section starts in the expanded state. When the toggle becomes selected, the section automatically expands regardless of this value. Only applies when `collapsible` is `true`. |
+| `errors`          | `string[] \| JSX.Element` | —       | Errors shown in an alert banner when the section is collapsed. Pass a `string[]` to render a titled error list, or a `JSX.Element` for a custom error presentation.                                  |
+
+## Rules
+
+-   `children` (main label) is mandatory.
+-   `indicator` is recommended when using `type="yes"` or `type="no"` to show the tick/cross icon.
+-   Always pass `indicator` for `type="checkbox"`, `type="radio"`, `type="yes"`, and `type="no"` — it shows the relevant icon (tick, dot, tick, cross) inside the toggle.
+-   Use `type="radio"` when the option cannot be deselected (e.g. single-select from a list).
+-   Use `compositeSection` to reveal dependent fields when a Toggle is selected — do not conditionally render fields outside the Toggle.
+-   Use `subLabel` for secondary supporting text — do not embed long descriptions in `children`.
+-   Use `childrenMaxLines` to constrain label height in dense list layouts.
+-   Place a `Form.Label` above each toggle group to provide the question or field label.
+
+### Spacing
+
+| Layout                    | Gap                                  |
+| ------------------------- | ------------------------------------ |
+| Stacked (checkbox, radio) | `spacing-8` between each Toggle      |
+| Side by side (yes / no)   | `spacing-16` between the two Toggles |
+
+```tsx
+{/* Stacked — checkbox or radio */}
+<Form.Label>Declaration</Form.Label>
+<ToggleWrapper> {/* margin-bottom: spacing-32 — matches Form field built-in */}
+  <Toggle indicator checked={a} onChange={...}>Option A</Toggle>
+  <div style={{ marginBottom: Spacing["spacing-8"] }} />
+  <Toggle indicator checked={b} onChange={...}>Option B</Toggle>
+</ToggleWrapper>
+
+{/* Side by side — yes / no */}
+<Form.Label>Do you have a disability?</Form.Label>
+<YesNoGroup> {/* display: flex; gap: spacing-16 */}
+  <Toggle type="yes" indicator checked={val === "yes"} onChange={...}>Yes</Toggle>
+  <Toggle type="no"  indicator checked={val === "no"}  onChange={...}>No</Toggle>
+</YesNoGroup>
+```
+
+## Anti-patterns
+
+-   Do not use bare `Checkbox` or `RadioButton` in forms when a labelled card container is needed — use `Toggle` instead.
+-   Do not conditionally render dependent fields outside the Toggle — use `compositeSection`.
+-   Do not use `type="yes"` or `type="no"` without pairing both options together in the UI.
+-   Do not omit `indicator` for any Toggle type — it is required for all variants.

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

@@ -0,0 +1,86 @@
+# Typography
+
+Import: `import { Typography } from "@lifesg/react-design-system/typography"`
+
+## When to use
+
+Use Typography components to render text content — headings, paragraphs, and links. Do not use for parent containers that have text children; use Font tokens instead (see `foundations/typography.md`).
+
+## Sub-components
+
+**Headings:** `Typography.HeadingXXL`, `Typography.HeadingXL`, `Typography.HeadingLG`, `Typography.HeadingMD`, `Typography.HeadingSM`, `Typography.HeadingXS`
+
+**Body:** `Typography.BodyBL`, `Typography.BodyMD`, `Typography.BodySM`, `Typography.BodyXS`
+
+**Links:** `Typography.LinkBL`, `Typography.LinkMD`, `Typography.LinkSM`, `Typography.LinkXS`
+
+## Variants
+
+| Component         | Default element | Usage                                  |
+| ----------------- | --------------- | -------------------------------------- |
+| `HeadingXXL`      | `h1`            | Hero/page-level title                  |
+| `HeadingXL`       | `h2`            | Page title or primary section heading  |
+| `HeadingLG`       | `h3`            | Section heading                        |
+| `HeadingMD`       | `h4`            | Subsection heading                     |
+| `HeadingSM`       | —               | Card heading, secondary heading        |
+| `HeadingXS`       | —               | Small heading                          |
+| `BodyBL`          | —               | Default paragraph text                 |
+| `BodyMD`          | —               | Medium body text                       |
+| `BodySM`          | —               | Helper text                            |
+| `BodyXS`          | —               | Metadata, timestamps                   |
+| `LinkBL/MD/SM/XS` | `<a>`           | Inline links, sized to match body text |
+
+## Usage
+
+```tsx
+import { Typography } from "@lifesg/react-design-system/typography";
+
+<>
+    <Typography.HeadingXL>Page title</Typography.HeadingXL>
+    <Typography.BodyBL paragraph>
+        Supporting body text for the section. Use{" "}
+        <Typography.LinkMD href="/learn-more">
+            link components
+        </Typography.LinkMD>{" "}
+        for inline anchors.
+    </Typography.BodyBL>
+</>;
+```
+
+## Props — `TypographyLinkProps`
+
+| Prop             | Type                       | Default     | Description                                                                                                   |
+| ---------------- | -------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------- |
+| `weight`         | `TypographyWeight`         | "regular"   | Font weight of the link text.                                                                                 |
+| `external`       | `boolean`                  | —           | Appends an external-link icon after the link text to signal that the destination is outside the current site. |
+| `underlineStyle` | `TypographyUnderlineStyle` | "underline" | Text-decoration style for the link.                                                                           |
+
+## Props — `TypographyProps`
+
+| Prop        | Type               | Default   | Description                                                                                                         |
+| ----------- | ------------------ | --------- | ------------------------------------------------------------------------------------------------------------------- |
+| `weight`    | `TypographyWeight` | "regular" | Font weight of the rendered text.                                                                                   |
+| `inline`    | `boolean`          | —         | Renders the element as an inline `span`. When `true`, the `as` prop is ignored and `maxLines` clamping is disabled. |
+| `paragraph` | `boolean`          | —         | Adds a bottom margin to separate the element from following content.                                                |
+| `maxLines`  | `number`           | —         | Clamps visible text to the given number of lines, truncating the remainder.                                         |
+| `as`        | `T`                | —         | Overrides the rendered HTML element, e.g. `"h2"`.                                                                   |
+
+## Rules
+
+-   Default HTML elements: `HeadingXXL` → `h1`, `HeadingXL` → `h2`, `HeadingLG` → `h3`, `HeadingMD` → `h4`.
+-   Text color is not set by the component — apply via `styled()` using Colour tokens.
+-   Do not pass `color` as a prop — `TypographyProps` extends `HTMLAttributes` and forwards the value to the DOM, triggering a React warning.
+-   Do not use Typography for parent containers — use Font tokens instead.
+-   Heading components render default HTML elements — use the `as` prop when visual size and reading order don't match.
+-   Heading levels must be sequential (h1 → h2 → h3) — never skip levels.
+-   Apply text color via `styled()` using Colour tokens — never pass `color` as a prop.
+-   Use the `weight` prop to adjust emphasis, not opacity.
+-   Links are underlined by default — use `underlineStyle="none"` only when context makes the link obvious.
+-   Always use the `external` prop for links that navigate outside the domain.
+
+## Anti-patterns
+
+-   Passing `color` directly as a prop — it forwards a Colour object to the DOM and triggers a React warning.
+-   Skipping heading levels for visual sizing — use the `as` prop instead.
+-   Using `<h1>` raw HTML inside a Typography component instead of `as="h1"`.
+-   Using Typography on a container element to inherit font styles — use Font tokens.

package/skills/fds-build/resources/components/uneditable-section.md

@@ -0,0 +1,84 @@
+# UneditableSection
+
+Import: `import { UneditableSection } from "@lifesg/react-design-system/uneditable-section"`
+
+## When to use
+
+-   Displaying read-only label/value pairs on summary or review screens.
+-   Showing retrieved or pre-filled data the user cannot edit.
+
+## Sub-components
+
+-   `UneditableSection.ItemSection` — wraps a group of items (extends `HTMLUListElement`)
+-   `UneditableSection.Item` — individual label/value item
+
+## Usage
+
+```tsx
+import { UneditableSection } from "@lifesg/react-design-system/uneditable-section";
+
+<UneditableSection
+    title="Personal details"
+    items={[
+        { label: "Full name", value: "Jane Tan", displayWidth: "half" },
+        { label: "Date of birth", value: "1 Jan 1990", displayWidth: "half" },
+        { label: "Address", value: "123 Example Road, Singapore 123456" },
+    ]}
+/>;
+```
+
+## Props — `UneditableSectionItemProps`
+
+| Prop                | Type                                    | Default | Description                                                                                                                                         |
+| ------------------- | --------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`                | `string`                                | —       | —                                                                                                                                                   |
+| `label` \*          | `string`                                | —       | Field label shown above the item value.                                                                                                             |
+| `value` \*          | `string \| React.ReactNode`             | —       | The display value for the field.                                                                                                                    |
+| `displayWidth`      | `UneditableSectionItemDisplayWidth`     | "full"  | Grid column span for the item within the section layout.                                                                                            |
+| `maskState`         | `UneditableSectionItemMaskState`        | —       | Controls whether the value is masked or unmasked. When undefined, no mask or unmask controls are rendered.                                          |
+| `maskLoadingState`  | `UneditableSectionItemMaskLoadingState` | —       | Async loading state during a mask or unmask action. When undefined, the resolved value is rendered directly.                                        |
+| `disableMaskUnmask` | `boolean`                               | —       | Prevents the user from toggling the mask or unmask control.                                                                                         |
+| `alert`             | `AlertProps`                            | —       | Alert rendered below the item value.                                                                                                                |
+| `maskRange`         | `number[]`                              | —       | Index range `[start, end]` of the characters to mask (inclusive, zero-based). Characters outside this range remain visible.                         |
+| `unmaskRange`       | `number[]`                              | —       | Index range `[start, end]` of the characters to keep visible (inclusive, zero-based). Characters outside this range are masked.                     |
+| `maskRegex`         | `RegExp`                                | —       | Regular expression whose matches are replaced with `maskChar`.                                                                                      |
+| `maskTransformer`   | `((value: string) => string)`           | —       | Custom function that receives the raw value and returns the fully masked string. Takes precedence over `maskRegex`, `maskRange`, and `unmaskRange`. |
+| `maskChar`          | `string`                                | "•"     | Character used to replace each masked character in the displayed value.                                                                             |
+
+## Props — `UneditableSectionItemSectionProps`
+
+| Prop      | Type      | Default | Description                                                    |
+| --------- | --------- | ------- | -------------------------------------------------------------- |
+| `stretch` | `boolean` | —       | Stretches every child item to fill the full width of the grid. |
+
+## Props — `UneditableSectionProps`
+
+| Prop            | Type                                           | Default | Description                                                                                      |
+| --------------- | ---------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------ |
+| `items`         | `UneditableSectionItemProps[]`                 | —       | List of labeled read-only field items to render in a responsive grid.                            |
+| `title`         | `string`                                       | —       | Optional heading rendered above the items grid.                                                  |
+| `description`   | `string`                                       | —       | Optional description rendered below `title` and above the items grid.                            |
+| `topSection`    | `JSX.Element`                                  | —       | Custom content rendered above the items grid, below `description`.                               |
+| `bottomSection` | `JSX.Element`                                  | —       | Custom content rendered below the items grid.                                                    |
+| `children`      | `JSX.Element \| JSX.Element[]`                 | —       | Fully custom section body.                                                                       |
+| `className`     | `string`                                       | —       | —                                                                                                |
+| `id`            | `string`                                       | —       | —                                                                                                |
+| `background`    | `boolean`                                      | true    | Applies a grey background to the section container. Set to `false` for a transparent background. |
+| `stretch`       | `boolean`                                      | —       | Stretches every item to fill the full column width of the grid.                                  |
+| `fullWidth`     | `boolean`                                      | —       | When `true`, allows the section to span the full available width of its parent.                  |
+| `onMask`        | `((item: UneditableSectionItemProps) => void)` | —       | Called when a mask control is activated on an item.                                              |
+| `onUnmask`      | `((item: UneditableSectionItemProps) => void)` | —       | Called when an unmask control is activated on an item.                                           |
+| `onTryAgain`    | `((item: UneditableSectionItemProps) => void)` | —       | Called when the retry button is clicked on an item in error state.                               |
+
+## Rules
+
+-   Always supply `items` with a `label` and `value` for each field.
+-   Use `displayWidth: "half"` for short values (names, dates, codes) to show two per row; omit for long values.
+-   Show `"—"` for any unanswered or empty field rather than leaving `value` blank.
+-   Set `background={false}` when rendering inside a `BoxContainer` — the container already provides the visual boundary; the default background creates an unwanted nested box appearance.
+-   Set `fullWidth` when rendering inside a container such as `BoxContainer` to remove the default `Layout.Content` spacing and allow content to fill the full width.
+
+## Anti-patterns
+
+-   Do not use `UneditableSection` for editable fields — use `Form.*` components with `readOnly` instead.
+-   Do not nest `UneditableSection` inside another `UneditableSection`.

package/skills/fds-build/resources/foundations/layout-composition-patterns.md

@@ -0,0 +1,53 @@
+# Layout & Composition Patterns
+
+Cross-cutting rules for assembling FDS components into polished layouts. Apply alongside per-page template files.
+
+---
+
+## Vertical Spacing Rhythm
+
+| Between…                                   | Token        |
+| ------------------------------------------ | ------------ |
+| Page title and first content section       | `spacing-32` |
+| Major page sections (cards → table)        | `spacing-48` |
+| Cards in a grid row (gap)                  | `spacing-24` |
+| Heading and its body text within a section | `spacing-8`  |
+| Form fields within a group                 | `spacing-24` |
+| Form field groups (personal → address)     | `spacing-32` |
+| Button row and the content above it        | `spacing-32` |
+| Last content section and page bottom       | `spacing-64` |
+
+Apply spacing tokens via inline `style` props:
+
+```tsx
+<section style={{ marginBottom: Spacing["spacing-48"] }}>...</section>
+```
+
+---
+
+## Visual Hierarchy
+
+Every page must use at least three distinct text levels.
+
+| Level   | Component              | Colour token   | Use for                                 |
+| ------- | ---------------------- | -------------- | --------------------------------------- |
+| Primary | `Typography.HeadingXL` | `text`         | Page title — one per page               |
+| Section | `Typography.HeadingMD` | `text`         | Section headings within the page        |
+| Card    | `Typography.HeadingSM` | `text`         | Card titles, panel headers              |
+| Body    | `Typography.BodyMD`    | `text`         | Default body text, descriptions         |
+| Support | `Typography.BodySM`    | `text-subtle`  | Secondary info, timestamps, helper text |
+| Caption | `Typography.BodyXS`    | `text-subtler` | Footnotes, disclaimers, metadata        |
+
+Page title pattern: `Typography.HeadingXL` as `h1`, `Typography.BodyMD` with `style={{ color: Colour["text-subtle"] }}` directly below as subtitle.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern                            | Fix                                                               |
+| --------------------------------------- | ----------------------------------------------------------------- |
+| All text the same size and colour       | Use at least 3 Typography sizes; `text-subtle` for secondary text |
+| No spacing between page sections        | `spacing-48` between major sections                               |
+| Summary metric cards stacked vertically | Use a responsive grid: 3–4 across on desktop, stacked on mobile   |
+| Buttons touching content above          | `spacing-32` above button row                                     |
+| Missing page-bottom spacing             | `spacing-64` padding-bottom on page wrapper                       |