@elabs-ai/components-ui 5.0.0 → 5.1.0

package/dist/lib/cn.js

@@ -13,7 +13,14 @@ var TEXT_ROLES = [
   "heading-xs",
   "kpi",
   "kpi-sm",
-  "code"
+  "code",
+  // Chart type roles (RM-019, themes.css § chart type roles). They were missing
+  // here from RM-019 until the 2026-09-21 new-user test: `cn("text-chart-source",
+  // "text-chart-foreground-muted")` dropped the role and every ChartCard source
+  // row rendered at body size. `cn.test.ts` now derives the expected list from
+  // themes.css, so a new `--text-<role>` token cannot drift from this list again.
+  "chart-value",
+  "chart-source"
 ];
 var isVarShorthand = (value) => /^\(--[\w-]+\)$/.test(value);
 var twMerge = extendTailwindMerge({

package/dist/lib/cn.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/lib/cn.ts"],"sourcesContent":["import { clsx, type ClassValue } from \"clsx\";\nimport { extendTailwindMerge } from \"tailwind-merge\";\n\n/**\n * The semantic type roles (`--text-<role>` tokens → `text-<role>` utilities, #187).\n * tailwind-merge doesn't know custom theme keys, so without registration it\n * classifies `text-title` as a text COLOR — and `cn(\"text-kpi\", \"text-foreground\")`\n * would silently drop the role. Registering the roles in the `font-size` class\n * group makes role-vs-role and role-vs-raw-size conflicts resolve correctly while\n * keeping role + color independent.\n */\nconst TEXT_ROLES = [\n  \"display-lg\",\n  \"display\",\n  \"title\",\n  \"subtitle\",\n  \"body\",\n  \"caption\",\n  \"meta\",\n  \"eyebrow\",\n  \"heading-xs\",\n  \"kpi\",\n  \"kpi-sm\",\n  \"code\",\n];\n\n/**\n * Tailwind v4's CSS-variable shorthand (`leading-(--card-title-leading)`).\n * tailwind-merge 2.x predates it and leaves such a class beside a caller's\n * `leading-tight`, letting stylesheet order pick the winner. A typed hint\n * (`text-(length:--x)`) is read as a variant prefix by 2.x and cannot be\n * registered — give that seam a named `@theme` utility instead\n * (`text-table-header`).\n */\nconst isVarShorthand = (value: string) => /^\\(--[\\w-]+\\)$/.test(value);\n\nconst twMerge = extendTailwindMerge({\n  extend: {\n    classGroups: {\n      \"font-size\": [{ text: [...TEXT_ROLES, \"table-header\"] }],\n      leading: [{ leading: [isVarShorthand] }],\n      tracking: [{ tracking: [isVarShorthand] }],\n      // `font-display` is the display-face seam (sibling of font-mono, #187).\n      \"font-family\": [{ font: [\"display\"] }],\n      // Theme-driven control/table/surface knobs (themes.css § CONTROL UTILITIES\n      // and the `@theme inline` bridge) — so a caller's `h-8` / `rounded-none` /\n      // `font-bold` / `shadow-none` still replaces the token default.\n      \"font-weight\": [{ font: [\"control\", \"table-header\", \"tabs-active\"] }],\n      rounded: [{ rounded: [\"control\", \"badge\"] }],\n      shadow: [{ shadow: [\"input\", \"card\", \"popover\", \"dialog\"] }],\n      h: [{ h: [\"control\", \"control-sm\", \"control-lg\", \"header\"] }],\n      size: [{ size: [\"control\", \"control-sm\", \"control-lg\"] }],\n      \"min-w\": [{ \"min-w\": [\"control\", \"control-sm\", \"control-lg\"] }],\n    },\n  },\n});\n\n/**\n * Merge class names with conflict resolution. `clsx` handles conditionals;\n * `tailwind-merge` ensures later Tailwind utilities win (e.g. `p-2 p-4` -> `p-4`).\n * Use this in every component that accepts a `className` prop.\n */\nexport function cn(...inputs: ClassValue[]): string {\n  return twMerge(clsx(inputs));\n}\n"],"mappings":";AAAA,SAAS,YAA6B;AACtC,SAAS,2BAA2B;AAUpC,IAAM,aAAa;AAAA,EACjB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAUA,IAAM,iBAAiB,CAAC,UAAkB,iBAAiB,KAAK,KAAK;AAErE,IAAM,UAAU,oBAAoB;AAAA,EAClC,QAAQ;AAAA,IACN,aAAa;AAAA,MACX,aAAa,CAAC,EAAE,MAAM,CAAC,GAAG,YAAY,cAAc,EAAE,CAAC;AAAA,MACvD,SAAS,CAAC,EAAE,SAAS,CAAC,cAAc,EAAE,CAAC;AAAA,MACvC,UAAU,CAAC,EAAE,UAAU,CAAC,cAAc,EAAE,CAAC;AAAA;AAAA,MAEzC,eAAe,CAAC,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC;AAAA;AAAA;AAAA;AAAA,MAIrC,eAAe,CAAC,EAAE,MAAM,CAAC,WAAW,gBAAgB,aAAa,EAAE,CAAC;AAAA,MACpE,SAAS,CAAC,EAAE,SAAS,CAAC,WAAW,OAAO,EAAE,CAAC;AAAA,MAC3C,QAAQ,CAAC,EAAE,QAAQ,CAAC,SAAS,QAAQ,WAAW,QAAQ,EAAE,CAAC;AAAA,MAC3D,GAAG,CAAC,EAAE,GAAG,CAAC,WAAW,cAAc,cAAc,QAAQ,EAAE,CAAC;AAAA,MAC5D,MAAM,CAAC,EAAE,MAAM,CAAC,WAAW,cAAc,YAAY,EAAE,CAAC;AAAA,MACxD,SAAS,CAAC,EAAE,SAAS,CAAC,WAAW,cAAc,YAAY,EAAE,CAAC;AAAA,IAChE;AAAA,EACF;AACF,CAAC;AAOM,SAAS,MAAM,QAA8B;AAClD,SAAO,QAAQ,KAAK,MAAM,CAAC;AAC7B;","names":[]}
+{"version":3,"sources":["../../src/lib/cn.ts"],"sourcesContent":["import { clsx, type ClassValue } from \"clsx\";\nimport { extendTailwindMerge } from \"tailwind-merge\";\n\n/**\n * The semantic type roles (`--text-<role>` tokens → `text-<role>` utilities, #187).\n * tailwind-merge doesn't know custom theme keys, so without registration it\n * classifies `text-title` as a text COLOR — and `cn(\"text-kpi\", \"text-foreground\")`\n * would silently drop the role. Registering the roles in the `font-size` class\n * group makes role-vs-role and role-vs-raw-size conflicts resolve correctly while\n * keeping role + color independent.\n */\nconst TEXT_ROLES = [\n  \"display-lg\",\n  \"display\",\n  \"title\",\n  \"subtitle\",\n  \"body\",\n  \"caption\",\n  \"meta\",\n  \"eyebrow\",\n  \"heading-xs\",\n  \"kpi\",\n  \"kpi-sm\",\n  \"code\",\n  // Chart type roles (RM-019, themes.css § chart type roles). They were missing\n  // here from RM-019 until the 2026-09-21 new-user test: `cn(\"text-chart-source\",\n  // \"text-chart-foreground-muted\")` dropped the role and every ChartCard source\n  // row rendered at body size. `cn.test.ts` now derives the expected list from\n  // themes.css, so a new `--text-<role>` token cannot drift from this list again.\n  \"chart-value\",\n  \"chart-source\",\n];\n\n/**\n * Tailwind v4's CSS-variable shorthand (`leading-(--card-title-leading)`).\n * tailwind-merge 2.x predates it and leaves such a class beside a caller's\n * `leading-tight`, letting stylesheet order pick the winner. A typed hint\n * (`text-(length:--x)`) is read as a variant prefix by 2.x and cannot be\n * registered — give that seam a named `@theme` utility instead\n * (`text-table-header`).\n */\nconst isVarShorthand = (value: string) => /^\\(--[\\w-]+\\)$/.test(value);\n\nconst twMerge = extendTailwindMerge({\n  extend: {\n    classGroups: {\n      \"font-size\": [{ text: [...TEXT_ROLES, \"table-header\"] }],\n      leading: [{ leading: [isVarShorthand] }],\n      tracking: [{ tracking: [isVarShorthand] }],\n      // `font-display` is the display-face seam (sibling of font-mono, #187).\n      \"font-family\": [{ font: [\"display\"] }],\n      // Theme-driven control/table/surface knobs (themes.css § CONTROL UTILITIES\n      // and the `@theme inline` bridge) — so a caller's `h-8` / `rounded-none` /\n      // `font-bold` / `shadow-none` still replaces the token default.\n      \"font-weight\": [{ font: [\"control\", \"table-header\", \"tabs-active\"] }],\n      rounded: [{ rounded: [\"control\", \"badge\"] }],\n      shadow: [{ shadow: [\"input\", \"card\", \"popover\", \"dialog\"] }],\n      h: [{ h: [\"control\", \"control-sm\", \"control-lg\", \"header\"] }],\n      size: [{ size: [\"control\", \"control-sm\", \"control-lg\"] }],\n      \"min-w\": [{ \"min-w\": [\"control\", \"control-sm\", \"control-lg\"] }],\n    },\n  },\n});\n\n/**\n * Merge class names with conflict resolution. `clsx` handles conditionals;\n * `tailwind-merge` ensures later Tailwind utilities win (e.g. `p-2 p-4` -> `p-4`).\n * Use this in every component that accepts a `className` prop.\n */\nexport function cn(...inputs: ClassValue[]): string {\n  return twMerge(clsx(inputs));\n}\n"],"mappings":";AAAA,SAAS,YAA6B;AACtC,SAAS,2BAA2B;AAUpC,IAAM,aAAa;AAAA,EACjB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA;AAAA,EACA;AACF;AAUA,IAAM,iBAAiB,CAAC,UAAkB,iBAAiB,KAAK,KAAK;AAErE,IAAM,UAAU,oBAAoB;AAAA,EAClC,QAAQ;AAAA,IACN,aAAa;AAAA,MACX,aAAa,CAAC,EAAE,MAAM,CAAC,GAAG,YAAY,cAAc,EAAE,CAAC;AAAA,MACvD,SAAS,CAAC,EAAE,SAAS,CAAC,cAAc,EAAE,CAAC;AAAA,MACvC,UAAU,CAAC,EAAE,UAAU,CAAC,cAAc,EAAE,CAAC;AAAA;AAAA,MAEzC,eAAe,CAAC,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC;AAAA;AAAA;AAAA;AAAA,MAIrC,eAAe,CAAC,EAAE,MAAM,CAAC,WAAW,gBAAgB,aAAa,EAAE,CAAC;AAAA,MACpE,SAAS,CAAC,EAAE,SAAS,CAAC,WAAW,OAAO,EAAE,CAAC;AAAA,MAC3C,QAAQ,CAAC,EAAE,QAAQ,CAAC,SAAS,QAAQ,WAAW,QAAQ,EAAE,CAAC;AAAA,MAC3D,GAAG,CAAC,EAAE,GAAG,CAAC,WAAW,cAAc,cAAc,QAAQ,EAAE,CAAC;AAAA,MAC5D,MAAM,CAAC,EAAE,MAAM,CAAC,WAAW,cAAc,YAAY,EAAE,CAAC;AAAA,MACxD,SAAS,CAAC,EAAE,SAAS,CAAC,WAAW,cAAc,YAAY,EAAE,CAAC;AAAA,IAChE;AAAA,EACF;AACF,CAAC;AAOM,SAAS,MAAM,QAA8B;AAClD,SAAO,QAAQ,KAAK,MAAM,CAAC;AAC7B;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elabs-ai/components-ui",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -81,7 +81,7 @@
     "react": "^18.2.0 || ^19.0.0",
     "react-dom": "^18.2.0 || ^19.0.0",
     "react-hook-form": "^7.54.2",
-    "@elabs-ai/components-tokens": "5.0.0"
+    "@elabs-ai/components-tokens": "^5.1.0"
   },
   "peerDependenciesMeta": {
     "@hookform/resolvers": {
@@ -113,8 +113,8 @@
     "vitest": "^3.0.2",
     "zod": "^3.24.1",
     "@elabs-ai/components-eslint-config": "0.1.0",
-    "@elabs-ai/components-typescript-config": "0.1.0",
-    "@elabs-ai/components-tokens": "5.0.0"
+    "@elabs-ai/components-tokens": "5.1.0",
+    "@elabs-ai/components-typescript-config": "0.1.0"
   },
   "scripts": {
     "build": "rm -rf dist && tsup && node ../../scripts/link-dist-css.mjs",

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/section-header/section-header.stories.tsx

@@ -55,3 +55,26 @@ export const DefaultLevelIsH2: Story = {
     await expect(canvas.queryByRole("heading", { level: 1 })).toBeNull();
   },
 };
+
+/**
+ * `size="lg"` is for the sections of a LONG page — a landing page, a docs overview — that a
+ * reader scans by its headings: the title moves up to the display rung and the description
+ * keeps a readable measure. The eyebrow stays small above it, and the heading level is still
+ * `as`'s business, so the outline is unchanged.
+ */
+export const LargeForLongPages: Story = {
+  args: {
+    size: "lg",
+    eyebrow: "02 / Blocks",
+    title: "Blocks you copy and own",
+    description:
+      "Compositions from the registry, grouped by what they are for. One command puts the source in your repo.",
+    actions: <Button variant="outline">All blocks</Button>,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const heading = canvas.getByRole("heading", { level: 2, name: "Blocks you copy and own" });
+    await expect(heading.classList.contains("text-display")).toBe(true);
+    await expect(heading.classList.contains("text-title")).toBe(false);
+  },
+};

package/src/components/section-header/section-header.tsx

@@ -10,14 +10,21 @@ export interface SectionHeaderProps {
   eyebrow?: ReactNode;
   /**
    * The heading LEVEL the title contributes to the document outline. The
-   * visual (`text-title`) is identical for every value — pick the level the
-   * page's structure calls for, not the size you want (WCAG 1.3.1).
+   * visual is identical for every value — pick the level the page's structure
+   * calls for, not the size you want (WCAG 1.3.1); the size is `size`.
    *
    * Use `as="h1"` when this header titles the PAGE (a screen whose route it
    * names); leave it at the default when it titles a section INSIDE a page
    * that already has an `<h1>` elsewhere. @default "h2"
    */
   as?: "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
+  /**
+   * Title size: `"default"` (`text-title`) for a section inside a screen; `"lg"`
+   * (`text-display`, description at a readable measure) for the sections of a LONG page a
+   * reader scans by its headings — a landing page, a docs overview. Visual only: it never
+   * changes the heading level (`as`). @default "default"
+   */
+  size?: "default" | "lg";
   className?: string;
 }
 
@@ -28,16 +35,29 @@ export function SectionHeader({
   actions,
   eyebrow,
   as: TitleTag = "h2",
+  size = "default",
   className,
 }: SectionHeaderProps) {
+  const lg = size === "lg";
   return (
-    <div className={cn("flex flex-wrap items-end justify-between gap-4", className)}>
-      <div className="space-y-1">
+    <div
+      data-size={size}
+      className={cn("flex flex-wrap items-end justify-between gap-4", className)}
+    >
+      <div className={lg ? "space-y-2" : "space-y-1"}>
         {eyebrow ? (
           <div className="text-eyebrow uppercase text-muted-foreground">{eyebrow}</div>
         ) : null}
-        <TitleTag className="text-title text-foreground">{title}</TitleTag>
-        {description ? <p className="text-body text-muted-foreground">{description}</p> : null}
+        <TitleTag
+          className={cn("text-foreground", lg ? "text-display text-balance" : "text-title")}
+        >
+          {title}
+        </TitleTag>
+        {description ? (
+          <p className={cn("text-body text-muted-foreground", lg && "max-w-prose text-pretty")}>
+            {description}
+          </p>
+        ) : null}
       </div>
       {actions ? <div className="flex items-center gap-2">{actions}</div> : null}
     </div>

package/src/components/sidebar/sidebar.tsx

@@ -531,7 +531,12 @@ export const SidebarInset = forwardRef<HTMLDivElement, SidebarInsetProps>(functi
       ref={ref}
       data-slot="sidebar-inset"
       className={cn(
-        "relative flex w-full flex-1 flex-col bg-background",
+        // `min-w-0`: a flex item defaults to `min-width: auto`, so one wide child
+        // (a Table, a chart in a CSS grid) pushed the whole page wider than the
+        // viewport instead of scrolling inside its card (2026-09-21 new-user
+        // test: 1076 px wide at an 820 px viewport). With it, overflow stays
+        // where the child's own `overflow-*` puts it.
+        "relative flex w-full min-w-0 flex-1 flex-col bg-background",
         // Ancestor-scoped (#342 fix): `group/sidebar-wrapper` spans the whole
         // frame, so this reaches a right-hand or reordered `Sidebar` the old
         // peer-* combinator could not (it only matches a sibling that comes