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

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

@@ -0,0 +1,54 @@
+# Alert
+
+Import: `import { Alert } from "@lifesg/react-design-system/alert"`
+
+## When to use
+
+Use to call out important information within page sections — warnings before a user starts a task, informational notes relevant to a specific section, or non-transient status messages. Not for form validation errors (use form error patterns instead).
+
+## Variants
+
+| `type`          | When to use                                |
+| --------------- | ------------------------------------------ |
+| `"success"`     | Action completed successfully              |
+| `"error"`       | Action failed or system error              |
+| `"warning"`     | User should proceed with caution           |
+| `"info"`        | Neutral informational message              |
+| `"description"` | Descriptive content with no status meaning |
+
+## Usage
+
+```tsx
+import { Alert } from "@lifesg/react-design-system/alert";
+
+<Alert type="warning" showIcon role="alert">
+    Your session will expire in 5 minutes. Save your work to avoid losing
+    progress.
+</Alert>;
+```
+
+## Props — `AlertProps`
+
+| Prop                 | Type                                            | Default            | Description                                                                                                                                                                                                                                 |
+| -------------------- | ----------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type` \*            | `AlertType`                                     | —                  | Visual severity or purpose of the alert banner.                                                                                                                                                                                             |
+| `actionLink`         | `React.AnchorHTMLAttributes<HTMLAnchorElement>` | —                  | Anchor attributes for an optional call-to-action link rendered below the alert content. The link is styled with a trailing arrow icon by default; supply `actionLinkIcon` to replace that icon.                                             |
+| `showIcon`           | `boolean`                                       | false              | Renders the type-specific icon to the left of the content.                                                                                                                                                                                  |
+| `actionLinkIcon`     | `JSX.Element`                                   | <ArrowRightIcon /> | Replaces the default trailing arrow on the action link. Only visible when `actionLink` is also provided.                                                                                                                                    |
+| `sizeType`           | `AlertSizeType`                                 | —                  | Controls the overall size of the alert, affecting typography and icon dimensions.                                                                                                                                                           |
+| `customIcon`         | `JSX.Element`                                   | —                  | Replaces the default type-specific icon. Only visible when `showIcon` is `true`.                                                                                                                                                            |
+| `maxCollapsedHeight` | `number`                                        | —                  | Maximum height in pixels before the content area is collapsed. When the rendered content exceeds this value a "Show more / Show less" toggle is displayed. The content container is marked as inert whenever the collapsed state is active. |
+
+## Rules
+
+-   Always use `showIcon` — icons provide immediate visual recognition of alert severity.
+-   Use `actionLink` for recoverable errors (retry, undo, view details).
+-   Set `role` based on how the alert appears: `"alert"` for dynamic alerts triggered by user action, `"status"` for background status updates, omit for static content visible on page load.
+-   Use `maxCollapsedHeight` to avoid long content overwhelming the layout.
+-   `role` is not set automatically — set `role="alert"` for dynamic alerts, `role="status"` for background updates, and omit for static content.
+
+## Anti-patterns
+
+-   Using Alert for form field validation errors — use inline form error patterns instead.
+-   Omitting `role` on dynamically injected alerts — screen readers will not announce them.
+-   Using `type="description"` with `showIcon` — description has no semantic status meaning.

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

@@ -0,0 +1,18 @@
+# Animation
+
+Import: `import { Animation } from "@lifesg/react-design-system/animation"`
+
+## Props — `AnimationProps`
+
+| Prop        | Type     | Default | Description |
+| ----------- | -------- | ------- | ----------- |
+| `id`        | `string` | —       | —           |
+| `className` | `string` | —       | —           |
+
+## Props — `CustomisableAnimationProps`
+
+| Prop        | Type                                                                      | Default | Description                                              |
+| ----------- | ------------------------------------------------------------------------- | ------- | -------------------------------------------------------- |
+| `id`        | `string`                                                                  | —       | —                                                        |
+| `className` | `string`                                                                  | —       | —                                                        |
+| `color`     | `\| string \| ColourCSSVariableString \| ComponentTokenCSSVariableString` | —       | The color that is to be applied on the animated elements |

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

@@ -0,0 +1,10 @@
+# Avatar
+
+Import: `import { Avatar } from "@lifesg/react-design-system/avatar"`
+
+## Props — `AvatarProps`
+
+| Prop          | Type                    | Default | Description                                                                                                                                                                                                            |
+| ------------- | ----------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `children` \* | `string \| JSX.Element` | —       | A string or JSX element to display inside the avatar. When a string is provided, only the first Unicode code point is rendered as an uppercase initial. Pass a JSX element (e.g. an `<img>`) to render custom content. |
+| `sizeType`    | `AvatarSize`            | —       | Controls the visual size of the avatar. `"small"` renders a compact variant with reduced typography; `"default"` uses the standard size.                                                                               |

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

@@ -0,0 +1,18 @@
+# Badge
+
+Import: `import { Badge } from "@lifesg/react-design-system/badge"`
+
+## Props — `BadgeProps`
+
+| Prop          | Type               | Default   | Description                                                                                                                                                                                           |
+| ------------- | ------------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `badgeOffset` | `[string, string]` | —         | Horizontal and vertical offset applied to the badge when it overlays a child element. Provided as a `[x, y]` tuple of CSS length values (e.g. `["-4px", "-4px"]`). Ignored when no child is rendered. |
+| `children`    | `JSX.Element`      | —         | Element that the badge overlays. When provided, the badge is positioned absolutely over the top-right corner of this child. Omit to render the badge as a standalone indicator.                       |
+| `color`       | `BadgeColor`       | "default" | Color scheme applied to the badge.                                                                                                                                                                    |
+| `count`       | `number`           | —         | Numeric value displayed inside `number`, `number-with-border`, and `square-number` variants. Values above 1000 are capped and shown as `"1K"` or `"1K+"`. Has no effect on dot variants.              |
+| `variant`     | `BadgeVariant`     | "number"  | Visual style of the badge indicator.                                                                                                                                                                  |
+
+## Rules
+
+-   `count` only applies to `"number"`, `"number-with-border"`, and `"square-number"` variants.
+-   When `children` is provided, the badge overlays the top-right corner of the child element.

package/skills/fds-build/resources/components/box-container.md

@@ -0,0 +1,61 @@
+# BoxContainer
+
+Import: `import { BoxContainer } from "@lifesg/react-design-system/box-container"`
+
+## When to use
+
+Use for a single collapsible panel displaying form data or structured content — typically a named section within a form or detail view. Supports an optional header action and a status indicator to flag section-level errors or warnings.
+
+## Sub-components
+
+### BoxContainerSubComponentTestIds
+
+| Prop               | Type     | Description                            |
+| ------------------ | -------- | -------------------------------------- |
+| `title`            | `string` | Test id for the header title           |
+| `displayStateIcon` | `string` | Test id for the display state icon     |
+| `handle`           | `string` | Test id for the expand/collapse handle |
+
+## Variants
+
+| `displayState` | When to use                                |
+| -------------- | ------------------------------------------ |
+| `"default"`    | Normal state — no icon                     |
+| `"error"`      | Section has validation errors              |
+| `"warning"`    | Section has a warning that needs attention |
+
+## Props — `BoxContainerSubComponentTestIds`
+
+| Prop               | Type     | Default | Description |
+| ------------------ | -------- | ------- | ----------- |
+| `title`            | `string` | —       | —           |
+| `handle`           | `string` | —       | —           |
+| `displayStateIcon` | `string` | —       | —           |
+
+## Props — `BoxContainerProps`
+
+| Prop                    | Type                              | Default   | Description                                                                                                                                             |
+| ----------------------- | --------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `children` \*           | `JSX.Element \| JSX.Element[]`    | —         | —                                                                                                                                                       |
+| `title` \*              | `string \| JSX.Element`           | —         | —                                                                                                                                                       |
+| `collapsible`           | `boolean`                         | true      | When `false`, the container is always expanded and the collapse handle is hidden.                                                                       |
+| `expanded`              | `boolean`                         | false     | Initial expanded state when `collapsible` is `true`.                                                                                                    |
+| `callToActionComponent` | `JSX.Element`                     | —         | Optional element rendered in the header alongside the title, e.g. a link or button.                                                                     |
+| `displayState`          | `BoxContainerDisplayState`        | "default" | Renders an inline alert icon next to the title and announces the state to screen readers. Has no effect when set to `"default"`.                        |
+| `className`             | `string`                          | —         | —                                                                                                                                                       |
+| `subComponentTestIds`   | `BoxContainerSubComponentTestIds` | —         | —                                                                                                                                                       |
+| `id`                    | `string`                          | —         | —                                                                                                                                                       |
+| `clickableHeader`       | `boolean`                         | —         | When `true` (and `collapsible` is also `true`), the entire header row becomes a click target for toggling expand/collapse, not just the chevron button. |
+
+## Rules
+
+-   Use `displayState` to indicate section-level status — not as a substitute for inline field errors.
+-   Use `callToActionComponent` for section-level actions only — not for form submission buttons.
+-   Use `collapsible={false}` when the content must always be visible.
+-   Use `clickableHeader` to make the full header row the expand/collapse trigger — improves usability for dense layouts.
+
+## Anti-patterns
+
+-   Using `displayState="error"` instead of inline form field errors — `displayState` signals section-level status only.
+-   Using `callToActionComponent` for form submission — use a dedicated submit button outside the container.
+-   Nesting BoxContainer inside another BoxContainer.

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

@@ -0,0 +1,60 @@
+# Breadcrumb
+
+Import: `import { Breadcrumb } from "@lifesg/react-design-system/breadcrumb"`
+
+## When to use
+
+Use on pages within a multi-level hierarchy to help users navigate to parent pages.
+
+Do not use on:
+
+-   The home page
+-   Pages with no parent
+-   Focused flows such as forms or wizards
+
+## Variants
+
+| `separatorStyle`      | When to use              |
+| --------------------- | ------------------------ |
+| `"chevron"` (default) | Standard pages           |
+| `"slash"`             | Alternative visual style |
+
+## Usage
+
+```tsx
+import { Breadcrumb } from "@lifesg/react-design-system/breadcrumb";
+
+<Breadcrumb
+    links={[
+        { children: "Home", href: "/" },
+        { children: "Services", href: "/services" },
+        { children: "Apply" },
+    ]}
+/>;
+```
+
+## Props
+
+| Prop             | Type                                              | Default      | Description                                                                                                                                                                                                                              |
+| ---------------- | ------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `links` \*       | `React.AnchorHTMLAttributes<HTMLAnchorElement>[]` | —            | Navigation items rendered as the breadcrumb trail. The last item is treated as the current page (`aria-current="page"`) and is not clickable. Items without `href` render as non-clickable labels. Items without `children` are skipped. |
+| `fadeColor`      | `string[] \| FadeColorSet`                        | —            | Gradient color stops for the fade overlays shown on horizontal scroll. Pass a `string[]` to apply the same gradient to both edges, or a `FadeColorSet` to configure each edge independently.                                             |
+| `fadePosition`   | `FadePosition`                                    | "both"       | Which edges display fade overlays when content overflows.                                                                                                                                                                                |
+| `separatorStyle` | `SeparatorStyle`                                  | "chevron"    | Visual separator between breadcrumb items.                                                                                                                                                                                               |
+| `className`      | `string`                                          | —            | —                                                                                                                                                                                                                                        |
+| `id`             | `string`                                          | "breadcrumb" | HTML `id` for the wrapper element.                                                                                                                                                                                                       |
+
+## Rules
+
+-   Always place the current page last in `links` — omit `href` on the last item.
+-   Keep breadcrumb trails to 4 items or fewer; 5 or more items automatically collapse the middle into an overflow menu.
+-   Set `fadeColor` to match the page background so the horizontal scroll fade blends correctly on mobile.
+-   The last item in `links` is rendered as the current page (non-clickable, `aria-current="page"`). Omit `href` on the last item.
+-   When 5 or more items are present, middle items automatically collapse into an overflow menu.
+-   On mobile, breadcrumbs scroll horizontally with a fade effect at the edges controlled by `fadeColor` and `fadePosition`.
+
+## Anti-patterns
+
+-   Do not add `href` to the last breadcrumb item — it represents the current page and must not be clickable.
+-   Do not use breadcrumbs on single-level or flat navigation structures.
+-   Do not use breadcrumbs inside forms or wizard flows.

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

@@ -0,0 +1,74 @@
+# Button
+
+Import: `import { Button } from "@lifesg/react-design-system/button"`
+
+## When to use
+
+`Button` handles all button variants in v4 — there are no separate `IconButton` or `ButtonWithIcon` components:
+
+| Need                | Usage                                                            |
+| ------------------- | ---------------------------------------------------------------- |
+| Text only           | `<Button>Label</Button>`                                         |
+| Text + icon         | `<Button icon={<Icon />}>Label</Button>` — icon defaults to left |
+| Icon only (no text) | `<Button icon={<Icon />} aria-label="..." />` — renders square   |
+
+## Size variants
+
+| Usage                                       | When to use                                             |
+| ------------------------------------------- | ------------------------------------------------------- |
+| `<Button>` or `<Button sizeType="default">` | Standard size — use for all buttons including hero CTAs |
+| `<Button sizeType="small">`                 | Dense layouts, toolbars                                 |
+| `<Button sizeType="large">`                 | Only when explicitly specified — do not use by default  |
+
+> **Deprecated:** `Button.Default`, `Button.Small`, `Button.Large` sub-components are deprecated in v4. Use `<Button sizeType="...">` instead.
+
+## Variants
+
+| `styleType`   | When to use                           |
+| ------------- | ------------------------------------- |
+| `"default"`   | Main action on the page               |
+| `"secondary"` | Cancel, go back, alternative option   |
+| `"light"`     | On colored or dark backgrounds        |
+| `"link"`      | Tertiary, de-emphasized inline action |
+
+Add `danger` for destructive actions (delete, remove) — applies to any `styleType`.
+
+## Usage
+
+```tsx
+import { Button } from "@lifesg/react-design-system/button";
+
+<Button styleType="default" onClick={() => {}}>
+    Save changes
+</Button>;
+```
+
+## Props
+
+| Prop                    | Type                 | Default   | Description                                                                                                                                                                                                                                       |
+| ----------------------- | -------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `styleType`             | `ButtonStyleType`    | "default" | Visual style variant of the button.                                                                                                                                                                                                               |
+| `sizeType`              | `ButtonSizeType`     | "default" | Controls the button's size.                                                                                                                                                                                                                       |
+| `danger`                | `boolean`            | false     | Applies a red color scheme for destructive actions.                                                                                                                                                                                               |
+| `loading`               | `boolean`            | false     | Displays a loading spinner and sets `aria-busy` on the button. The spinner replaces the icon (if present); children continue to render.                                                                                                           |
+| `focusableWhenDisabled` | `boolean`            | false     | Keeps the button keyboard-focusable when disabled. When true, the HTML `disabled` attribute is not set, but `aria-disabled` remains true and the click handler is suppressed.                                                                     |
+| `icon`                  | `JSX.Element`        | —         | Icon element rendered inside the button. The icon receives `aria-hidden` automatically. When provided without children, the button renders in icon-only mode (square layout) — provide `aria-label` on the button for accessibility in that case. |
+| `iconPosition`          | `ButtonIconPosition` | "left"    | Position of the icon relative to the button label.                                                                                                                                                                                                |
+
+## Rules
+
+-   `styleType` is mandatory.
+-   Use sentence case for all labels — "Save changes" not "Save Changes".
+-   Use concise verb + noun labels — avoid "OK", "Yes", "Click here".
+-   Do not use `sizeType="large"` unless explicitly required — default size is correct for hero CTAs.
+-   Combine `loading` and `disabled` during async operations to prevent double-submission.
+-   Never use raw `<button>` elements — always use design system button components.
+-   Do not nest buttons inside buttons or links.
+-   `danger` applies to any `styleType`.
+
+## Anti-patterns
+
+-   Do not use `sizeType="large"` as a default choice — it is a special case only.
+-   Do not use `Button.Default`, `Button.Small`, or `Button.Large` — these sub-components are deprecated in v4.
+-   Do not use vague labels like "OK" or "Yes" — labels must describe the action.
+-   Do not use `loading` alone without also setting `disabled`.

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

@@ -0,0 +1,113 @@
+# Calendar
+
+Import: `import { Calendar } from "@lifesg/react-design-system/calendar"`
+
+## When to use
+
+-   Displaying an inline date picker when a full-page or panel calendar is preferable over a dropdown.
+-   Use `variant="single"` for standard single-date selection.
+-   Use `variant="multi"` when the user must pick multiple non-contiguous dates (e.g. recurring appointments).
+
+## Usage
+
+### variant="single" — single date selection
+
+```tsx
+import { useState } from "react";
+import { Calendar } from "@lifesg/react-design-system/calendar";
+
+const AppointmentCalendar = () => {
+    const [date, setDate] = useState("2024-06-15");
+
+    return (
+        <Calendar
+            variant="single"
+            value={date}
+            minDate="2024-01-01"
+            maxDate="2024-12-31"
+            onChange={(selected) => setDate(selected)}
+        />
+    );
+};
+```
+
+### variant="multi" — multiple date selection
+
+Note `values` (plural) and `onChange` receives the full updated array.
+
+```tsx
+import { useState } from "react";
+import { Calendar } from "@lifesg/react-design-system/calendar";
+
+const MultiDateCalendar = () => {
+    const [dates, setDates] = useState<string[]>([]);
+
+    return (
+        <Calendar
+            variant="multi"
+            values={dates}
+            minDate="2024-01-01"
+            maxDate="2024-12-31"
+            maxSelectable={5}
+            onChange={(selected) => setDates(selected)}
+        />
+    );
+};
+```
+
+## YearMonthDisplay
+
+| Prop    | Type     | Description                           |
+| ------- | -------- | ------------------------------------- |
+| `year`  | `number` | Current visible year in `YYYY` format |
+| `month` | `number` | Current visible month, 1–12           |
+
+## Props — `CalendarSingleProps`
+
+| Prop       | Type                        | Default  | Description                            |
+| ---------- | --------------------------- | -------- | -------------------------------------- |
+| `variant`  | `"single"`                  | "single" | —                                      |
+| `value`    | `string`                    | —        | Selected date in `YYYY-MM-DD` format   |
+| `onChange` | `((value: string) => void)` | —        | Called when the selected date changes. |
+| `onSelect` | `((value: string) => void)` | —        | Called when a date is selected.        |
+
+## Props — `CalendarMultiProps`
+
+| Prop            | Type                           | Default | Description                                   |
+| --------------- | ------------------------------ | ------- | --------------------------------------------- |
+| `variant` \*    | `"multi"`                      | —       | —                                             |
+| `values`        | `string[]`                     | —       | Selected dates in `YYYY-MM-DD` format         |
+| `minSelectable` | `number`                       | —       | Minimum number of dates that must be selected |
+| `maxSelectable` | `number`                       | —       | Maximum number of dates that can be selected  |
+| `onChange`      | `((values: string[]) => void)` | —       | Called when the selection changes.            |
+
+## Props — `CalendarProps`
+
+| Prop                       | Type                                  | Default    | Description                                                                                           |
+| -------------------------- | ------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------- |
+| `className`                | `string`                              | —          | —                                                                                                     |
+| `id`                       | `string`                              | —          | —                                                                                                     |
+| `styleType`                | `"no-border" \| "bordered"`           | "bordered" | Border style of the calendar container.                                                               |
+| `onHover`                  | `((value: string) => void)`           | —          | Called when a day cell is hovered.                                                                    |
+| `onYearMonthDisplayChange` | `((value: YearMonthDisplay) => void)` | —          | Called when the visible month or year changes.                                                        |
+| `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                            |
+| `variant`                  | `"single"`                            | "single"   | —                                                                                                     |
+| `onChange`                 | `((value: string) => void)`           | —          | Called when the selected date changes.                                                                |
+
+## Rules
+
+-   `variant="single"` uses `value: string` and `onChange: (date: string) => void`.
+-   `variant="multi"` uses `values: string[]` and `onChange: (dates: string[]) => void` — note the plural prop names.
+-   All dates must be in `YYYY-MM-DD` format.
+-   Use `minDate`/`maxDate` to constrain selectable range.
+-   Use `disabledDates` for specific non-selectable dates within the allowed range.
+
+## Anti-patterns
+
+-   Do not pass `value` to `variant="multi"` — the prop is `values` (plural).
+-   Do not pass `values` to `variant="single"` — the prop is `value` (singular).
+-   Do not use Calendar inside a form for simple date entry — prefer `Form.DateInput` for that pattern.

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

@@ -0,0 +1,43 @@
+# Card
+
+Import: `import { Card } from "@lifesg/react-design-system/card"`
+
+## When to use
+
+Use to visually group related content — information panels, form sections, list items, or grid tiles.
+
+## Usage
+
+```tsx
+import styles from "./Card.module.css";
+import { Card } from "@lifesg/react-design-system/card";
+import { Typography } from "@lifesg/react-design-system/typography";
+
+<Card>
+    <div className={styles.cardBody}>
+        <Typography.HeadingSM>Card title</Typography.HeadingSM>
+        <Typography.BodyMD>Card content goes here.</Typography.BodyMD>
+    </div>
+</Card>;
+```
+
+```css
+/* Card.module.css */
+.cardBody {
+    padding: var(--fds-spacing-24);
+}
+```
+
+## Rules
+
+-   Card has no default padding — use `spacing-24` internal padding and `spacing-16` gap between content items as the standard.
+-   Shadow (`Shadow["md-subtle"]`) is applied automatically — do not add `box-shadow` manually.
+-   Do not nest cards inside cards.
+-   Use Typography components for all text inside Card — not raw HTML elements.
+-   Combine with `Layout.Container` and `Layout.ColDiv` for responsive card grids.
+
+## Anti-patterns
+
+-   Adding `box-shadow` via CSS — the Card component already applies the correct elevation shadow.
+-   Using raw `<div>` with custom styling instead of Card when the DS Card fits the use case.
+-   Nesting `<Card>` inside another `<Card>`.

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

@@ -0,0 +1,53 @@
+# Checkbox
+
+Import: `import { Checkbox } from "@lifesg/react-design-system/checkbox"`
+
+## When to use
+
+-   Simple boolean selections where a compact tick-box is sufficient.
+-   Table row selection (single or "select all").
+-   Filter lists with multiple independent options.
+-   "Select all" patterns using the `indeterminate` state.
+
+Prefer `Toggle` over `Checkbox` when building form inputs that need a visible card-style label container.
+
+## Variants
+
+| `displaySize` | When to use                    |
+| ------------- | ------------------------------ |
+| `"default"`   | Standard use                   |
+| `"small"`     | Dense layouts, inline controls |
+
+## Usage
+
+```tsx
+import { Checkbox } from "@lifesg/react-design-system/checkbox";
+
+<label>
+    <Checkbox checked={agreed} onChange={(e) => {}} />I agree to the terms and
+    conditions
+</label>;
+```
+
+## Props
+
+| Prop                    | Type           | Default   | Description                                                                                                                                                                                                                                                            |
+| ----------------------- | -------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `checked`               | `boolean`      | —         | Controls the checked state of the checkbox. When omitted, the checkbox is uncontrolled.                                                                                                                                                                                |
+| `displaySize`           | `CheckboxSize` | "default" | Controls the visual size of the checkbox.                                                                                                                                                                                                                              |
+| `indeterminate`         | `boolean`      | —         | Puts the checkbox into an indeterminate visual and accessibility state.                                                                                                                                                                                                |
+| `focusableWhenDisabled` | `boolean`      | —         | Allows the checkbox to receive focus 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. |
+
+## Rules
+
+-   Always pair with a visible label — wrap in `<label>` or use `aria-label`.
+-   Use `indeterminate` for "select all" controls when only some items in a list are selected — not as a permanent state.
+-   Use the same `name` attribute when grouping checkboxes in a form.
+-   No dedicated `disabled` prop — use the inherited `disabled` from `InputHTMLAttributes`, or `focusableWhenDisabled` to retain focus while blocking interaction.
+-   `indeterminate` is a visual state; manage controlled `checked` separately.
+
+## Anti-patterns
+
+-   Do not use `indeterminate` as a permanent or final state — it is a transitional indicator only.
+-   Do not use `Checkbox` alone without a label — always provide accessible text.
+-   Do not use `Checkbox` when only one option from a set can be selected — use `RadioButton` instead.

package/skills/fds-build/resources/components/countdown-timer.md

@@ -0,0 +1,20 @@
+# CountdownTimer
+
+Import: `import { CountdownTimer } from "@lifesg/react-design-system/countdown-timer"`
+
+## Props
+
+| Prop               | Type                          | Default     | Description                                                                                                                                                                              |
+| ------------------ | ----------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `show` \*          | `boolean`                     | —           | Controls whether the timer is visible and actively counting down.                                                                                                                        |
+| `fixed`            | `boolean`                     | true        | When `true`, the timer switches to a fixed viewport overlay once its inline position scrolls out of view, keeping the countdown visible at all times.                                    |
+| `notifyTimer`      | `number`                      | —           | Remaining-seconds threshold at which the warning state activates. Once the countdown reaches this value, `onNotify` fires once and `onTick` fires every second until the timer finishes. |
+| `offset`           | `Offset`                      | —           | Fine-tunes the fixed overlay position on tablet and desktop viewports.                                                                                                                   |
+| `mobileOffset`     | `MobileOffset`                | { top: 80 } | Fine-tunes the fixed overlay position on mobile viewports.                                                                                                                               |
+| `align`            | `AlignPosition`               | "right"     | Side of the inline wrapper the fixed overlay is pinned to when scrolled into sticky mode.                                                                                                |
+| `onTick`           | `((seconds: number) => void)` | —           | Called every second with the remaining seconds once the countdown falls at or below `notifyTimer`.                                                                                       |
+| `onNotify`         | `(() => void)`                | —           | Called once when the remaining seconds first reach the `notifyTimer` threshold.                                                                                                          |
+| `onFinish`         | `(() => void)`                | —           | Called when the countdown reaches zero.                                                                                                                                                  |
+| `reminderInterval` | `number`                      | 120         | Interval in seconds between polite screen-reader announcement of the remaining time while the timer is above the `notifyTimer` threshold.                                                |
+| `timer` \*         | `number`                      | —           | Duration of the countdown in seconds.                                                                                                                                                    |
+| `timestamp`        | `number`                      | —           | —                                                                                                                                                                                        |