@cl-light-ds/ui 0.1.0

package/src/components/button/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog for Button.astro
+
+All notable changes to the `Button` component will be documented in this file.
+
+## Date 8th Sep 2026
+## Figma alignment (node 114-6897, prop table 7185-13418) 
+
+### Variants
+
+- **Primary:** removed the duplicated/conflicting hover utilities (`hover:bg-primary/80` next to `hover:bg-primary/90`); Figma's hover state resolves to `#3785e0cc`, i.e. `bg-primary` at 80% opacity. Kept `hover:bg-primary/80` only.
+- **Destructive:** completely rebuilt. It previously mixed `text-destructive` and `text-white`, and stacked four different hover opacities (`/20`, `/30`, `/60`, `/90`) across light/dark. Figma's destructive is flat: `bg-destructive text-destructive-foreground`, hover `bg-destructive-hover` (`#ef4444`, already an existing token).
+- **Outline:** dropped the leftover `dark:bg-input/30 dark:border-input dark:hover:bg-input/50` and the duplicate `border`/`shadow-xs shadow-none` pair. Now `border border-border bg-background text-foreground`, hover `bg-background-hover`.
+- **Secondary:** hover changed from `hover:bg-secondary/80` to `hover:bg-background-button-hover` (`#e4e4e7`), matching the resolved Figma value and the same token Badge already uses for its secondary hover.
+- **Ghost:** dropped the implicit `bg-secondary`/`bg-muted` hover mix; now `text-foreground hover:bg-background-hover`, matching Figma exactly.
+- **Link:** was rendered with `p-0` (no padding box) and no hover treatment beyond `hover:underline`. Figma's Link symbol keeps the same padding box as every other variant and adds a `hover:bg-background-hover` wash in addition to the underline. Removed `p-0`.
+- Dropped `aria-expanded:*` variant styling that had no corresponding Figma state — components should express open/active state through `variant`/`class`, not baked into every variant.
+
+### States
+
+- **Disabled:** was `disabled:opacity-50` (just dims whatever variant color). Figma switches every variant to the same flat `bg-muted`/`text-muted-foreground`/`border-transparent`, confirmed identical across Primary, Secondary, Outline, Ghost and Destructive. Moved to the shared base class so it applies uniformly.
+- **Focus:** ring was `focus-visible:ring-ring/50` (translucent). Figma's focus ring is a solid 2px ring in `chart-1` (`#afcef3`, = `primary-200`) plus a `border-ring` border — both already existing tokens. Now `focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-chart-1`.
+
+### Sizing & Spacing
+
+- **Radius:** unified to `rounded-lg` (8px) for every size. Previously `sm` used a one-off `rounded-[min(var(--radius-md),10px)]` and only `lg`/`default` used `rounded-lg` — Figma uses the same 8px radius across all three sizes and both icon-only and labeled buttons.
+- **Font size:** `default`/`sm` were rendering at Tailwind's `text-sm` (14px) but Figma's token for those sizes is 12px (`text-xs` in this Tailwind scale). `lg` was `text-base` (16px) but Figma's large text token is 14px (`text-sm`). Fixed both.
+- **Icon size:** replaced the single blanket `[&_svg:not([class*='size-'])]:size-4` (16px for every size) with per-size rules: `size-3.5` (14px) for `sm`, `size-4` (16px) for `default`, `size-5` (20px) for `lg` — confirmed against Figma's lead/tail icon dimensions per size.
+- **Gap:** simplified nested Figma auto-layout spacing (2px flex gap + 2px label padding on each side ≈ 4px effective gap) down to a single `gap-1` (4px) on the root, applied uniformly across sizes.
+- **Horizontal padding:** `sm` uses `px-2` (8px), `default`/`lg` both use `px-2.5` (10px) — confirmed from Figma's resolved padding tokens (large's extra height comes from its bigger icon/font/fixed `h-10`, not extra horizontal padding).
+
+### New Props
+
+- `leadIcon` / `tailIcon` / `badge` (`boolean`): render the `lead-icon` / `tail-icon` / `badge` named slots before/after the label. Auto-detected from slot presence if not explicitly passed — same pattern as Badge's `leadIcon`/`tailIcon`.
+- This replaces the previous implicit convention of dropping an icon in as a bare child with a `data-icon="inline-start"|"inline-end"` attribute and relying on `has-data-[icon=...]`/`has-[.badge:last-child]` selectors for spacing. No existing usages in the repo relied on that convention (grepped for `data-icon=`), so this is a clean cutover.
+- Docs updated: the "With badge" example now also sets `shape="sharp" size="sm"` on the nested `Badge`, matching the compact/square badge Figma nests inside a Button (`rounded-xs`, `px-1 py-0.5`) rather than Badge's own pill/default sizing.
+
+### Tokens (`globals.css`)
+
+No new tokens were needed — every color Button uses already exists: `primary`/`primary-foreground`, `secondary`/`secondary-foreground`, `background`/`background-hover`/`background-button-hover`, `destructive`/`destructive-foreground`/`destructive-hover`, `muted`/`muted-foreground`, `border`, `ring`, `chart-1`.
+
+## Unreleased

package/src/components/button/index.ts

@@ -0,0 +1,2 @@
+export { default as Button } from "./Button.astro";
+

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

@@ -0,0 +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>

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

@@ -0,0 +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,
+  )}
+/>

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

@@ -0,0 +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>

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

@@ -0,0 +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

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

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

package/src/components/card/CHANGELOG.md

@@ -0,0 +1,119 @@
+# Changelog
+
+All notable changes to the `Card` component will be documented in this file.
+
+## Date 9th Sep 2026
+## Figma alignment (node 54-1310, prop table 7350-1279)
+
+### Variants
+
+- Added an `overlay` variant (`variant: "default" | "ghost" | "overlay"`, was `"default" | "ghost"`). Renders `CardMedia` as a full-bleed background behind the card's content — no separate prop is needed on `CardMedia`, `Card` drives the positioning via a `[&_[data-slot=card-media]]:` selector on its own root, so `<Card variant="overlay">` is the single source of truth.
+- **Fixed `ghost`:** previously only added a `data-[variant=ghost]` marker attribute while the root still always applied `border border-border shadow-lg bg-card` unconditionally — visually a no-op, so "ghost" cards rendered identically to default. `border`/`bg`/`shadow` are now scoped to `variant: "default"` only, so `ghost` (and `overlay`) render fully chrome-less as Figma specifies.
+- Removed the always-on `ring-1 ring-foreground/10 shadow-sm` legacy base styling, which conflicted with the newer `border border-border shadow-lg` layered on top of it. Figma shows no shadow/ring at rest for `default` — the ring only appears in the Focus state.
+
+### States
+
+- **Focus:** `focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-chart-1`, resolved from Figma's `border-ring` + `shadow-[0px_0px_0px_2px_var(--chart-1,#afcef3)]`. Wired as a real, reachable `:focus-visible` state (not a forced class) now that `Card` can render as a native `<a>` — see `as` below.
+- **Pressed** (Overlay only): not exposed as a `state` prop. Approximated purely via CSS `:active` on a scrim layer (`bg-card-overlay-pressed/80 backdrop-blur-[3px]`), demonstrated inline in `CardStory.astro`'s Overlay-Pressed composition rather than as a new prop.
+
+### Sizing & Spacing
+
+- Added `size: "default" | "large"` — replaces dead `data-[size=sm]` infra that nothing ever wired up (and whose `sm` naming was backwards vs. Figma's own prop table, which calls its compact size `"default"`).
+- Switched from a root-owned `py-*`/`gap-*` vertical-rhythm model to a self-padded-block model, since Large's content padding is asymmetric (`pt-8 pb-6 px-6`) and can't be expressed by a single root `py-*` value: `CardHeader` `pt-6` → `pt-8` (large), `CardContent` `pt-8 pb-6` (constant both sizes), `CardFooter` `p-6` (constant both sizes).
+- `CardMedia` inner image radius fixed from `rounded-lg` (8px) to `rounded-md` (6px) for the inset/padded case, matching Figma's flat `rounded-[6px]` on the image against the card's 8px outer radius. The Overlay full-bleed image keeps `rounded-lg` (8px, matching Figma exactly), since there it touches the card's own edges with no inset padding.
+- `CardTitle`: dropped the `md:text-xl` responsive fallback and the wrong-axis `group-data-[size=sm]/card:text-sm`; now a flat `text-xl`, dropping to `text-base` only in `orientation="horizontal"` (title size varies by orientation, not by size).
+- `CardDescription`: `text-sm` base, `text-base` only for `size="large"` + `orientation="vertical"` (Large-Horizontal stays `text-sm`).
+- `CardContent`: now a real `flex flex-col gap-8` container (was `cva("")`, i.e. no layout at all — consumers previously had to add `space-y-*` manually). **Heads up for existing consumers:** this changes CardContent's default display from block to flex-column; anything relying on block-flow spacing inside it should double check.
+
+### New Props
+
+- `size: "default" | "large"` — see above.
+- `orientation: "vertical" | "horizontal"` — horizontal is currently only authored in Figma for `variant="ghost"` + `size="large"`; no `default`/`overlay` horizontal frames exist yet.
+- `as: "div" | "a"` (Button-style polymorphic tag, was fixed to `<div>`). Lets `Card` render as a real, natively focusable `<a>` so the whole card can be a clickable unit with a genuine `:focus-visible` state — resolves the gap between Figma's Focus state / Overlay arrow-icon affordance and the previous non-interactive `<div>`-only implementation.
+
+### Tokens (`globals.css`)
+
+- Added `--card-overlay-pressed: #051729` (+ `@theme inline` mapping `--color-card-overlay-pressed`) for the Overlay variant's Pressed-state scrim, used at `bg-card-overlay-pressed/80`. This color doesn't match any existing semantic token (closest was `--foreground` at `#09090b`, a different hue), so a new single-purpose token was added rather than approximated, per design decision.
+- No other new tokens needed — every other color already existed: `card`, `border`, `ring`, `chart-1`, `primary`, `primary-foreground`, `secondary`, `secondary-foreground`, `muted-foreground`.
+
+### Storybook & Docs
+
+- New stories: `Large`, `Ghost`, `GhostLarge`, `GhostHorizontal`, `Overlay`, `OverlayLarge`, `OverlayPressed`, `Focus`.
+- Replaced the dead `[.border-t]:pt-*`/`[.border-b]:pb-*` marker-class divider convention (grepped — no consumer relied on it) with an explicit `<Separator />` (existing, token-bound `bg-border` component) placed between `CardContent` and `CardFooter`.
+- Fixed category `Badge` usages in Card's docs/stories to pass `shape="sharp"` (were rendering as pill, not matching Figma's `rounded-xs`).
+- Updated the `apps/web` storybook props table and previews to document `variant` (3 values), `size`, `orientation`, and `as`.
+
+### Not changed
+
+- `CardAction.astro` — no Figma delta identified.
+- `CardOverlay.astro` — confirmed distinct/unrelated hover-reveal component (opacity fade on `group-hover/card`), intentionally kept separate from the new `variant="overlay"` (same name, different concept).
+
+### Flagged for the designer (Figma-file gaps, not addressed in this pass)
+
+- Avatar size (32px) and background-image height (285px) don't scale between `default`/`large` Card sizes in the current Figma file — matched as authored (unscaled) rather than inventing scaling behavior the design doesn't show.
+- Large-Overlay has no documented Pressed state in Figma (only Small-Overlay does) — worth confirming if intentional.
+- `--radius-card` (24px) token exists in `globals.css` but is unused anywhere in the codebase and doesn't match Card's actual 8px radius (`--radius-lg`) — likely dead/mis-specified, worth a separate cleanup pass.
+
+## Date 9th Sep 2026 (follow-up)
+## Fix: Ghost/Large/Horizontal spacing (node 2547-9489)
+
+### Fixed
+
+- **Layout bug:** `variant="ghost" size="large" orientation="horizontal"` rendered `CardMedia`, `CardHeader`, and `CardContent` as three separate direct children of `Card`. Since `Card`'s root switches to `flex-row` for horizontal orientation, this produced three side-by-side columns instead of two — `CardHeader`'s avatar/date/badge row floated as its own skinny column between the image and the text, instead of stacking above the title. Figma's own structure for this composition confirms there's no separate header concept here at all — it's a single flex-column "Content" area.
+- **Fix:** the horizontal composition (`CardStory.astro`, and the storybook docs preview) now nests the Details row (avatar group + date + badge) directly inside `CardContent`, grouped with the Title/Description block in a `flex flex-col gap-6` wrapper (the 24px gap the designer just retokenized in Figma), with the Buttons row as `CardContent`'s only other child. This gives `Card`'s root exactly two flex-row children (`CardMedia`, `CardContent`), matching Figma, and lets `CardContent`'s existing `justify-between`/`self-stretch` overrides correctly push the Buttons row to the bottom of the image's height.
+- Removed the now-dead `group-data-[orientation=horizontal]/card:px-0 group-data-[orientation=horizontal]/card:pt-0` overrides from `CardHeader.astro`, since no composition uses `CardHeader` in a horizontal layout anymore (matches Figma, which never had a header concept there).
+- No changes needed to `Card.astro` or `CardContent.astro` — the horizontal overrides already there were correct, they just weren't receiving the right children.
+
+## Date 9th Sep 2026 (follow-up)
+## Fix: Overlay's Pressed state removed (node 2544-3164)
+
+### Removed
+
+- The designer updated Figma's Card component set — Overlay now documents exactly two sizes (`Small`/`Large`, matching the existing `default`/`large` prop) and, for now, only **Default** and **Focus** states. The **Pressed** state symbol no longer exists in the file.
+- Removed the `pressed` prop, its inline scrim demo (`bg-card-overlay-pressed/80 backdrop-blur-[3px] ... group-active/card:opacity-100`), and the `OverlayPressed` story from `CardStory.astro`/`Card.stories.ts` — there's no longer a corresponding Figma reference to demonstrate.
+- Removed the now-unused `--card-overlay-pressed` token (and its `@theme inline` mapping) from `globals.css`, per design decision — no dead tokens left dangling; easy to re-add from this changelog entry if Pressed returns later.
+- Overlay's Default/Focus states, both sizes, are otherwise unchanged — this was a pure removal.
+
+## Date 9th Sep 2026 (follow-up)
+## Fix: Overlay/Small alignment (node 2547-2175)
+
+### Fixed
+
+- **Font color:** `CardDescription` hardcoded `text-muted-foreground` (gray) unconditionally, overriding the white text `CardContent` already applies for `variant="overlay"`. Added `group-data-[variant=overlay]/card:text-primary-foreground` to `CardDescription.astro` so overlay descriptions render white like Figma, matching how `CardTitle` (no explicit color) already inherited it correctly.
+- **Avatar/badge row not pinned to the top:** Figma's Small-Overlay structure pins the avatar/badge row to the top and the name/description to the bottom via a `flex-1` spacer between them. The equivalent code composition (`CardHeader` for the avatar/badge row, `CardContent` for the text) only has two flex children, but `Card.astro`'s `variant="overlay" size="default"` compound variant used `justify-end` — with no spacer and only two children, that pushed the whole `[CardHeader, CardContent]` group to the bottom together instead of spreading them apart. Changed to `justify-between` (matching what `size="large"` already correctly used), which alone fixes the pinning.
+- **Missing aspect ratio:** `variant="overlay"` makes `CardMedia` `position: absolute`, taken out of flow — so the card's box height was driven only by `CardHeader`+`CardContent`'s natural content height, collapsing far shorter than Figma's frames. Added `aspect-[360/260]` (small) and `aspect-[481/576]` (large) to `Card.astro`'s overlay compound variants — a real component-level fix, not just a demo tweak, since any consumer of `variant="overlay"` would hit this.
+
+### Storybook & Docs
+
+- Header badges in the Overlay composition (`CardStory.astro` and the docs page) changed from `variant="outline" shape="rounded"` to `variant="secondary" shape="pill" size="sm"`, matching the current Figma frame exactly (confirmed by the designer).
+- Added the missing arrow-icon `Button` to the docs page's Overlay preview, matching what `CardStory.astro` and Figma both already show.
+
+## Date 9th Sep 2026 (follow-up)
+## Fix: Overlay/Default/Small avatar + icon sizing (node 2547-8683)
+
+### Fixed
+
+- **Avatar wrong size + doubled border:** the Overlay header avatar rendered at `Avatar`'s default size (32px, `border-[1.5px]`) instead of Figma's `24px`. Worse, `Avatar.astro`'s own base class always applies a hardcoded `border-border` (gray), and the composition additionally wrapped it in `ring-2 ring-background` (a white halo pattern meant for avatars on a plain card background) — stacking a gray border and a white ring instead of Figma's single solid white border. Fixed by using `<Avatar size="sm" class="border-primary-foreground">` (24px, white border override) and dropping the redundant `ring-*` wrapper classes, in both `CardStory.astro` and the docs page.
+- **Arrow icon undersized:** the inline arrow-up-right SVG was `size-4` (16px); Figma's icon is `size-[24px]`. Changed to `size-6` in both files. The 32px button box around it (`Button size="icon-sm"`) was already correct.
+
+## Date 9th Sep 2026 (follow-up)
+## Fix: Visual re-audit against Figma (default/ghost/overlay, node 54-1310)
+
+### Fixed
+
+- **`CardTitle` line-height:** was `leading-normal` (1.5× → 30px for the 20px title, 60px across two lines), overshooting Figma's title text style, which specifies a flat `lineHeight: 24` regardless of font size (confirmed for both the `text-xl` vertical title and the `text-base` horizontal/overlay title). Changed to `leading-6` (a fixed 24px) so two-line titles match Figma's 48px box instead of rendering 12px taller.
+- **Focus ring width:** was `focus-visible:ring-3` (3px); Figma's `border-focus` effect is a `DROP_SHADOW` with `spread: 2` (2px) — the same 2px value this component's own changelog already documented as the target (`shadow-[0px_0px_0px_2px_var(--chart-1)]`) but the implementation used `ring-3` instead of `ring-2`. Changed to `ring-2`.
+- **Overlay avatar group was missing its second avatar:** Figma's header row (both Small and Large Overlay) shows two overlapping avatar photos (`-space-x-2`, white border); `CardStory.astro` and the docs preview only rendered one `Avatar` with an initials fallback. Added a second `<Avatar>` (`https://github.com/thomkrupa.png` + `https://github.com/bejamas.png`, matching the "Thom Krupa, Co-founder at Bejamas" copy) inside the existing `-space-x-2` wrapper.
+- **Overlay avatar/badge sizing now scales with `size`:** Small-Overlay uses 24px avatars + `size="sm"` badges (unchanged); Large-Overlay uses 32px avatars + default-size badges per Figma — previously both were hardcoded to `size="sm"`.
+- **Overlay (size="default") title→description gap:** was `gap-3` (12px); Figma's Small-Overlay "Thom Krupa"/"Co-funder at Bejamas" spacing measures 8px from node positions. Changed to `gap-2`.
+- **Overlay (size="default") description weight/size:** "Co-funder at Bejamas" is a 16px/semibold profile byline in Figma (a local override on that text node, distinct from the shared 14px/regular `CardDescription`), not the plain paragraph style. Added `class="text-base font-semibold"` to that specific `CardDescription` instance in `CardStory.astro` and the docs preview — not a `CardDescription.astro` component change, since Large-Overlay reuses the plain paragraph description as-is (see next point).
+- **Overlay badges were invisible, hidden behind the background photo:** caught during visual verification of the fixes above. `CardMedia` is `position:absolute` (`z-0`) for `variant="overlay"`, and `CardContent` already compensates with `relative z-10` — but `CardHeader` never got the same treatment. Per CSS stacking rules, a positioned `z-index:0` box (`CardMedia`) paints *above* an unpositioned in-flow sibling's static descendants (`Badge`, which has no `position` of its own), regardless of DOM order — so the header's badges silently rendered underneath the photo. `Avatar` happened to survive because it's independently `position:relative`, which is what exposed the bug (avatars visible, badges gone). Added the same `group-data-[variant=overlay]/card:relative group-data-[variant=overlay]/card:z-10` to `CardHeader.astro` that `CardContent.astro` already has. Verified via a live render (Playwright screenshot + `elementFromPoint` at the badge's screen coordinates, which resolved to the `<img>` before the fix and to the badge `<span>` after).
+- **Overlay `size="large"` was rendering the wrong content pattern:** Figma's Large-Overlay is a headline + full paragraph + single icon-only button (same copy pattern as `Default`, just over an image), not the Small-Overlay's name/role profile pattern. `CardStory.astro`'s overlay branch wasn't gated on `size`, so `OverlayLarge` incorrectly showed "Thom Krupa" / "Co-founder at Bejamas". Branched the composition on `size` so `size="large"` now renders the headline/paragraph pattern (reusing the existing `gap-6 group-data-[size=large]/card:gap-3` title/description convention).
+
+- **Overlay `CardContent` layout — text and arrow button belong on one row, not stacked:** re-checked against the Figma node positions for both Overlay sizes (Small: "Text" frame has the name/role `Group 1` and the arrow `Button` as side-by-side siblings, `Button` bottom-aligned with the two-line text block; Large: same pattern — "Text" and "Button" siblings inside "Bottom", `Button` bottom-aligned with the text block). `CardContent` was still using its base `flex-col` (text block above, button below) for overlay. Added `group-data-[variant=overlay]/card:flex-row group-data-[variant=overlay]/card:items-end group-data-[variant=overlay]/card:justify-between` so the arrow button now sits to the right of the text block, bottom-aligned, on both Overlay sizes.
+
+### Storybook & Docs
+
+- Added an `Overlay, large` preview to the `apps/web` docs page (previously only the Storybook `OverlayLarge` story existed; the docs page never showcased the large-overlay composition, and was showing the same — now-fixed — mismatched content as `CardStory.astro`).
+
+## Unreleased

package/src/components/card/Card.astro

@@ -0,0 +1,182 @@
+---
+/**
+ * @component Card
+ * @title Card
+ * @description UI container for grouping content with header, footer, etc.
+ * @figmaUrl https://www.figma.com/design/qXkzdqZ3QPQqgckU3AwIAH/ClickLearn-Lightning-Design-Library?node-id=54-1310
+ * @preview
+ *
+ * <Card class="w-full max-w-sm">
+ *   <CardMedia>
+ *     <img src="/mount-fuji.png" alt="Mount Fuji at sunset" width="374" height="250" loading="lazy" />
+ *   </CardMedia>
+ *   <CardHeader>
+ *     <div class="flex items-center gap-2 justify-between">
+ *       <div class="*:data-[slot=avatar]:ring-background flex -space-x-2 *:data-[slot=avatar]:ring-2">
+ *         <Avatar>
+ *           <AvatarImage>
+ *             <img src="https://gradient.bejamas.com/presets/bejamas/marine.png" alt="grdient avatar" />
+ *           </AvatarImage>
+ *           <AvatarFallback>AW</AvatarFallback>
+ *         </Avatar>
+ *       </div>
+ *       <Date date="2025-08-24T12:00:00Z" class="text-sm text-muted-foreground" />
+ *     </div>
+ *   </CardHeader>
+ *   <CardContent>
+ *     <div class="flex flex-col gap-6 group-data-[size=large]/card:gap-3">
+ *       <CardTitle>Strong Foundations, Built to Scale</CardTitle>
+ *       <CardDescription>Like any enduring system, a scalable design system relies on clear structure, solid foundations, and careful layering over time.</CardDescription>
+ *     </div>
+ *     <Button variant="outline" as="a" href="#">Read more</Button>
+ *   </CardContent>
+ *   <Separator />
+ *   <CardFooter>
+ *     <p class="text-sm text-muted-foreground">Categories</p>
+ *     <div class="flex items-center gap-1">
+ *       <Badge variant="secondary" shape="sharp">Marketing</Badge>
+ *       <Badge variant="secondary" shape="sharp">UI Design</Badge>
+ *     </div>
+ *   </CardFooter>
+ * </Card>
+ *
+ * @usage
+ *
+ * ```astro nocollapse
+ * ---
+ * import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@bejamas/ui/components/card';
+ * import { Separator } from '@bejamas/ui/components/separator';
+ * ---
+ *
+ * <Card>
+ *   <CardHeader>
+ *     <CardTitle>Card Title</CardTitle>
+ *     <CardDescription>Card Description</CardDescription>
+ *   </CardHeader>
+ *   <CardContent>
+ *     Card content goes here.
+ *   </CardContent>
+ *   <Separator />
+ *   <CardFooter>
+ *     <button>OK</button>
+ *   </CardFooter>
+ * </Card>
+ * ```
+ *
+ * @examples
+ *
+ * ### Sizes
+ *
+ * Use `size="default"` (compact, the default) or `size="large"` for more generous padding and larger title/description text.
+ *
+ * <Card size="large">...</Card>
+ *
+ * ### Ghost
+ *
+ * `variant="ghost"` removes the card's border, background, and shadow — useful for embedding a card's content inline without visual chrome. Ghost also supports `orientation="horizontal"` for a side-by-side media + content layout.
+ *
+ * <Card variant="ghost" orientation="horizontal">...</Card>
+ *
+ * ### Overlay
+ *
+ * `variant="overlay"` renders `<CardMedia>` as a full-bleed background behind the card's content — no separate prop is needed on `CardMedia` itself, `Card` handles the positioning. Pair with `text-primary-foreground` content since it always sits on a photo.
+ *
+ * <Card variant="overlay">...</Card>
+ *
+ * ### As a link
+ *
+ * Pass `as="a"` (with `href`) to render the whole card as a real, natively focusable anchor — this is how to make Figma's Focus state reachable via keyboard, since a plain `<div>` can't receive `:focus-visible`.
+ *
+ * <Card as="a" href="#">...</Card>
+ */
+
+import { cva } from "class-variance-authority";
+import { cn } from "@cl-light-ds/ui/lib/utils";
+import type { HTMLAttributes } from "astro/types";
+
+type CardVariant = "default" | "ghost" | "overlay";
+type CardSize = "default" | "large";
+type CardOrientation = "vertical" | "horizontal";
+
+type CardAsDiv = {
+  as?: "div";
+} & HTMLAttributes<"div">;
+
+type CardAsAnchor = {
+  as: "a";
+} & HTMLAttributes<"a">;
+
+type CardOwnProps = {
+  variant?: CardVariant;
+  size?: CardSize;
+  orientation?: CardOrientation;
+};
+
+export type Props = (CardAsDiv | CardAsAnchor) & CardOwnProps;
+
+const {
+  as: Tag = "div",
+  class: className = "",
+  variant = "default",
+  size = "default",
+  orientation = "vertical",
+  ...rest
+} = Astro.props as Props;
+
+const cardVariants = cva(
+  "group/card relative flex overflow-clip rounded-lg text-sm text-card-foreground outline-none focus-visible:border-ring focus-visible:ring-2 focus-visible:ring-chart-1",
+  {
+    variants: {
+      variant: {
+        default: "bg-card border border-border",
+        ghost: "",
+        overlay: "",
+      },
+      size: {
+        default: "",
+        large: "",
+      },
+      orientation: {
+        vertical: "flex-col",
+        horizontal: "flex-row items-start",
+      },
+    },
+    compoundVariants: [
+      { variant: "overlay", size: "default", class: "justify-between p-8 aspect-[360/260]" },
+      { variant: "overlay", size: "large", class: "justify-between p-8 aspect-[481/576]" },
+      { variant: "ghost", orientation: "horizontal", class: "gap-8 p-2" },
+    ],
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+      orientation: "vertical",
+    },
+  },
+);
+---
+
+{
+  /*
+  TS can't reconcile our discriminated union props with a dynamic intrinsic Tag.
+  The public Props type *is* strict (href only allowed when as="a"),
+  but JSX wants an intersection of button+anchor attributes here.
+  We deliberately suppress this internal error and rely on Props for caller safety.
+*/
+}
+<!-- @ts-expect-error – union Props + dynamic Tag confuse JSX typing (see comment above) -->
+<Tag
+  {...rest}
+  data-slot="card"
+  data-variant={variant}
+  data-size={size}
+  data-orientation={orientation}
+  class={cn(
+    cardVariants({ variant, size, orientation }),
+    "*:[img:first-child]:rounded-t-lg *:[img:last-child]:rounded-b-lg",
+    variant === "overlay" &&
+      "[&_[data-slot=card-media]]:absolute [&_[data-slot=card-media]]:inset-0 [&_[data-slot=card-media]]:z-0 [&_[data-slot=card-media]]:rounded-lg [&_[data-slot=card-media]]:p-0 [&_[data-slot=card-media]_img]:rounded-lg",
+    className,
+  )}
+>
+  <slot />
+</Tag>

package/src/components/card/CardAction.astro

@@ -0,0 +1,26 @@
+---
+import { cva } from "class-variance-authority";
+import { cn } from "@cl-light-ds/ui/lib/utils";
+import type { HTMLAttributes } from "astro/types";
+
+interface Props extends HTMLAttributes<"div"> {
+  class?: string;
+}
+
+const {
+  class: className = "",
+  ...rest
+} = Astro.props as Props;
+
+const actionVariants = cva(
+  "col-start-2 row-span-2 row-start-1 self-start justify-self-end",
+);
+---
+
+<div
+  {...rest}
+  data-slot="card-action"
+  class={cn("", actionVariants(), className)}
+>
+  <slot />
+</div>

package/src/components/card/CardContent.astro

@@ -0,0 +1,28 @@
+---
+import { cva } from "class-variance-authority";
+import { cn } from "@cl-light-ds/ui/lib/utils";
+import type { HTMLAttributes } from "astro/types";
+
+interface Props extends HTMLAttributes<"div"> {
+  class?: string;
+}
+
+const {
+  class: className = "",
+  ...rest
+} = Astro.props as Props;
+
+const contentVariants = cva("");
+---
+
+<div
+  {...rest}
+  data-slot="card-content"
+  class={cn(
+    "flex flex-col gap-8 px-6 pt-8 pb-6 group-data-[orientation=horizontal]/card:flex-1 group-data-[orientation=horizontal]/card:justify-between group-data-[orientation=horizontal]/card:self-stretch group-data-[orientation=horizontal]/card:px-0 group-data-[orientation=horizontal]/card:py-3 group-data-[variant=overlay]/card:relative group-data-[variant=overlay]/card:z-10 group-data-[variant=overlay]/card:flex-row group-data-[variant=overlay]/card:items-end group-data-[variant=overlay]/card:justify-between group-data-[variant=overlay]/card:px-0 group-data-[variant=overlay]/card:pt-0 group-data-[variant=overlay]/card:pb-0 group-data-[variant=overlay]/card:text-primary-foreground",
+    contentVariants(),
+    className,
+  )}
+>
+  <slot />
+</div>