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

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

@@ -0,0 +1,150 @@
+# ModalV2
+
+Import: `import { ModalV2 } from "@lifesg/react-design-system/modal-v2"`
+
+## When to use
+
+Use for focused interactions that interrupt the user's flow — confirmations, detail views, or short multi-field forms that do not warrant a new page.
+
+> **Note:** `Modal` is deprecated. Use `ModalV2` — it provides improved scroll behaviour, proper focus management via `@floating-ui/react`, and a composable slot-based API.
+
+## Sub-components
+
+`ModalV2`, `ModalV2.Card`, `ModalV2.Header`, `ModalV2.Content`, `ModalV2.Footer`, `ModalV2.CloseButton`
+
+## Variants
+
+| Use case            | Structure                                                        |
+| ------------------- | ---------------------------------------------------------------- |
+| Confirmation dialog | `ModalV2.Header` + `ModalV2.Content` + `ModalV2.Footer`          |
+| Detail view         | `ModalV2.Header` (close only, no title) + `ModalV2.Content`      |
+| Short form          | `ModalV2.Header` + `ModalV2.Content` (fields) + `ModalV2.Footer` |
+
+## Usage
+
+### Confirmation dialog
+
+```tsx
+import { useState } from "react";
+import { ModalV2 } from "@lifesg/react-design-system/modal-v2";
+import { Button } from "@lifesg/react-design-system/button";
+import { Typography } from "@lifesg/react-design-system/typography";
+
+const ConfirmDeleteModal = () => {
+    const [show, setShow] = useState(false);
+
+    const handleClose = () => setShow(false);
+
+    const handleConfirm = () => {
+        // perform action
+        setShow(false);
+    };
+
+    return (
+        <>
+            <Button onClick={() => setShow(true)}>Delete item</Button>
+
+            <ModalV2
+                show={show}
+                onClose={handleClose}
+                enableOverlayClick
+                onOverlayClick={handleClose}
+            >
+                <ModalV2.Card>
+                    <ModalV2.Header title="Delete this item?" />
+                    <ModalV2.Content>
+                        <Typography.BodyBL>
+                            This action cannot be undone.
+                        </Typography.BodyBL>
+                    </ModalV2.Content>
+                    <ModalV2.Footer
+                        primaryButton={
+                            <Button onClick={handleConfirm}>Confirm</Button>
+                        }
+                        secondaryButton={
+                            <Button styleType="secondary" onClick={handleClose}>
+                                Cancel
+                            </Button>
+                        }
+                    />
+                </ModalV2.Card>
+            </ModalV2>
+        </>
+    );
+};
+```
+
+### Detail view (close button only, no title)
+
+```tsx
+<ModalV2 show={show} onClose={handleClose}>
+    <ModalV2.Card>
+        <ModalV2.Header />
+        <ModalV2.Content>
+            <Typography.BodyBL>Supplementary details here.</Typography.BodyBL>
+        </ModalV2.Content>
+    </ModalV2.Card>
+</ModalV2>
+```
+
+## Props — `ModalCardProps`
+
+| Prop          | Type                        | Default | Description                                                                                                                       |
+| ------------- | --------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `children` \* | `React.ReactNode`           | —       | —                                                                                                                                 |
+| `elementRef`  | `React.Ref<HTMLDivElement>` | —       | Ref to the modal card DOM element. When used within `Modal`, the default `ref` is not available and you can specify this instead. |
+| `fullscreen`  | `boolean`                   | —       | When `true`, the card expands to fill the viewport with no border-radius, padding, or box-shadow.                                 |
+
+## Props — `ModalHeaderProps`
+
+| Prop                  | Type                | Default | Description                                                                                                                    |
+| --------------------- | ------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `title`               | `string`            | —       | Heading text rendered in the header. Always centered regardless of `closeButtonPosition`. Omit for a close-button-only header. |
+| `closeButtonPosition` | `"left" \| "right"` | "right" | Which side of the header the close button is placed on. The title alignment adjusts automatically.                             |
+
+## Props — `ModalContentProps`
+
+| Prop          | Type              | Default | Description |
+| ------------- | ----------------- | ------- | ----------- |
+| `children` \* | `React.ReactNode` | —       | —           |
+
+## Props — `ModalFooterProps`
+
+| Prop              | Type              | Default | Description                                     |
+| ----------------- | ----------------- | ------- | ----------------------------------------------- |
+| `primaryButton`   | `React.ReactNode` | —       | Node rendered in the primary action position.   |
+| `secondaryButton` | `React.ReactNode` | —       | Node rendered in the secondary action position. |
+
+## Props — `ModalV2Props`
+
+| Prop                    | Type                      | Default  | Description                                                                                                                                             |
+| ----------------------- | ------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `show` \*               | `boolean`                 | false    | Controls whether the modal is visible.                                                                                                                  |
+| `children` \*           | `React.JSX.Element`       | —        | The content of the modal. The parent element must be a valid HTML element or a component that forwards a ref to a valid HTML element.                   |
+| `animationFrom`         | `ModalAnimationDirection` | "bottom" | Direction from which the modal animates in and out.                                                                                                     |
+| `enableOverlayClick`    | `boolean`                 | true     | Whether clicking the overlay backdrop triggers `onOverlayClick`. The caller is responsible for dismissing the modal in the callback.                    |
+| `rootComponentId`       | `string`                  | —        | The `id` of the DOM element to portal the modal into.                                                                                                   |
+| `zIndex`                | `number`                  | —        | The z-index applied to the overlay stack.                                                                                                               |
+| `onClose`               | `(() => void)`            | —        | Called when the modal is dismissed via the Escape key and close button.                                                                                 |
+| `onOverlayClick`        | `(() => void)`            | —        | Called when the overlay backdrop is clicked and `enableOverlayClick` is `true`.                                                                         |
+| `dismissKeyboardOnShow` | `boolean`                 | true     | Blurs the currently focused element when the modal becomes visible, dismissing the on-screen keyboard on mobile to prevent it from obscuring the modal. |
+| `disableInitialFocus`   | `boolean`                 | false    | Disables automatic focus on the modal container when it opens. When `true`, the consumer is responsible for focusing an element within the modal.       |
+
+## Rules
+
+-   Always pass `onClose` to `ModalV2` — it is used by `ModalV2.Header` / `ModalV2.CloseButton` via context.
+-   Always wrap content in `ModalV2.Card` — it handles internal layout of slots.
+-   Use `ModalV2.Header` (not `ModalV2.CloseButton`) when the modal has a title — the header provides the close button automatically.
+-   Use `ModalV2.CloseButton` only for custom layouts where `ModalV2.Header` is not present.
+-   Pass action buttons to `ModalV2.Footer` via `primaryButton` / `secondaryButton` — do not place them inside `ModalV2.Content`.
+-   Provide `enableOverlayClick` + `onOverlayClick` together to allow overlay dismissal.
+-   Use `animationFrom="bottom"` for mobile-friendly sheet-style modals.
+-   Keep modal content focused — one task or decision per modal.
+
+## Anti-patterns
+
+-   Do not use the deprecated `Modal` — use `ModalV2`.
+-   Do not pass a Fragment as the direct child of `ModalV2` — use `ModalV2.Card` or a forwardRef component.
+-   Do not put buttons inside `ModalV2.Content` — use `ModalV2.Footer`.
+-   Do not stack modals unless using `zIndex` explicitly.
+-   Do not use modals for complex multi-step forms — navigate to a dedicated page instead.

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

@@ -0,0 +1,270 @@
+# Navbar
+
+Import: `import { Navbar } from "@lifesg/react-design-system/navbar"`
+
+## When to use
+
+Place at the top of every page. Required on all pages. Automatically collapses navigation items into a hamburger drawer on mobile.
+
+## Variants
+
+| `layout`    | When to use                                     |
+| ----------- | ----------------------------------------------- |
+| `"default"` | Centered content container — standard pages     |
+| `"stretch"` | Full-width content — must match Footer `layout` |
+
+## Usage
+
+### Complete Navbar with link items, a submenu, and an action button
+
+`NavItemProps` is a discriminated union on `itemType`. The default (no `itemType`) is a link item. Use `itemType: "component"` for custom elements like an avatar with a dropdown.
+
+```tsx
+import { useState } from "react";
+import { Navbar } from "@lifesg/react-design-system/navbar";
+
+const AppNavbar = () => {
+    const [selectedId, setSelectedId] = useState("home");
+
+    return (
+        <Navbar
+            masthead
+            selectedId={selectedId}
+            onItemClick={(item) => item.id && setSelectedId(item.id)}
+            items={{
+                desktop: [
+                    // itemType defaults to "link"
+                    {
+                        id: "home",
+                        children: "Home",
+                        href: "/",
+                    },
+                    {
+                        id: "guides",
+                        children: "Guides",
+                        href: "/guides",
+                        // subMenu items share the same shape as top-level link items
+                        subMenu: [
+                            {
+                                id: "guides-start",
+                                children: "Getting started",
+                                href: "/guides/start",
+                            },
+                            {
+                                id: "guides-api",
+                                children: "API reference",
+                                href: "/guides/api",
+                            },
+                        ],
+                    },
+                    {
+                        // itemType: "component" — renders arbitrary JSX; no href or id needed
+                        itemType: "component",
+                        children: <UserAvatar />,
+                    },
+                ],
+            }}
+            actionButtons={{
+                desktop: [
+                    {
+                        type: "button",
+                        args: { children: "Log in", styleType: "secondary" },
+                    },
+                ],
+            }}
+            resources={{
+                primary: { brandName: "MyService", logoSrc: "/logo.svg" },
+            }}
+        />
+    );
+};
+```
+
+Key points:
+
+-   Omit `itemType` (or set `itemType: "link"`) for standard anchor items.
+-   `subMenu` accepts the same `NavItemCommonProps` shape as top-level items.
+-   `itemType: "component"` items take `children: JSX.Element`; they do not accept `id`, `href`, or `subMenu`.
+-   `selectedId` matches against the `id` field of link items to highlight the active page.
+
+## Props — `NavItemLinkProps`
+
+| Prop             | Type                       | Default     | Description                                                                                                                                                                                                                                     |
+| ---------------- | -------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `itemType`       | `"link"`                   | —           | —                                                                                                                                                                                                                                               |
+| `subMenu`        | `NavItemCommonProps<T>[]`  | —           | —                                                                                                                                                                                                                                               |
+| `subMenuColumns` | `number`                   | —           | Renders `subMenu` as a multi-column layout on desktop. Items flow vertically (top-to-bottom) within each column before wrapping to the next. Has no effect on the mobile drawer, which always renders `subMenu` as an expandable vertical list. |
+| `id` \*          | `string`                   | —           | —                                                                                                                                                                                                                                               |
+| `options`        | `T`                        | —           | Arbitrary data passed through to callback arguments such as `onItemClick`.                                                                                                                                                                      |
+| `weight`         | `TypographyWeight`         | "regular"   | Font weight of the link text.                                                                                                                                                                                                                   |
+| `external`       | `boolean`                  | —           | Appends an external-link icon after the link text to signal that the destination is outside the current site.                                                                                                                                   |
+| `underlineStyle` | `TypographyUnderlineStyle` | "underline" | Text-decoration style for the link.                                                                                                                                                                                                             |
+
+## Props — `NavItemComponentProps`
+
+| Prop          | Type          | Default | Description |
+| ------------- | ------------- | ------- | ----------- |
+| `itemType` \* | `"component"` | —       | —           |
+| `children` \* | `JSX.Element` | —       | —           |
+
+## Props — `NavItemCommonProps`
+
+| Prop             | Type                       | Default     | Description                                                                                                   |
+| ---------------- | -------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------- |
+| `id` \*          | `string`                   | —           | —                                                                                                             |
+| `options`        | `T`                        | —           | Arbitrary data passed through to callback arguments such as `onItemClick`.                                    |
+| `weight`         | `TypographyWeight`         | "regular"   | Font weight of the link text.                                                                                 |
+| `external`       | `boolean`                  | —           | Appends an external-link icon after the link text to signal that the destination is outside the current site. |
+| `underlineStyle` | `TypographyUnderlineStyle` | "underline" | Text-decoration style for the link.                                                                           |
+
+## Props — `NavItemsProps`
+
+| Prop         | Type                | Default | Description                                                                |
+| ------------ | ------------------- | ------- | -------------------------------------------------------------------------- |
+| `desktop` \* | `NavItemProps<T>[]` | —       | Items rendered in the desktop navbar.                                      |
+| `mobile`     | `NavItemProps<T>[]` | —       | Items rendered in the mobile drawer. Falls back to `desktop` when omitted. |
+
+## Props — `NavbarActionButtonDownloadProps`
+
+| Prop            | Type          | Default | Description                                                                                            |
+| --------------- | ------------- | ------- | ------------------------------------------------------------------------------------------------------ |
+| `type` \*       | `"download"`  | —       | —                                                                                                      |
+| `args`          | `ButtonProps` | —       | —                                                                                                      |
+| `uncollapsible` | `boolean`     | false   | When `true`, the button remains visible outside the mobile drawer rather than being collapsed into it. |
+
+## Props — `NavbarActionButtonCtaProps`
+
+| Prop            | Type          | Default | Description                                                                                            |
+| --------------- | ------------- | ------- | ------------------------------------------------------------------------------------------------------ |
+| `type` \*       | `"button"`    | —       | —                                                                                                      |
+| `args` \*       | `ButtonProps` | —       | —                                                                                                      |
+| `uncollapsible` | `boolean`     | false   | When `true`, the button remains visible outside the mobile drawer rather than being collapsed into it. |
+
+## Props — `NavbarActionButtonComponentProps`
+
+| Prop            | Type                         | Default | Description                                                                                            |
+| --------------- | ---------------------------- | ------- | ------------------------------------------------------------------------------------------------------ |
+| `type` \*       | `"component"`                | —       | —                                                                                                      |
+| `args`          | `NavbarButtonComponentProps` | —       | —                                                                                                      |
+| `uncollapsible` | `boolean`                    | false   | When `true`, the button remains visible outside the mobile drawer rather than being collapsed into it. |
+
+## Props — `NavbarActionButtonsProps`
+
+| Prop         | Type                  | Default | Description                                                                         |
+| ------------ | --------------------- | ------- | ----------------------------------------------------------------------------------- |
+| `desktop` \* | `NavbarButtonProps[]` | —       | Action buttons rendered in the desktop navbar.                                      |
+| `mobile`     | `NavbarButtonProps[]` | —       | Action buttons rendered in the mobile drawer. Falls back to `desktop` when omitted. |
+
+## Props — `NavbarBrandingProps`
+
+| Prop           | Type     | Default | Description                                                 |
+| -------------- | -------- | ------- | ----------------------------------------------------------- |
+| `brandName` \* | `string` | —       | The name of the brand, used for accessibility and alt text. |
+| `logoSrc` \*   | `string` | —       | The source URL for the brand logo image.                    |
+
+## Props — `NavbarResourcesProps`
+
+| Prop        | Type                  | Default | Description                                                         |
+| ----------- | --------------------- | ------- | ------------------------------------------------------------------- |
+| `primary`   | `NavbarBrandingProps` | —       | When omitted, a default logo derived from the active theme is used. |
+| `secondary` | `NavbarBrandingProps` | —       | When omitted, the secondary brand slot is hidden.                   |
+
+## Props — `NavbarSharedProps`
+
+| Prop                | Type                       | Default | Description                                                                |
+| ------------------- | -------------------------- | ------- | -------------------------------------------------------------------------- |
+| `resources`         | `NavbarResourcesProps`     | —       | Branding and logo resources for the navbar.                                |
+| `actionButtons`     | `NavbarActionButtonsProps` | —       | Action buttons rendered in the navbar and mobile drawer.                   |
+| `hideNavBranding`   | `boolean`                  | false   | Hides all brand logos from the navbar and drawer.                          |
+| `hideLinkIndicator` | `boolean`                  | false   | Hides the active-item underline indicator across desktop and drawer views. |
+
+## Props — `NavbarDrawerProps`
+
+| Prop                | Type                                                                           | Default | Description                                                                         |
+| ------------------- | ------------------------------------------------------------------------------ | ------- | ----------------------------------------------------------------------------------- |
+| `show` \*           | `boolean`                                                                      | —       | Controls whether the drawer is visible.                                             |
+| `children` \*       | `JSX.Element \| JSX.Element[]`                                                 | —       | —                                                                                   |
+| `onClose`           | `(() => void)`                                                                 | —       | Called when the drawer requests to be closed via the close button or overlay click. |
+| `onBrandClick`      | `\| (( event: React.MouseEvent<HTMLAnchorElement>, type: BrandType ) => void)` | —       | Called when a brand logo inside the drawer is clicked.                              |
+| `drawerLabel`       | `string`                                                                       | —       | Accessible label announced for the mobile navigation drawer.                        |
+| `mobileMenuRef`     | `React.RefObject<HTMLButtonElement>`                                           | —       | Ref to the mobile menu button used to return focus when the drawer closes.          |
+| `resources`         | `NavbarResourcesProps`                                                         | —       | Branding and logo resources for the navbar.                                         |
+| `actionButtons`     | `NavbarActionButtonsProps`                                                     | —       | Action buttons rendered in the navbar and mobile drawer.                            |
+| `hideNavBranding`   | `boolean`                                                                      | false   | Hides all brand logos from the navbar and drawer.                                   |
+| `hideLinkIndicator` | `boolean`                                                                      | false   | Hides the active-item underline indicator across desktop and drawer views.          |
+
+## Props — `NavbarProps`
+
+| Prop                        | Type                                                            | Default                | Description                                                                                                                                        |
+| --------------------------- | --------------------------------------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `items` \*                  | `NavItemsProps<T>`                                              | —                      | —                                                                                                                                                  |
+| `className`                 | `string`                                                        | —                      | —                                                                                                                                                  |
+| `id`                        | `string`                                                        | —                      | —                                                                                                                                                  |
+| `selectedId`                | `string`                                                        | —                      | The currently selected navigation item identifier. Must match the `id` of one of the rendered items.                                               |
+| `compress`                  | `boolean`                                                       | false                  | Reduces the height and logo size of the navbar.                                                                                                    |
+| `fixed`                     | `boolean`                                                       | true                   | Pins the navbar to the top of the viewport while the page scrolls.                                                                                 |
+| `drawerDismissalExclusions` | `DrawerDismissalMethod[]`                                       | —                      | Drawer dismissal methods that should be suppressed. The drawer will not close when the user performs any of the listed actions.                    |
+| `hideNavElements`           | `boolean`                                                       | false                  | Hides nav items and action buttons, leaving only the brand area visible.                                                                           |
+| `onBrandClick`              | `((type: BrandType) => void)`                                   | —                      | Called when a brand logo is clicked. `type` identifies which brand slot was activated.                                                             |
+| `onItemClick`               | `\| ((item: NavItemProps<T> \| NavItemCommonProps<T>) => void)` | —                      | Called when a navigation item is activated from the desktop bar or the mobile drawer. The item's full props object is passed as the argument.      |
+| `onActionButtonClick`       | `\| ((actionButton: NavbarButtonProps) => void)`                | —                      | Called when an action button without its own `onClick` handler is activated. The button's full props object is passed as the argument.             |
+| `masthead`                  | `boolean`                                                       | true                   | Renders the `Masthead` (SGDS official government banner) above the navbar.                                                                         |
+| `layout`                    | `"default" \| "stretch"`                                        | "default"              | Controls how the navbar content fills its container. `"stretch"` expands to the full container width; `"default"` uses the standard content width. |
+| `headerLabel`               | `string`                                                        | "Main navigation menu" | Accessible label announced for the main navigation header.                                                                                         |
+| `drawerLabel`               | `string`                                                        | —                      | Accessible label announced for the mobile navigation drawer.                                                                                       |
+| `resources`                 | `NavbarResourcesProps`                                          | —                      | Branding and logo resources for the navbar.                                                                                                        |
+| `actionButtons`             | `NavbarActionButtonsProps`                                      | —                      | Action buttons rendered in the navbar and mobile drawer.                                                                                           |
+| `hideNavBranding`           | `boolean`                                                       | false                  | Hides all brand logos from the navbar and drawer.                                                                                                  |
+| `hideLinkIndicator`         | `boolean`                                                       | false                  | Hides the active-item underline indicator across desktop and drawer views.                                                                         |
+
+## Props — `NavItemProps`
+
+| Prop          | Type          | Default | Description |
+| ------------- | ------------- | ------- | ----------- |
+| `itemType` \* | `"component"` | —       | —           |
+| `children` \* | `JSX.Element` | —       | —           |
+
+## Props — `NavbarButtonProps`
+
+| Prop            | Type          | Default | Description                                                                                            |
+| --------------- | ------------- | ------- | ------------------------------------------------------------------------------------------------------ |
+| `type` \*       | `"download"`  | —       | —                                                                                                      |
+| `args`          | `ButtonProps` | —       | —                                                                                                      |
+| `uncollapsible` | `boolean`     | false   | When `true`, the button remains visible outside the mobile drawer rather than being collapsed into it. |
+
+## Props — `NavbarDrawerApi`
+
+| Prop               | Type         | Default | Description                                                                   |
+| ------------------ | ------------ | ------- | ----------------------------------------------------------------------------- |
+| `dismissDrawer` \* | `() => void` | —       | Programmatically closes the mobile navigation drawer with its exit animation. |
+
+## Props — `NavbarDrawerHandle`
+
+| Prop               | Type         | Default | Description                                                                   |
+| ------------------ | ------------ | ------- | ----------------------------------------------------------------------------- |
+| `dismissDrawer` \* | `() => void` | —       | Programmatically closes the mobile navigation drawer with its exit animation. |
+
+## Rules
+
+-   Always set `masthead` — all government services must display the masthead.
+-   Always provide a meaningful `id` on each `NavItemCommonProps` item — used by `selectedId` to highlight the active page.
+-   `items.desktop` is required; the component crashes without it.
+-   `items.mobile` is optional — falls back to `desktop` if omitted.
+-   `layout` must match the `Footer` `layout` prop; do not mix `"default"` and `"stretch"`.
+-   Limit action buttons to 2–3 maximum.
+-   Use SVG format for brand logos.
+-   When using `fixed`, add corresponding top padding to page content to prevent overlap.
+-   Set `uncollapsible: true` on action buttons that must remain visible on mobile (e.g. avatar).
+-   Use `itemType: "component"` for custom nav elements such as an avatar with a `Menu` dropdown.
+-   Pass `type: "component"` with `args: { render: <Element /> }` for custom action button elements.
+-   `BrandType` is `"primary" | "secondary"` — passed to `onBrandClick`.
+-   The `"download"` button type is pre-programmed for LifeSG purposes.
+-   `NavbarButtonComponentProps` accepts a `render: JSX.Element` field for custom components.
+
+## Anti-patterns
+
+-   Do not omit `masthead` — it is required for government compliance.
+-   Do not supply a custom `resources.primary.logoSrc` unless the service has its own brand logo — omit `resources` to let the theme render its built-in logo.
+-   Do not use `hideNavElements` as a default state — it is for special page states only (e.g. maintenance).
+-   Do not use `fixed: false` unless the layout explicitly requires a non-fixed header.
+-   Do not add more than 3 action buttons — the navbar becomes visually cluttered.

package/skills/fds-build/resources/components/notification-banner.md

@@ -0,0 +1,106 @@
+# NotificationBanner
+
+Import: `import { NotificationBanner } from "@lifesg/react-design-system/notification-banner"`
+
+## When to use
+
+Use for notices that must always be visible to the user — maintenance windows, policy changes, mandatory announcements. Unlike Toast, it does not auto-dismiss. Unlike Alert, it applies to the entire page, not a specific section.
+
+## Sub-components
+
+-   `NotificationBanner.Link` — Inherits `TypographyLinkProps`. Use for links within banner content.
+
+## HOC
+
+```ts
+withNotificationBanner(data: NotificationContentAttributes[])
+```
+
+### NotificationContentAttributes
+
+| Prop              | Type                                       | Default | Description                                      |
+| ----------------- | ------------------------------------------ | ------- | ------------------------------------------------ |
+| `type`            | `"text"` \| `"link"`                       | —       | Type of content — required                       |
+| `content`         | `string`                                   | —       | Text content — required                          |
+| `otherAttributes` | `TypographyLinkProps` \| `TypographyProps` | —       | Additional props passed to the content component |
+
+## Usage
+
+```tsx
+import { NotificationBanner } from "@lifesg/react-design-system/notification-banner";
+
+<NotificationBanner dismissible sticky onDismiss={() => {}}>
+    Scheduled maintenance on 1 Feb 2026, 2–4 AM.{" "}
+    <NotificationBanner.Link href="/status">
+        View status
+    </NotificationBanner.Link>
+</NotificationBanner>;
+```
+
+## Props — `NotificationBannerProps`
+
+| Prop                 | Type                                            | Default | Description                                                                                                                                            |
+| -------------------- | ----------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `children`           | `React.ReactNode`                               | —       | —                                                                                                                                                      |
+| `dismissible`        | `boolean`                                       | true    | Whether the dismiss button is rendered. The caller is responsible for dismissing the banner in the callback.                                           |
+| `visible`            | `boolean`                                       | true    | Controls the visibility of the banner.                                                                                                                 |
+| `sticky`             | `boolean`                                       | true    | Whether the banner sticks to the top of the viewport while the page scrolls.                                                                           |
+| `icon`               | `JSX.Element`                                   | —       | An optional icon element rendered at the leading edge of the banner.                                                                                   |
+| `onDismiss`          | `(() => void)`                                  | —       | Called when the user activates the dismiss button and `dismissible` is `true`.                                                                         |
+| `maxCollapsedHeight` | `number`                                        | —       | Maximum height in pixels for the content area. When the rendered content exceeds this value, the overflow is clipped.                                  |
+| `actionButton`       | `React.ButtonHTMLAttributes<HTMLButtonElement>` | —       | An action button rendered inside the content area. When `actionButton.onClick` is provided it stops propagation to the banner's own `onClick` handler. |
+
+## Props — `NotificationBannerWithForwardedRefProps`
+
+| Prop                 | Type                                            | Default | Description                                                                                                                                            |
+| -------------------- | ----------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `forwardedRef`       | `React.Ref<HTMLDivElement>`                     | —       | —                                                                                                                                                      |
+| `children`           | `React.ReactNode`                               | —       | —                                                                                                                                                      |
+| `dismissible`        | `boolean`                                       | true    | Whether the dismiss button is rendered. The caller is responsible for dismissing the banner in the callback.                                           |
+| `visible`            | `boolean`                                       | true    | Controls the visibility of the banner.                                                                                                                 |
+| `sticky`             | `boolean`                                       | true    | Whether the banner sticks to the top of the viewport while the page scrolls.                                                                           |
+| `icon`               | `JSX.Element`                                   | —       | An optional icon element rendered at the leading edge of the banner.                                                                                   |
+| `onDismiss`          | `(() => void)`                                  | —       | Called when the user activates the dismiss button and `dismissible` is `true`.                                                                         |
+| `maxCollapsedHeight` | `number`                                        | —       | Maximum height in pixels for the content area. When the rendered content exceeds this value, the overflow is clipped.                                  |
+| `actionButton`       | `React.ButtonHTMLAttributes<HTMLButtonElement>` | —       | An action button rendered inside the content area. When `actionButton.onClick` is provided it stops propagation to the banner's own `onClick` handler. |
+
+## Props — `ContentLinkAttributes`
+
+| Prop             | Type                       | Default     | Description                                                                                                   |
+| ---------------- | -------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------- |
+| `weight`         | `TypographyWeight`         | "regular"   | Font weight of the link text.                                                                                 |
+| `external`       | `boolean`                  | —           | Appends an external-link icon after the link text to signal that the destination is outside the current site. |
+| `underlineStyle` | `TypographyUnderlineStyle` | "underline" | Text-decoration style for the link.                                                                           |
+
+## Props — `ContentTextAttributes`
+
+| Prop        | Type               | Default   | Description                                                                                                         |
+| ----------- | ------------------ | --------- | ------------------------------------------------------------------------------------------------------------------- |
+| `weight`    | `TypographyWeight` | "regular" | Font weight of the rendered text.                                                                                   |
+| `inline`    | `boolean`          | —         | Renders the element as an inline `span`. When `true`, the `as` prop is ignored and `maxLines` clamping is disabled. |
+| `paragraph` | `boolean`          | —         | Adds a bottom margin to separate the element from following content.                                                |
+| `maxLines`  | `number`           | —         | Clamps visible text to the given number of lines, truncating the remainder.                                         |
+| `as`        | `T`                | —         | Overrides the rendered HTML element, e.g. `"h2"`.                                                                   |
+
+## Props — `NotificationContentAttributes`
+
+| Prop              | Type                                     | Default | Description                                                      |
+| ----------------- | ---------------------------------------- | ------- | ---------------------------------------------------------------- |
+| `type` \*         | `ContentType`                            | —       | Determines how `content` is rendered inside the banner.          |
+| `content` \*      | `string`                                 | —       | The text string or link label to display.                        |
+| `otherAttributes` | `TypographyLinkProps \| TypographyProps` | —       | Additional props forwarded to the rendered text or link element. |
+
+## Rules
+
+-   Place directly below the Navbar — above all page content.
+-   Use for page-wide or system-wide notices only — not for section-specific messages.
+-   Use `dismissible={false}` for mandatory notices users must not be able to dismiss.
+-   Use `NotificationBanner.Link` for all links within the banner — renders with the external link indicator automatically.
+-   Use `maxCollapsedHeight` for long notices to avoid overwhelming the layout.
+-   Use the `withNotificationBanner` HOC for banner content driven from a backend or external data source.
+
+## Anti-patterns
+
+-   Using NotificationBanner for section-specific messages — use Alert instead.
+-   Using raw anchor tags inside banner content — use `NotificationBanner.Link`.
+-   Placing the banner below page content — it must sit directly below the Navbar.