@cl-light-ds/ui 0.1.0 → 0.3.0

package/src/components/card/CHANGELOG.md

@@ -1,119 +1,162 @@
-# 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
+# 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`).
+
+## Date 27th Sep 2026
+## Figma re-sync: Hover state + detail alignment (node 54-1310, component set 2544-3164)
+
+### Added
+
+- **Hover state** (Figma `7546:3534`, `variant="default"`, applied to both sizes):
+  - `CardMedia` fades in a `card-hover` scrim (`#112843` @ 70%) over the image on `group-hover/card` and `group-focus-within/card`.
+  - `Card` gets `shadow-card-light` (`0 1px 1px rgba(5,23,41,.06)`) on hover and focus-within.
+  - Ghost and overlay are unaffected.
+- **New slots `CardMediaSelect` and `CardMediaActions`.** Both go inside `CardMedia`, are hidden until hover or focus-within, and are always visible under `@media (hover: none)`.
+  - `CardMediaSelect` is the top-left slot for `<Checkbox size="lg" />`.
+  - `CardMediaActions` is the top-right icon toolbar: `rounded-md`, a `slider-background-disabled` border, a `card-hover` background, and 20px icons.
+  - Figma's fractional values from the scaled component (19.38px offsets, a 14.77px gap, a 1.231px border) were normalized to 20px / 16px / 1px.
+  - They are composable slots rather than props, so consumers wire their own actions.
+- **Tokens (`globals.css`):**
+  - `--card-hover` (`color-mix(primary-950 70%)`) with a `--color-card-hover` mapping.
+  - `--shadow-card-light` with a `shadow-card-light` utility.
+
+### Fixed
+
+- **Overlay Focus border was invisible.** `focus-visible:border-ring` had no border width to color on ghost and overlay. Both now have `border border-transparent`, so Figma's 1px `ring` border shows together with the 2px `chart-1` ring.
+- **Overlay Large content row:**
+  - Added `gap-10` (40px) between the text block and the arrow button.
+  - The description is now 14px (it was picking up 16px from the large + vertical rule). The rule now uses `not-in-data-[variant=overlay]`.
+- **Overlay arrow icon (docs page) rendered at 14px.** `Button size="icon-sm"`'s `[&_svg]:size-3.5` outranked the SVG's own `size-6`. It now passes `[&_svg]:size-6` on the Button.
+
+### Storybook & Docs
+
+- Avatars now show the status dot (`status="active"`), matching Figma's `showStatus=true`.
+- Overlay (both sizes) now uses a **single** default-size (32px) avatar with the default `border-border`. This replaces the two stacked avatars with the `border-primary-foreground` override.
+- Footer copy changed to "31 steps · 10 min" (semibold). It now has three **pill** badges (Marketing, UI Design, AI) instead of two `shape="sharp"` ones.
+- The Date in the Details row is semibold.
+- The first preview now matches Figma's defaults: 400px wide, title only, no description or buttons (`description=false`, `buttons=false`). The richer composition moved to "With description & actions".
+- New previews: **Hover** and **Overlay focus**. There is also a new "Sub-components" table for the new slots.
+
+### Flagged for the designer (not changed)
+
+- There's no Large-Hover frame. The Small behaviour was applied to Large.
+- Large-Focus (`2545:950`) still uses sharp (2px) badges and `p-6` content padding, while Large-Default uses `pt-8`. These look like stale instances.
+- Ghost-Large (`2547:9398`) uses small-size spacing (`p-6`, `gap-6`, 14px description), while code applies the large rules. It also has a trailing separator with no footer.
+- The toolbar background `rgba(32,41,57,.7)` isn't a token, so `card-hover` is reused. The toolbar border is bound to `slider-background-disabled`, which isn't a semantic match.
+- The description text inherits Semibold from Figma's "Text" frame. Confirm whether it should be regular weight, as the code has it now.
+
+## Unreleased

package/src/components/card/Card.astro

@@ -13,14 +13,14 @@
  *   <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>
+ *         <Avatar status="active">
  *           <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" />
+ *       <Date date="2025-08-24T12:00:00Z" class="text-sm font-semibold text-muted-foreground" />
  *     </div>
  *   </CardHeader>
  *   <CardContent>
@@ -32,10 +32,11 @@
  *   </CardContent>
  *   <Separator />
  *   <CardFooter>
- *     <p class="text-sm text-muted-foreground">Categories</p>
+ *     <p class="text-sm font-semibold text-muted-foreground">31 steps · 10 min</p>
  *     <div class="flex items-center gap-1">
- *       <Badge variant="secondary" shape="sharp">Marketing</Badge>
- *       <Badge variant="secondary" shape="sharp">UI Design</Badge>
+ *       <Badge variant="secondary">Marketing</Badge>
+ *       <Badge variant="secondary">UI Design</Badge>
+ *       <Badge variant="secondary">AI</Badge>
  *     </div>
  *   </CardFooter>
  * </Card>
@@ -83,6 +84,19 @@
  *
  * <Card variant="overlay">...</Card>
  *
+ * ### Hover actions
+ *
+ * On `variant="default"`, hovering the card (or focusing anything inside it) fades a `card-hover` scrim over `<CardMedia>` and lifts the card with `shadow-card-light`. Place `<CardMediaSelect>` (top-left, e.g. `<Checkbox size="lg" />`) and/or `<CardMediaActions>` (top-right icon toolbar) inside `<CardMedia>` — both stay hidden until hover/focus-within, and are always visible on touch devices. Don't combine them with `as="a"`: interactive children inside an anchor are invalid HTML.
+ *
+ * <CardMedia>
+ *   <img ... />
+ *   <CardMediaSelect><Checkbox size="lg" aria-label="Select card" /></CardMediaSelect>
+ *   <CardMediaActions>
+ *     <button aria-label="Copy link"><Link /></button>
+ *     <button aria-label="More actions"><Ellipsis /></button>
+ *   </CardMediaActions>
+ * </CardMedia>
+ *
  * ### 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`.
@@ -128,9 +142,10 @@ const cardVariants = cva(
   {
     variants: {
       variant: {
-        default: "bg-card border border-border",
-        ghost: "",
-        overlay: "",
+        default:
+          "bg-card border border-border transition-shadow hover:shadow-card-light focus-within:shadow-card-light",
+        ghost: "border border-transparent",
+        overlay: "border border-transparent",
       },
       size: {
         default: "",

package/src/components/card/CardContent.astro

@@ -19,7 +19,7 @@ const contentVariants = cva("");
   {...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",
+    "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 group-data-[variant=overlay]/card:group-data-[size=large]/card:gap-10",
     contentVariants(),
     className,
   )}

package/src/components/card/CardDescription.astro

@@ -19,7 +19,7 @@ const descriptionVariants = cva("");
   {...rest}
   data-slot="card-description"
   class={cn(
-    "text-muted-foreground text-sm group-data-[size=large]/card:group-data-[orientation=vertical]/card:text-base group-data-[variant=overlay]/card:text-primary-foreground",
+    "text-muted-foreground text-sm group-data-[size=large]/card:group-data-[orientation=vertical]/card:not-in-data-[variant=overlay]:text-base group-data-[variant=overlay]/card:text-primary-foreground",
     descriptionVariants(),
     className,
   )}

package/src/components/card/CardMedia.astro

@@ -13,7 +13,7 @@ const {
 } = Astro.props as Props;
 
 const mediaVariants = cva(
-  "relative z-0 overflow-hidden pt-2 px-2 [&_img]:size-full [&_img]:rounded-md [&_img]:object-cover group-data-[orientation=horizontal]/card:w-2/5 group-data-[orientation=horizontal]/card:self-stretch group-data-[orientation=horizontal]/card:p-0",
+  "relative z-0 overflow-hidden pt-2 px-2 [&_img]:size-full [&_img]:rounded-md [&_img]:object-cover group-data-[orientation=horizontal]/card:w-2/5 group-data-[orientation=horizontal]/card:self-stretch group-data-[orientation=horizontal]/card:p-0 group-data-[variant=default]/card:after:pointer-events-none group-data-[variant=default]/card:after:absolute group-data-[variant=default]/card:after:inset-x-2 group-data-[variant=default]/card:after:top-2 group-data-[variant=default]/card:after:bottom-0 group-data-[variant=default]/card:after:rounded-md group-data-[variant=default]/card:after:bg-card-hover group-data-[variant=default]/card:after:opacity-0 group-data-[variant=default]/card:after:transition-opacity group-data-[variant=default]/card:after:duration-200 group-data-[variant=default]/card:group-hover/card:after:opacity-100 group-data-[variant=default]/card:group-focus-within/card:after:opacity-100",
 );
 ---
 

package/src/components/card/CardMediaActions.astro

@@ -0,0 +1,21 @@
+---
+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;
+---
+
+<div
+  {...rest}
+  data-slot="card-media-actions"
+  class={cn(
+    "absolute top-5 right-5 z-10 flex items-center gap-4 rounded-md border border-slider-background-disabled bg-card-hover py-1 pr-1.5 pl-2.5 text-primary-foreground opacity-0 transition-opacity duration-200 group-hover/card:opacity-100 group-focus-within/card:opacity-100 [@media(hover:none)]:opacity-100 [&_svg]:size-5",
+    className,
+  )}
+>
+  <slot />
+</div>

package/src/components/card/CardMediaSelect.astro

@@ -0,0 +1,21 @@
+---
+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;
+---
+
+<div
+  {...rest}
+  data-slot="card-media-select"
+  class={cn(
+    "absolute top-5 left-5 z-10 flex opacity-0 transition-opacity duration-200 group-hover/card:opacity-100 group-focus-within/card:opacity-100 [@media(hover:none)]:opacity-100",
+    className,
+  )}
+>
+  <slot />
+</div>

package/src/components/card/index.ts

@@ -1,10 +1,12 @@
-export { default as Card } from "./Card.astro";
-export { default as CardMedia } from "./CardMedia.astro";
-export { default as CardHeader } from "./CardHeader.astro";
-export { default as CardTitle } from "./CardTitle.astro";
-export { default as CardDescription } from "./CardDescription.astro";
-export { default as CardAction } from "./CardAction.astro";
-export { default as CardContent } from "./CardContent.astro";
-export { default as CardFooter } from "./CardFooter.astro";
-export { default as CardOverlay } from "./CardOverlay.astro";
-
+export { default as Card } from "./Card.astro";
+export { default as CardMedia } from "./CardMedia.astro";
+export { default as CardMediaSelect } from "./CardMediaSelect.astro";
+export { default as CardMediaActions } from "./CardMediaActions.astro";
+export { default as CardHeader } from "./CardHeader.astro";
+export { default as CardTitle } from "./CardTitle.astro";
+export { default as CardDescription } from "./CardDescription.astro";
+export { default as CardAction } from "./CardAction.astro";
+export { default as CardContent } from "./CardContent.astro";
+export { default as CardFooter } from "./CardFooter.astro";
+export { default as CardOverlay } from "./CardOverlay.astro";
+

package/src/components/carousel/CHANGELOG.md

@@ -1,5 +1,5 @@
-# Changelog
-
-All notable changes to the `Carousel` component will be documented in this file.
-
-## Unreleased
+# Changelog
+
+All notable changes to the `Carousel` component will be documented in this file.
+
+## Unreleased

package/src/components/carousel/index.ts

@@ -1,3 +1,3 @@
-export { default as Carousel } from "./Carousel.astro";
-export { default as CarouselSlide } from "./CarouselSlide.astro";
-
+export { default as Carousel } from "./Carousel.astro";
+export { default as CarouselSlide } from "./CarouselSlide.astro";
+