@cl-light-ds/ui 0.2.0 → 0.4.0

package/src/components/button-group/ButtonGroup.astro

@@ -1,130 +1,130 @@
----
-/**
- * @component ButtonGroup
- * @title Button Group
- * @description A set of related buttons grouped together, with support for horizontal or vertical layouts.
- * @figmaUrl https://www.figma.com/design/qXkzdqZ3QPQqgckU3AwIAH/ClickLearn-Lightning-Design-Library?node-id=114-9882
- *
- * @preview
- *
- * <ButtonGroup>
- *   <Button variant="outline">Left</Button>
- *   <Button variant="outline">Middle</Button>
- *   <Button variant="outline">Right</Button>
- * </ButtonGroup>
- *
- * @usage
- *
- * ```astro nocollapse
- * ---
- * import { ButtonGroup } from '@bejamas/ui/components/button-group';
- * import { Button } from '@bejamas/ui/components/button';
- * ---
- * <ButtonGroup>
- *   <Button>One</Button>
- *   <Button>Two</Button>
- *   <Button>Three</Button>
- * </ButtonGroup>
- * ```
- *
- * @props
- * - orientation?: "horizontal" | "vertical" — Default: "horizontal".
- * - class?: string — Additional classes for the container.
- *
- * @examples
- *
- * ### Orientation
- *
- * <ButtonGroup orientation="vertical" aria-label="Media controls" class="h-fit">
- *   <Button variant="outline" size="icon">
- *     <PlusIcon />
- *   </Button>
- *   <Button variant="outline" size="icon">
- *     <MinusIcon />
- *   </Button>
- * </ButtonGroup>
- *
- * ### Size
- *
- * <div class="flex flex-col items-start gap-8">
- *   <ButtonGroup>
- *     <Button variant="outline" size="sm">
- *       Small
- *     </Button>
- *     <Button variant="outline" size="sm">
- *       Button
- *     </Button>
- *     <Button variant="outline" size="sm">
- *       Group
- *     </Button>
- *     <Button variant="outline" size="icon-sm">
- *       <PlusIcon />
- *      </Button>
- *   </ButtonGroup>
- *   <ButtonGroup>
- *     <Button variant="outline">Default</Button>
- *     <Button variant="outline">Button</Button>
- *     <Button variant="outline">Group</Button>
- *     <Button variant="outline" size="icon">
- *       <PlusIcon />
- *     </Button>
- *   </ButtonGroup>
- *   <ButtonGroup>
- *     <Button variant="outline" size="lg">
- *       Large
- *     </Button>
- *     <Button variant="outline" size="lg">
- *       Button
- *     </Button>
- *     <Button variant="outline" size="lg">
- *       Group
- *     </Button>
- *     <Button variant="outline" size="icon-lg">
- *       <PlusIcon />
- *     </Button>
- *   </ButtonGroup>
- * </div>
- */
-
-import type { HTMLAttributes } from "astro/types";
-import { cva, type VariantProps } from "class-variance-authority";
-import { cn } from "@cl-light-ds/ui/lib/utils";
-
-interface Props
-  extends VariantProps<typeof buttonGroupVariants>, HTMLAttributes<"div"> {
-  class?: string;
-}
-
-const {
-  orientation = "horizontal",
-  class: className = "",
-  ...props
-} = Astro.props as Props;
-
-export const buttonGroupVariants = cva(
-  "flex w-fit items-stretch *:focus-visible:relative *:focus-visible:z-10 has-[>[data-slot=button-group]]:gap-2 has-[select[aria-hidden=true]:last-child]:[&>[data-slot=select-trigger]:last-of-type]:rounded-e-lg [&>[data-slot=select-trigger]:not([class*='w-'])]:w-fit [&>input]:flex-1",
-  {
-    variants: {
-      orientation: {
-        horizontal:
-          "*:data-slot:rounded-e-none [&>[data-slot]:not(:has(~[data-slot]))]:rounded-e-lg! [&>[data-slot]~[data-slot]]:border-s-0 [&>[data-slot]~[data-slot]]:rounded-s-none [&>[data-slot]~[data-slot]_[data-slot]]:border-s-0 [&>[data-slot]~[data-slot]_[data-slot]]:rounded-s-none",
-        vertical:
-          "flex-col *:data-slot:rounded-b-none [&>[data-slot]:not(:has(~[data-slot]))]:rounded-b-lg! [&>[data-slot]~[data-slot]]:rounded-t-none [&>[data-slot]~[data-slot]]:border-t-0 [&>[data-slot]~[data-slot]_[data-slot]]:rounded-t-none [&>[data-slot]~[data-slot]_[data-slot]]:border-t-0",
-      },
-    },
-    defaultVariants: {
-      orientation: "horizontal",
-    },
-  },
-);
----
-
-<div
-  role="group"
-  data-slot="button-group"
-  data-orientation={orientation}
-  class={cn("has-[>[data-slot=button-group]]:gap-2 has-[select[aria-hidden=true]:last-child]:[&>[data-slot=select-trigger]:last-of-type]:rounded-r-md", buttonGroupVariants({ orientation }), className)}
-  {...props}
->
-  <slot />
-</div>
+---
+/**
+ * @component ButtonGroup
+ * @title Button Group
+ * @description A set of related buttons grouped together, with support for horizontal or vertical layouts.
+ * @figmaUrl https://www.figma.com/design/qXkzdqZ3QPQqgckU3AwIAH/ClickLearn-Lightning-Design-Library?node-id=114-9882
+ *
+ * @preview
+ *
+ * <ButtonGroup>
+ *   <Button variant="outline">Left</Button>
+ *   <Button variant="outline">Middle</Button>
+ *   <Button variant="outline">Right</Button>
+ * </ButtonGroup>
+ *
+ * @usage
+ *
+ * ```astro nocollapse
+ * ---
+ * import { ButtonGroup } from '@bejamas/ui/components/button-group';
+ * import { Button } from '@bejamas/ui/components/button';
+ * ---
+ * <ButtonGroup>
+ *   <Button>One</Button>
+ *   <Button>Two</Button>
+ *   <Button>Three</Button>
+ * </ButtonGroup>
+ * ```
+ *
+ * @props
+ * - orientation?: "horizontal" | "vertical" — Default: "horizontal".
+ * - class?: string — Additional classes for the container.
+ *
+ * @examples
+ *
+ * ### Orientation
+ *
+ * <ButtonGroup orientation="vertical" aria-label="Media controls" class="h-fit">
+ *   <Button variant="outline" size="icon">
+ *     <PlusIcon />
+ *   </Button>
+ *   <Button variant="outline" size="icon">
+ *     <MinusIcon />
+ *   </Button>
+ * </ButtonGroup>
+ *
+ * ### Size
+ *
+ * <div class="flex flex-col items-start gap-8">
+ *   <ButtonGroup>
+ *     <Button variant="outline" size="sm">
+ *       Small
+ *     </Button>
+ *     <Button variant="outline" size="sm">
+ *       Button
+ *     </Button>
+ *     <Button variant="outline" size="sm">
+ *       Group
+ *     </Button>
+ *     <Button variant="outline" size="icon-sm">
+ *       <PlusIcon />
+ *      </Button>
+ *   </ButtonGroup>
+ *   <ButtonGroup>
+ *     <Button variant="outline">Default</Button>
+ *     <Button variant="outline">Button</Button>
+ *     <Button variant="outline">Group</Button>
+ *     <Button variant="outline" size="icon">
+ *       <PlusIcon />
+ *     </Button>
+ *   </ButtonGroup>
+ *   <ButtonGroup>
+ *     <Button variant="outline" size="lg">
+ *       Large
+ *     </Button>
+ *     <Button variant="outline" size="lg">
+ *       Button
+ *     </Button>
+ *     <Button variant="outline" size="lg">
+ *       Group
+ *     </Button>
+ *     <Button variant="outline" size="icon-lg">
+ *       <PlusIcon />
+ *     </Button>
+ *   </ButtonGroup>
+ * </div>
+ */
+
+import type { HTMLAttributes } from "astro/types";
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "@cl-light-ds/ui/lib/utils";
+
+interface Props
+  extends VariantProps<typeof buttonGroupVariants>, HTMLAttributes<"div"> {
+  class?: string;
+}
+
+const {
+  orientation = "horizontal",
+  class: className = "",
+  ...props
+} = Astro.props as Props;
+
+export const buttonGroupVariants = cva(
+  "flex w-fit items-stretch *:focus-visible:relative *:focus-visible:z-10 has-[>[data-slot=button-group]]:gap-2 has-[select[aria-hidden=true]:last-child]:[&>[data-slot=select-trigger]:last-of-type]:rounded-e-lg [&>[data-slot=select-trigger]:not([class*='w-'])]:w-fit [&>input]:flex-1",
+  {
+    variants: {
+      orientation: {
+        horizontal:
+          "*:data-slot:rounded-e-none [&>[data-slot]:not(:has(~[data-slot]))]:rounded-e-lg! [&>[data-slot]~[data-slot]]:border-s-0 [&>[data-slot]~[data-slot]]:rounded-s-none [&>[data-slot]~[data-slot]_[data-slot]]:border-s-0 [&>[data-slot]~[data-slot]_[data-slot]]:rounded-s-none",
+        vertical:
+          "flex-col *:data-slot:rounded-b-none [&>[data-slot]:not(:has(~[data-slot]))]:rounded-b-lg! [&>[data-slot]~[data-slot]]:rounded-t-none [&>[data-slot]~[data-slot]]:border-t-0 [&>[data-slot]~[data-slot]_[data-slot]]:rounded-t-none [&>[data-slot]~[data-slot]_[data-slot]]:border-t-0",
+      },
+    },
+    defaultVariants: {
+      orientation: "horizontal",
+    },
+  },
+);
+---
+
+<div
+  role="group"
+  data-slot="button-group"
+  data-orientation={orientation}
+  class={cn("has-[>[data-slot=button-group]]:gap-2 has-[select[aria-hidden=true]:last-child]:[&>[data-slot=select-trigger]:last-of-type]:rounded-r-md", buttonGroupVariants({ orientation }), className)}
+  {...props}
+>
+  <slot />
+</div>

package/src/components/button-group/ButtonGroupSeparator.astro

@@ -1,30 +1,30 @@
----
-import type { HTMLAttributes } from "astro/types";
-import { cn } from "@cl-light-ds/ui/lib/utils";
-import Separator from "../separator/Separator.astro";
-
-interface Props extends HTMLAttributes<"div"> {
-  class?: string;
-  orientation?: "horizontal" | "vertical";
-  decorative?: boolean;
-}
-
-const {
-  class: className = "",
-  orientation = "vertical",
-  decorative = true,
-  ...rest
-} = Astro.props as Props;
----
-
-<Separator
-  {...rest}
-  decorative={decorative}
-  data-slot="button-group-separator"
-  data-orientation={orientation}
-  orientation={orientation}
-  class={cn(
-    "bg-input relative self-stretch data-[orientation=horizontal]:mx-px data-[orientation=horizontal]:w-auto data-[orientation=vertical]:my-px data-[orientation=vertical]:h-auto",
-    className,
-  )}
-/>
+---
+import type { HTMLAttributes } from "astro/types";
+import { cn } from "@cl-light-ds/ui/lib/utils";
+import Separator from "../separator/Separator.astro";
+
+interface Props extends HTMLAttributes<"div"> {
+  class?: string;
+  orientation?: "horizontal" | "vertical";
+  decorative?: boolean;
+}
+
+const {
+  class: className = "",
+  orientation = "vertical",
+  decorative = true,
+  ...rest
+} = Astro.props as Props;
+---
+
+<Separator
+  {...rest}
+  decorative={decorative}
+  data-slot="button-group-separator"
+  data-orientation={orientation}
+  orientation={orientation}
+  class={cn(
+    "bg-input relative self-stretch data-[orientation=horizontal]:mx-px data-[orientation=horizontal]:w-auto data-[orientation=vertical]:my-px data-[orientation=vertical]:h-auto",
+    className,
+  )}
+/>

package/src/components/button-group/ButtonGroupText.astro

@@ -1,21 +1,21 @@
----
-import type { HTMLAttributes } from "astro/types";
-import { cn } from "@cl-light-ds/ui/lib/utils";
-
-interface Props extends HTMLAttributes<"div"> {
-  class?: string;
-}
-
-const { class: className = "", ...rest } = Astro.props as Props;
----
-
-<div
-  {...rest}
-  data-slot="button-group-text"
-  class={cn(
-    "bg-muted flex items-center gap-2 rounded-lg border px-2.5 text-sm font-semibold [&_svg:not([class*='size-'])]:size-4 [&_svg]:pointer-events-none",
-    className,
-  )}
->
-  <slot />
-</div>
+---
+import type { HTMLAttributes } from "astro/types";
+import { cn } from "@cl-light-ds/ui/lib/utils";
+
+interface Props extends HTMLAttributes<"div"> {
+  class?: string;
+}
+
+const { class: className = "", ...rest } = Astro.props as Props;
+---
+
+<div
+  {...rest}
+  data-slot="button-group-text"
+  class={cn(
+    "bg-muted flex items-center gap-2 rounded-lg border px-2.5 text-sm font-semibold [&_svg:not([class*='size-'])]:size-4 [&_svg]:pointer-events-none",
+    className,
+  )}
+>
+  <slot />
+</div>

package/src/components/button-group/CHANGELOG.md

@@ -1,34 +1,34 @@
-# Changelog for ButtonGroup.astro
-
-All notable changes to the `ButtonGroup` component will be documented in this file.
-
-## Date 8th Sep 2026
-## Figma alignment (node 114-9882)
-
-### Sizing & Spacing
-
-- **Radius fixed:** `Button.astro` was forcing `in-data-[slot=button-group]:rounded-md` (6px) on the `default`, `sm`, `lg`, and `icon-sm` sizes whenever a button sat inside a group, while `icon` and `icon-lg` had no such override. Figma's grouped item corners are unambiguously `--radius/rounded-lg` (8px, same token as `--radius-lg` in `globals.css`) across every size. Removed the override entirely — end-item corners on a `ButtonGroup` now render at 8px consistently, matching standalone `Button` and every size.
-- No changes were needed to `ButtonGroup.astro`'s own merge logic (`rounded-e-lg!`, `border-s-0`, etc.) — it already resolved to 8px correctly; the bug was solely in `Button.astro`'s per-size override.
-
-### States (new, `Button.astro`, scoped via `in-data-[slot=button-group]:`)
-
-Previously, grouped buttons had no state styling of their own — they just inherited standalone `outline`-variant hover (`hover:bg-background-hover`) and the shared global focus ring. Figma's `Button Group` states are defined per-size in the `Button Group / Items` master symbols frame (node `114:11217`) — note the separate `States` showcase page (node `2597:6822`) had its `Hover`/`Focus` symbol instances swapped, so the master symbols frame was used as the authoritative source instead:
-
-- **Hover:** background becomes `bg-background-hover` (`#f4f4f5`, existing `--background-hover` token), border uses Figma's `accent` variable (`#ebf3fc`) — which doesn't match this codebase's `--accent` token (a neutral gray) but is identical to the existing `--badge-accent`/`--primary-50` token, so bound to `border-badge-accent` (same token/pattern `Badge.astro` already uses for its own `accent` variant). No shadow. New `in-data-[slot=button-group]:hover:*` rule on `Button.astro`.
-- **Focus-visible:** background stays `bg-background` (white, unchanged), border is `border-ring` (`#5f9de6`, existing `--ring` token), plus a 2px `ring-chart-1` shadow (the effect is literally named `border-focus` in the Figma file). This is **exactly** `Button.astro`'s existing global `focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-chart-1` rule — no grouped-context override needed; grouped and standalone buttons share identical focus-visible styling.
-- **Disabled:** unchanged — `bg-muted`/`text-muted-foreground`/`border-transparent` from `Button.astro`'s shared `disabled:` classes already matches Figma's grouped disabled state (`bg-muted`/`border-muted`/`text-muted-foreground`) visually.
-- **Default:** unchanged — Figma's grouped item (`bg-background`/`border-border`/`text-foreground`) is exactly `Button`'s existing `outline` variant, which is what every documented `ButtonGroup` usage already passes.
-
-### Storybook & Docs (`_sections/button-group.astro`)
-
-- Added a "Disabled" preview block, alongside the existing `Preview`/`Vertical orientation`/`Sizes` sections, so the disabled state is visible in Storybook.
-
-### Not changed (flagged, not acted on)
-
-A few things in Figma's `Button Group` variants don't match `Button`'s already-finalized standalone sizing from its own alignment pass, and read more like authoring artifacts in the Figma file than intentional grouped-only rules — left as-is rather than re-touching `Button.astro`'s validated standalone spacing:
-
-- Figma's grouped "Medium/Default" item uses 8px horizontal padding vs. standalone `Button` `default` size's 10px (`px-2.5`). Small and Large sizes match their standalone counterparts exactly, so this looks like one mistyped padding token in the Figma file.
-- Figma's grouped `lg` item shows a 6px icon/label gap vs. `Button`'s current `lg` gap of 4px (`gap-1`).
-- Figma's grouped icons are a flat 14px (text mode) / 16px (icon-only) regardless of size, vs. `Button`'s current per-size icon scaling (14/16/20 for sm/default/lg) — which the prior `Button` alignment pass deliberately validated against `Button`'s own (different) Figma variants.
-
-## Unreleased
+# Changelog for ButtonGroup.astro
+
+All notable changes to the `ButtonGroup` component will be documented in this file.
+
+## Date 8th Sep 2026
+## Figma alignment (node 114-9882)
+
+### Sizing & Spacing
+
+- **Radius fixed:** `Button.astro` was forcing `in-data-[slot=button-group]:rounded-md` (6px) on the `default`, `sm`, `lg`, and `icon-sm` sizes whenever a button sat inside a group, while `icon` and `icon-lg` had no such override. Figma's grouped item corners are unambiguously `--radius/rounded-lg` (8px, same token as `--radius-lg` in `globals.css`) across every size. Removed the override entirely — end-item corners on a `ButtonGroup` now render at 8px consistently, matching standalone `Button` and every size.
+- No changes were needed to `ButtonGroup.astro`'s own merge logic (`rounded-e-lg!`, `border-s-0`, etc.) — it already resolved to 8px correctly; the bug was solely in `Button.astro`'s per-size override.
+
+### States (new, `Button.astro`, scoped via `in-data-[slot=button-group]:`)
+
+Previously, grouped buttons had no state styling of their own — they just inherited standalone `outline`-variant hover (`hover:bg-background-hover`) and the shared global focus ring. Figma's `Button Group` states are defined per-size in the `Button Group / Items` master symbols frame (node `114:11217`) — note the separate `States` showcase page (node `2597:6822`) had its `Hover`/`Focus` symbol instances swapped, so the master symbols frame was used as the authoritative source instead:
+
+- **Hover:** background becomes `bg-background-hover` (`#f4f4f5`, existing `--background-hover` token), border uses Figma's `accent` variable (`#ebf3fc`) — which doesn't match this codebase's `--accent` token (a neutral gray) but is identical to the existing `--badge-accent`/`--primary-50` token, so bound to `border-badge-accent` (same token/pattern `Badge.astro` already uses for its own `accent` variant). No shadow. New `in-data-[slot=button-group]:hover:*` rule on `Button.astro`.
+- **Focus-visible:** background stays `bg-background` (white, unchanged), border is `border-ring` (`#5f9de6`, existing `--ring` token), plus a 2px `ring-chart-1` shadow (the effect is literally named `border-focus` in the Figma file). This is **exactly** `Button.astro`'s existing global `focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-chart-1` rule — no grouped-context override needed; grouped and standalone buttons share identical focus-visible styling.
+- **Disabled:** unchanged — `bg-muted`/`text-muted-foreground`/`border-transparent` from `Button.astro`'s shared `disabled:` classes already matches Figma's grouped disabled state (`bg-muted`/`border-muted`/`text-muted-foreground`) visually.
+- **Default:** unchanged — Figma's grouped item (`bg-background`/`border-border`/`text-foreground`) is exactly `Button`'s existing `outline` variant, which is what every documented `ButtonGroup` usage already passes.
+
+### Storybook & Docs (`_sections/button-group.astro`)
+
+- Added a "Disabled" preview block, alongside the existing `Preview`/`Vertical orientation`/`Sizes` sections, so the disabled state is visible in Storybook.
+
+### Not changed (flagged, not acted on)
+
+A few things in Figma's `Button Group` variants don't match `Button`'s already-finalized standalone sizing from its own alignment pass, and read more like authoring artifacts in the Figma file than intentional grouped-only rules — left as-is rather than re-touching `Button.astro`'s validated standalone spacing:
+
+- Figma's grouped "Medium/Default" item uses 8px horizontal padding vs. standalone `Button` `default` size's 10px (`px-2.5`). Small and Large sizes match their standalone counterparts exactly, so this looks like one mistyped padding token in the Figma file.
+- Figma's grouped `lg` item shows a 6px icon/label gap vs. `Button`'s current `lg` gap of 4px (`gap-1`).
+- Figma's grouped icons are a flat 14px (text mode) / 16px (icon-only) regardless of size, vs. `Button`'s current per-size icon scaling (14/16/20 for sm/default/lg) — which the prior `Button` alignment pass deliberately validated against `Button`'s own (different) Figma variants.
+
+## Unreleased

package/src/components/button-group/index.ts

@@ -1,3 +1,3 @@
-export { default as ButtonGroup } from "./ButtonGroup.astro";
-export { default as ButtonGroupSeparator } from "./ButtonGroupSeparator.astro";
-export { default as ButtonGroupText } from "./ButtonGroupText.astro";
+export { default as ButtonGroup } from "./ButtonGroup.astro";
+export { default as ButtonGroupSeparator } from "./ButtonGroupSeparator.astro";
+export { default as ButtonGroupText } from "./ButtonGroupText.astro";

package/src/components/callout/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to the `Callout` component will be documented in this file.
+
+## 2026-10-06 — Initial implementation (ClickLearn Lightning Design Library, node `7650-5947`)
+
+Figma documents Callout as a single component set (`7656:12714`) with one property, `Type = Default | Info | Warning | Danger`.
+
+### Added
+
+- `Callout`, `CalloutTitle`, `CalloutDescription`.
+- `variant: "default" | "info" | "warning" | "danger"` — maps 1:1 to Figma's `Type` (Figma's "Danger" kept as `danger`, its background token is `callout-background-error`).
+- Default icon per variant, rendered in a 30px bordered white box, matching Figma: `Lightbulb` (foreground), `Info` (primary), `CircleAlert` (warning), `ShieldAlert` (destructive). Override with `icon={…}` or hide with `icon={false}`.
+- `actions` named slot — right-aligned row under the copy. Figma's actions are small buttons, so pass `<Button size="sm">` (use `variant="destructive"` for the Danger primary action, as in Figma).
+- `dismissible` (default `true`, Figma always shows the X). Visual only, same as `Alert`.
+- `role="note"` — callouts are static, in-flow content, unlike `Alert`'s `role="alert"`.
+
+### New tokens (`globals.css`)
+
+| Token | Light | Dark | Figma variable |
+|---|---|---|---|
+| `--warning` / `bg-warning`, `text-warning` | `#eab308` | — | `badge-warning-backgground` |
+| `--warning-foreground` | white | — | — |
+| `--callout-background-info` / `bg-callout-info` | `var(--primary-50)` (`#ebf3fc`) | primary-500 15% on background | `callout-background-info` |
+| `--callout-background-warning` / `bg-callout-warning` | `#fefce8` | `#eab308` 12% on background | `callout-background-warning` |
+| `--callout-background-error` / `bg-callout-error` | `#fef2f2` | red-600 15% on background | `callout-background-error` |
+
+### Notes
+
+- Default variant uses `bg-popover` + `border-border`; tinted variants use a transparent border so all four keep identical dimensions.
+- Radius is `rounded-md` (6px) and padding `p-3` per Figma's `radius/rounded-md` and `padding/p-3`.
+- Dark values are not defined in Figma; they are tinted mixes chosen to keep contrast with `foreground`.

package/src/components/callout/Callout.astro

@@ -0,0 +1,147 @@
+---
+/**
+ * @component Callout
+ * @title Callout
+ * @description An inline, in-flow message that highlights a tip, update, warning or problem, with optional actions.
+ * @figmaUrl https://www.figma.com/design/qXkzdqZ3QPQqgckU3AwIAH/ClickLearn-Lightning-Design-Library?node-id=7650-5947
+ * @status stable
+ * @since 0.4.0
+ *
+ * @preview
+ *
+ * <Callout variant="info" class="max-w-md">
+ *   <CalloutTitle>Bookmark your organisation link</CalloutTitle>
+ *   <CalloutDescription>Save your organisation URL to sign in directly next time.</CalloutDescription>
+ *   <Fragment slot="actions">
+ *     <Button size="sm">View updates</Button>
+ *     <Button size="sm" variant="outline">Not now</Button>
+ *   </Fragment>
+ * </Callout>
+ *
+ * @usage
+ *
+ * ```astro nocollapse
+ * ---
+ * import { Callout, CalloutTitle, CalloutDescription } from '@cl-light-ds/ui/components/callout';
+ * import { Button } from '@cl-light-ds/ui/components/button';
+ * ---
+ * <Callout variant="warning">
+ *   <CalloutTitle>Your session is about to expire</CalloutTitle>
+ *   <CalloutDescription>Save your work or extend the session.</CalloutDescription>
+ *   <Fragment slot="actions">
+ *     <Button size="sm">Extend session</Button>
+ *     <Button size="sm" variant="outline">Save work</Button>
+ *   </Fragment>
+ * </Callout>
+ * ```
+ */
+import { cva } from "class-variance-authority";
+import { CircleAlert, Info, Lightbulb, ShieldAlert, X as XIcon } from "@lucide/astro";
+import type { AstroComponent } from "@lucide/astro";
+import { cn } from "@cl-light-ds/ui/lib/utils";
+import type { HTMLAttributes } from "astro/types";
+
+type CalloutVariant = "default" | "info" | "warning" | "danger";
+
+interface Props extends HTMLAttributes<"div"> {
+  variant?: CalloutVariant;
+  /** Icon component; defaults to the variant's icon. Pass `false` to hide it. */
+  icon?: AstroComponent | false;
+  dismissible?: boolean;
+  class?: string;
+}
+
+const defaultIcons: Record<CalloutVariant, AstroComponent> = {
+  default: Lightbulb,
+  info: Info,
+  warning: CircleAlert,
+  danger: ShieldAlert,
+};
+
+const {
+  class: className = "",
+  variant = "default",
+  icon,
+  dismissible = true,
+  ...rest
+} = Astro.props as Props;
+
+const Icon = icon === false ? undefined : (icon ?? defaultIcons[variant]);
+const hasActions = Astro.slots.has("actions");
+
+const calloutVariants = cva(
+  "group/callout relative flex w-full items-start gap-2 rounded-md border p-3",
+  {
+    variants: {
+      variant: {
+        default: "border-border bg-popover",
+        info: "border-transparent bg-callout-info",
+        warning: "border-transparent bg-callout-warning",
+        danger: "border-transparent bg-callout-error",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  },
+);
+
+const iconVariants = cva(
+  "flex size-7.5 shrink-0 items-center justify-center rounded-lg border border-border bg-background [&>svg]:size-[15px]",
+  {
+    variants: {
+      variant: {
+        default: "text-foreground",
+        info: "text-primary",
+        warning: "text-warning",
+        danger: "text-destructive",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  },
+);
+---
+
+<div
+  {...rest}
+  data-slot="callout"
+  data-variant={variant}
+  role="note"
+  class={cn(calloutVariants({ variant }), className)}
+>
+  <div data-slot="callout-message" class="flex min-w-0 flex-1 items-start gap-3">
+    {
+      Icon && (
+        <div data-slot="callout-icon" class={iconVariants({ variant })}>
+          <Icon aria-hidden="true" />
+        </div>
+      )
+    }
+    <div data-slot="callout-content" class="flex min-w-0 flex-1 flex-col gap-3 pt-0.5">
+      <div class="flex flex-col gap-1">
+        <slot />
+      </div>
+      {
+        hasActions && (
+          <div data-slot="callout-actions" class="flex w-full items-center justify-end gap-2">
+            <slot name="actions" />
+          </div>
+        )
+      }
+    </div>
+  </div>
+  {
+    dismissible && (
+      <button
+        type="button"
+        data-slot="callout-dismiss"
+        class="flex shrink-0 items-center justify-center rounded-lg p-2 text-muted-foreground [&>svg]:size-4"
+      >
+        <XIcon aria-hidden="true" />
+        <span class="sr-only">Dismiss</span>
+      </button>
+    )
+  }
+</div>

package/src/components/callout/CalloutDescription.astro

@@ -0,0 +1,16 @@
+---
+import { cn } from "@cl-light-ds/ui/lib/utils";
+import type { HTMLAttributes } from "astro/types";
+
+interface Props extends HTMLAttributes<"div"> {}
+
+const { class: className = "", ...rest } = Astro.props as Props;
+---
+
+<div
+  {...rest}
+  data-slot="callout-description"
+  class={cn("text-sm leading-5 text-muted-foreground", className)}
+>
+  <slot />
+</div>