@elabs-ai/components-ui 4.2.0 → 5.1.0

package/src/components/context-menu/context-menu.tsx

@@ -23,7 +23,7 @@ export const ContextMenuSubTrigger = forwardRef<
       ref={ref}
       data-slot="context-menu-sub-trigger"
       className={cn(
-        "flex cursor-default select-none items-center rounded-sm px-2 py-1.5 text-body outline-none transition-colors duration-fast focus:bg-accent data-[state=open]:bg-accent",
+        "flex cursor-default select-none items-center rounded-sm px-2 py-1.5 text-body outline-none transition-colors duration-fast focus:bg-accent focus:text-accent-foreground focus-ring-inset data-[state=open]:bg-accent",
         inset && "ps-8",
         className,
       )}
@@ -44,7 +44,7 @@ export const ContextMenuSubContent = forwardRef<
       ref={ref}
       data-slot="context-menu-sub-content"
       className={cn(
-        "z-50 min-w-[8rem] overflow-hidden rounded-md bg-popover p-1 text-popover-foreground shadow-ring-md data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 data-[state=closed]:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=top]:slide-in-from-bottom-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2",
+        "z-50 min-w-[8rem] overflow-hidden rounded-md bg-popover p-1 text-popover-foreground shadow-popover data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 data-[state=closed]:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=top]:slide-in-from-bottom-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2",
         className,
       )}
       {...props}
@@ -62,7 +62,7 @@ export const ContextMenuContent = forwardRef<
         ref={ref}
         data-slot="context-menu-content"
         className={cn(
-          "z-50 min-w-[12rem] overflow-hidden rounded-md bg-popover p-1 text-popover-foreground shadow-ring-md data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 data-[state=closed]:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=top]:slide-in-from-bottom-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2",
+          "z-50 min-w-[12rem] overflow-hidden rounded-md bg-popover p-1 text-popover-foreground shadow-popover data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 data-[state=closed]:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=top]:slide-in-from-bottom-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2",
           className,
         )}
         {...props}
@@ -80,7 +80,7 @@ export const ContextMenuItem = forwardRef<
       ref={ref}
       data-slot="context-menu-item"
       className={cn(
-        "relative flex cursor-default select-none items-center gap-2 rounded-sm px-2 py-1.5 text-body outline-none transition-colors duration-fast focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:size-4",
+        "relative flex cursor-default select-none items-center gap-2 rounded-sm px-2 py-1.5 text-body outline-none transition-colors duration-fast focus:bg-accent focus:text-accent-foreground focus-ring-inset data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:size-4",
         inset && "ps-8",
         className,
       )}
@@ -99,7 +99,7 @@ export const ContextMenuCheckboxItem = forwardRef<
       data-slot="context-menu-checkbox-item"
       checked={checked}
       className={cn(
-        "relative flex cursor-default select-none items-center rounded-sm py-1.5 ps-8 pe-2 text-body outline-none transition-colors duration-fast focus:bg-accent",
+        "relative flex cursor-default select-none items-center rounded-sm py-1.5 ps-8 pe-2 text-body outline-none transition-colors duration-fast focus:bg-accent focus:text-accent-foreground focus-ring-inset",
         className,
       )}
       {...props}
@@ -123,7 +123,7 @@ export const ContextMenuRadioItem = forwardRef<
       ref={ref}
       data-slot="context-menu-radio-item"
       className={cn(
-        "relative flex cursor-default select-none items-center rounded-sm py-1.5 ps-8 pe-2 text-body outline-none transition-colors duration-fast focus:bg-accent",
+        "relative flex cursor-default select-none items-center rounded-sm py-1.5 ps-8 pe-2 text-body outline-none transition-colors duration-fast focus:bg-accent focus:text-accent-foreground focus-ring-inset",
         className,
       )}
       {...props}

package/src/components/context-rail/context-rail.tsx

@@ -155,8 +155,10 @@ const COUNT_BADGE_BASE =
 // (measured before the strip gained its own padding). `CONTEXT_RAIL_HEADER`'s
 // `px-2` now buys that margin back, so this is belt and braces rather than the
 // only guard — keep it: a host restyling the rail through `className` can put
-// the item back on the edge. The vertical `-top-1` overhang is kept: nothing
-// clips it.
+// the item back on the edge. The vertical `-top-1` overhang is kept — but the
+// expanded row switcher is an `overflow-x-auto` scroller, which clips on BOTH
+// axes, so that row carries `py-1` to keep the overhang inside its own box
+// (measured: without it the count was cut in half at the top).
 const COUNT_BADGE_POSITION = "end-0 -top-1 h-4 min-w-4 px-0.5";
 
 // The rail's own header band. Two jobs, and both are geometry the rail cannot
@@ -216,7 +218,7 @@ function ContextRailSwitcher({
         // narrow strip) it is the whole column again, with no cap and no
         // scroller.
         orientation === "row"
-          ? "w-auto max-w-1/2 shrink-0 flex-row overflow-x-auto [&>li]:shrink-0 group-data-[collapsible=icon]:w-full group-data-[collapsible=icon]:max-w-none group-data-[collapsible=icon]:flex-col group-data-[collapsible=icon]:overflow-x-visible"
+          ? "w-auto max-w-1/2 shrink-0 flex-row overflow-x-auto py-1 [&>li]:shrink-0 group-data-[collapsible=icon]:w-full group-data-[collapsible=icon]:max-w-none group-data-[collapsible=icon]:flex-col group-data-[collapsible=icon]:overflow-x-visible"
           : "flex-col"
       }
     >
@@ -241,6 +243,11 @@ function ContextRailSwitcher({
               aria-current={isActive ? "true" : undefined}
               disabled={section.disabled}
               onClick={() => handleClick(section)}
+              // No leading accent bar: in a nav LIST it marks the row, but on a
+              // 32px icon button in this switcher it read as a stray vertical
+              // line beside the glyph. The accent fill is the active cue here
+              // (a shape, so it survives greyscale), and `aria-current` names it.
+              className="data-[active=true]:before:hidden"
             >
               <span
                 aria-hidden="true"
@@ -658,7 +665,18 @@ export const ContextRail = forwardRef<HTMLDivElement, ContextRailProps>(function
       ) : (
         // `variant` is hardcoded, not a public prop (#382) — see the doc
         // comment on `ContextRailProps` above.
-        <Sidebar side="right" collapsible="icon" variant="sidebar">
+        // No edge line (the variant draws it under the same group selector, so the
+        // override uses that selector too). The rail's `bg-sidebar` chrome fill is
+        // already the boundary against the canvas (`surface-elevation` keeps
+        // the two apart in every theme), and beside an inset content card the
+        // card's own elevation is — so the line only ever drew a stray hairline.
+        <Sidebar
+          side="right"
+          collapsible="icon"
+          variant="sidebar"
+          // eslint-disable-next-line conventions/logical-props -- must cancel Sidebar's own physical `group-data-[side=right]:border-l` under the same selector; a logical override loses the cascade
+          className="group-data-[side=right]:border-l-0"
+        >
           <ContextRailWide
             ref={ref}
             sections={sections}

package/src/components/date-picker/date-picker.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import { forwardRef } from "react";
 import { Calendar as CalendarIcon } from "lucide-react";
 import { cn } from "../../lib/cn";

package/src/components/descriptions/descriptions.stories.tsx

@@ -32,6 +32,12 @@ export const Default: Story = {
   render: (args) => <Descriptions {...args}>{items}</Descriptions>,
 };
 
+/** Short labels beside sentence-long values earn a narrower label column. */
+export const NarrowLabels: Story = {
+  args: { columns: 1, layout: "horizontal", labelWidth: "1/5" },
+  render: (args) => <Descriptions {...args}>{items}</Descriptions>,
+};
+
 export const TwoColumns: Story = {
   args: { columns: 2, layout: "horizontal" },
   render: (args) => <Descriptions {...args}>{items}</Descriptions>,

package/src/components/descriptions/descriptions.test.tsx

@@ -39,3 +39,21 @@ describe("Descriptions", () => {
     expect(container.querySelectorAll("dd")).toHaveLength(1);
   });
 });
+
+describe("Descriptions labelWidth", () => {
+  it("defaults the horizontal label column to a third and honours a narrower share", () => {
+    const { rerender } = render(
+      <Descriptions>
+        <DescriptionsItem label="Owner">Sofia</DescriptionsItem>
+      </Descriptions>,
+    );
+    expect(screen.getByText("Owner")).toHaveClass("w-1/3");
+    rerender(
+      <Descriptions labelWidth="1/5">
+        <DescriptionsItem label="Owner">Sofia</DescriptionsItem>
+      </Descriptions>,
+    );
+    expect(screen.getByText("Owner")).toHaveClass("w-1/5");
+    expect(screen.getByText("Owner")).not.toHaveClass("w-1/3");
+  });
+});

package/src/components/descriptions/descriptions.tsx

@@ -18,11 +18,29 @@ const descriptionsVariants = cva("grid gap-x-6 gap-y-3 text-body", {
 
 type DescriptionsLayout = "horizontal" | "vertical";
 
+/**
+ * The label column's share of a `horizontal` item. Static class names, never
+ * a computed `w-[…]`, so Tailwind can see them. `"1/3"` is the default and
+ * the historical render; `"1/4"`/`"1/5"` suit a record whose labels are
+ * short ("What it did", "Owner") and whose values are sentences.
+ */
+export type DescriptionsLabelWidth = "1/3" | "1/4" | "1/5";
+
+const LABEL_WIDTH_CLASS: Record<DescriptionsLabelWidth, string> = {
+  "1/3": "w-1/3",
+  "1/4": "w-1/4",
+  "1/5": "w-1/5",
+};
+
 interface DescriptionsContextValue {
   layout: DescriptionsLayout;
+  labelWidth: DescriptionsLabelWidth;
 }
 
-const DescriptionsContext = createContext<DescriptionsContextValue>({ layout: "horizontal" });
+const DescriptionsContext = createContext<DescriptionsContextValue>({
+  layout: "horizontal",
+  labelWidth: "1/3",
+});
 
 export interface DescriptionsProps
   extends HTMLAttributes<HTMLDListElement>, VariantProps<typeof descriptionsVariants> {
@@ -36,6 +54,11 @@ export interface DescriptionsProps
    * label above the value. Default `horizontal`.
    */
   layout?: DescriptionsLayout;
+  /**
+   * Width of the label column in the `horizontal` layout, as a share of the
+   * item. Default `"1/3"`. Ignored by `vertical`.
+   */
+  labelWidth?: DescriptionsLabelWidth;
 }
 
 /**
@@ -45,11 +68,11 @@ export interface DescriptionsProps
  * `columns` controls the grid; `layout` controls label placement per item.
  */
 export const Descriptions = forwardRef<HTMLDListElement, DescriptionsProps>(function Descriptions(
-  { columns = 1, layout = "horizontal", className, children, ...props },
+  { columns = 1, layout = "horizontal", labelWidth = "1/3", className, children, ...props },
   ref,
 ) {
   return (
-    <DescriptionsContext value={{ layout }}>
+    <DescriptionsContext value={{ layout, labelWidth }}>
       <dl ref={ref} className={cn(descriptionsVariants({ columns }), className)} {...props}>
         {children}
       </dl>
@@ -72,7 +95,7 @@ export interface DescriptionsItemProps extends HTMLAttributes<HTMLDivElement> {
  */
 export const DescriptionsItem = forwardRef<HTMLDivElement, DescriptionsItemProps>(
   function DescriptionsItem({ label, numeric, className, children, ...props }, ref) {
-    const { layout } = use(DescriptionsContext);
+    const { layout, labelWidth } = use(DescriptionsContext);
     return (
       <div
         ref={ref}
@@ -83,7 +106,12 @@ export const DescriptionsItem = forwardRef<HTMLDivElement, DescriptionsItemProps
         )}
         {...props}
       >
-        <dt className={cn("text-muted-foreground", layout === "horizontal" && "w-1/3 shrink-0")}>
+        <dt
+          className={cn(
+            "text-muted-foreground",
+            layout === "horizontal" && cn(LABEL_WIDTH_CLASS[labelWidth], "shrink-0"),
+          )}
+        >
           {label}
         </dt>
         <dd className={cn("min-w-0 break-words text-foreground", numeric && "tabular-nums")}>

package/src/components/descriptions/index.ts

@@ -1,6 +1,7 @@
 export {
   Descriptions,
   DescriptionsItem,
+  type DescriptionsLabelWidth,
   type DescriptionsProps,
   type DescriptionsItemProps,
 } from "./descriptions";

package/src/components/dialog/dialog.stories.tsx

@@ -66,6 +66,7 @@ export const Default: Story = {
  * horizontally. Before the fix the implicit `auto` column blew past `max-w-md`.
  */
 export const OverflowGuard: Story = {
+  name: "Long unbreakable text keeps the dialog width",
   render: () => (
     <Dialog>
       <DialogTrigger asChild>
@@ -392,6 +393,7 @@ export const FocusRingClearance: Story = {
  * `play` so a future regression of THIS story is caught rather than repeated.
  */
 export const FocusRingClearanceDark: Story = {
+  tags: ["!dev"],
   name: "Focus ring clearance — dark",
   globals: { theme: "dark" },
   render: FocusRingClearance.render,
@@ -450,6 +452,7 @@ export const WideWithSections: Story = {
 };
 
 export const WideWithSectionsDark: Story = {
+  tags: ["!dev"],
   name: "Wide with sections — dark",
   decorators: [
     (Story) => (
@@ -463,6 +466,7 @@ export const WideWithSectionsDark: Story = {
 };
 
 export const WideWithSectionsHighDecoration: Story = {
+  tags: ["!dev"],
   name: "Wide with sections — high decoration",
   globals: { decoration: "10" },
   render: () => <WideSettingsDialog prefix="wide-decorated" />,
@@ -685,6 +689,7 @@ function GuardedDialog({ children }: { children?: ReactNode }) {
  * because the component must not own app state (D5).
  */
 export const DirtyGuard: Story = {
+  name: "Unsaved changes confirm before closing",
   render: () => <GuardedDialog />,
   play: async ({ canvas, canvasElement, userEvent }) => {
     const doc = within(canvasElement.ownerDocument.body);

package/src/components/dialog/dialog.tsx

@@ -51,7 +51,7 @@ export const dialogContentVariants = cva(
   //      is INERT for every dialog that has no `DialogBody`.
   // `size="full"`'s own `h-/max-h-/overflow-hidden` still wins — cva emits the
   // base first, so tailwind-merge resolves the later variant utilities over it.
-  "fixed left-1/2 top-1/2 z-50 grid grid-cols-[minmax(0,1fr)] w-full -translate-x-1/2 -translate-y-1/2 gap-4 max-h-[calc(100dvh-2rem)] overflow-y-auto overscroll-contain has-[[data-slot=dialog-body]]:overflow-hidden has-[[data-slot=dialog-body]]:grid-rows-[auto_minmax(0,1fr)_auto] rounded-xl bg-card p-6 text-card-foreground shadow-ring-lg data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95",
+  "fixed left-1/2 top-1/2 z-50 grid grid-cols-[minmax(0,1fr)] w-full -translate-x-1/2 -translate-y-1/2 gap-4 max-h-[calc(100dvh-2rem)] overflow-y-auto overscroll-contain has-[[data-slot=dialog-body]]:overflow-hidden has-[[data-slot=dialog-body]]:grid-rows-[auto_minmax(0,1fr)_auto] rounded-xl bg-card p-6 text-card-foreground shadow-dialog data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95",
   {
     variants: {
       size: {

package/src/components/drafting-marks/drafting-marks.stories.tsx

@@ -0,0 +1,88 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect } from "storybook/test";
+import { DraftingMarks } from "./drafting-marks";
+
+const meta = {
+  title: "Foundations/DraftingMarks",
+  component: DraftingMarks,
+  tags: ["autodocs"],
+  parameters: { layout: "fullscreen" },
+  argTypes: {
+    anchor: {
+      description: "The corner the construction grows out of, and fades away from.",
+      control: { type: "radio" },
+      options: ["top-start", "top-end", "bottom-start", "bottom-end"],
+      table: { category: "Appearance" },
+    },
+    accent: {
+      description: "Ink the station point in `--primary` and the plate in `--chart-2`.",
+      control: "boolean",
+      table: { category: "Appearance" },
+    },
+  },
+} satisfies Meta<typeof DraftingMarks>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+function Band({ children, className }: { children: React.ReactNode; className?: string }) {
+  return (
+    <header
+      className={`relative isolate overflow-hidden bg-surface-muted px-6 py-24 text-center ${className ?? ""}`}
+    >
+      {children}
+      <h2 className="relative text-display font-semibold text-balance">
+        The hard screens, one system.
+      </h2>
+      <p className="relative mx-auto mt-3 max-w-prose text-subtitle text-muted-foreground">
+        A construction drawing in the corner the copy leaves empty. It fades out long before it
+        reaches the text.
+      </p>
+    </header>
+  );
+}
+
+/** One drawing, in the corner the header's content leaves empty. */
+export const Default: Story = {
+  args: { anchor: "top-start", accent: true },
+  render: (args) => (
+    <Band>
+      <DraftingMarks {...args} />
+    </Band>
+  ),
+  play: async ({ canvasElement }) => {
+    const svg = canvasElement.querySelector('[data-slot="drafting-marks"]') as SVGSVGElement;
+    await expect(svg).toHaveAttribute("aria-hidden", "true");
+    await expect(getComputedStyle(svg).pointerEvents).toBe("none");
+    await expect(getComputedStyle(svg).maskImage).toContain("radial-gradient");
+  },
+};
+
+/** Paired with the corner stripes: drawing at one end of the band, stripes at the other. */
+export const WithCornerStripes: Story = {
+  render: () => (
+    <Band className="bg-hairline-stripes">
+      <DraftingMarks anchor="bottom-start" />
+    </Band>
+  ),
+};
+
+/** `accent={false}` — rule ink only, for a band that already carries colour. */
+export const RuleInkOnly: Story = {
+  render: () => (
+    <Band>
+      <DraftingMarks anchor="top-end" accent={false} />
+    </Band>
+  ),
+};
+
+/** All four anchors are the same drawing, mirrored. */
+export const Anchors: Story = {
+  render: () => (
+    <div className="relative isolate h-[44rem] overflow-hidden bg-background">
+      <DraftingMarks anchor="top-start" />
+      <DraftingMarks anchor="top-end" />
+      <DraftingMarks anchor="bottom-start" />
+      <DraftingMarks anchor="bottom-end" />
+    </div>
+  ),
+};

package/src/components/drafting-marks/drafting-marks.test.tsx

@@ -0,0 +1,55 @@
+import { describe, expect, it } from "vitest";
+import { render } from "@testing-library/react";
+import { createRef } from "react";
+import { DraftingMarks } from "./drafting-marks";
+
+const marks = (container: HTMLElement) =>
+  container.querySelector('[data-slot="drafting-marks"]') as SVGSVGElement;
+
+describe("DraftingMarks", () => {
+  it("is decorative and inert: hidden from AT, no pointer events, absolutely positioned", () => {
+    const { container } = render(<DraftingMarks />);
+    const svg = marks(container);
+    expect(svg).toHaveAttribute("aria-hidden", "true");
+    expect(svg).toHaveClass("pointer-events-none", "absolute");
+  });
+
+  it("grows out of the top-start corner by default and mirrors for the other anchors", () => {
+    const { container, rerender } = render(<DraftingMarks />);
+    expect(marks(container)).toHaveAttribute("data-anchor", "top-start");
+    expect(marks(container)).toHaveClass("top-0", "start-0");
+    rerender(<DraftingMarks anchor="bottom-end" />);
+    expect(marks(container)).toHaveClass("bottom-0", "end-0", "-scale-100");
+  });
+
+  it("inks from tokens only, and fades away from its corner", () => {
+    const { container } = render(<DraftingMarks />);
+    const svg = marks(container);
+    expect(svg).toHaveAttribute("stroke", "var(--hairline-ink-strong)");
+    expect(svg.style.maskImage).toBe("var(--drafting-marks-fade, var(--deco-fade-corner))");
+    const fills = Array.from(svg.querySelectorAll("[fill]")).map((el) => el.getAttribute("fill"));
+    for (const fill of fills) expect(fill).toMatch(/^(none|var\(--|url\(#)/);
+  });
+
+  it("`accent={false}` drops the two coloured accents", () => {
+    const { container, rerender } = render(<DraftingMarks />);
+    expect(marks(container).querySelectorAll('[fill="var(--primary)"]').length).toBe(2);
+    rerender(<DraftingMarks accent={false} />);
+    expect(marks(container).querySelectorAll('[fill="var(--primary)"]').length).toBe(0);
+    expect(marks(container).querySelector('[fill="var(--chart-2)"]')).toBeNull();
+  });
+
+  it("gives each instance its own dot-pattern id, forwards the ref and merges className", () => {
+    const ref = createRef<SVGSVGElement>();
+    const { container } = render(
+      <div>
+        <DraftingMarks ref={ref} className="opacity-60" />
+        <DraftingMarks />
+      </div>,
+    );
+    const ids = Array.from(container.querySelectorAll("pattern")).map((p) => p.id);
+    expect(new Set(ids).size).toBe(2);
+    expect(ref.current).toBe(container.querySelector("svg"));
+    expect(ref.current).toHaveClass("opacity-60");
+  });
+});

package/src/components/drafting-marks/drafting-marks.tsx

@@ -0,0 +1,120 @@
+import * as React from "react";
+import { cn } from "../../lib/cn";
+
+/** Which corner of the host the drawing grows out of. Logical: `start`/`end` follow the text direction. */
+export type DraftingMarksAnchor = "top-start" | "top-end" | "bottom-start" | "bottom-end";
+
+export interface DraftingMarksProps extends Omit<React.SVGAttributes<SVGSVGElement>, "children"> {
+  /** The corner the construction grows out of, and fades away from. Default `"top-start"`. */
+  anchor?: DraftingMarksAnchor;
+  /**
+   * Ink the two small accents — a `--primary` station point and a `--chart-2` tinted plate.
+   * `false` keeps the whole drawing in rule ink. Default `true`.
+   */
+  accent?: boolean;
+}
+
+/** The drawing's own size, in px. Fixed, so every hairline stays one device-crisp pixel. */
+export const DRAFTING_MARKS_WIDTH = 560;
+export const DRAFTING_MARKS_HEIGHT = 360;
+
+// The drawing is authored ONCE, growing out of the top-left corner; the other three anchors
+// are the same drawing mirrored. `start`/`end` are logical, so the mirror itself flips under RTL.
+const ANCHOR_CLASS: Record<DraftingMarksAnchor, string> = {
+  "top-start": "top-0 start-0 rtl:-scale-x-100",
+  "top-end": "top-0 end-0 -scale-x-100 rtl:scale-x-100",
+  "bottom-start": "bottom-0 start-0 -scale-y-100 rtl:-scale-x-100",
+  "bottom-end": "bottom-0 end-0 -scale-100 rtl:scale-x-100",
+};
+
+/**
+ * DraftingMarks — a quiet construction drawing in one corner of a header or hero band: two
+ * guides that cross at a station point, the arcs struck from it, a dimension tick, a field of
+ * dots and a few registration crosses. It is the hairline family's one ILLUSTRATION: where the
+ * `hairline-*` utilities rule edges, this gives an empty corner the look of a sheet someone
+ * measured on.
+ *
+ * Decorative and inert: `aria-hidden`, `pointer-events: none`, absolutely positioned in the
+ * corner named by `anchor` and faded out away from it, so it never reaches the text in the
+ * middle of the band (`--drafting-marks-fade` swaps the falloff — e.g.
+ * `var(--deco-fade-corner-tight)` where the copy comes close). Put it first inside a positioned (`relative`) host that clips
+ * (`overflow-hidden`). Lines take the theme's `--hairline-ink-strong`; the two accents take
+ * `--primary` and `--chart-2` — no literal colour, so it re-inks with the theme.
+ *
+ * One per band, in a corner the content leaves empty. It is a ground gesture like the paper
+ * utilities — never behind body text, never inside a control.
+ */
+export const DraftingMarks = React.forwardRef<SVGSVGElement, DraftingMarksProps>(
+  function DraftingMarks({ anchor = "top-start", accent = true, className, style, ...props }, ref) {
+    const dotsId = `drafting-dots-${React.useId().replace(/:/g, "")}`;
+    return (
+      <svg
+        ref={ref}
+        aria-hidden="true"
+        data-slot="drafting-marks"
+        data-anchor={anchor}
+        fill="none"
+        height={DRAFTING_MARKS_HEIGHT}
+        width={DRAFTING_MARKS_WIDTH}
+        viewBox={`0 0 ${DRAFTING_MARKS_WIDTH} ${DRAFTING_MARKS_HEIGHT}`}
+        stroke="var(--hairline-ink-strong)"
+        strokeWidth={1}
+        className={cn("pointer-events-none absolute max-w-none", ANCHOR_CLASS[anchor], className)}
+        style={{
+          // Fades away from its own corner (authored top-left; the mirror carries the mask along).
+          maskImage: "var(--drafting-marks-fade, var(--deco-fade-corner))",
+          WebkitMaskImage: "var(--drafting-marks-fade, var(--deco-fade-corner))",
+          ...style,
+        }}
+        {...props}
+      >
+        <defs>
+          <pattern id={dotsId} width={12} height={12} patternUnits="userSpaceOnUse">
+            <circle cx={6} cy={6} r={0.75} fill="var(--hairline-ink-strong)" stroke="none" />
+          </pattern>
+        </defs>
+
+        {/* The dot field, tucked between the guides. */}
+        <rect x={132} y={36} width={216} height={48} fill={`url(#${dotsId})`} stroke="none" />
+
+        {/* The tinted plate, hung from the horizontal guide. */}
+        {accent ? (
+          <rect
+            x={40}
+            y={96.5}
+            width={56}
+            height={44}
+            fill="var(--chart-2)"
+            fillOpacity={0.16}
+            stroke="none"
+          />
+        ) : null}
+
+        {/* Guides: they cross at the station point (96.5, 96.5). Half-pixel centres keep a
+            1px stroke on one device row. */}
+        <path d="M0 96.5H520M520 90.5v12" />
+        <path d="M96.5 0v300M90.5 300.5h12" />
+        <path d="M72.5 24v250M0 140.5h210" strokeDasharray="1 4" />
+
+        {/* Arcs struck from the station point. */}
+        <path d="M252.5 96.5A156 156 0 0 1 40 241.8" />
+        <path d="M96.5 40.5A56 56 0 0 0 40.5 96.5V241.8" />
+        <path d="M40.5 222.5h78M118.5 218.5v8" />
+
+        {/* A dimension tick and the registration crosses. */}
+        <path d="M18.5 40v28M14.5 40.5h8M14.5 67.5h8" />
+        <path d="M52 322.5h12M58.5 316v12M404 44.5h12M410.5 38v12M236 292.5h12M242.5 286v12" />
+
+        {/* A door-swing of three concentric arcs, further along the floor line. */}
+        <path d="M300.5 300.5H470M300.5 300.5V236M300.5 244.5A56 56 0 0 1 356.5 300.5M300.5 252.5A48 48 0 0 1 348.5 300.5M300.5 260.5A40 40 0 0 1 340.5 300.5" />
+
+        {accent ? (
+          <>
+            <rect x={289} y={222} width={7} height={12} fill="var(--primary)" stroke="none" />
+            <circle cx={96.5} cy={96.5} r={3} fill="var(--primary)" stroke="none" />
+          </>
+        ) : null}
+      </svg>
+    );
+  },
+);

package/src/components/drafting-marks/index.ts

@@ -0,0 +1,7 @@
+export {
+  DraftingMarks,
+  DRAFTING_MARKS_HEIGHT,
+  DRAFTING_MARKS_WIDTH,
+  type DraftingMarksAnchor,
+  type DraftingMarksProps,
+} from "./drafting-marks";

package/src/components/dropdown-menu/dropdown-menu.stories.tsx

@@ -156,6 +156,7 @@ export const SubmenuRadioAndCheckbox: Story = {
  * persisting to localStorage across runs.
  */
 export const SubmenuRadioAndCheckboxDark: Story = {
+  tags: ["!dev"],
   name: "Submenu, radio group and checkbox item — dark",
   decorators: [
     (Story) => (
@@ -169,8 +170,44 @@ export const SubmenuRadioAndCheckboxDark: Story = {
 };
 
 export const SubmenuRadioAndCheckboxHighDecoration: Story = {
+  tags: ["!dev"],
   name: "Submenu, radio group and checkbox item — high decoration",
   globals: { decoration: "10" },
   render: SubmenuRadioAndCheckbox.render,
   play: SubmenuRadioAndCheckbox.play,
 };
+
+/**
+ * Locks WCAG 1.4.11 keyboard-focus contrast (#308): a menu item's
+ * `focus:bg-accent` fill alone measures ~1.17–1.40:1 against `--popover` in
+ * both themes — not a visible indicator. Moving focus with the keyboard must
+ * additionally paint a compound ring (`focus-ring-inset`): a real `boxShadow`
+ * layer, or a non-zero, non-`none` `outline`.
+ */
+export const KeyboardFocusIndicator: Story = {
+  name: "Keyboard focus",
+  render: Default.render,
+  play: async ({ canvas, canvasElement, userEvent }) => {
+    const trigger = canvas.getByRole("button", { name: /open menu/i });
+    await userEvent.click(trigger);
+    const body = within(canvasElement.ownerDocument.body);
+    await body.findByRole("menuitem", { name: "Profile" });
+    await userEvent.keyboard("{ArrowDown}");
+    const focused = canvasElement.ownerDocument.activeElement as HTMLElement;
+    await expect(focused).toHaveAttribute("role", "menuitem");
+    const style = getComputedStyle(focused);
+    const hasRing = style.boxShadow !== "none";
+    const hasOutline = style.outlineStyle !== "none" && parseFloat(style.outlineWidth) > 0;
+    await expect(hasRing || hasOutline).toBe(true);
+    // Close before the axe afterEach scan — an open portal otherwise leaves a
+    // stray focusable node behind an `aria-hidden` sibling from an earlier
+    // story's not-yet-cleaned-up DOM (aria-hidden-focus). Waiting for the menu
+    // to actually leave the DOM (not just sending the keystroke) matters: on a
+    // slower close — observed reproducibly under `STORYBOOK_THEME=dark`, never
+    // under light — the axe scan can otherwise run mid-close-transition, while
+    // the still-focusable menuitem sits inside a portal Radix has already
+    // marked `aria-hidden`.
+    await userEvent.keyboard("{Escape}");
+    await waitFor(() => expect(body.queryByRole("menu")).not.toBeInTheDocument());
+  },
+};