@cl-light-ds/ui 0.1.0

package/src/components/input/Input.astro

@@ -0,0 +1,130 @@
+---
+/**
+ * @component Input
+ * @title Input
+ * @description Base input field used in forms.
+ * @description A field for collecting user input.
+ * @figmaUrl https://www.figma.com/design/qXkzdqZ3QPQqgckU3AwIAH/ClickLearn-Lightning-Design-Library?node-id=145-3
+ * @status stable
+ * @since 0.1.0
+ *
+ * @preview
+ *
+ * <Input type="text" placeholder="Enter your name" />
+ *
+ * @usage
+ *
+ * ```astro nocollapse
+ * ---
+ * import { Input } from '@bejamas/ui/components/input';
+ * ---
+ * <Input type="email" placeholder="Enter your email" />
+ * ```
+ *
+ * @examples
+ *
+ * ### Default
+ *
+ * <Input type="email" placeholder="Enter your email" />
+ *
+ * ### Disabled
+ *
+ * <Input type="email" placeholder="Enter your email" disabled />
+ *
+ * ### Sizes
+ *
+ * <div class="grid w-full max-w-sm gap-3">
+ *   <div class="flex items-center gap-2">
+ *     <Input size="sm" placeholder="Small input (h-8)" />
+ *     <Button size="sm" variant="outline">
+ *       Small
+ *     </Button>
+ *   </div>
+ *   <div class="flex items-center gap-2">
+ *     <Input placeholder="Default input (h-9)" />
+ *     <Button variant="outline">Default</Button>
+ *   </div>
+ *   <div class="flex items-center gap-2">
+ *     <Input size="lg" placeholder="Large input (h-10)" />
+ *     <Button size="lg" variant="outline">
+ *       Large
+ *     </Button>
+ *   </div>
+ * </div>
+ *
+ * ### File
+ *
+ * <div class="grid w-full max-w-sm items-center gap-3">
+ *   <Label htmlFor="picture">Picture</Label>
+ *   <Input id="picture" type="file" />
+ * </div>
+ *
+ * ### With Label
+ *
+ * <div class="grid w-full max-w-sm items-center gap-3">
+ *   <Label htmlFor="email">Email</Label>
+ *   <Input id="email" type="email" placeholder="Enter your email" />
+ * </div>
+ *
+ * ### With Button
+ *
+ *  <div class="flex w-full max-w-sm items-center gap-2">
+ *    <Input type="email" placeholder="Email" />
+ *    <Button type="submit" variant="outline">
+ *      Subscribe
+ *    </Button>
+ *  </div>
+ */
+
+import { cn } from "@cl-light-ds/ui/lib/utils";
+import { cva, type VariantProps } from "class-variance-authority";
+import type { HTMLAttributes } from "astro/types";
+
+const inputVariants = cva(
+  "w-full min-w-0 outline-none file:inline-flex file:border-0 file:bg-transparent disabled:pointer-events-none disabled:cursor-not-allowed",
+  {
+    variants: {
+      size: {
+        sm: "data-[size=sm]",
+        default: "data-[size=default]",
+        lg: "data-[size=lg]",
+      },
+    },
+    defaultVariants: {
+      size: "default",
+    },
+  },
+);
+
+type InputUiSize = NonNullable<VariantProps<typeof inputVariants>["size"]>;
+type NativeInputSize = HTMLAttributes<"input">["size"];
+
+interface Props extends Omit<HTMLAttributes<"input">, "size"> {
+  size?: InputUiSize | NativeInputSize;
+  nativeSize?: NativeInputSize;
+}
+
+const {
+  class: className = "",
+  type = "text",
+  size: sizeProp,
+  nativeSize,
+  ...props
+} = Astro.props as Props;
+
+const isUiSize = (value: unknown): value is InputUiSize =>
+  value === "sm" || value === "default" || value === "lg";
+
+const resolvedUiSize = isUiSize(sizeProp) ? sizeProp : "default";
+const resolvedNativeSize =
+  nativeSize ?? (!isUiSize(sizeProp) ? sizeProp : undefined);
+---
+
+<input
+  type={type}
+  size={resolvedNativeSize}
+  data-slot={props["data-slot"] ?? "input"}
+  data-size={resolvedUiSize}
+  class={cn("border-input focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive dark:aria-invalid:border-destructive/50 active:border-ring rounded-lg border bg-card shadow-xs transition-[color,box-shadow] file:h-7 file:text-sm file:font-medium focus-visible:ring-3 aria-invalid:ring-3 disabled:bg-muted disabled:text-muted-foreground data-[size=sm]:h-8 data-[size=sm]:px-2.5 data-[size=sm]:py-1 data-[size=sm]:md:text-xs data-[size=default]:h-9 data-[size=default]:px-2.5 data-[size=default]:py-1 data-[size=default]:md:text-sm data-[size=lg]:h-10 data-[size=lg]:px-3.5 data-[size=lg]:py-1.5 data-[size=lg]:md:text-base", inputVariants({ size: resolvedUiSize }), className)}
+  {...props}
+/>

package/src/components/input/index.ts

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

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

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to the `InputGroup` component family (`InputGroup`, `InputGroupAddon`, `InputGroupButton`, `InputGroupInput`, `InputGroupText`, `InputGroupTextarea`) are documented in this file.
+
+## 2026-09-10 — Figma alignment (ClickLearn Lightning Design Library, node `2282-6923`)
+
+Figma documents a single "Default" composition with three example rows: a lead-icon search input with trailing supportive text, a plain input with a trailing icon, and a multi-line textarea with a toolbar (icon button + ghost text button + supportive text + separator + circular primary send button). No Sizes/States/Variants pages exist for this component in Figma (unlike `Input`) — scope is narrower accordingly.
+
+### Fixed
+
+- Updated `@figmaUrl` from the old Bejamas file to the ClickLearn Lightning Design Library link.
+- Background: the root `InputGroup` container had no light-mode background at all (`dark:bg-input/30` with nothing for light mode, fully transparent) — Figma's surface token is `card` (`#ffffff`). Fixed to `bg-card`, same category of fix already made to `Input`/`DialogContent`/`HoverCardContent`.
+- Toolbar icon buttons (the leading `+` and the trailing send button in the textarea/toolbar composition): Figma's instances measure exactly 32×32px, which is the existing `icon-sm` size tier, not the `icon-xs` (24px) tier the demos were using. Fixed in `InputGroup.astro`'s own JSDoc preview, `InputGroupStory.astro`, and the storybook docs page (`_sections/input-group.astro`), plus the equivalent "Wide" example added to `Input`'s own storybook page.
+
+### Added
+
+- A "Tail icon" storybook example (plain input + trailing icon, no button) matching Figma's second documented row exactly — this composition wasn't previously demonstrated (the existing "https://" + "Check"-button example is a different, still-valid pattern, kept alongside).
+
+### Notes
+
+- `primary`/`primary-foreground` (send button), `foreground`/`background` (plain icon button), `muted-foreground` (addon text), and `radius-lg` all already matched Figma's tokens exactly — no changes needed.
+- No new props added — `InputGroup`'s existing `InputGroupAddon`/`InputGroupButton`/`InputGroupText`/`InputGroupTextarea` primitives already cover every composition Figma documents.
+
+## 2026-09-10 — Fixed `InputGroupButton` `size="sm"` no-op bug
+
+Surfaced by the new side-by-side sizes comparison above: `size="sm"` mapped to an empty string in `inputGroupButtonVariants`, so it added no override classes at all. Since `InputGroupButton` never forwards its own `size` prop to the underlying `Button` (only a `data-size` attribute), this meant `sm` silently fell through to `Button`'s own unscaled default size (`h-9`, 36px) — rendering *larger* than `xs` (24px), the opposite of what its name implies.
+
+### Fixed
+
+- `sm` → `"h-8 gap-1 px-2 text-xs [&>svg:not([class*='size-'])]:size-3.5"`, matching `Button`'s own existing `sm` tier (`h-8`, 32px) and lining up with `icon-sm`'s 32px — giving a clean two-tier scale (24px compact / 32px comfortable) across both text and icon-only buttons.
+
+## 2026-09-10 — Fixed `InputGroup`'s `size` prop doing nothing
+
+The user asked what the `size` prop actually controls — turned out to be nothing. Two separate, compounding bugs:
+
+1. `InputGroup.astro`'s root had a hard-coded, unconditional `h-9` — never actually responsive to its own `data-size` attribute, so the group container's own height never changed for `sm`/`lg`.
+2. The intended mechanism for resizing the *inner* `InputGroupInput` control (`group-data-[size=sm]/input-group:h-8`, etc.) existed only in `controlClasses.ts`'s `inputGroupControlClasses` export — but nothing in the codebase imported it. `InputGroupInput.astro` had its own separate, non-responsive hard-coded class list instead. Confirmed live: `sm`/`default`/`lg` all rendered at an identical 36px / 14px font.
+
+### Fixed
+
+- `InputGroup.astro`: replaced the unconditional `h-9` with `data-[size=sm]:h-8 data-[size=default]:h-9 data-[size=lg]:h-10` on the root.
+- `InputGroupInput.astro`: now imports and applies `inputGroupControlClasses` from `controlClasses.ts` instead of its own disconnected duplicate class list.
+- `controlClasses.ts`: even after reconnecting it, `sm`/`lg` still had no effect — inspected the actual matched CSS rules via Chrome DevTools Protocol and found a genuine specificity conflict: Tailwind compiles the `group-data-[size=sm]/input-group:h-8` ancestor selector wrapped in `:where(...)` (zero specificity), so the whole rule resolves to a single-class specificity — lower than `Input`'s own self-referential `data-[size=default]:h-9` (class + attribute selector), which is *always* active since `Input` always sets its own `data-size="default"` unless given an explicit `size` prop. Added `!` (Tailwind v4 important-marker) to every `group-data-[size=*]/input-group:` class in `inputGroupControlClasses` to force it to win regardless — same convention already used elsewhere in this codebase for equivalent specificity fights (e.g. `HoverCardContent`'s `data-[instant]:...!` classes).
+- Verified live: `sm`/`default`/`lg` now correctly render the group container **and** the inner input at 32/36/40px with 12/14/16px font, matching the demo labels for the first time.
+
+### Fixed (regression from the above)
+
+- Making the root's height conditional (`data-[size=default]:h-9`, one class + one attribute selector) accidentally gave it the *same* specificity as the existing `has-[>textarea]:h-auto` / `has-[>[data-align=block-*]]:h-auto` overrides (also one class + one pseudo-class) that make the "Wide" toolbar/textarea composition grow to fit its content instead of clipping to a fixed height. Previously the plain unconditional `h-9` (lower specificity, one class only) always lost to those `has-[]:` overrides safely — the new conditional version could win the specificity tie instead, depending on Tailwind's internal rule-emission order. Confirmed live: the "Wide" example's container had collapsed to a fixed 36px, clipping the toolbar row outside its border.
+- Fixed by adding `!` to `has-[>textarea]:h-auto`, `has-[>[data-align=block-end]]:h-auto`, and `has-[>[data-align=block-start]]:h-auto` on `InputGroup.astro`'s root, so they unconditionally win over the sizing classes whenever a textarea or block-aligned addon is present. Verified live: the "Wide" example is back to its correct auto-height (112px), and `sm`/`default`/`lg` sizing is unaffected (still 32/36/40px).

package/src/components/input-group/InputGroup.astro

@@ -0,0 +1,135 @@
+---
+/**
+ * @component InputGroup
+ * @title Input Group
+ * @description An input field with attached addons like icons, buttons, or text labels.
+ * @figmaUrl https://www.figma.com/design/qXkzdqZ3QPQqgckU3AwIAH/ClickLearn-Lightning-Design-Library?node-id=2282-6923
+ *
+ * @preview
+ *
+ * <div class="grid w-full max-w-sm gap-6">
+ *   <InputGroup>
+ *     <InputGroupInput placeholder="Search..." />
+ *     <InputGroupAddon>
+ *       <SearchIcon />
+ *     </InputGroupAddon>
+ *     <InputGroupAddon align="inline-end">12 results</InputGroupAddon>
+ *   </InputGroup>
+ *
+ *   <InputGroup>
+ *     <InputGroupInput placeholder="example.com" />
+ *     <InputGroupAddon>
+ *       <InputGroupText>https://</InputGroupText>
+ *     </InputGroupAddon>
+ *     <InputGroupAddon align="inline-end">
+ *       <InputGroupButton size="xs">Check</InputGroupButton>
+ *     </InputGroupAddon>
+ *   </InputGroup>
+ *
+ *   <InputGroup>
+ *     <InputGroupTextarea placeholder="Ask, Search or Chat..." />
+ *     <InputGroupAddon align="block-end">
+ *       <InputGroupButton size="icon-sm" class="rounded-full">
+ *         <PlusIcon />
+ *       </InputGroupButton>
+ *       <InputGroupButton variant="ghost">Auto</InputGroupButton>
+ *       <InputGroupText class="ml-auto">52% used</InputGroupText>
+ *       <Separator orientation="vertical" class="!h-4" />
+ *       <InputGroupButton size="icon-sm" variant="default" class="rounded-full">
+ *         <ArrowUpIcon />
+ *         <span class="sr-only">Send</span>
+ *       </InputGroupButton>
+ *     </InputGroupAddon>
+ *   </InputGroup>
+ * </div>
+ *
+ * @usage
+ *
+ * ```astro nocollapse
+ * ---
+ * import { InputGroup, InputGroupInput, InputGroupAddon, InputGroupButton, InputGroupText } from '@bejamas/ui/components/input-group';
+ * ---
+ *
+ * <InputGroup>
+ *   <InputGroupInput placeholder="Search..." />
+ *   <InputGroupAddon><SearchIcon /></InputGroupAddon>
+ * </InputGroup>
+ * ```
+ *
+ * @examples
+ *
+ * ### Sizes
+ *
+ * <div class="grid w-full max-w-sm gap-3">
+ *   <InputGroup size="sm">
+ *     <InputGroupInput placeholder="Small (h-8)" />
+ *   </InputGroup>
+ *   <InputGroup>
+ *     <InputGroupInput placeholder="Default (h-9)" />
+ *   </InputGroup>
+ *   <InputGroup size="lg">
+ *     <InputGroupInput placeholder="Large (h-10)" />
+ *   </InputGroup>
+ * </div>
+ *
+ * @api
+ *
+ * | Prop | Type | Default |
+ * | --- | --- | --- |
+ * | `size` | `"sm" \| "default" \| "lg"` | `"default"` |
+ */
+import type { HTMLAttributes } from "astro/types";
+import { cn } from "@cl-light-ds/ui/lib/utils";
+
+interface Props extends HTMLAttributes<"div"> {
+  size?: "sm" | "default" | "lg";
+  class?: string;
+}
+
+const {
+  size = "default",
+  class: className = "",
+  ...rest
+} = Astro.props as Props;
+---
+
+<div
+  {...rest}
+  role="group"
+  data-slot="input-group"
+  data-size={size}
+  class={cn(
+    "group/input-group border-input bg-card has-[[data-slot=input-group-control]:focus-visible]:border-ring has-[[data-slot=input-group-control]:focus-visible]:ring-ring/50 has-[[data-slot][aria-invalid=true]]:ring-destructive/20 has-[[data-slot][aria-invalid=true]]:border-destructive dark:has-[[data-slot][aria-invalid=true]]:ring-destructive/40 data-[size=sm]:h-8 data-[size=default]:h-9 data-[size=lg]:h-10 rounded-lg border shadow-xs transition-[color,box-shadow] in-data-[slot=combobox-content]:focus-within:border-inherit in-data-[slot=combobox-content]:focus-within:ring-0 has-[[data-slot=input-group-control]:focus-visible]:ring-3 has-[[data-slot][aria-invalid=true]]:ring-3 has-[>[data-align=block-end]]:h-auto! has-[>[data-align=block-end]]:flex-col has-[>[data-align=block-start]]:h-auto! has-[>[data-align=block-start]]:flex-col has-[>[data-align=block-end]]:[&>input]:pt-3 has-[>[data-align=block-start]]:[&>input]:pb-3 has-[>[data-align=inline-end]]:[&>input]:pr-1.5 has-[>[data-align=inline-start]]:[&>input]:pl-1.5 relative flex w-full min-w-0 items-center outline-none has-[>textarea]:h-auto!",
+    className,
+  )}
+>
+  <slot />
+</div>
+
+<script is:inline type="module">
+  // Focus the nearest input when clicking on addons (unless clicking a button)
+  document.addEventListener("click", (e) => {
+    const addon = e.target.closest("[data-slot='input-group-addon']");
+    if (!addon) return;
+    if (e.target.closest("button")) return;
+    const root = addon.closest("[data-slot='input-group']");
+    if (!root) return;
+    const input = root.querySelector(
+      "[data-input-group-control], [data-slot='input-group-control']",
+    );
+    input?.focus();
+  });
+  // Disabled styling passthrough when any control is disabled
+  document.querySelectorAll("[data-slot='input-group']").forEach((group) => {
+    const updateDisabled = () => {
+      const ctrl = group.querySelector(
+        "[data-input-group-control], [data-slot='input-group-control']",
+      );
+      group.dataset.disabled = ctrl?.hasAttribute("disabled")
+        ? "true"
+        : "false";
+    };
+    updateDisabled();
+    group.addEventListener("change", updateDisabled, { capture: true });
+  });
+</script>

package/src/components/input-group/InputGroupAddon.astro

@@ -0,0 +1,49 @@
+---
+import type { HTMLAttributes } from "astro/types";
+import { cva } from "class-variance-authority";
+import { cn } from "@cl-light-ds/ui/lib/utils";
+
+type Align = "inline-start" | "inline-end" | "block-start" | "block-end";
+
+interface Props extends HTMLAttributes<"div"> {
+  align?: Align;
+  class?: string;
+}
+
+const {
+  align = "inline-start",
+  class: className = "",
+  ...rest
+} = Astro.props as Props;
+
+const addonVariants = cva(
+  "text-muted-foreground h-auto gap-2 py-1.5 text-sm font-medium group-data-[disabled=true]/input-group:opacity-50 [&>kbd]:rounded-[calc(var(--radius)-5px)] [&>svg:not([class*='size-'])]:size-4 flex cursor-text items-center justify-center select-none",
+  {
+    variants: {
+      align: {
+        "inline-start":
+          "pl-2 has-[>button]:-ml-1 has-[>kbd]:ml-[-0.15rem] order-first",
+        "inline-end":
+          "pr-2 has-[>button]:-mr-1 has-[>kbd]:mr-[-0.15rem] order-last",
+        "block-start":
+          "px-2.5 pt-2 group-has-[>input]/input-group:pt-2 [.border-b]:pb-2 order-first w-full justify-start",
+        "block-end":
+          "px-2.5 pb-2 group-has-[>input]/input-group:pb-2 [.border-t]:pt-2 order-last w-full justify-start",
+      },
+    },
+    defaultVariants: {
+      align: "inline-start",
+    },
+  },
+);
+---
+
+<div
+  {...rest}
+  role="group"
+  data-slot="input-group-addon"
+  data-align={align}
+  class={cn(addonVariants({ align }), className)}
+>
+  <slot />
+</div>

package/src/components/input-group/InputGroupButton.astro

@@ -0,0 +1,58 @@
+---
+import type { HTMLAttributes } from "astro/types";
+import { cva } from "class-variance-authority";
+import { cn } from "@cl-light-ds/ui/lib/utils";
+import { Button } from "../button";
+
+type GroupButtonSize = "xs" | "sm" | "icon-xs" | "icon-sm";
+
+interface Props extends HTMLAttributes<"button"> {
+  size?: GroupButtonSize;
+  variant?:
+  | "default"
+  | "secondary"
+  | "outline"
+  | "ghost"
+  | "destructive"
+  | "link";
+  type?: "button" | "submit" | "reset";
+  class?: string;
+}
+
+const {
+  size = "xs",
+  variant = "ghost",
+  type = "button",
+  class: className = "",
+  ...rest
+} = Astro.props as Props;
+
+const inputGroupButtonVariants = cva(
+  "gap-2 text-sm flex items-center shadow-none",
+  {
+    variants: {
+      size: {
+        xs: "h-6 gap-1 rounded-[calc(var(--radius)-5px)] px-1.5 [&>svg:not([class*='size-'])]:size-3.5",
+        sm: "h-8 gap-1 px-2 text-xs [&>svg:not([class*='size-'])]:size-3.5",
+        "icon-xs":
+          "size-6 rounded-[calc(var(--radius)-5px)] p-0 has-[>svg]:p-0",
+        "icon-sm": "size-8 p-0 has-[>svg]:p-0",
+      },
+    },
+    defaultVariants: {
+      size: "xs",
+    },
+  },
+);
+---
+
+<Button
+  type={type}
+  data-size={size}
+  variant={variant}
+  data-slot="input-group-button"
+  class={cn(inputGroupButtonVariants({ size }), className)}
+  {...rest}
+>
+  <slot />
+</Button>

package/src/components/input-group/InputGroupInput.astro

@@ -0,0 +1,18 @@
+---
+import type { HTMLAttributes } from "astro/types";
+import { cn } from "@cl-light-ds/ui/lib/utils";
+import { Input } from "../input";
+import { inputGroupControlClasses } from "./controlClasses";
+
+interface Props extends HTMLAttributes<"input"> {
+  class?: string;
+}
+
+const { class: className = "", ...rest } = Astro.props as Props;
+---
+
+<Input
+  data-slot="input-group-control"
+  class={cn(inputGroupControlClasses, className)}
+  {...rest}
+/>

package/src/components/input-group/InputGroupText.astro

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

package/src/components/input-group/InputGroupTextarea.astro

@@ -0,0 +1,17 @@
+---
+import type { HTMLAttributes } from "astro/types";
+import { cn } from "@cl-light-ds/ui/lib/utils";
+import { Textarea } from "../textarea";
+
+interface Props extends HTMLAttributes<"textarea"> {
+  class?: string;
+}
+
+const { class: className = "", ...rest } = Astro.props as Props;
+---
+
+<Textarea
+  data-slot="input-group-control"
+  class={cn("rounded-none border-0 bg-transparent py-2 shadow-none ring-0 focus-visible:ring-0 aria-invalid:ring-0 dark:bg-transparent flex-1 resize-none", className)}
+  {...rest}
+/>

package/src/components/input-group/controlClasses.ts

@@ -0,0 +1,2 @@
+export const inputGroupControlClasses =
+  "rounded-none border-0 bg-transparent text-base shadow-none ring-0 focus-visible:ring-0 disabled:bg-transparent aria-invalid:ring-0 dark:bg-transparent dark:disabled:bg-transparent flex-1 min-w-0 group-data-[size=sm]/input-group:h-8! group-data-[size=sm]/input-group:px-2.5! group-data-[size=sm]/input-group:py-1! group-data-[size=sm]/input-group:md:text-xs! group-data-[size=default]/input-group:h-9! group-data-[size=default]/input-group:px-3! group-data-[size=default]/input-group:py-1! group-data-[size=default]/input-group:md:text-sm! group-data-[size=lg]/input-group:h-10! group-data-[size=lg]/input-group:px-3.5! group-data-[size=lg]/input-group:py-1.5! group-data-[size=lg]/input-group:md:text-base!";

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

@@ -0,0 +1,6 @@
+export { default as InputGroup } from "./InputGroup.astro";
+export { default as InputGroupAddon } from "./InputGroupAddon.astro";
+export { default as InputGroupButton } from "./InputGroupButton.astro";
+export { default as InputGroupInput } from "./InputGroupInput.astro";
+export { default as InputGroupText } from "./InputGroupText.astro";
+export { default as InputGroupTextarea } from "./InputGroupTextarea.astro";

package/src/components/item/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to the `Item` component family (`Item`, `ItemGroup`, `ItemSeparator`, `ItemHeader`, `ItemFooter`, `ItemMedia`, `ItemContent`, `ItemTitle`, `ItemDescription`, `ItemActions`) are documented in this file.
+
+## 2026-09-10 — Figma alignment (ClickLearn Lightning Design Library, node `2329-7472`)
+
+Figma documents Item across four pages: Variants (Default, Outline, Muted), Sizes (Small, Large, Header), States (Default, Hover, Focus, Disabled), and Contents (Tail Icon, Tail Button, Lead Icon, Lead Image).
+
+### Fixed
+
+- Updated `@figmaUrl` from the old Bejamas file to the ClickLearn Lightning Design Library link.
+- Removed a dead, redundant `rounded-md` — `rounded-lg` (added afterward in the same class string) always won anyway, same class of cleanup already done on Dialog/HoverCard/Input/TooltipContent.
+- Removed a broken hover selector, `[a]:hover:bg-muted` — invalid Tailwind arbitrary-variant syntax (missing `&`), effectively dead/no-op. Per the standing project direction to skip hover states ("ignore hover states, they are not necessary... I will delete from figma"), removed rather than fixed into a working hover state.
+- Removed dead, unreachable `group-data-[size=xs]/item:...` selectors in `ItemMedia`/`ItemContent`/`ItemDescription` and `has-data-[size=xs]:...` in `ItemGroup` — these referenced a size value that has never existed in `Item`'s own `size` prop type and isn't documented in Figma either; pure leftover dead code.
+
+### Added
+
+- **Focus state**: `has-[:focus-visible]:border-ring has-[:focus-visible]:ring-3 has-[:focus-visible]:ring-ring/50` on the root — Figma shows a border+glow-ring treatment on the whole item (ring hex confirmed `#5f9de6` = `--ring`; the baked-in glow color Figma shows, `#afcef3`, is just `--ring` at ~50% opacity over white, confirming this is the same `ring-3 ring-ring/50` idiom used everywhere else, e.g. `HoverCardContent`). Since `Item`'s root is a plain non-focusable `<div>`, this activates whenever a focusable descendant (e.g. an action button) receives keyboard focus.
+- **`disabled` prop** (new, `boolean`, default `false`): sets `aria-disabled="true"` + `data-disabled` on the root, styled via `data-[disabled=true]:bg-muted data-[disabled=true]:pointer-events-none` — matches Figma's Disabled state (a real `bg-muted` swap, not an opacity fade, same category as the Checkbox/Input disabled fixes). Scope note: this only styles/blocks-interaction on the `Item` root itself — it does not automatically disable nested interactive children (e.g. an `ItemActions` button); consumers should still set `disabled` on those separately, as shown in the new JSDoc example.
+- **`size="header"`** (new): Figma's third documented size is a fundamentally different vertical/card layout — full-width square media on top, title/description below, no trailing action. `Item`'s `flex-wrap`/`items-center` row layout is now driven entirely per-size (`default`/`sm` stay row-based; `header` switches to `flex-col items-start gap-4 p-4`), and `ItemMedia`'s `image` variant grows to a full-width square (`w-full aspect-square`, canceling the row-oriented baseline nudge) whenever the parent `Item` has `data-size="header"`.
+
+### Notes
+
+- Variants (`default`/`outline`/`muted`) already matched Figma's three variants exactly — no change needed.
+- Lead Icon / Lead Image / Tail Button content compositions were already fully achievable via the existing `ItemMedia`/`ItemActions` primitives.
+- **Tail Icon** (a trailing chevron, no lead media) is already achievable today via `<ItemActions><ChevronRight /></ItemActions>` — no new prop needed, just added a storybook example since it wasn't previously demonstrated.
+- Figma's "Small"/"Large" size names correspond to the code's existing `sm`/`default` tiers respectively — same recurring size-naming situation as Accordion/Checkbox/Input, not renamed here.

package/src/components/item/Item.astro

@@ -0,0 +1,122 @@
+---
+/**
+ * @component Item
+ * @title Item
+ * @description A versatile component for displaying any content, combining elements like title, description, media, and actions.
+ * @figmaUrl https://www.figma.com/design/qXkzdqZ3QPQqgckU3AwIAH/ClickLearn-Lightning-Design-Library?node-id=2329-7472
+ *
+ * @preview
+ *
+ * <div class="flex w-full max-w-md flex-col gap-6">
+ *   <Item variant="outline">
+ *     <ItemContent>
+ *       <ItemTitle>Basic Item</ItemTitle>
+ *       <ItemDescription>A simple item with title and description.</ItemDescription>
+ *     </ItemContent>
+ *     <ItemActions><Button variant="outline" size="sm">Action</Button></ItemActions>
+ *   </Item>
+ * </div>
+ *
+ * @usage
+ *
+ * ```astro nocollapse
+ * ---
+ * import { Item, ItemContent, ItemTitle, ItemDescription, ItemActions, ItemMedia } from '@bejamas/ui/components/item';
+ * ---
+ *
+ * <Item variant="outline">
+ *   <ItemContent>
+ *     <ItemTitle>Basic Item</ItemTitle>
+ *     <ItemDescription>A simple item.</ItemDescription>
+ *   </ItemContent>
+ *   <ItemActions>
+ *     <Button variant="outline" size="sm">Action</Button>
+ *   </ItemActions>
+ * </Item>
+ * ```
+ *
+ * @examples
+ *
+ * ### Header size
+ *
+ * <Item variant="outline" size="header" class="max-w-xs">
+ *   <ItemMedia mediaVariant="image">
+ *     <img src="https://gradient.bejamas.com/presets/bejamas/marine.png" alt="" />
+ *   </ItemMedia>
+ *   <ItemContent>
+ *     <ItemTitle>Security Alert</ItemTitle>
+ *     <ItemDescription>A simple item with title and description.</ItemDescription>
+ *   </ItemContent>
+ * </Item>
+ *
+ * ### Disabled
+ *
+ * <Item variant="outline" disabled>
+ *   <ItemContent>
+ *     <ItemTitle>Basic Item</ItemTitle>
+ *     <ItemDescription>A simple item with title and description.</ItemDescription>
+ *   </ItemContent>
+ *   <ItemActions><Button variant="outline" size="sm" disabled>Action</Button></ItemActions>
+ * </Item>
+ */
+
+import type { HTMLAttributes } from "astro/types";
+import { cva } from "class-variance-authority";
+import { cn } from "@cl-light-ds/ui/lib/utils";
+
+type ItemRootVariant = "default" | "outline" | "muted";
+type ItemRootSize = "default" | "sm" | "header";
+
+interface Props extends HTMLAttributes<"div"> {
+  variant?: ItemRootVariant;
+  size?: ItemRootSize;
+  disabled?: boolean;
+  class?: string;
+}
+
+const {
+  class: className = "",
+  variant = "default",
+  size = "default",
+  disabled = false,
+  ...rest
+} = Astro.props as Props;
+
+const itemVariants = cva(
+  "group/item flex outline-none transition-colors",
+  {
+    variants: {
+      variant: {
+        default: "border-transparent",
+        outline: "border-border",
+        muted: "bg-muted/50 border-transparent",
+      },
+      size: {
+        default: "flex-row flex-wrap items-center gap-3.5 px-4 py-3.5",
+        sm: "flex-row flex-wrap items-center gap-2.5 px-3 py-2.5",
+        header: "flex-col items-start gap-4 p-4",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  },
+);
+---
+
+<div
+  {...rest}
+  data-slot="item"
+  data-variant={variant}
+  data-size={size}
+  data-disabled={disabled}
+  aria-disabled={disabled ? "true" : undefined}
+  class={cn(
+    "border text-sm rounded-lg has-[:focus-visible]:border-ring has-[:focus-visible]:ring-3 has-[:focus-visible]:ring-ring/50 data-[disabled=true]:bg-muted data-[disabled=true]:pointer-events-none",
+    itemVariants({ variant, size }),
+    className,
+  )}
+>
+  <slot />
+</div>