@cl-light-ds/ui 0.1.0

package/src/components/dialog/Dialog.astro

@@ -0,0 +1,196 @@
+---
+/**
+ * @component Dialog
+ * @title Dialog
+ * @description An accessible modal window for focused content or user actions with customizable open/close behavior.
+ * @figmaUrl https://www.figma.com/design/qXkzdqZ3QPQqgckU3AwIAH/ClickLearn-Lightning-Design-Library?node-id=141-6002
+ *
+ * @preview
+ *
+ * <Dialog>
+ *   <DialogTrigger asChild>
+ *     <Button>Manage Cookies</Button>
+ *   </DialogTrigger>
+ *
+ *   <DialogContent class="sm:max-w-lg">
+ *     <DialogHeader>
+ *       <DialogTitle>Manage Cookies</DialogTitle>
+ *       <DialogDescription>
+ *         Using websites and apps involves storing and retrieving information from your device, including cookies and other identifiers.
+ *       </DialogDescription>
+ *     </DialogHeader>
+ *     <div class="mt-3">
+ *       <div class="flex items-center gap-3">
+ *         <Checkbox id="cookies-necessary" name="cookies-necessary" disabled checked />
+ *         <Label for="cookies-necessary">Strictly Necessary Cookies (always active)</Label>
+ *       </div>
+ *       <p class="text-sm text-muted-foreground ml-8 mt-1">These cookies are essential for the site to function and cannot be toggled off. They assist with security, user authentication, customer support, etc.</p>
+ *     </div>
+ *     <div class="mt-3">
+ *       <div class="flex items-center gap-3">
+ *         <Checkbox id="cookies-analytics" name="cookies-analytics" />
+ *         <Label for="cookies-analytics">Analytics Cookies</Label>
+ *       </div>
+ *       <p class="text-sm text-muted-foreground ml-8 mt-1">These cookies help us understand how visitors interact with our site. They allow us to measure traffic and improve site performance.</p>
+ *     </div>
+ *     <div class="mt-3">
+ *       <div class="flex items-center gap-3">
+ *         <Checkbox id="cookies-marketing-performance" name="cookies-marketing-performance" />
+ *         <Label for="cookies-marketing-performance">Marketing Performance Cookies</Label>
+ *       </div>
+ *       <p class="text-sm text-muted-foreground ml-8 mt-1">These cookies help us measure the effectiveness of our marketing campaigns.</p>
+ *     </div>
+ *     <DialogFooter>
+ *       <Button data-slot="dialog-close" class="mt-4" variant="outline">Close</Button>
+ *       <Button data-dialog-close class="mt-4">Save changes</Button>
+ *     </DialogFooter>
+ *   </DialogContent>
+ * </Dialog>
+ *
+ * @usage
+ *
+ * ```astro nocollapse
+ * ---
+ * import { Dialog, DialogTitle, DialogDescription, DialogContent, DialogFooter, DialogClose } from '@bejamas/ui/components/dialog';
+ * import { Button } from '@bejamas/ui/components/button';
+ * ---
+ *
+ *
+ * <Dialog id="myDialog">
+ *   <DialogTrigger>Open Dialog</DialogTrigger>
+ *   <DialogContent>
+ *     <DialogTitle>Dialog Title</DialogTitle>
+ *     <DialogDescription>Dialog description.</DialogDescription>
+ *     Content here
+ *     <DialogFooter>
+ *       <DialogClose>Close</DialogClose>
+ *     </DialogFooter>
+ *   </DialogContent>
+ * </Dialog>
+ * ```
+ *
+ * @api
+ *
+ * ### Events
+ *
+ * The dialog emits custom events that you can listen to:
+ *
+ * | Event | Detail | Description |
+ * |-------|--------|-------------|
+ * | `dialog:change` | `{ open: boolean }` | Fired when the open state changes |
+ *
+ * ```astro nocollapse
+ * <Dialog id="my-dialog">
+ *   <DialogTrigger>Open Dialog</DialogTrigger>
+ *   <DialogContent>
+ *     <DialogTitle>Title</DialogTitle>
+ *     <DialogDescription>Description</DialogDescription>
+ *   </DialogContent>
+ * </Dialog>
+ * ```
+ *
+ * ```js nocollapse
+ *   const dialog = document.getElementById('my-dialog');
+ *
+ *   dialog.addEventListener('dialog:change', (e) => {
+ *     console.log('Is open:', e.detail.open);
+ *   });
+ * ```
+ *
+ * ### Programmatic Control
+ *
+ * You can control the dialog programmatically by dispatching a `dialog:set` event:
+ *
+ * ```js nocollapse
+ * const dialog = document.getElementById('my-dialog');
+ *
+ * // Open the dialog
+ * dialog.dispatchEvent(new CustomEvent('dialog:set', {
+ *   detail: { open: true }
+ * }));
+ *
+ * // Close the dialog
+ * dialog.dispatchEvent(new CustomEvent('dialog:set', {
+ *   detail: { open: false }
+ * }));
+ * ```
+ *
+ * ### Data Attributes
+ *
+ * The dialog sets these data attributes that you can use for styling or querying state:
+ *
+ * | Attribute | Element | Description |
+ * |-----------|---------|-------------|
+ * | `data-state` | dialog | Current state (`open` or `closed`) |
+ *
+ * @examples
+ *
+ * ### Nested Dialogs
+ *
+ * <Dialog>
+ *   <Button data-slot="dialog-trigger" class="">Open Nested Dialog</Button>
+ *   <DialogContent class="sm:max-w-lg">
+ *     <DialogHeader>
+ *       <DialogTitle>Nested Dialog</DialogTitle>
+ *       <DialogDescription>
+ *         Using websites and apps involves storing and retrieving information from your device, including cookies and other identifiers.
+ *       </DialogDescription>
+ *     </DialogHeader>
+ *     <DialogFooter>
+ *       <Button data-slot="dialog-close" class="mt-4" variant="outline">Close</Button>
+ *       <Dialog>
+ *         <Button data-slot="dialog-trigger" class="mt-4">Open Nested Dialog</Button>
+ *         <DialogContent class="sm:max-w-md">
+ *           <DialogHeader>
+ *             <DialogTitle>Nested Dialog</DialogTitle>
+ *             <DialogDescription>
+ *               Using websites and apps involves storing and retrieving information from your device, including cookies and other identifiers.
+ *             </DialogDescription>
+ *           </DialogHeader>
+ *         </DialogContent>
+ *       </Dialog>
+ *     </DialogFooter>
+ *   </DialogContent>
+ * </Dialog>
+ *
+ */
+import { cn } from "@cl-light-ds/ui/lib/utils";
+import type { HTMLAttributes } from "astro/types";
+
+interface Props extends HTMLAttributes<"div"> {
+  defaultOpen?: boolean;
+  class?: string;
+  closeOnClickOutside?: boolean;
+  closeOnEscape?: boolean;
+  lockScroll?: boolean;
+}
+
+const {
+  class: className = "",
+  defaultOpen = false,
+  closeOnClickOutside = true,
+  closeOnEscape = true,
+  lockScroll = true,
+  ...rest
+} = Astro.props as Props;
+---
+
+<div
+  data-slot="dialog"
+  data-default-open={defaultOpen}
+  data-close-on-click-outside={closeOnClickOutside}
+  data-close-on-escape={closeOnEscape}
+  data-lock-scroll={lockScroll}
+  class={cn("", className)}
+  {...rest}
+>
+  <slot />
+</div>
+
+<script>
+  import { createDialog } from "@data-slot/dialog";
+
+  document
+    .querySelectorAll<HTMLElement>('[data-slot="dialog"]')
+    .forEach((el) => createDialog(el));
+</script>

package/src/components/dialog/DialogClose.astro

@@ -0,0 +1,23 @@
+---
+import { cn } from "@cl-light-ds/ui/lib/utils";
+import type { HTMLAttributes } from "astro/types";
+import Button from "../button/Button.astro";
+
+interface Props extends HTMLAttributes<"button"> {
+  class?: string;
+}
+
+const { class: className = "", ...rest } = Astro.props as Props;
+---
+
+<Button
+  {...rest}
+  data-slot="dialog-close"
+  data-dialog-close
+  variant="ghost"
+  size="icon-sm"
+  class={cn("absolute top-2 right-2", className)}
+>
+  <slot />
+  {!Astro.slots.has("default") && <span class="sr-only">Close</span>}
+</Button>

package/src/components/dialog/DialogContent.astro

@@ -0,0 +1,42 @@
+---
+import { cn } from "@cl-light-ds/ui/lib/utils";
+import type { HTMLAttributes } from "astro/types";
+
+import DialogClose from "./DialogClose.astro";
+import DialogOverlay from "./DialogOverlay.astro";
+
+interface Props extends HTMLAttributes<"div"> {
+  showCloseButton?: boolean;
+}
+
+const {
+  showCloseButton = true,
+  class: className = "",
+  ...rest
+} = Astro.props as Props;
+---
+
+<div data-slot="dialog-portal" class="z-50 isolate absolute">
+  <DialogOverlay />
+  <div
+    data-slot="dialog-content"
+    hidden
+    class={cn(
+      "bg-card border-border data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 max-w-[calc(100%-2rem)] rounded-lg border shadow-lg duration-100 sm:max-w-md fixed top-1/2 left-1/2 z-50 w-full -translate-x-1/2 -translate-y-1/2 outline-none",
+      className,
+    )}
+    {...rest}
+  >
+    <div class="grid gap-6 p-6 text-sm">
+      <slot />
+    </div>
+    {
+      showCloseButton && (
+        <DialogClose>
+          <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M18 6L6 18M6 6l12 12"/></svg>
+          <span class="sr-only">Close</span>
+        </DialogClose>
+      )
+    }
+  </div>
+</div>

package/src/components/dialog/DialogDescription.astro

@@ -0,0 +1,18 @@
+---
+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="dialog-description"
+  class={cn("text-muted-foreground *:[a]:hover:text-foreground text-sm *:[a]:underline *:[a]:underline-offset-3", className)}
+>
+  <slot />
+</div>

package/src/components/dialog/DialogFooter.astro

@@ -0,0 +1,18 @@
+---
+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="dialog-footer"
+  class={cn("flex justify-end gap-2", className)}
+>
+  <slot />
+</div>

package/src/components/dialog/DialogHeader.astro

@@ -0,0 +1,18 @@
+---
+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
+  data-slot="dialog-header"
+  class={cn("gap-2 flex flex-col", className)}
+  {...rest}
+>
+  <slot />
+</div>

package/src/components/dialog/DialogOverlay.astro

@@ -0,0 +1,19 @@
+---
+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
+  hidden
+  data-slot="dialog-overlay"
+  class={cn("data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 bg-black/10 duration-100 supports-backdrop-filter:backdrop-blur-xs fixed inset-0 isolate z-50", className)}
+  {...rest}
+>
+  <slot />
+</div>

package/src/components/dialog/DialogTitle.astro

@@ -0,0 +1,18 @@
+---
+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="dialog-title"
+  class={cn("text-xl leading-6 font-semibold cn-font-heading", className)}
+>
+  <slot />
+</div>

package/src/components/dialog/DialogTrigger.astro

@@ -0,0 +1,37 @@
+---
+import { cn } from "@cl-light-ds/ui/lib/utils";
+import type { HTMLAttributes } from "astro/types";
+
+interface Props extends HTMLAttributes<"button"> {
+  class?: string;
+  /** Radix-like: render wrapper so the child can be the interactive element */
+  asChild?: boolean;
+}
+
+const {
+  class: className = "",
+  asChild = false,
+  type = "button",
+  ...rest
+} = Astro.props as Props;
+
+const defaultClasses =
+  "cursor-pointer select-none outline-none group-focus-within:pointer-events-none inline-flex items-center gap-1";
+---
+
+{
+  asChild ? (
+    <div data-slot="dialog-trigger" data-as-child class={cn("", defaultClasses, className)}>
+      <slot />
+    </div>
+  ) : (
+    <button
+      {...rest}
+      type={type}
+      data-slot="dialog-trigger"
+      class={cn("", defaultClasses, className)}
+    >
+      <slot />
+    </button>
+  )
+}

package/src/components/dialog/index.ts

@@ -0,0 +1,9 @@
+export { default as Dialog } from "./Dialog.astro";
+export { default as DialogTitle } from "./DialogTitle.astro";
+export { default as DialogDescription } from "./DialogDescription.astro";
+export { default as DialogContent } from "./DialogContent.astro";
+export { default as DialogFooter } from "./DialogFooter.astro";
+export { default as DialogClose } from "./DialogClose.astro";
+export { default as DialogHeader } from "./DialogHeader.astro";
+export { default as DialogTrigger } from "./DialogTrigger.astro";
+export { default as DialogOverlay } from "./DialogOverlay.astro";

package/src/components/dropdown-menu/CHANGELOG.md

@@ -0,0 +1,194 @@
+# Changelog
+
+All notable changes to the `DropdownMenu` component will be documented in this file.
+
+## Date 10th Sep 2026
+## Figma alignment (node 2329-6521, prop table 7392-10142)
+
+### Variants
+
+- Added a `category` variant to `DropdownMenuItem` (`variant: "default" | "destructive" | "category"`, was `"default" | "destructive"`), matching Figma's `.item` component set which documents `Category` as a third item variant. Renders as a non-interactive (`role="presentation"`, `tabindex={-1}`, `pointer-events-none`), muted (`text-muted-foreground font-medium`) row — the visual is intentionally close to the existing `DropdownMenuLabel`, but this variant lives on `DropdownMenuItem` itself so it can sit inline in a list without an extra import, per Figma's own prop table contract. It does not render a separator automatically — pair it with the existing `<DropdownMenuSeparator />` if a divider is wanted, same as any other item.
+- Converted `DropdownMenuItem` from hardcoded `data-[variant=...]:` Tailwind selectors to `class-variance-authority` (`cva`), matching the pattern already used by `Card`/`Button`/`Badge`/`Avatar`.
+
+### Sizing & Spacing
+
+- **Radius:** `rounded-sm` (4px) → `rounded-lg` (8px) on `DropdownMenuItem`, `DropdownMenuCheckboxItem`, and `DropdownMenuRadioItem` — Figma's item box is consistently `rounded-[8px]`.
+- **Padding:** `py-1.5` (6px) → `py-1` (4px) on all three item components — Figma's item is `py-[4px]` (`spacing/1`), horizontal `px-2` (`spacing/2`, 8px) was already correct.
+- **Typography:** item label moved from unstyled `text-sm` (14px, regular) → `text-xs font-semibold` (12px/600) on all three item components, matching Figma's `text/sm/sm-semibold` text style for the item label. Supportive text (new, see below) is `text-xs font-normal text-muted-foreground`.
+- **Popover chrome** (`DropdownMenuContent`): `ring-1 ring-foreground/10` → `border border-border` (Figma uses a real 1px border, not a ring); `shadow-md` → Figma's actual 3-layer `shadow-lg` drop-shadow (`0.3px 2px/-2.2 spread #1F003B05, 0.5px 3.2px/-1.4 #1F003B08, 0.7px 4px/-1.8 #1F003B0F`); `p-1` (4px) → `p-2` (8px); added an explicit `gap-1.5` (6px) between items, matching Figma's item-to-item gap (previously no gap was set at all, relying on nothing — items had no separation beyond their own padding).
+
+### New Props (`DropdownMenuItem` only)
+
+Following the Button/Badge "boolean prop, auto-detected from a named slot via `Astro.slots.has(...)`" convention:
+
+- `checked?: boolean` (default `false`) — presentational checked state, only visible when `showCheckbox` is also set.
+- `showCheckbox?: boolean` (default `false`) — reserves a 20px leading slot for a checkmark; **kept the existing indicator pattern** (no visible box at rest, a checkmark fades in when `checked`), matching `DropdownMenuCheckboxItem`'s existing visual language rather than inventing Figma's filled-square glyph, which has no documented unchecked state in the file. `DropdownMenuCheckboxItem` itself is unchanged — this is a separate, presentation-only affordance for a plain `DropdownMenuItem`.
+- `leadingIcon?: boolean` (default: has a `leading-icon` slot) — renders `<slot name="leading-icon" />` at 20px.
+- `avatar?: boolean` (default: has an `avatar` slot) — renders `<slot name="avatar" />`. Use `<Avatar size="sm">` (24px) — it already matches Figma's item avatar size exactly, no new Avatar sizing needed.
+- `showBadge?: boolean` (default: has a `badge` slot) — renders `<slot name="badge" />`. Use `<Badge size="sm">`.
+- `showSubmenuIcon?: boolean` (default `false`) — renders a static 20px chevron-right. **Cosmetic only** — there is no nested-submenu infrastructure (flyout positioning, keyboard handling) anywhere in `DropdownMenu` yet. See "Flagged for the designer" below.
+- `supportiveText?: boolean` (default: has a `supportive-text` slot) — renders a second, muted line under the item label via `<slot name="supportive-text" />`.
+
+`leadingIcon`, `avatar`, and `showCheckbox` are independent booleans (can combine), per Figma's literal prop table — not consolidated into a single `leading` enum.
+
+### Trigger
+
+- `DropdownMenuTrigger` now defaults `variant="outline"` (was inheriting `Button`'s own default `"default"`/primary-blue variant) — Figma's default/closed trigger state is a white/bordered button, not primary. Still fully overridable via the existing `variant` prop.
+- `DropdownMenuTrigger` now renders a default trailing chevron (`ChevronDown` from `@lucide/astro`) when the consumer doesn't slot their own `tail-icon` content — Figma's trigger always shows a chevron as core anatomy, not an opt-in add-on. It rotates 180° when the menu is open via a new `group/dropdown-menu` marker added to `DropdownMenu.astro`'s root (`data-state` lands on that root element, confirmed in `@data-slot/dropdown-menu`'s runtime). Pass `tailIcon={false}` to opt out entirely, or your own `<Icon slot="tail-icon" />` to override.
+
+### Tokens (`globals.css`)
+
+- No new tokens needed. Every color/radius used above (`background`, `background-hover`, `muted`, `muted-foreground`, `foreground`, `border`, `ring`, `chart-1`, `destructive`, `popover`, `primary`, `primary-foreground`) already existed — this was a binding/usage fix, not a token-addition pass.
+
+### Storybook & Docs
+
+- `apps/web/src/pages/storybook/_sections/dropdown-menu.astro`: added the seven new `DropdownMenuItem` prop rows to `itemProps`, updated the `variant` row to include `"category"`, and added preview blocks for leading icon / avatar / badge / supportive text / category / checkbox.
+- `DropdownMenuStory.astro` / `DropdownMenu.stories.ts`: added stories covering the new item variants/props.
+
+### Not changed
+
+- `DropdownMenuLabel.astro` — spotted a pre-existing bug while auditing (its class list sets both `text-xs` and `text-sm`, with `text-sm` winning via `tailwind-merge`, so labels render at 14px instead of the intended 12px) but left as-is since it wasn't part of this pass's scope; worth a follow-up fix.
+- `DropdownMenuGroup.astro`, `DropdownMenuSeparator.astro`, `DropdownMenuPortal.astro`, `DropdownMenuRadioGroup.astro`, `DropdownMenuShortcut.astro` — no Figma delta identified.
+
+### Flagged for the designer / engineering (not addressed in this pass)
+
+- **Real nested submenus:** Figma's `.item` prop table documents `showSubmenuIcon`, implying a submenu affordance, but no submenu flyout, positioning, or keyboard-navigation behavior exists anywhere in `DropdownMenu`'s runtime (`@data-slot/dropdown-menu`). This pass ships the chevron as a static, cosmetic icon only. Building real nested submenus is a separate, larger feature.
+- **Checkbox unchecked state:** Figma's item file only shows a filled/checked 20px checkbox square in its Left Content — there's no authored unchecked-square state to match. `showCheckbox`/`checked` on `DropdownMenuItem` therefore reuses the existing checkmark-only indicator pattern instead; worth designing a real unchecked square in Figma if a literal checkbox control (vs. a checked-indicator) is wanted here later.
+- **`DropdownMenuLabel` vs. `DropdownMenuItem variant="category"` overlap:** these are now two different ways to render a muted section header (one a dedicated component, one an item variant). Worth a follow-up design decision on whether `DropdownMenuLabel` should be deprecated in favor of `variant="category"`, or the two are meant to serve genuinely different call sites.
+
+## Date 10th Sep 2026 (follow-up)
+## Fix: menuitemcheckbox/menuitemradio alignment + item padding (node 2329-6521, prop table 7392-10142)
+
+The designer updated Figma again after the first pass above: the `DropdownMenuItem` prop table now
+explicitly ties `showCheckbox` to *"menuitemcheckbox"* and adds a new `showRadio` → *"menuitemradio"*,
+and the item component's padding/radio glyph changed. This entry reconciles that with the framework's
+existing three-component structure (`DropdownMenuItem` / `DropdownMenuCheckboxItem` / `DropdownMenuRadioItem`)
+rather than collapsing them into one — see "Architecture" below for why.
+
+### Architecture
+
+- Extracted the shared item chrome into two new **internal, non-exported** files (not added to `index.ts`,
+  same precedent as `DropdownMenuStory.astro`): `dropdown-menu-item-variants.ts` (the single `cva` box-class
+  builder) and `DropdownMenuItemContent.astro` (the shared Left Content / label / Right Content layout).
+  `DropdownMenuItem`, `DropdownMenuCheckboxItem`, and `DropdownMenuRadioItem` all now render through these,
+  instead of each duplicating the same padding/typography classes.
+- **Did not consolidate into one role-switching component.** Figma's single-component mental model
+  (`DropdownMenuItem` + a boolean that "becomes" a checkbox/radio) doesn't map cleanly onto this
+  framework: `@data-slot/dropdown-menu`'s runtime detects real interactive item type purely from each
+  element's `data-slot` value and manages `role`/`tabindex`/`aria-checked`/checked-state tracking
+  automatically for `[data-slot="dropdown-menu-checkbox-item"]` / `[data-slot="dropdown-menu-radio-item"]`.
+  Collapsing three ARIA-correct, already-working components into one conditionally-shaped component would
+  have been a much larger, riskier change for no framework-side benefit — the shared-chrome extraction above
+  gets the same "one visual spec, one place" outcome without touching the runtime contract.
+
+### Sizing & Spacing
+
+- **Padding correction:** Figma's item box is now uniform `p-2` (8px on all sides) for `default`/`destructive`
+  — was `px-2 py-1` last pass (a padding fix I hadn't fully caught the first time). Row height grows
+  24px → 32px accordingly, on `DropdownMenuItem`, `DropdownMenuCheckboxItem`, and `DropdownMenuRadioItem`.
+- **`category` has its own distinct, tighter padding** (`pt-1 px-1 pb-0 gap-1`, no `p-2`) — this was already
+  structurally different in Figma and wasn't captured correctly last pass, where it incorrectly shared the
+  interactive variants' row padding.
+- `DropdownMenuCheckboxItem`/`DropdownMenuRadioItem` **dropped their old asymmetric `pr-8 pl-2` padding**
+  entirely — no longer needed now that the checked/selected indicator lives in Left Content instead of
+  floating absolute-right (see below), so they use the exact same `p-2` box as a plain `DropdownMenuItem`.
+
+### Checkbox / Radio glyph — switched to Figma's literal look
+
+- `DropdownMenuCheckboxItem`/`DropdownMenuRadioItem` moved from the old shadcn-style indicator (invisible
+  until checked, a bare checkmark fading in at `absolute right-2`) to Figma's literal glyph: an
+  always-reserved 20px box (`rounded-sm`, checkbox) or circle (`rounded-full`, radio) in Left Content,
+  outlined (`border-input`) when unchecked and `bg-primary border-primary` + a white check icon / centered
+  dot when checked. Visual language borrowed directly from the existing `Checkbox.astro`/`RadioGroupItem.astro`
+  components (same token usage, scaled to the item's 20px glyph size) rather than inventing new colors.
+- This is driven purely by CSS off the `data-checked` attribute the runtime **already sets** on these exact
+  elements (confirmed in `@data-slot/dropdown-menu`'s source) via `group-data-checked/dropdown-menu-item:` —
+  no new JavaScript needed, no change to the runtime's checked-state tracking or click/keyboard handling.
+- `DropdownMenuItem`'s own presentational `showCheckbox` also switched from the old checkmark-only pattern to
+  the same 20px box glyph (driven by its static `checked` prop, not runtime state), for visual consistency
+  with the real components. New presentational `showRadio` (see below) uses the matching circle glyph.
+- **Resolves last pass's "Checkbox unchecked state" flag** — Figma still doesn't author a literal unchecked
+  square, but reusing `Checkbox`'s existing unchecked visual (bordered, no fill) is a defensible, low-risk
+  default that's already established elsewhere in the design system.
+
+### New Props
+
+- `DropdownMenuItem` gains `showRadio?: boolean` (default `false`), mirroring `showCheckbox` — presentational
+  only, reuses the shared `checked` prop. Per Figma's prop table: `showRadio` → *"Show radiobutton which is
+  menuitemradio"*.
+- `DropdownMenuCheckboxItem` and `DropdownMenuRadioItem` both gain the same extra prop surface
+  `DropdownMenuItem` got last pass: `leadingIcon`, `avatar`, `showBadge`, `showSubmenuIcon`, `supportiveText`
+  (same `Astro.slots.has(...)`-default convention). Sharing chrome made this nearly free, and Figma's own
+  item variants already mix a checkbox with other leading/trailing content in the same row.
+- `value`, `disabled`, `inset`, `defaultChecked`, `role="menuitemcheckbox"`/`"menuitemradio"`,
+  `data-slot="dropdown-menu-checkbox-item"`/`"dropdown-menu-radio-item"` are all **unchanged** — this is the
+  ARIA/runtime contract and was not touched.
+
+### Fixed (implementation bug, not a Figma delta)
+
+- While building the shared chrome, caught a real bug in the first draft: forwarding a
+  `<Fragment slot="leading-icon">` etc. from each root component into the shared `DropdownMenuItemContent`
+  made `Astro.slots.has("leading-icon")` always return `true` inside that shared partial (it saw the
+  pass-through Fragment, not whether the real end-consumer supplied content), so empty leading-icon/avatar/
+  badge wrapper `<span>`s rendered on every single item regardless of props. Fixed by resolving
+  `Astro.slots.has(...)` defaults in each outer component (`DropdownMenuItem`/`CheckboxItem`/`RadioItem`,
+  against their *own* callers) and passing explicit resolved booleans down — the shared partial no longer
+  does any slot introspection of its own. Verified via built story output before/after (span count per item
+  went from unconditional-always to matching only the items that actually set the prop).
+
+### Storybook & Docs
+
+- `apps/web/src/pages/storybook/_sections/dropdown-menu.astro`: added a `showRadio` row to `itemProps`;
+  updated `leadingIcon`/`avatar`/`showBadge`/`showSubmenuIcon`/`supportiveText` descriptions to note they now
+  apply to all three item components, not just `DropdownMenuItem`; enriched the Single Select/Multi Select
+  preview blocks to exercise the new prop parity (`supportiveText` on a radio item, `showBadge` on a checkbox
+  item); added `showRadio` to the "Item content" preview.
+- `DropdownMenuStory.astro`/`DropdownMenu.stories.ts`: added a new `CheckboxRadioContent` story
+  (`showCheckboxRadio` prop) covering presentational checked/unchecked checkbox and radio glyphs side by side
+  with the real, runtime-tracked `DropdownMenuCheckboxItem`/`DropdownMenuRadioItem` (one with `avatar`, one
+  with `showBadge`) so both visual systems are directly comparable.
+
+### Flagged for the designer / engineering (not addressed in this pass)
+
+- **`showCheckbox`/`showRadio` on plain `DropdownMenuItem` are cosmetic only** — they draw the glyph via a
+  static prop and don't manage checked/selected state or emit events. Don't reach for them expecting real
+  interactivity; that's what `DropdownMenuCheckboxItem`/`DropdownMenuRadioItem` are for. Worth a naming pass
+  if this keeps causing confusion (e.g. renaming the presentational props to make the distinction more
+  obvious in autocomplete).
+- Carried over from last pass, still open: real nested submenus (`showSubmenuIcon` is still cosmetic-only),
+  and the `DropdownMenuLabel` vs. `variant="category"` overlap.
+
+## Date 10th Sep 2026 (follow-up)
+## Fix: distinct Hover vs. Focus states (node 2529-2338, item states)
+
+While adding a states preview to the Storybook docs, caught that `DropdownMenuItem` (and by extension
+`DropdownMenuCheckboxItem`/`DropdownMenuRadioItem`, which share its `cva`) only ever had **one** interactive
+style — `focus:bg-background-hover` — with no real `:hover` class at all. Figma documents Hover and Focused
+as two visually distinct states (Hover: grey background only; Focused: a blue border + ring, no background
+change), which wasn't implemented.
+
+### Fixed
+
+- `dropdown-menu-item-variants.ts`: added a real `hover:bg-background-hover` (per variant, `destructive` gets
+  `hover:text-destructive dark:hover:bg-destructive/20`) so mouse hover now works with plain CSS — no JS
+  required, matching Figma's Hover state.
+- Replaced `focus:bg-background-hover` with `focus-visible:border-ring focus-visible:ring-2
+  focus-visible:ring-chart-1`, matching Figma's Focused effect (`border-ring` + a 2px ring) and the same
+  `focus-visible:border-ring focus-visible:ring-*` pattern already used by `Button`/`Card`. Added
+  `border border-transparent` to the shared base so the border can swap color on focus without any layout
+  shift (same technique `Button`/`Card` already use).
+- Using `:focus-visible` instead of plain `:focus` is deliberate: the dropdown runtime calls a real
+  `element.focus()` on pointer hover (so highlight tracks the mouse for accessibility purposes) — with
+  `:focus-visible`, browsers' own heuristics correctly suppress the keyboard-style ring for that
+  pointer-triggered focus (real `:hover` covers the visual instead) while still showing the ring for genuine
+  keyboard navigation (Tab/Arrow keys). Net effect: mouse hover shows grey background only, keyboard
+  navigation shows the blue ring — exactly Figma's distinction, with no behavior change to the runtime itself.
+
+### Storybook & Docs
+
+- `apps/web/src/pages/storybook/_sections/dropdown-menu.astro`: added a new "DropdownMenuItem states" preview
+  (Default/Hover/Focus/Disabled) above "DropdownMenuItem variants" — Hover/Focus rows use a forced `class`
+  override for an always-visible reference, with a note that the same states are live (hover/Tab to see them
+  for real anywhere in the gallery).
+
+## Unreleased