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

package/skills/fds-build/resources/components/smart-app-banner.md

@@ -0,0 +1,28 @@
+# SmartAppBanner
+
+Import: `import { SmartAppBanner } from "@lifesg/react-design-system/smart-app-banner"`
+
+## Props — `SmartAppBannerProps`
+
+| Prop           | Type                         | Default                                                                    | Description                                                                   |
+| -------------- | ---------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `show` \*      | `boolean`                    | —                                                                          | Controls whether the banner is visible.                                       |
+| `href` \*      | `string`                     | —                                                                          | Destination URL opened in a new tab when the banner or CTA button is clicked. |
+| `content` \*   | `SmartAppBannerContentProps` | —                                                                          | Text, labels, and rating content rendered inside the banner.                  |
+| `offset`       | `number`                     | 0                                                                          | Top offset in pixels applied to the banner's position.                        |
+| `icon`         | `string`                     | "https://assets.life.gov.sg/react-design-system/img/app-icon/app-icon.png" | URL of the app icon image displayed in the banner.                            |
+| `animated`     | `boolean`                    | false                                                                      | Applies a slide-in entrance animation to the banner.                          |
+| `className`    | `string`                     | —                                                                          | —                                                                             |
+| `onDismiss` \* | `() => void`                 | —                                                                          | Called when the user clicks the dismiss button.                               |
+| `onClick`      | `(() => void)`               | —                                                                          | Called when the user clicks on the banner or the CTA button.                  |
+
+## Props — `SmartAppBannerContentProps`
+
+| Prop               | Type     | Default | Description                                                                    |
+| ------------------ | -------- | ------- | ------------------------------------------------------------------------------ |
+| `title` \*         | `string` | —       | Primary heading text, typically the app name.                                  |
+| `buttonLabel` \*   | `string` | —       | Label text for the CTA button.                                                 |
+| `iconAriaLabel`    | `string` | ""      | Alt text for the app icon image.                                               |
+| `buttonAriaLabel`  | `string` | —       | Accessible label for the CTA button. Falls back to `buttonLabel` when omitted. |
+| `message`          | `string` | —       | Secondary description text displayed beneath the title.                        |
+| `numberOfStars` \* | `number` | —       | App store rating rendered as up to 5 star icons.                               |

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

@@ -0,0 +1,107 @@
+# Tab
+
+Import: `import { Tab } from "@lifesg/react-design-system/tab"`
+
+## When to use
+
+Use to switch between related views within the same context — not for navigating between pages.
+
+## Sub-components
+
+```
+Tab                          ← tab strip container, manages active state
+├── Tab.Item                 ← individual tab (title + panel content)
+├── Tab.Item
+└── Tab.Item
+```
+
+All direct children of `Tab` must be `Tab.Item`. `Tab.Item` renders both the tab label and its associated panel content.
+
+## Variants
+
+| Mode                         | When to use                                |
+| ---------------------------- | ------------------------------------------ |
+| Uncontrolled (default)       | Tab manages its own active state           |
+| Controlled (`currentActive`) | Parent needs to control which tab is shown |
+
+## Props — `TabProps`
+
+| Prop                     | Type                                       | Default | Description                                                                                                                                                                                                                            |
+| ------------------------ | ------------------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `children` \*            | `JSX.Element \| JSX.Element[]`             | —       | —                                                                                                                                                                                                                                      |
+| `initialActive`          | `number`                                   | 0       | Zero-based index of the tab panel displayed on first render. Ignored when `currentActive` is provided.                                                                                                                                 |
+| `currentActive`          | `number`                                   | —       | Zero-based index of the currently active tab panel. When provided, the component operates in controlled mode — the caller is responsible for updating this value in response to `onTabClick` to reflect tab changes.                   |
+| `className`              | `string`                                   | —       | —                                                                                                                                                                                                                                      |
+| `id`                     | `string`                                   | —       | —                                                                                                                                                                                                                                      |
+| `onTabClick`             | `((title: string, index: number) => void)` | —       | Called when the user clicks a tab link.                                                                                                                                                                                                |
+| `fullWidthIndicatorLine` | `boolean`                                  | false   | Extends all tab indicator lines to the full width of the tab bar instead of matching only the tab link width.                                                                                                                          |
+| `fadeColor`              | `string[] \| FadeColorSet`                 | —       | Background color(s) used for the fade overlays at the edges of the scrollable tab link bar. Pass a `string[]` to apply the same gradient stop colors on both edges, or a `FadeColorSet` to specify left and right edges independently. |
+
+## Props — `TabItemProps`
+
+| Prop          | Type                           | Default | Description                                                                         |
+| ------------- | ------------------------------ | ------- | ----------------------------------------------------------------------------------- |
+| `title` \*    | `string`                       | —       | Text label rendered in the tab link bar for this panel.                             |
+| `children` \* | `JSX.Element \| JSX.Element[]` | —       | —                                                                                   |
+| `titleAddon`  | `TitleAddonProps`              | —       | Optional addon element rendered alongside the tab title in the link bar.            |
+| `className`   | `string`                       | —       | —                                                                                   |
+| `id`          | `string`                       | —       | —                                                                                   |
+| `width`       | `string`                       | —       | Explicit width for this tab link in the tab bar. Accepts any valid CSS width value. |
+
+## Props — `TitleAddonProps`
+
+| Prop         | Type                | Default | Description                                       |
+| ------------ | ------------------- | ------- | ------------------------------------------------- |
+| `content` \* | `JSX.Element`       | —       | The element rendered as the addon.                |
+| `position`   | `"left" \| "right"` | "right" | Which side of the tab title the addon appears on. |
+
+## Props — `TabContextProps`
+
+| Prop            | Type                                       | Default | Description                                                                                                                                                                                                          |
+| --------------- | ------------------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `children` \*   | `React.ReactNode`                          | —       | —                                                                                                                                                                                                                    |
+| `initialActive` | `number`                                   | 0       | Zero-based index of the tab panel displayed on first render. Ignored when `currentActive` is provided.                                                                                                               |
+| `currentActive` | `number`                                   | —       | Zero-based index of the currently active tab panel. When provided, the component operates in controlled mode — the caller is responsible for updating this value in response to `onTabClick` to reflect tab changes. |
+| `onTabClick`    | `((title: string, index: number) => void)` | —       | Called when the user clicks a tab link.                                                                                                                                                                              |
+
+## Props — `TabListProps`
+
+| Prop                     | Type                       | Default | Description                                                                                                                                                                                                                            |
+| ------------------------ | -------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `children` \*            | `React.ReactNode`          | —       | —                                                                                                                                                                                                                                      |
+| `fullWidthIndicatorLine` | `boolean`                  | false   | Extends all tab indicator lines to the full width of the tab bar instead of matching only the tab link width.                                                                                                                          |
+| `fadeColor`              | `string[] \| FadeColorSet` | —       | Background color(s) used for the fade overlays at the edges of the scrollable tab link bar. Pass a `string[]` to apply the same gradient stop colors on both edges, or a `FadeColorSet` to specify left and right edges independently. |
+
+## Props — `TabListItemProps`
+
+| Prop         | Type              | Default | Description                                                                         |
+| ------------ | ----------------- | ------- | ----------------------------------------------------------------------------------- |
+| `title` \*   | `string`          | —       | Text label rendered in the tab link bar for this item.                              |
+| `titleAddon` | `TitleAddonProps` | —       | Optional addon element rendered alongside the tab title in the link bar.            |
+| `width`      | `string`          | —       | Explicit width for this tab link in the tab bar. Accepts any valid CSS width value. |
+
+## Props — `TabPanelProps`
+
+| Prop          | Type              | Default | Description                                                              |
+| ------------- | ----------------- | ------- | ------------------------------------------------------------------------ |
+| `index` \*    | `number`          | —       | Zero-based index identifying which active tab this panel corresponds to. |
+| `children` \* | `React.ReactNode` | —       | —                                                                        |
+| `className`   | `string`          | —       | —                                                                        |
+| `id`          | `string`          | —       | —                                                                        |
+
+## Rules
+
+-   When `currentActive` is set, the component is in controlled mode — you must update it via `onTabClick`.
+-   Tab order is determined by the order of `Tab.Item` children.
+-   Keep tab labels short — labels truncate beyond 20 characters on tablet and mobile.
+-   Use controlled mode (`currentActive` + `onTabClick`) only when the parent needs to sync tab state with external logic (e.g. URL params, deep links).
+-   Use `titleAddon` with a `Badge` to show counts or status indicators on tab labels.
+-   Set `headingLevel` to match the component's position in the page heading hierarchy.
+-   Set `fadeColor` to match the page background so the horizontal scroll fade blends correctly on mobile.
+
+## Anti-patterns
+
+-   Do not use tabs for page-level navigation — use Navbar or LocalNav instead.
+-   Do not use more than 5–6 tabs — consider a different navigation pattern for many sections.
+-   Do not use long labels — they truncate on mobile and tablet.
+-   Do not set `currentActive` without also providing `onTabClick` — the tab state will be stuck.

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

@@ -0,0 +1,65 @@
+# Table
+
+Import: `import { Table } from "@lifesg/react-design-system/table"`
+
+## When to use
+
+-   Displaying read-only structured data with no sorting, selection, or pagination needed.
+-   Use `DataTable` instead when you need sortable columns, row selection, or pagination controls.
+
+## Composition
+
+`Table` is a thin styled wrapper over semantic HTML table elements:
+
+| Sub-component      | Renders as             |
+| ------------------ | ---------------------- |
+| `Table.Container`  | `<div>` scroll wrapper |
+| `Table`            | `<table>`              |
+| `Table.Head`       | `<thead>`              |
+| `Table.Body`       | `<tbody>`              |
+| `Table.Row`        | `<tr>`                 |
+| `Table.HeaderCell` | `<th>`                 |
+| `Table.Cell`       | `<td>`                 |
+
+Always wrap with `Table.Container` so the table scrolls horizontally on narrow viewports.
+
+## Usage
+
+```tsx
+import { Table } from "@lifesg/react-design-system/table";
+import { Typography } from "@lifesg/react-design-system/typography";
+
+const ServiceTable = () => (
+    <Table.Container>
+        <Table>
+            <Table.Head>
+                <Table.Row>
+                    <Table.HeaderCell>Service</Table.HeaderCell>
+                    <Table.HeaderCell>Status</Table.HeaderCell>
+                    <Table.HeaderCell>Last updated</Table.HeaderCell>
+                </Table.Row>
+            </Table.Head>
+            <Table.Body>
+                <Table.Row>
+                    <Table.Cell>MyService</Table.Cell>
+                    <Table.Cell>Active</Table.Cell>
+                    <Table.Cell>1 Jan 2024</Table.Cell>
+                </Table.Row>
+            </Table.Body>
+        </Table>
+    </Table.Container>
+);
+```
+
+## Rules
+
+-   Always wrap in `Table.Container` — it provides horizontal scroll on small viewports.
+-   Use `Table.HeaderCell` (`<th>`) for column headers, not `Table.Cell`.
+-   Use `DataTable` for sortable, selectable, or paginated tables — `Table` is read-only only.
+-   All props pass through to the underlying HTML element — use `style` or `className` for custom layout only when DS tokens don't cover the need.
+
+## Anti-patterns
+
+-   Do not use `Table` when rows need to be selected or sorted — use `DataTable`.
+-   Do not nest tables.
+-   Do not omit `Table.Container` — the table will overflow on mobile without it.

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

@@ -0,0 +1,68 @@
+# Tag
+
+Import: `import { Tag } from "@lifesg/react-design-system/tag"`
+
+## When to use
+
+Use to label categories, apply filters, or tag items. Can be static or interactive — set `interactive` to render as a button for toggleable filters or selectable categories. For status labels, use Pill instead.
+
+## Variants
+
+| `type`      | Usage                                                 |
+| ----------- | ----------------------------------------------------- |
+| `"outline"` | Subtle, secondary label — default for most uses       |
+| `"solid"`   | Higher emphasis — use when the tag needs to stand out |
+
+| `colorType` | Semantic use                  |
+| ----------- | ----------------------------- |
+| `"green"`   | Success, active, approved     |
+| `"red"`     | Error, rejected, danger       |
+| `"yellow"`  | Warning, pending, in progress |
+| `"blue"`    | Informational                 |
+| `"grey"`    | Neutral, inactive, draft      |
+| `"primary"` | Theme primary color           |
+| `"black"`   | Default, no semantic meaning  |
+
+## Usage
+
+```tsx
+import { Tag } from "@lifesg/react-design-system/tag";
+
+{
+    /* Static category tag */
+}
+<Tag type="outline" colorType="blue">
+    Health
+</Tag>;
+
+{
+    /* Interactive filter tag */
+}
+<Tag type="solid" colorType="primary" interactive onClick={() => {}}>
+    Finance
+</Tag>;
+```
+
+## Props — `TagProps`
+
+| Prop           | Type                | Default | Description                                                                                                                                          |
+| -------------- | ------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type` \*      | `TagType`           | —       | Visual style variant.                                                                                                                                |
+| `colorType`    | `TagColorType`      | "black" | Color theme applied to the tag.                                                                                                                      |
+| `icon`         | `JSX.Element`       | —       | Optional icon rendered alongside the label. The position is controlled by `iconPosition`.                                                            |
+| `iconPosition` | `"left" \| "right"` | "left"  | Position of the icon relative to the label text.                                                                                                     |
+| `interactive`  | `boolean`           | false   | When `true`, renders the tag as a `<button>` element to support click and keyboard interactions. When `false`, renders as a non-interactive `<div>`. |
+
+## Rules
+
+-   When `interactive` is `true`, the component renders as a `<button>` with an extended touch target on mobile.
+-   Always pair `interactive` with `onClick` — interactive tags are larger on mobile to extend the touch target.
+-   Use color semantically — do not use `"red"` for non-error states.
+-   Keep label text short — text does not wrap inside a tag.
+-   Use Tag for categories, filters, and tagging — use Pill for statuses.
+
+## Anti-patterns
+
+-   Using Tag for status labels — use Pill instead.
+-   Setting `interactive` without providing an `onClick` handler.
+-   Using `"red"` for non-error states.

package/skills/fds-build/resources/components/text-list.md

@@ -0,0 +1,44 @@
+# TextList
+
+Import: `import { TextList } from "@lifesg/react-design-system/text-list"`
+
+## When to use
+
+Use for semantic list content. For navigation links, use `LinkList` instead.
+
+## Sub-components
+
+| Sub-component | Renders | When to use                                  |
+| ------------- | ------- | -------------------------------------------- |
+| `TextList.Ul` | `<ul>`  | Unordered list — items without a sequence    |
+| `TextList.Ol` | `<ol>`  | Ordered list — numbered or lettered sequence |
+
+## Props — `OrderedListProps`
+
+| Prop               | Type                           | Default   | Description                                                             |
+| ------------------ | ------------------------------ | --------- | ----------------------------------------------------------------------- |
+| `counterType`      | `CounterType`                  | "decimal" | Counter style applied to each list item.                                |
+| `counterSeparator` | `string`                       | ")"       | Character or string rendered after each counter value.                  |
+| `reversed`         | `boolean`                      | —         | The counter is decremented from the start value instead of incremented. |
+| `start`            | `number`                       | —         | The value to start the list count from.                                 |
+| `children` \*      | `JSX.Element \| JSX.Element[]` | —         | —                                                                       |
+| `bottomMargin`     | `number`                       | —         | Bottom margin in pixels applied to each list item except the last.      |
+| `size`             | `TextListSize`                 | —         | Text size applied to the list content.                                  |
+| `id`               | `string`                       | —         | —                                                                       |
+| `className`        | `string`                       | —         | —                                                                       |
+
+## Props — `UnorderedListProps`
+
+| Prop           | Type                             | Default | Description                                                                                                                                                      |
+| -------------- | -------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `bulletType`   | `BulletType \| CustomBulletIcon` | "disc"  | Marker style for list items. Pass a `BulletType` token for a predefined marker, or any React node to render a custom decorative icon before each item's content. |
+| `children` \*  | `JSX.Element \| JSX.Element[]`   | —       | —                                                                                                                                                                |
+| `bottomMargin` | `number`                         | —       | Bottom margin in pixels applied to each list item except the last.                                                                                               |
+| `size`         | `TextListSize`                   | —       | Text size applied to the list content.                                                                                                                           |
+| `id`           | `string`                         | —       | —                                                                                                                                                                |
+| `className`    | `string`                         | —       | —                                                                                                                                                                |
+
+## Rules
+
+-   Children must be `<li>` elements.
+-   Use `bulletType` as a `ReactNode` to render a custom icon bullet — the icon is automatically marked `aria-hidden`.

package/skills/fds-build/resources/components/time-slot-bar-week.md

@@ -0,0 +1,66 @@
+# TimeSlotBarWeek
+
+Import: `import { TimeSlotBarWeek } from "@lifesg/react-design-system/time-slot-bar-week"`
+
+## Sub-components
+
+-   `YearMonthWeekDisplay` — returned by `onWeekDisplayChange`
+-   `TimeSlot` — shape of each slot in the `slots` map
+-   `TimeSlotBarStyleAttributes` — visual styling for a slot
+
+## YearMonthWeekDisplay
+
+| Prop    | Type                                                | Description                                            |
+| ------- | --------------------------------------------------- | ------------------------------------------------------ |
+| `week`  | `{ firstDayOfWeek: string; lastDayOfWeek: string }` | First and last days of the visible week (`YYYY-MM-DD`) |
+| `year`  | `number`                                            | Visible year                                           |
+| `month` | `number`                                            | Visible month (1–12)                                   |
+
+## TimeSlot
+
+| Prop              | Type                         | Description                        |
+| ----------------- | ---------------------------- | ---------------------------------- |
+| `id` \*           | `string`                     | Unique identifier of the slot      |
+| `startTime` \*    | `string`                     | Start time (`HH:mm`)               |
+| `endTime` \*      | `string`                     | End time (`HH:mm`)                 |
+| `styleAttributes` | `TimeSlotBarStyleAttributes` | Visual styling                     |
+| `label`           | `string`                     | Text content within the slot cell  |
+| `clickable`       | `boolean`                    | Whether the slot cell is clickable |
+
+## TimeSlotBarStyleAttributes
+
+| Prop                 | Type                     | Default     | Description                                       |
+| -------------------- | ------------------------ | ----------- | ------------------------------------------------- |
+| `backgroundColor` \* | `string`                 | —           | The color of the slot                             |
+| `styleType`          | `"default" \| "stripes"` | `"default"` | The style type of the slot                        |
+| `backgroundColor2`   | `string`                 | —           | Secondary color; used with `styleType: "stripes"` |
+
+## Props — `TimeSlotBarWeekProps`
+
+| Prop                      | Type                                           | Default    | Description                                                                                           |
+| ------------------------- | ---------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------- |
+| `className`               | `string`                                       | —          | —                                                                                                     |
+| `id`                      | `string`                                       | —          | —                                                                                                     |
+| `slots` \*                | `{ [date: string]: TimeSlot[] }`               | —          | Map of date strings (YYYY-MM-DD) to the time slot arrays to render for that date.                     |
+| `startTime`               | `string`                                       | —          | The start boundary of the visible time range, in HH:mm format.                                        |
+| `endTime`                 | `string`                                       | —          | The end boundary of the visible time range, in HH:mm format.                                          |
+| `value`                   | `string`                                       | —          | The currently selected date in YYYY-MM-DD format. Controls the highlighted day column.                |
+| `interval`                | `number`                                       | 30         | Duration in minutes that each time slot cell represents.                                              |
+| `variant`                 | `TimeSlotCellsVariant`                         | "flexible" | Controls how time slot cells are sized within each day column.                                        |
+| `maxVisibleCellHeight`    | `number`                                       | —          | Maximum height in pixels for the time slot area before it becomes truncated.                          |
+| `showNavigationHeader`    | `boolean`                                      | true       | Whether to show the month/year pickers and the prev/next week navigation arrows above the week grid.  |
+| `enableSelection`         | `boolean`                                      | true       | When `true`, the user can click a day column to select that date, triggering `onChange`.              |
+| `currentCalendarDate`     | `string`                                       | —          | The date used to determine which week is shown on first render, in YYYY-MM-DD format.                 |
+| `onSlotClick`             | `((date: string, timeSlot: TimeSlot) => void)` | —          | Called when the user clicks a time slot cell.                                                         |
+| `onChange`                | `((value: string) => void)`                    | —          | Called when the user selects a date. Requires `enableSelection` to be `true`.                         |
+| `onWeekDisplayChange`     | `((value: YearMonthWeekDisplay) => void)`      | —          | Called when the visible week changes due to navigation.                                               |
+| `minDate`                 | `string`                                       | —          | The minimum date that can be selected (inclusive) in 'YYYY-MM-DD' format.                             |
+| `maxDate`                 | `string`                                       | —          | The maximum date that can be selected (inclusive) in 'YYYY-MM-DD' format.                             |
+| `disabledDates`           | `string[]`                                     | —          | Dates to disable in `YYYY-MM-DD` format. Example: `["2023-04-30"]`                                    |
+| `allowDisabledSelection`  | `boolean`                                      | —          | Specifies if dates normally disabled by `minDate`, `maxDate` and `disabledDates` are still selectable |
+| `showActiveMonthDaysOnly` | `boolean`                                      | —          | Specifies if the calendar should display only dates for the selected month                            |
+
+## Rules
+
+-   `slots` is mandatory.
+-   `startTime`/`endTime` on the component must be full hours (e.g. `"08:00"`, `"13:00"`).

package/skills/fds-build/resources/components/time-slot-bar.md

@@ -0,0 +1,57 @@
+# TimeSlotBar
+
+Import: `import { TimeSlotBar } from "@lifesg/react-design-system/time-slot-bar"`
+
+## TimeSlot
+
+| Prop              | Type                         | Default | Description                                |
+| ----------------- | ---------------------------- | ------- | ------------------------------------------ |
+| `id` \*           | `string`                     | —       | Unique identifier of the slot              |
+| `startTime` \*    | `string`                     | —       | Slot start time in `HH:mm` (15-min blocks) |
+| `endTime` \*      | `string`                     | —       | Slot end time in `HH:mm` (15-min blocks)   |
+| `styleAttributes` | `TimeSlotBarStyleAttributes` | —       | Styling for this slot                      |
+| `label`           | `string`                     | —       | Text content within the slot cell          |
+| `clickable`       | `boolean`                    | —       | Whether the slot cell is clickable         |
+
+## TimeSlotBarStyleAttributes
+
+| Prop                    | Type                     | Default     | Description                                                            |
+| ----------------------- | ------------------------ | ----------- | ---------------------------------------------------------------------- |
+| `backgroundColor` \*    | `string`                 | —           | Slot color                                                             |
+| `styleType`             | `"default" \| "stripes"` | `"default"` | Style type of the slot                                                 |
+| `backgroundColor2`      | `string`                 | —           | Secondary color; used with `styleType="stripes"`                       |
+| `hoverBackgroundColor`  | `string`                 | —           | Background on hover; only when `clickable`                             |
+| `hoverBackgroundColor2` | `string`                 | —           | Secondary hover color for `styleType="stripes"`; only when `clickable` |
+
+## Props — `TimeSlotBarRef`
+
+| Prop             | Type         | Default | Description                                                                                     |
+| ---------------- | ------------ | ------- | ----------------------------------------------------------------------------------------------- |
+| `resetScroll` \* | `() => void` | —       | Scrolls the bar back to `initialScrollTime`, or to the start if `initialScrollTime` is not set. |
+
+## Props — `TimeSlotBarProps`
+
+| Prop                     | Type                           | Default   | Description                                                                                                                                                                          |
+| ------------------------ | ------------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `className`              | `string`                       | —         | —                                                                                                                                                                                    |
+| `variant`                | `TimeSlotBarVariant`           | "default" | Visual density of the bar.                                                                                                                                                           |
+| `startTime` \*           | `string`                       | —         | Start of the visible time range in `HH:mm` format.                                                                                                                                   |
+| `endTime` \*             | `string`                       | —         | End of the visible time range in `HH:mm` format.                                                                                                                                     |
+| `initialScrollTime`      | `string`                       | —         | Time position the bar scrolls to on mount, in `HH:mm` format. When `roundInitialScrollTime` is `true`, the value is rounded down to the nearest 30-minute interval before scrolling. |
+| `slots` \*               | `TimeSlot[]`                   | —         | The individual time slots shown within the configured time range.                                                                                                                    |
+| `onSlotClick` \*         | `(timeSlot: TimeSlot) => void` | —         | Called when the user clicks a slot cell.                                                                                                                                             |
+| `onClick`                | `() => void`                   | —         | Called when the user clicks an empty slot.                                                                                                                                           |
+| `styleAttributes`        | `TimeSlotBarStyleAttributes`   | —         | Styling applied to the bar background region not covered by any slot. Required to make the background region visible or interactive.                                                 |
+| `roundInitialScrollTime` | `boolean`                      | true      | When `true`, `initialScrollTime` is rounded down to the nearest 30-minute interval before the bar scrolls to it.                                                                     |
+
+## Props — `TimeSlot`
+
+| Prop                 | Type                         | Default | Description                                                                                                      |
+| -------------------- | ---------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
+| `id` \*              | `string`                     | —       | Unique identifier for this slot.                                                                                 |
+| `startTime` \*       | `string`                     | —       | Start boundary of the slot in `HH:mm` format.                                                                    |
+| `endTime` \*         | `string`                     | —       | End boundary of the slot in `HH:mm` format.                                                                      |
+| `label`              | `string`                     | —       | Text rendered inside the slot cell. Replaced with `"..."` when the cell is too narrow to display the full label. |
+| `clickable`          | `boolean`                    | true    | Whether the slot responds to clicks.                                                                             |
+| `styleAttributes` \* | `TimeSlotBarStyleAttributes` | —       | Visual styling for the slot.                                                                                     |
+| `ariaLabel`          | `string`                     | —       | Accessible label for this slot.                                                                                  |

package/skills/fds-build/resources/components/time-slot-week-view.md

@@ -0,0 +1,70 @@
+# TimeSlotWeekView
+
+Import: `import { TimeSlotWeekView } from "@lifesg/react-design-system/time-slot-week-view"`
+
+## Sub-components
+
+-   `YearMonthWeekDisplay` — returned by `onWeekDisplayChange`
+-   `TimeSlot` — shape of each slot in the `slots` map
+-   `TimeSlotBarStyleAttributes` — visual styling for a slot
+
+## YearMonthWeekDisplay
+
+| Prop    | Type                                                | Description                                            |
+| ------- | --------------------------------------------------- | ------------------------------------------------------ |
+| `week`  | `{ firstDayOfWeek: string; lastDayOfWeek: string }` | First and last days of the visible week (`YYYY-MM-DD`) |
+| `year`  | `number`                                            | Visible year                                           |
+| `month` | `number`                                            | Visible month (1–12)                                   |
+
+## TimeSlot
+
+| Prop              | Type                         | Description                                                       |
+| ----------------- | ---------------------------- | ----------------------------------------------------------------- |
+| `id` \*           | `string`                     | Unique identifier of the slot                                     |
+| `startTime` \*    | `string`                     | Start time (`HH:mm`; minutes in 15-minute blocks: 00, 15, 30, 45) |
+| `endTime` \*      | `string`                     | End time (`HH:mm`; minutes in 15-minute blocks: 00, 15, 30, 45)   |
+| `styleAttributes` | `TimeSlotBarStyleAttributes` | Visual styling                                                    |
+| `label`           | `string`                     | Text content within the slot cell                                 |
+| `clickable`       | `boolean`                    | Whether the slot cell is clickable                                |
+
+## TimeSlotBarStyleAttributes
+
+| Prop             | Type                     | Default     | Description                                       |
+| ---------------- | ------------------------ | ----------- | ------------------------------------------------- |
+| `color` \*       | `string`                 | —           | The color of the slot                             |
+| `styleType`      | `"default" \| "stripes"` | `"default"` | The style type of the slot                        |
+| `secondaryColor` | `string`                 | —           | Secondary color; used with `styleType: "stripes"` |
+
+## Props — `TimeSlotWeekViewProps`
+
+| Prop                      | Type                                           | Default | Description                                                                                           |
+| ------------------------- | ---------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------- |
+| `className`               | `string`                                       | —       | —                                                                                                     |
+| `id`                      | `string`                                       | —       | —                                                                                                     |
+| `value`                   | `string`                                       | —       | The currently selected date in `YYYY-MM-DD` format. Controls the highlighted day in the week view.    |
+| `slots`                   | `{ [date: string]: TimeSlot[] }`               | —       | Map of date strings (YYYY-MM-DD) to an array of `TimeSlot` entries displayed in that day's column.    |
+| `showNavigationHeader`    | `boolean`                                      | true    | Whether to show the month/year picker and the prev/next week navigation arrows above the week grid.   |
+| `enableSelection`         | `boolean`                                      | true    | When `true`, the user can click a day column to select that date, triggering `onChange`               |
+| `currentCalendarDate`     | `string`                                       | —       | The date used to determine which week is shown on first render, in YYYY-MM-DD format.                 |
+| `onSlotClick`             | `((date: string, timeSlot: TimeSlot) => void)` | —       | Called when the user clicks a time slot cell.                                                         |
+| `onChange`                | `((value: string) => void)`                    | —       | Called when the user selects a date. Requires `enableSelection` to be `true`.                         |
+| `onWeekDisplayChange`     | `((value: YearMonthWeekDisplay) => void)`      | —       | Called when the visible week changes due to navigation.                                               |
+| `minDate`                 | `string`                                       | —       | The minimum date that can be selected (inclusive) in 'YYYY-MM-DD' format.                             |
+| `maxDate`                 | `string`                                       | —       | The maximum date that can be selected (inclusive) in 'YYYY-MM-DD' format.                             |
+| `disabledDates`           | `string[]`                                     | —       | Dates to disable in `YYYY-MM-DD` format. Example: `["2023-04-30"]`                                    |
+| `allowDisabledSelection`  | `boolean`                                      | —       | Specifies if dates normally disabled by `minDate`, `maxDate` and `disabledDates` are still selectable |
+| `showActiveMonthDaysOnly` | `boolean`                                      | —       | Specifies if the calendar should display only dates for the selected month                            |
+
+## Props — `YearMonthWeekDisplay`
+
+| Prop       | Type                                                | Default | Description                                                               |
+| ---------- | --------------------------------------------------- | ------- | ------------------------------------------------------------------------- |
+| `week` \*  | `{ firstDayOfWeek: string; lastDayOfWeek: string }` | —       | The first and last days of the newly displayed week in YYYY-MM-DD format. |
+| `year` \*  | `number`                                            | —       | —                                                                         |
+| `month` \* | `number`                                            | —       | `month` is 1-indexed                                                      |
+
+## Rules
+
+-   `slots` is mandatory.
+-   `TimeSlot` minutes must be in 15-minute blocks (00, 15, 30, 45).
+-   `TimeSlotBarStyleAttributes` uses `color`/`secondaryColor` — not `backgroundColor`/`backgroundColor2` as in `TimeSlotBarWeek`.

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

@@ -0,0 +1,69 @@
+# Timeline
+
+Import: `import { Timeline } from "@lifesg/react-design-system/timeline"`
+
+## When to use
+
+Use to communicate a process, application history, or sequence of steps. Use the `numeric` variant for numbered step-by-step instructions.
+
+## Sub-components
+
+### TimelineItemProps
+
+| Prop       | Type                                                                                                         | Default | Description                                            |
+| ---------- | ------------------------------------------------------------------------------------------------------------ | ------- | ------------------------------------------------------ |
+| `title`    | `string`                                                                                                     | —       | Item title — required                                  |
+| `content`  | `JSX.Element`                                                                                                | —       | Item content — required                                |
+| `variant`  | `"completed" \| "current" \| "upcoming-active" \| "upcoming-inactive" \| "numeric" \| "error" \| "disabled"` | —       | Visual state of the item indicator                     |
+| `statuses` | `PillProps[]`                                                                                                | —       | Status pills shown alongside the item (max 2 rendered) |
+
+## Variants
+
+| `variant`             | Usage                                |
+| --------------------- | ------------------------------------ |
+| `"completed"`         | Step or event is done                |
+| `"current"`           | Step currently in progress           |
+| `"upcoming-active"`   | Next actionable step                 |
+| `"upcoming-inactive"` | Future step, not yet actionable      |
+| `"error"`             | Step has an error                    |
+| `"disabled"`          | Step is not available                |
+| `"numeric"`           | Numbered step — use for instructions |
+
+## Props — `TimelineItemProps`
+
+| Prop         | Type                    | Default                                                                      | Description                                                                                                                    |
+| ------------ | ----------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `title` \*   | `string \| JSX.Element` | —                                                                            | Title of the step.                                                                                                             |
+| `content` \* | `string \| JSX.Element` | —                                                                            | Body content of the step.                                                                                                      |
+| `statuses`   | `PillProps[]`           | —                                                                            | Up to two status `Pill` descriptors rendered below the title. Only the first two entries are displayed when more are provided. |
+| `variant`    | `Variant`               | "current" for the first item and "upcoming-active" for all subsequent items. | Visual state of this step.                                                                                                     |
+
+## Props — `TimelineProps`
+
+| Prop                         | Type                  | Default | Description                                                                                         |
+| ---------------------------- | --------------------- | ------- | --------------------------------------------------------------------------------------------------- |
+| `items` \*                   | `TimelineItemProps[]` | —       | Ordered list of steps to render.                                                                    |
+| `title`                      | `string`              | —       | Heading text displayed above the step list.                                                         |
+| `startCol`                   | `number`              | —       | CSS grid column the timeline wrapper starts on. Useful if component is wrapped in a css grid div.   |
+| `colSpan`                    | `number`              | —       | Number of grid columns the timeline wrapper spans. Useful if component is wrapped in a css grid div |
+| `headingLevel`               | `number`              | 2       | Heading level assigned to the `title` element. Item titles are rendered at `headingLevel + 1`.      |
+| `counterOffset`              | `number`              | 0       | Value added to each step's displayed counter when `variant` is `"numeric"`.                         |
+| `className`                  | `string`              | —       | —                                                                                                   |
+| `id`                         | `string`              | —       | —                                                                                                   |
+| `data-base-indicator-testid` | `string`              | —       | —                                                                                                   |
+
+## Rules
+
+-   The first item defaults to `variant="current"` and subsequent items default to `variant="upcoming-active"` when `variant` is not specified.
+-   Only a maximum of 2 `statuses` pills will render per item regardless of how many are provided.
+-   `counterOffset` shifts the numeric counter: if `offset=2`, the first item shows `3`.
+-   Always set `headingLevel` when `title` is provided — ensures correct heading hierarchy.
+-   Use `counterOffset` when showing a partial sequence (e.g. steps 3–5 of a larger flow).
+-   Use `statuses` with `PillProps` — follow Pill color semantics (see `pill.md`).
+-   Use `"numeric"` variant consistently across all items in an instruction list — do not mix with status variants.
+
+## Anti-patterns
+
+-   Mixing `"numeric"` and status variants in the same timeline — choose one paradigm per use case.
+-   Providing more than 2 status pills per item — only 2 will render.
+-   Using Timeline for non-sequential content — use a list or table instead.