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

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

@@ -0,0 +1,51 @@
+# Input
+
+Import: `import { Input } from "@lifesg/react-design-system/input"`
+
+## When to use
+
+Use `Input` for standalone inputs that do not need a label or error message — search bars, inline editing, filter fields, or composition contexts where the form layout is provided externally. For all labelled form fields with validation messages, use `Form.Input` instead.
+
+## Variants
+
+| `styleType`            | When to use                                                                                                      |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `"bordered"` (default) | Standard standalone input — provides clear affordance                                                            |
+| `"no-border"`          | Inline editing or search bars embedded in headers/toolbars where a border would conflict with the surrounding UI |
+
+## Props — `InputProps`
+
+| Prop         | Type             | Default    | Description                                                                                                   |
+| ------------ | ---------------- | ---------- | ------------------------------------------------------------------------------------------------------------- |
+| `spacing`    | `number`         | —          | Inserts a space after every `spacing` characters in the displayed value. Only applies when `type` is `"tel"`. |
+| `error`      | `boolean`        | —          | Marks the input wrapper in an error state.                                                                    |
+| `allowClear` | `boolean`        | false      | Shows a clear button when the field has a value and is neither disabled nor read-only.                        |
+| `onClear`    | `() => void`     | —          | Called when the user activates the clear button. Use this to clear the controlled value.                      |
+| `styleType`  | `InputStyleType` | "bordered" | Visual style variant.                                                                                         |
+
+## Props — `InputPartialProps`
+
+| Prop         | Type             | Default    | Description                                                                                                   |
+| ------------ | ---------------- | ---------- | ------------------------------------------------------------------------------------------------------------- |
+| `spacing`    | `number`         | —          | Inserts a space after every `spacing` characters in the displayed value. Only applies when `type` is `"tel"`. |
+| `allowClear` | `boolean`        | false      | Shows a clear button when the field has a value and is neither disabled nor read-only.                        |
+| `onClear`    | `() => void`     | —          | Called when the user activates the clear button. Use this to clear the controlled value.                      |
+| `styleType`  | `InputStyleType` | "bordered" | Visual style variant.                                                                                         |
+
+## Rules
+
+-   Use `type="email"` for email fields and `type="tel"` for phone fields — triggers the correct mobile keyboard.
+-   Use `spacing` for formatted `tel` inputs (e.g. `spacing={4}` for `9123 4567`) — do not implement custom character splitting.
+-   Use `allowClear` for search inputs and optional fields; pair with `onClear` to reset the controlled value.
+-   Set `error={true}` to communicate an invalid state visually — provide a separate error message element in the surrounding layout.
+-   Use `styleType="no-border"` only when the surrounding container or background provides sufficient visual separation.
+-   `Input` is the bare input field with no label or error message wrapper. Use `Form.Input` when a label or validation message is needed.
+-   `spacing` only has effect when `type="tel"`.
+-   `styleType="no-border"` removes the visible border — use only when the surrounding context provides sufficient visual distinction.
+-   `error` drives error-state styling only; there is no built-in error message — pair with external error text if needed.
+
+## Anti-patterns
+
+-   Do not use `Input` inside a form that needs labels or validation messages — use `Form.Input`.
+-   Do not use `spacing` with input types other than `"tel"`.
+-   Do not rely on `Input` alone to surface error messages — it has no built-in error text slot.

package/skills/fds-build/resources/components/language-switcher.md

@@ -0,0 +1,15 @@
+# LanguageSwitcher
+
+Import: `import { LanguageSwitcher } from "@lifesg/react-design-system/language-switcher"`
+
+## Props — `LanguageSwitcherProps`
+
+| Prop               | Type                                         | Default    | Description                                                                |
+| ------------------ | -------------------------------------------- | ---------- | -------------------------------------------------------------------------- |
+| `variant`          | `LanguageSwitcherVariant`                    | "dropdown" | Presentation mode.                                                         |
+| `selectedLanguage` | `LanguageSwitcherCode`                       | "en"       | The currently active language code.                                        |
+| `onSelectLanguage` | `((language: LanguageSwitcherCode) => void)` | —          | Called when the user selects a language different from `selectedLanguage`. |
+
+## Rules
+
+-   `LanguageSwitcherCode` is the union of supported language codes: `"en" | "zh" | "ms" | "ta"`.

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

@@ -0,0 +1,156 @@
+# Layout
+
+Import: `import { Layout } from "@lifesg/react-design-system/layout"`
+
+## Composition
+
+```
+Layout.Container type="grid"        ← responsive 12-col grid (desktop) / 8-col (mobile)
+├── Layout.ColDiv xsCols lgCols     ← column span — always set xsCols
+├── Layout.ColDiv xsCols lgCols
+└── Layout.ColDiv xsCols lgCols
+
+Layout.Container type="flex"        ← horizontal flexbox row
+└── {children}
+
+Layout.Container type="flex-column" ← vertical flexbox column
+└── {children}
+```
+
+`Layout.Section` and `Layout.Content` share the same props as `Layout.Container` and can be used in place of it for semantic HTML structure. Never nest `Layout.Container` inside another `Layout.Container`. Always set `xsCols` on every `Layout.ColDiv` — never set only `lgCols`.
+
+-   `Layout.ColDiv` — responsive grid column div
+
+## Usage
+
+```tsx
+import { Layout } from "@lifesg/react-design-system/layout";
+
+<Layout.Container type="grid">
+    <Layout.ColDiv xsCols={8} lgCols={6}>
+        Content
+    </Layout.ColDiv>
+</Layout.Container>;
+```
+
+| `type`          | Use case                         |
+| --------------- | -------------------------------- |
+| `"grid"`        | Responsive column grid (default) |
+| `"flex"`        | Horizontal flexbox layout        |
+| `"flex-column"` | Vertical flexbox layout          |
+
+## Breakpoints
+
+| Breakpoint | Min width | Columns | Gutter | Device                |
+| ---------- | --------- | ------- | ------ | --------------------- |
+| `xxs`      | 0px       | 8       | 16px   | Smallest mobile       |
+| `xs`       | 321px     | 8       | 16px   | Small mobile          |
+| `sm`       | 376px     | 8       | 16px   | Mobile                |
+| `md`       | 481px     | 8       | 16px   | Large mobile / tablet |
+| `lg`       | 769px     | 12      | 32px   | Desktop               |
+| `xl`       | 1201px    | 12      | 32px   | Large desktop         |
+| `xxl`      | 1441px    | 12      | 32px   | Extra-large           |
+
+### Common column widths
+
+| Use case                             | `xsCols` | `lgCols` | `xlCols` |
+| ------------------------------------ | -------- | -------- | -------- |
+| Full width                           | 8        | 12       | —        |
+| Full width (form progress indicator) | 12       | 12       | —        |
+| Narrow content (forms)               | 12       | 9        | 8        |
+| Half-width (2-up cards)              | 8        | 6        | —        |
+| Third-width (3-up cards)             | 8        | 4        | —        |
+| Quarter-width (4-up metrics)         | 8        | 6        | 3        |
+| Sidebar                              | 8        | 3        | —        |
+| Main + sidebar main                  | 8        | 9        | —        |
+
+## Responsive styles
+
+Use CSS Module classes for responsive styles in v4. The `MediaQuery` breakpoint body classes replace `@media` queries in CSS Modules.
+
+```tsx
+import styles from "./MyComponent.module.css";
+
+<div className={styles.responsiveDiv}>...</div>;
+```
+
+```css
+/* MyComponent.module.css */
+.responsiveDiv {
+    padding: var(--fds-spacing-16);
+}
+
+:global(body.fds-breakpoint-lg-min) .responsiveDiv {
+    padding: var(--fds-spacing-32);
+}
+```
+
+| CSS Module selector                        | Query type          | When it applies                  |
+| ------------------------------------------ | ------------------- | -------------------------------- |
+| `:global(body.fds-breakpoint-md-min) .cls` | `min-width: 481px`  | md and up (tablet+)              |
+| `:global(body.fds-breakpoint-lg-min) .cls` | `min-width: 769px`  | lg and up (desktop+)             |
+| `:global(body.fds-breakpoint-md-max) .cls` | `max-width: 768px`  | md and below (mobile only)       |
+| `:global(body.fds-breakpoint-lg-max) .cls` | `max-width: 1200px` | lg and below (non-large-desktop) |
+
+Design mobile-first — define base styles for mobile, then override with `MinWidth` for larger screens.
+
+## Props — `ContainerProps`
+
+| Prop          | Type              | Default | Description                                               |
+| ------------- | ----------------- | ------- | --------------------------------------------------------- |
+| `type`        | `ContainerType`   | "flex"  | Display mode applied to the container.                    |
+| `children` \* | `React.ReactNode` | —       | —                                                         |
+| `stretch`     | `boolean`         | false   | Stretches the element to fill its container's full width. |
+
+## Props — `SectionProps`
+
+| Prop          | Type              | Default | Description                                               |
+| ------------- | ----------------- | ------- | --------------------------------------------------------- |
+| `children` \* | `React.ReactNode` | —       | —                                                         |
+| `stretch`     | `boolean`         | false   | Stretches the element to fill its container's full width. |
+
+## Props — `ContentProps`
+
+| Prop          | Type              | Default | Description                                               |
+| ------------- | ----------------- | ------- | --------------------------------------------------------- |
+| `type`        | `ContainerType`   | "flex"  | Display mode applied to the container.                    |
+| `children` \* | `React.ReactNode` | —       | —                                                         |
+| `stretch`     | `boolean`         | false   | Stretches the element to fill its container's full width. |
+
+## Props — `ColProps`
+
+| Prop      | Type      | Default | Description                                                                                                                                      |
+| --------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `xxlCols` | `ColSpan` | —       | Column span at the `xxl` breakpoint.                                                                                                             |
+| `xlCols`  | `ColSpan` | —       | Column span at the `xl` breakpoint.                                                                                                              |
+| `lgCols`  | `ColSpan` | —       | Column span at the `lg` breakpoint.                                                                                                              |
+| `mdCols`  | `ColSpan` | —       | Column span at the `md` breakpoint.                                                                                                              |
+| `smCols`  | `ColSpan` | —       | Column span at the `sm` breakpoint.                                                                                                              |
+| `xsCols`  | `ColSpan` | —       | Column span at the `xs` breakpoint.                                                                                                              |
+| `xxsCols` | `ColSpan` | —       | Column span at the `xxs` (smallest) breakpoint. Acts as the base value. All larger breakpoints fall back to this when their own prop is not set. |
+
+## Props — `ColDivProps`
+
+| Prop      | Type      | Default | Description                                                                                                                                      |
+| --------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `xxlCols` | `ColSpan` | —       | Column span at the `xxl` breakpoint.                                                                                                             |
+| `xlCols`  | `ColSpan` | —       | Column span at the `xl` breakpoint.                                                                                                              |
+| `lgCols`  | `ColSpan` | —       | Column span at the `lg` breakpoint.                                                                                                              |
+| `mdCols`  | `ColSpan` | —       | Column span at the `md` breakpoint.                                                                                                              |
+| `smCols`  | `ColSpan` | —       | Column span at the `sm` breakpoint.                                                                                                              |
+| `xsCols`  | `ColSpan` | —       | Column span at the `xs` breakpoint.                                                                                                              |
+| `xxsCols` | `ColSpan` | —       | Column span at the `xxs` (smallest) breakpoint. Acts as the base value. All larger breakpoints fall back to this when their own prop is not set. |
+
+## Rules
+
+-   Use CSS Modules for component-level styles — do not use plain inline styles for layout concerns.
+-   Use `:where(body.fds-breakpoint-{bp}-min)` selectors for responsive styles — never hardcoded pixel breakpoints.
+-   Use CSS custom properties for spacing (e.g. `var(--fds-spacing-16)`) — never hardcode pixel values.
+
+Grid rules:
+
+-   Always use `type="grid"` on Container for responsive column layouts.
+-   Always specify `xsCols` on ColDiv — mobile-first; never only `lgCols`.
+-   Max `xsCols` is 8 (mobile/tablet), max `lgCols` is 12 (desktop).
+-   Never nest `Layout.Container` inside another `Layout.Container`.
+-   A column span applies to all larger viewports until overridden.

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

@@ -0,0 +1,120 @@
+# LinkList
+
+Import: `import { LinkList } from "@lifesg/react-design-system/link-list"`
+
+## When to use
+
+Use to present a set of related links — related articles, resources, or quick-access shortcuts. Use `style="small"` for compact contexts such as sidebars or footnotes.
+
+## Sub-components
+
+### LinkListItemProps
+
+| Prop                   | Type                                                   | Default | Description                                        |
+| ---------------------- | ------------------------------------------------------ | ------- | -------------------------------------------------- |
+| `title`                | `string`                                               | —       | Link label — required                              |
+| `description`          | `string`                                               | —       | First-level supporting text below the title        |
+| `secondaryDescription` | `string`                                               | —       | Second-level supporting text below the description |
+| `options`              | `T`                                                    | —       | Custom properties to pass to the item              |
+| `onClick`              | `(event: React.MouseEvent<HTMLAnchorElement>) => void` | —       | Per-item click handler — overrides `onItemClick`   |
+| `data-testid`          | `string`                                               | —       | Test identifier for the item                       |
+
+Inherits `HTMLAnchorElement` attributes (e.g. `href`, `target`).
+
+### Custom labels
+
+| Prop       | Type     | Default       | Description                    |
+| ---------- | -------- | ------------- | ------------------------------ |
+| `viewMore` | `string` | `"View more"` | Label for the show-more button |
+| `viewLess` | `string` | `"View less"` | Label for the show-less button |
+
+## Variants
+
+| `style`     | Usage                                                  |
+| ----------- | ------------------------------------------------------ |
+| `"default"` | Standard size — use in main content areas              |
+| `"small"`   | Compact — use in sidebars, footnotes, or dense layouts |
+
+| `loadMode` | Usage                                                         |
+| ---------- | ------------------------------------------------------------- |
+| `"eager"`  | All items loaded upfront; use `maxShown` to collapse the list |
+| `"lazy"`   | Items fetched on demand; requires `loadMore` and `onLoadMore` |
+
+## Usage
+
+```tsx
+import { LinkList } from "@lifesg/react-design-system/link-list";
+
+<LinkList
+    items={[
+        {
+            title: "Apply for a grant",
+            description: "Find out if you qualify.",
+            href: "/grants/apply",
+        },
+        { title: "Check application status", href: "/grants/status" },
+        { title: "Download forms", href: "/grants/forms" },
+    ]}
+    maxShown={2}
+/>;
+```
+
+## Props — `LinkListItemProps`
+
+| Prop                   | Type                                                        | Default | Description                                                                                          |
+| ---------------------- | ----------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------- |
+| `title` \*             | `string \| JSX.Element`                                     | —       | Primary label displayed as the link text.                                                            |
+| `description`          | `string \| JSX.Element`                                     | —       | Secondary text shown below the title.                                                                |
+| `secondaryDescription` | `JSX.Element`                                               | —       | Additional content rendered below the description. Accepts a JSX element for rich secondary content. |
+| `options`              | `T`                                                         | —       | Arbitrary custom data passed through to the `onItemClick` callback.                                  |
+| `onClick`              | `\| ((event: React.MouseEvent<HTMLAnchorElement>) => void)` | —       | Called when an item is clicked. This overrides the `onItemClick` event handler.                      |
+
+## Props — `LinkListBaseProps`
+
+| Prop           | Type                                                                                      | Default   | Description                                                                                           |
+| -------------- | ----------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------- |
+| `items` \*     | `LinkListItemProps<T>[]`                                                                  | —         | The list of link items to render.                                                                     |
+| `style`        | `LinkListStyle`                                                                           | "default" | Visual size variant applied to all items.                                                             |
+| `className`    | `string`                                                                                  | —         | —                                                                                                     |
+| `onItemClick`  | `\| (( item: LinkListItemProps<T>, event: React.MouseEvent<HTMLAnchorElement> ) => void)` | —         | Component-level click handler called for every item click, unless the item defines its own `onClick`. |
+| `customLabels` | `\| { viewMore?: string; viewLess?: string; }`                                            | —         | Overrides the default toggle button labels.                                                           |
+
+## Props — `LinkListEagerProps`
+
+| Prop       | Type      | Default | Description                                                                                                                                                                               |
+| ---------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `loadMode` | `"eager"` | —       | When `"eager"`, all items are rendered immediately.                                                                                                                                       |
+| `maxShown` | `number`  | —       | Maximum number of items shown before the list is truncated. Items beyond this count are hidden until the user activates the toggle. When omitted, all items are shown without truncation. |
+
+## Props — `LinkListLazyProps`
+
+| Prop            | Type                          | Default | Description                                                                               |
+| --------------- | ----------------------------- | ------- | ----------------------------------------------------------------------------------------- |
+| `loadMode` \*   | `"lazy"`                      | —       | When `"lazy"`, items are loaded on demand.                                                |
+| `loadMore` \*   | `boolean`                     | —       | Whether more items are available to load. When `false`, the "View more" button is hidden. |
+| `onLoadMore` \* | `() => void \| Promise<void>` | —       | Called when the user activates the "View more" button.                                    |
+
+## Props — `LinkListProps`
+
+| Prop           | Type                                                                                      | Default   | Description                                                                                           |
+| -------------- | ----------------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------- |
+| `items` \*     | `LinkListItemProps<T>[]`                                                                  | —         | The list of link items to render.                                                                     |
+| `style`        | `LinkListStyle`                                                                           | "default" | Visual size variant applied to all items.                                                             |
+| `className`    | `string`                                                                                  | —         | —                                                                                                     |
+| `onItemClick`  | `\| (( item: LinkListItemProps<T>, event: React.MouseEvent<HTMLAnchorElement> ) => void)` | —         | Component-level click handler called for every item click, unless the item defines its own `onClick`. |
+| `customLabels` | `\| { viewMore?: string; viewLess?: string; }`                                            | —         | Overrides the default toggle button labels.                                                           |
+| `loadMode`     | `"eager"`                                                                                 | —         | When `"eager"`, all items are rendered immediately.                                                   |
+
+## Rules
+
+-   Use `maxShown` when the list has many items to avoid overwhelming the user on first load (eager mode).
+-   In `"lazy"` mode, both `loadMore` and `onLoadMore` are required.
+-   `onItemClick` applies to all items; per-item `onClick` in `LinkListItemProps` overrides it for that item.
+-   Use per-item `onClick` when individual items need different handling; use `onItemClick` for a uniform handler across all items.
+-   Use `description` to give users enough context to choose the right link without clicking.
+
+## Anti-patterns
+
+-   Using lazy mode without providing `onLoadMore` — the "View more" button will be non-functional.
+-   Omitting `description` when link titles are ambiguous.
+-   Using LinkList for non-link content — use a list or table instead.

package/skills/fds-build/resources/components/local-nav.md

@@ -0,0 +1,119 @@
+# LocalNav
+
+Import: `import { LocalNavMenu, LocalNavDropdown } from "@lifesg/react-design-system/local-nav"`
+
+## When to use
+
+Use to let users navigate between sections on the same page (in-page navigation). Two components exist for different breakpoints — use both together for full responsive coverage.
+
+## Sub-components
+
+`LocalNavMenu`, `LocalNavDropdown`
+
+## Variants
+
+| Component          | Viewport          | Behaviour                                                              |
+| ------------------ | ----------------- | ---------------------------------------------------------------------- |
+| `LocalNavMenu`     | Desktop           | Vertical link list fixed to the left of page content, sticky on scroll |
+| `LocalNavDropdown` | Tablet and mobile | Renders inline, then sticks to top of viewport after scroll            |
+
+## Usage
+
+```tsx
+import {
+    LocalNavMenu,
+    LocalNavDropdown,
+} from "@lifesg/react-design-system/local-nav";
+
+const navItems = [
+    { title: "Overview", id: "overview" },
+    { title: "Eligibility", id: "eligibility" },
+    { title: "How to apply", id: "how-to-apply" },
+];
+
+{
+    /* Desktop */
+}
+<LocalNavMenu
+    items={navItems}
+    selectedItemIndex={activeIndex}
+    onNavItemSelect={(e, item, index) => {}}
+/>;
+
+{
+    /* Mobile / tablet */
+}
+<LocalNavDropdown
+    items={navItems}
+    selectedItemIndex={activeIndex}
+    defaultLabel="Jump to section"
+    onNavItemSelect={(e, item, index) => {}}
+/>;
+```
+
+## Props — `TitleAddonProps`
+
+| Prop    | Type          | Default | Description                                                             |
+| ------- | ------------- | ------- | ----------------------------------------------------------------------- |
+| `left`  | `JSX.Element` | —       | Element rendered immediately before the title.                          |
+| `right` | `JSX.Element` | —       | Element rendered after the title, flushed to the far right of the item. |
+
+## Props — `LocalNavItemProps`
+
+| Prop         | Type                        | Default | Description                                                                                                                                                 |
+| ------------ | --------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title` \*   | `string \| React.ReactNode` | —       | —                                                                                                                                                           |
+| `id`         | `string`                    | —       | —                                                                                                                                                           |
+| `titleAddon` | `TitleAddonProps`           | —       | Optional addon element rendered alongside the item title. Ignored when a custom `renderItem` is provided, since the caller then controls the item's layout. |
+
+## Props — `LocalNavMenuItemRenderProps`
+
+| Prop          | Type      | Default | Description                                                  |
+| ------------- | --------- | ------- | ------------------------------------------------------------ |
+| `selected` \* | `boolean` | —       | Whether this item is the currently selected navigation item. |
+
+## Props — `LocalNavMenuProps`
+
+| Prop                 | Type                                                                                                                       | Default | Description                                      |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------ |
+| `renderItem`         | `\| (( item: LocalNavItemProps, renderProps: LocalNavMenuItemRenderProps ) => React.ReactNode)`                            | —       | Custom renderer for each navigation item.        |
+| `className`          | `string`                                                                                                                   | —       | —                                                |
+| `id`                 | `string`                                                                                                                   | —       | —                                                |
+| `onNavItemSelect` \* | `( e: React.MouseEvent<HTMLElement> \| React.KeyboardEvent<HTMLElement>, item: LocalNavItemProps, index: number ) => void` | —       | Called when a navigation item is activated.      |
+| `items` \*           | `LocalNavItemProps[]`                                                                                                      | —       | The list of navigation items to render.          |
+| `selectedItemIndex`  | `number`                                                                                                                   | —       | Zero-based index of the currently selected item. |
+
+## Props — `LocalNavDropdownItemRenderProps`
+
+| Prop          | Type      | Default | Description                                                                                                                                |
+| ------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `selected` \* | `boolean` | —       | Whether this item is the currently selected navigation item.                                                                               |
+| `stickied` \* | `boolean` | —       | Whether the dropdown is currently in its stickied (fixed) state. Use this to conditionally style items differently when the nav is pinned. |
+
+## Props — `LocalNavDropdownProps`
+
+| Prop                 | Type                                                                                                                       | Default | Description                                                                                                                                                                                                        |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `defaultLabel` \*    | `string \| React.ReactNode`                                                                                                | —       | Label shown in the collapsed trigger when no item is selected or when the dropdown is not stickied. Once the dropdown is stickied and an item is selected, the trigger displays the selected item's title instead. |
+| `stickyOffset`       | `number`                                                                                                                   | 0       | Distance in pixels from the top of the viewport while the dropdown is stickied.                                                                                                                                    |
+| `renderItem`         | `\| (( item: LocalNavItemProps, renderProps: LocalNavDropdownItemRenderProps ) => React.ReactNode)`                        | —       | Custom renderer for each item in the dropdown list.                                                                                                                                                                |
+| `className`          | `string`                                                                                                                   | —       | —                                                                                                                                                                                                                  |
+| `id`                 | `string`                                                                                                                   | —       | —                                                                                                                                                                                                                  |
+| `onNavItemSelect` \* | `( e: React.MouseEvent<HTMLElement> \| React.KeyboardEvent<HTMLElement>, item: LocalNavItemProps, index: number ) => void` | —       | Called when a navigation item is activated.                                                                                                                                                                        |
+| `items` \*           | `LocalNavItemProps[]`                                                                                                      | —       | The list of navigation items to render.                                                                                                                                                                            |
+| `selectedItemIndex`  | `number`                                                                                                                   | —       | Zero-based index of the currently selected item.                                                                                                                                                                   |
+
+## Rules
+
+-   Use `LocalNavMenu` on desktop and `LocalNavDropdown` on tablet/mobile — render both and show/hide with CSS breakpoints.
+-   Always implement scroll-spy: update `selectedItemIndex` as the user scrolls to keep the active item in sync with the visible section. This is not automatic.
+-   Place `LocalNavMenu` on the left side of the page content area — not above it.
+-   Set `stickyOffset` on `LocalNavDropdown` equal to the height of the fixed Navbar so the dropdown does not overlap it when sticky.
+-   Keep item labels short — long labels cause overflow.
+-   `defaultLabel` is required on `LocalNavDropdown` — it is the placeholder shown before any item is selected.
+
+## Anti-patterns
+
+-   Do not use `LocalNavMenu` on tablet or mobile — use `LocalNavDropdown` instead.
+-   Do not omit scroll-spy logic — without it, `selectedItemIndex` will not reflect the current section.
+-   Do not place `LocalNavMenu` above the content — it must be a left sidebar.

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

@@ -0,0 +1,14 @@
+# Masthead
+
+Import: `import { Masthead } from "@lifesg/react-design-system/masthead"`
+
+## Props
+
+| Prop      | Type      | Default | Description                                                                                                       |
+| --------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
+| `stretch` | `boolean` | false   | Allows the masthead to span the full width of its container rather than constraining to the default layout width. |
+
+## Rules
+
+-   No mandatory props.
+-   `Masthead` is typically included via the `Navbar` `masthead` prop — use this standalone component only when rendering the masthead outside a Navbar context.

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

@@ -0,0 +1,109 @@
+# Menu
+
+Import: `import { Menu } from "@lifesg/react-design-system/menu"`
+
+## When to use
+
+Use when a trigger element (button, avatar, nav link) should open a floating dropdown with a list of actions or links.
+
+Common use cases:
+
+-   Avatar / user account menu in authenticated dashboards
+-   Navbar link dropdown for sub-navigation
+
+## Sub-components
+
+`Menu`, `Menu.Content`, `Menu.Section`, `Menu.Item`, `Menu.Link`
+
+## Variants
+
+| Use case          | Structure                                                                                                                   |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| User account menu | First section: name + email as `Menu.Item`. Subsequent sections: `Menu.Link` for profile/settings, `Menu.Item` for sign out |
+| Nav link dropdown | Single `Menu.Section` with `Menu.Link` items                                                                                |
+| Action menu       | `Menu.Section` with `Menu.Item` elements and optional `label`                                                               |
+
+## Usage
+
+```tsx
+import { Menu } from "@lifesg/react-design-system/menu";
+import { Button } from "@lifesg/react-design-system/button";
+
+<Menu
+    menuContent={
+        <Menu.Content>
+            <Menu.Section showDivider={false}>
+                <Menu.Link href="/profile">Profile</Menu.Link>
+                <Menu.Link href="/settings">Settings</Menu.Link>
+            </Menu.Section>
+            <Menu.Section>
+                <Menu.Item label="Sign out" onClick={() => {}} />
+            </Menu.Section>
+        </Menu.Content>
+    }
+>
+    <Button styleType="secondary">Account</Button>
+</Menu>;
+```
+
+## Props — `MenuProps`
+
+| Prop               | Type                                         | Default            | Description                                                                                                                                                                     |
+| ------------------ | -------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `menuContent` \*   | `FunctionComponentElement<MenuContentProps>` | —                  | The `Menu.Content` element to display inside the popover panel.                                                                                                                 |
+| `position`         | `PopoverPosition`                            | "bottom-start"     | Preferred placement of the popover relative to the trigger.                                                                                                                     |
+| `children` \*      | `React.ReactNode`                            | —                  | The trigger element rendered inside a focusable wrapper div.                                                                                                                    |
+| `trigger`          | `PopoverTriggerType`                         | "click"            | Interaction that opens the popover.                                                                                                                                             |
+| `id`               | `string`                                     | —                  | —                                                                                                                                                                               |
+| `zIndex`           | `number`                                     | —                  | Overrides the stacking context z-index for the floating popover layer. Falls back to the inherited floating context z-index when omitted.                                       |
+| `className`        | `string`                                     | —                  | —                                                                                                                                                                               |
+| `rootNode`         | `RefObject<HTMLElement>`                     | document.body      | The root element that contains the popover element.                                                                                                                             |
+| `customOffset`     | `number`                                     | 16                 | Distance in pixels between the trigger element and the popover panel.                                                                                                           |
+| `delay`            | `\| { open?: number; close?: number }`       | —                  | Open and close delays in milliseconds. Only applies when `trigger` is `"hover"`.                                                                                                |
+| `enableFlip`       | `boolean`                                    | true               | Allows the popover to flip to the opposite side when the preferred position has insufficient viewport space.                                                                    |
+| `enableResize`     | `boolean`                                    | false              | Resizes the popover to fit the remaining vertical space in the viewport.                                                                                                        |
+| `overflow`         | `PopoverOverflowType`                        | "auto"             | CSS `overflow` value forwarded to the popover card when `enableResize` is active.                                                                                               |
+| `popoverAriaLabel` | `string`                                     | "More information" | Accessible label for the popover dialog element.                                                                                                                                |
+| `triggerOnFocus`   | `boolean`                                    | false              | Also opens the popover when the trigger element receives focus.                                                                                                                 |
+| `isModal`          | `boolean`                                    | true               | When `true`, focus is trapped inside the popover until dismissed. When `false`, the popover closes automatically once the user tabs away from both the trigger and the popover. |
+| `onPopoverAppear`  | `(() => void)`                               | —                  | Called when the popover becomes visible.                                                                                                                                        |
+| `onPopoverDismiss` | `(() => void)`                               | —                  | Called when the popover is dismissed.                                                                                                                                           |
+
+## Props — `MenuContentProps`
+
+| Prop          | Type                                                                 | Default | Description                                                      |
+| ------------- | -------------------------------------------------------------------- | ------- | ---------------------------------------------------------------- |
+| `children` \* | `ReactElement<MenuSectionProps> \| ReactElement<MenuSectionProps>[]` | —       | One or more `Menu.Section` elements that make up the panel body. |
+| `overflow`    | `PopoverOverflowType`                                                | —       | CSS `overflow` value applied to the popover card body.           |
+| `maxHeight`   | `number`                                                             | —       | Maximum height of the popover card in pixels.                    |
+
+## Props — `MenuSectionProps`
+
+| Prop          | Type                                   | Default | Description                                                                                                                                                                                                                                      |
+| ------------- | -------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `children` \* | `MenuSectionItem \| MenuSectionItem[]` | —       | One or more `Menu.Item` or `Menu.Link` elements within this section.                                                                                                                                                                             |
+| `showDivider` | `boolean`                              | true    | Whether to render a top divider separating this section from the one above.                                                                                                                                                                      |
+| `columns`     | `number`                               | —       | Renders section children in a grid with the given number of columns on desktop. Items flow vertically (top-to-bottom) within each column before wrapping to the next. Has no effect on mobile viewports, which always render as a single column. |
+| `label`       | `string`                               | —       | Accessible group label rendered above the section items.                                                                                                                                                                                         |
+
+## Props — `MenuItemProps`
+
+| Prop       | Type     | Default | Description                                        |
+| ---------- | -------- | ------- | -------------------------------------------------- |
+| `label`    | `string` | —       | Primary text label.                                |
+| `subLabel` | `string` | —       | Secondary descriptive text rendered below `label`. |
+
+## Rules
+
+-   `Menu` wraps a trigger element as its child — the trigger can be any element (e.g. `Avatar`, `Button`, `NavbarLink`).
+-   Pass `Menu.Content` as the `menuContent` prop — not as a child of `Menu`.
+-   Use `Menu.Link` for navigation (href-based); use `Menu.Item` for in-page actions (onClick-based).
+-   Use `Menu.Section` with `showDivider` to visually separate unrelated groups of actions.
+-   For user account menus, always show the user's name and email as the first section.
+-   Use `position` to control which side of the trigger the menu appears on; default `"bottom-start"` suits most cases.
+
+## Anti-patterns
+
+-   Do not pass `Menu.Content` as a child of `Menu` — it must be passed as `menuContent`.
+-   Do not mix navigation links and action items in the same `Menu.Section` without a divider.
+-   Do not use `Menu.Item` for links that navigate to a new page — use `Menu.Link` instead.