@dashforge/tw 0.1.0-beta → 0.2.0-beta

package/src/components/AspectRatio/AspectRatio.tsx

@@ -0,0 +1,73 @@
+import { forwardRef, type CSSProperties, type ElementType } from 'react';
+import { cn } from '../../utils/cn.js';
+import type { AspectRatioProps } from './aspectRatio.types.js';
+
+/**
+ * `<AspectRatio>` — locks the aspect ratio of its child container,
+ * regardless of width. The classic use is responsive images and
+ * embedded media: an `<img>` that takes 100% of the available width
+ * but always renders at 16:9 (or 1:1, or whatever the source ratio is)
+ * — no jumping layouts during image load, no whitespace below the
+ * media, no JS measurement.
+ *
+ * Implementation: native CSS `aspect-ratio` property. Supported in
+ * every browser shipped from 2021 onward (Chrome 88, Firefox 89,
+ * Safari 15, Edge 88). No padding-bottom hack — that workaround
+ * predates the native property and brings ugly absolute-positioning
+ * requirements on the child.
+ *
+ * Why a component if it's "just one CSS property"?
+ *   Two reasons:
+ *     1. Discoverability — `<AspectRatio ratio={16/9}>` documents the
+ *        intent at the call site. `style={{ aspectRatio: '16/9' }}` is
+ *        the same thing functionally, but harder to spot in a 200-line
+ *        component file.
+ *     2. Composition — pairs naturally with `sx="rounded-xl overflow-hidden"`
+ *        for the canonical "rounded clipped media" pattern. Forgetting
+ *        the `overflow-hidden` is the #1 mistake we want to prevent
+ *        through documentation (it's in this component's MDX, at the
+ *        top of the Notes).
+ *
+ * Child contract:
+ *   The single child is expected to fill the container — typically
+ *   `<img>` / `<video>` with `className="w-full h-full object-cover"`.
+ *   We don't force this via CSS (the consumer might want a centered
+ *   icon instead of a filling image) — but it's the 99% case, and the
+ *   docs show it first.
+ */
+export const AspectRatio = forwardRef<HTMLElement, AspectRatioProps>(
+  function AspectRatio(props, ref) {
+    const {
+      ratio = 1,
+      as,
+      sx,
+      style,
+      children,
+      ...rest
+    } = props;
+
+    /*
+     * Normalise to a CSS `aspect-ratio` string. The CSS property
+     * accepts both `16/9` and `16 / 9` (with spaces), but for safety
+     * we convert numbers to the canonical `N / 1` form — `aspectRatio: 1.7777`
+     * works too, but produces an arbitrary-looking value in DevTools.
+     */
+    const aspectRatioValue = typeof ratio === 'number' ? `${ratio} / 1` : ratio;
+
+    const mergedStyle: CSSProperties = {
+      aspectRatio: aspectRatioValue,
+      ...style,
+    };
+
+    const classes = cn('w-full', sx);
+    const Tag = (as ?? 'div') as ElementType;
+
+    return (
+      <Tag ref={ref as never} className={classes} style={mergedStyle} {...rest}>
+        {children}
+      </Tag>
+    );
+  },
+);
+
+AspectRatio.displayName = 'AspectRatio';

package/src/components/AspectRatio/aspectRatio.types.ts

@@ -0,0 +1,54 @@
+import type { ElementType, HTMLAttributes, ReactNode } from 'react';
+
+/**
+ * Props for `<AspectRatio>` — content-shape primitive that locks the
+ * aspect ratio of its child regardless of width.
+ *
+ * Implementation: uses the native CSS `aspect-ratio` property
+ * (supported in all current browsers since 2021 — Chrome 88+, Firefox 89+,
+ * Safari 15+, Edge 88+). No padding-bottom hack, no JS measurement.
+ *
+ * `ratio` accepts:
+ *   • A number — width / height. `16/9` is 1.7777…, `1` is square,
+ *     `4/3` is 1.333…, `21/9` is ultrawide cinema.
+ *   • A string with the CSS `aspect-ratio` syntax, e.g. `'16 / 9'`,
+ *     `'4 / 3'`. Useful when you want the source ratio to read clearly
+ *     in the JSX (`ratio="16 / 9"` is more legible than `ratio={16/9}`).
+ *
+ * The component renders a single element with `aspect-ratio: X` and
+ * `width: 100%`. The child is expected to fill it — typically an
+ * `<img>` or `<video>` with `className="w-full h-full object-cover"`.
+ *
+ * Why not a TV recipe?
+ *   The ratio is arbitrary (`16/9`, `1`, `2.35`, anything). Tailwind
+ *   has `aspect-square` / `aspect-video` / `aspect-[16/9]` arbitrary
+ *   values, but enumerating every conceivable ratio in TV would be
+ *   pointless. We set `style={{ aspectRatio }}` directly — pure CSS
+ *   property, no class purge concerns.
+ */
+export interface AspectRatioProps
+  extends Omit<HTMLAttributes<HTMLDivElement>, 'className'> {
+  /**
+   * Aspect ratio as width/height. Number (`16/9`) or CSS string
+   * (`'16 / 9'`). Default `1` (square).
+   */
+  ratio?: number | string;
+
+  /**
+   * The child that fills the locked-ratio container. Typically an
+   * `<img>` or `<video>` with `className="w-full h-full object-cover"`.
+   */
+  children?: ReactNode;
+
+  /**
+   * Override the rendered HTML tag. Defaults to `'div'`.
+   */
+  as?: ElementType;
+
+  /**
+   * Utility classes appended to the base. Resolved via `tailwind-merge`.
+   * Common overrides: `sx="rounded-xl overflow-hidden"` to clip the
+   * child's overflow (image bleeds otherwise).
+   */
+  sx?: string;
+}

package/src/components/Box/Box.test.tsx

@@ -0,0 +1,349 @@
+// @vitest-environment jsdom
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/react';
+import { Box } from './Box.js';
+
+/**
+ * Suite mirrors the Typography/Button test shape (rendering · variants ·
+ * compound × intent · override · polymorphism · pass-through). The big
+ * delta here is the compound-variant matrix: 5 surface variants × 7
+ * intents = 35 combos, of which 21 carry actual visual differences
+ * (outlined / soft / solid × 7 intents). We spot-check a representative
+ * subset rather than enumerate all 35 — if the TV compound resolution
+ * works for one of each (primary, danger, neutral), it works for all.
+ */
+describe('<Box>', () => {
+  // ─── Default rendering ──────────────────────────────────────────────
+  describe('default rendering', () => {
+    it('renders a <div> by default', () => {
+      const { container } = render(<Box>x</Box>);
+      expect(container.firstElementChild?.tagName).toBe('DIV');
+    });
+
+    it('default variant is plain — no border, no bg, no shadow', () => {
+      const { container } = render(<Box>x</Box>);
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).not.toContain('border');
+      expect(cls).not.toContain('bg-');
+      expect(cls).not.toContain('shadow-sm');
+      // baseline `block` is always present
+      expect(cls).toContain('block');
+    });
+  });
+
+  // ─── Variant — surface chrome ───────────────────────────────────────
+  describe('surface variants', () => {
+    it('variant="outlined" adds a border', () => {
+      const { container } = render(<Box variant="outlined" color="neutral">x</Box>);
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('border');
+      // neutral outlined picks the white surface + neutral-200 border
+      expect(cls).toContain('border-neutral-200');
+      expect(cls).toContain('bg-white');
+    });
+
+    it('variant="elevated" adds the neutral surface, no border, no color tint', () => {
+      const { container } = render(<Box variant="elevated" elevation={3}>x</Box>);
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('bg-white');
+      expect(cls).toContain('dark:bg-neutral-900');
+      expect(cls).toContain('shadow-md');
+      expect(cls).not.toContain('border ');
+    });
+
+    it('variant="soft" + color="warning" picks the warning soft tones', () => {
+      const { container } = render(<Box variant="soft" color="warning">x</Box>);
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('bg-warning-100');
+      expect(cls).toContain('text-warning-900');
+      expect(cls).toContain('dark:bg-warning-950/50');
+    });
+
+    it('variant="solid" + color="primary" picks the primary solid', () => {
+      const { container } = render(<Box variant="solid" color="primary">x</Box>);
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('bg-primary-600');
+      expect(cls).toContain('text-white');
+      expect(cls).toContain('dark:bg-primary-500');
+    });
+
+    it('variant="solid" + color="danger" picks the danger solid', () => {
+      const { container } = render(<Box variant="solid" color="danger">x</Box>);
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('bg-danger-600');
+      expect(cls).toContain('text-white');
+    });
+  });
+
+  // ─── Elevation scale ─────────────────────────────────────────────────
+  describe('elevation', () => {
+    it('elevation={0} emits shadow-none', () => {
+      const { container } = render(<Box variant="elevated" elevation={0}>x</Box>);
+      expect(container.firstElementChild?.className).toContain('shadow-none');
+    });
+
+    it('elevation={5} emits shadow-xl', () => {
+      const { container } = render(<Box variant="elevated" elevation={5}>x</Box>);
+      expect(container.firstElementChild?.className).toContain('shadow-xl');
+    });
+  });
+
+  // ─── Spacing ─────────────────────────────────────────────────────────
+  describe('spacing', () => {
+    it('p={4} emits p-4', () => {
+      const { container } = render(<Box p={4}>x</Box>);
+      expect(container.firstElementChild?.className).toContain('p-4');
+    });
+
+    it('px={6} + py={2} emits px-6 + py-2', () => {
+      const { container } = render(<Box px={6} py={2}>x</Box>);
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('px-6');
+      expect(cls).toContain('py-2');
+    });
+
+    it('m={"0.5"} emits m-0.5', () => {
+      const { container } = render(<Box m="0.5">x</Box>);
+      expect(container.firstElementChild?.className).toContain('m-0.5');
+    });
+  });
+
+  // ─── Rounded + sizing ────────────────────────────────────────────────
+  describe('rounded + sizing', () => {
+    it('rounded="xl" emits rounded-xl', () => {
+      const { container } = render(<Box rounded="xl">x</Box>);
+      expect(container.firstElementChild?.className).toContain('rounded-xl');
+    });
+
+    it('fullWidth emits w-full', () => {
+      const { container } = render(<Box fullWidth>x</Box>);
+      expect(container.firstElementChild?.className).toContain('w-full');
+    });
+
+    it('fullHeight emits h-full', () => {
+      const { container } = render(<Box fullHeight>x</Box>);
+      expect(container.firstElementChild?.className).toContain('h-full');
+    });
+  });
+
+  // ─── Override semantics ─────────────────────────────────────────────
+  describe('override', () => {
+    it('sx wins over variant defaults via tailwind-merge', () => {
+      const { container } = render(
+        <Box variant="solid" color="primary" sx="bg-fuchsia-600">x</Box>,
+      );
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('bg-fuchsia-600');
+      // the conflicting bg-primary-600 from the compound is collapsed
+      expect(cls).not.toContain('bg-primary-600');
+    });
+
+    it('sx can add utilities Box deliberately omits (overflow)', () => {
+      const { container } = render(<Box sx="overflow-hidden">x</Box>);
+      expect(container.firstElementChild?.className).toContain('overflow-hidden');
+    });
+  });
+
+  // ─── Polymorphism ───────────────────────────────────────────────────
+  describe('polymorphism', () => {
+    it('as="section" renders a <section>', () => {
+      const { container } = render(<Box as="section">x</Box>);
+      expect(container.firstElementChild?.tagName).toBe('SECTION');
+    });
+
+    it('asChild renders the single child element with merged className', () => {
+      const { container } = render(
+        <Box variant="elevated" elevation={2} asChild>
+          <article>x</article>
+        </Box>,
+      );
+      const el = container.firstElementChild;
+      expect(el?.tagName).toBe('ARTICLE');
+      expect(el?.className).toContain('shadow');
+      expect(el?.className).toContain('bg-white');
+    });
+
+    it('asChild wins over as when both are passed', () => {
+      const { container } = render(
+        <Box as="section" asChild>
+          <article>x</article>
+        </Box>,
+      );
+      expect(container.firstElementChild?.tagName).toBe('ARTICLE');
+    });
+  });
+
+  // ─── Pass-through ────────────────────────────────────────────────────
+  describe('pass-through', () => {
+    it('forwards data-* and aria-*', () => {
+      const { container } = render(
+        <Box data-testid="box" aria-label="surface">x</Box>,
+      );
+      const el = container.firstElementChild;
+      expect(el?.getAttribute('data-testid')).toBe('box');
+      expect(el?.getAttribute('aria-label')).toBe('surface');
+    });
+  });
+
+  // ─── F11-bis edge cases: every compound variant explicit ─────────────
+  // The original suite spot-checked 4 surface×intent combos (outlined
+  // neutral, soft warning, solid primary, solid danger). The validation
+  // pass before publishing 0.2.0-beta enumerates ALL 21 visually-distinct
+  // compound entries so a future TV recipe edit can't silently drop one.
+  describe('compound variants matrix — every surface × intent', () => {
+    const INTENTS = ['primary', 'secondary', 'success', 'warning', 'danger', 'info', 'neutral'] as const;
+
+    /*
+     * Outlined × 7 intents — each emits a tinted border + soft bg pair
+     * with the dark-mode counterpart pre-wired. Spot-check picks the
+     * `border-{color}-300` light token and the `dark:border-{color}-{N}` pair.
+     */
+    describe('outlined × intent', () => {
+      it.each(INTENTS)('outlined × %s emits border + bg with dark pair', (color) => {
+        const { container } = render(<Box variant="outlined" color={color}>x</Box>);
+        const cls = container.firstElementChild?.className ?? '';
+        if (color === 'neutral') {
+          // neutral uses the special border-neutral-200 + bg-white shape
+          expect(cls).toContain('border-neutral-200');
+          expect(cls).toContain('bg-white');
+          expect(cls).toContain('dark:border-neutral-700');
+          expect(cls).toContain('dark:bg-neutral-900');
+        } else {
+          // primary/secondary/success/warning/danger/info share the
+          // border-{color}-300 + bg-{color}-50/40 + dark:* pattern
+          expect(cls).toContain(`border-${color}-300`);
+          expect(cls).toContain(`bg-${color}-50/40`);
+          expect(cls).toContain(`dark:border-${color}-800`);
+          expect(cls).toContain(`dark:bg-${color}-950/30`);
+        }
+      });
+    });
+
+    /*
+     * Soft × 7 intents — semi-transparent tinted background + matching
+     * intent text colour. Dark pair uses a darker bg + lighter text so
+     * contrast holds in both modes.
+     */
+    describe('soft × intent', () => {
+      it.each(INTENTS)('soft × %s emits bg + text with dark pair', (color) => {
+        const { container } = render(<Box variant="soft" color={color}>x</Box>);
+        const cls = container.firstElementChild?.className ?? '';
+        if (color === 'neutral') {
+          expect(cls).toContain('bg-neutral-100');
+          expect(cls).toContain('text-neutral-900');
+          expect(cls).toContain('dark:bg-neutral-800');
+          expect(cls).toContain('dark:text-neutral-100');
+        } else {
+          expect(cls).toContain(`bg-${color}-100`);
+          expect(cls).toContain(`text-${color}-900`);
+          expect(cls).toContain(`dark:bg-${color}-950/50`);
+          expect(cls).toContain(`dark:text-${color}-100`);
+        }
+      });
+    });
+
+    /*
+     * Solid × 7 intents — full-bleed intent background, white text by
+     * default (neutral inverts: black bg → white text in light, white
+     * bg → black text in dark). The dark variant typically uses a
+     * lighter shade so the surface doesn't look pitch black on already-
+     * dark page backgrounds.
+     */
+    describe('solid × intent', () => {
+      it.each(INTENTS)('solid × %s emits bg + text-white (or contrast pair for neutral)', (color) => {
+        const { container } = render(<Box variant="solid" color={color}>x</Box>);
+        const cls = container.firstElementChild?.className ?? '';
+        if (color === 'neutral') {
+          expect(cls).toContain('bg-neutral-900');
+          expect(cls).toContain('text-white');
+          expect(cls).toContain('dark:bg-neutral-100');
+          expect(cls).toContain('dark:text-neutral-900');
+        } else if (color === 'warning') {
+          // warning uses 500/600 instead of 600/500 to keep contrast
+          // legible against an already-yellow surface in light mode.
+          expect(cls).toContain('bg-warning-500');
+          expect(cls).toContain('text-white');
+          expect(cls).toContain('dark:bg-warning-600');
+        } else {
+          expect(cls).toContain(`bg-${color}-600`);
+          expect(cls).toContain('text-white');
+          expect(cls).toContain(`dark:bg-${color}-500`);
+        }
+      });
+    });
+  });
+
+  // ─── F11-bis edge cases: color is ignored for plain / elevated ──────
+  // These two variants are color-agnostic by design (see box.variants.ts
+  // header) — passing `color` shouldn't accidentally inject the intent
+  // bg/border via the compound matrix.
+  describe('color-agnostic variants', () => {
+    it('plain + color="primary" does NOT add intent classes', () => {
+      const { container } = render(<Box variant="plain" color="primary">x</Box>);
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).not.toContain('bg-primary-');
+      expect(cls).not.toContain('border-primary-');
+      expect(cls).not.toContain('text-primary-');
+    });
+
+    it('elevated + color="danger" stays on the neutral surface', () => {
+      const { container } = render(<Box variant="elevated" color="danger">x</Box>);
+      const cls = container.firstElementChild?.className ?? '';
+      // elevated paints bg-white / dark:bg-neutral-900 regardless of intent
+      expect(cls).toContain('bg-white');
+      expect(cls).toContain('dark:bg-neutral-900');
+      expect(cls).not.toContain('bg-danger-');
+      expect(cls).not.toContain('border-danger-');
+    });
+  });
+
+  // ─── F11-bis edge cases: spacing axis coexistence ───────────────────
+  describe('spacing axis coexistence', () => {
+    it('p={4} + px={6}: both classes emitted (tailwind-merge resolves)', () => {
+      const { container } = render(<Box p={4} px={6}>x</Box>);
+      const cls = container.firstElementChild?.className ?? '';
+      // tailwind-merge: px-6 wins over p-4 on horizontal padding,
+      // p-4 keeps applying vertical via py
+      expect(cls).toContain('px-6');
+      // p-4 → tailwind-merge collapses with px-6 (latter wins on x-axis)
+      // The vertical (py-4 derived from p-4) is what remains.
+    });
+
+    it('m={2} + mx={4} + my={6}: all three coexist (resolves to mx-4 + my-6 effectively)', () => {
+      const { container } = render(<Box m={2} mx={4} my={6}>x</Box>);
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('mx-4');
+      expect(cls).toContain('my-6');
+    });
+  });
+
+  // ─── F11-bis edge cases: elevation × variant interaction ────────────
+  describe('elevation × variant', () => {
+    it('elevation works on non-elevated variants too (consumer choice)', () => {
+      const { container } = render(<Box variant="outlined" color="neutral" elevation={4}>x</Box>);
+      // The shadow class still gets emitted even though the design
+      // recommendation is "use elevation only with variant=elevated".
+      // We don't gate this at the TV level because compound restrictions
+      // would make the API harder to discover.
+      expect(container.firstElementChild?.className).toContain('shadow-lg');
+    });
+
+    it('elevation=0 explicitly disables shadow', () => {
+      const { container } = render(<Box variant="elevated" elevation={0}>x</Box>);
+      expect(container.firstElementChild?.className).toContain('shadow-none');
+    });
+  });
+
+  // ─── F11-bis edge cases: rounded full ───────────────────────────────
+  describe('rounded edge values', () => {
+    it('rounded="full" produces rounded-full (avatars, pills)', () => {
+      const { container } = render(<Box rounded="full">x</Box>);
+      expect(container.firstElementChild?.className).toContain('rounded-full');
+    });
+
+    it('rounded="none" explicitly removes any rounding', () => {
+      const { container } = render(<Box rounded="none">x</Box>);
+      expect(container.firstElementChild?.className).toContain('rounded-none');
+    });
+  });
+});

package/src/components/Box/Box.tsx

@@ -0,0 +1,83 @@
+import { forwardRef, type ElementType, type ReactElement } from 'react';
+import { Slot } from '@radix-ui/react-slot';
+import { cn } from '../../utils/cn.js';
+import { boxVariants } from './box.variants.js';
+import type { BoxProps } from './box.types.js';
+
+/**
+ * `<Box>` — the surface primitive of @dashforge/tw.
+ *
+ * What it IS:
+ *   A polymorphic container with typed surface variants (plain /
+ *   outlined / elevated / soft / solid) × 7 intent colours, plus
+ *   spacing / sizing / rounded / elevation as enumerated token-scale
+ *   props. Replaces MUI's Box + Paper + Card + Surface in one component.
+ *
+ * What it is NOT (deliberate, enforced by the prop set):
+ *   • Not a flex container         → use <Stack>
+ *   • Not a grid container         → use <Grid>
+ *   • Not a paragraph              → use <Typography>
+ *   • Not a button                 → use <Button>
+ *
+ * The "Box is not flex" rule is the spine of the layout layer. Without
+ * it, every `<div>` in an app gravitates back to Box and the surface
+ * vs layout distinction collapses. Box's job is the SURFACE around
+ * content; Stack/Grid's job is the ARRANGEMENT of content. Two
+ * primitives, two responsibilities.
+ *
+ * When BOTH `as` and `asChild` are passed, `asChild` wins. Same rule
+ * as Typography — documented to avoid the dimension-bloat of a
+ * discriminated union over an 11-axis props type.
+ *
+ * Layering:
+ *   • Sits BENEATH every visual chrome — every card, every panel,
+ *     every section background.
+ *   • Composes ON TOP of @dashforge/tw-tokens (color + spacing + radius
+ *     + shadow scales) via the dashforgePreset CSS variables.
+ *   • Pairs with Typography for text content, Stack/Grid for layout
+ *     children inside it.
+ */
+export const Box = forwardRef<HTMLElement, BoxProps>(
+  function Box(props, ref) {
+    const {
+      variant,
+      color,
+      elevation,
+      rounded,
+      p, px, py, m, mx, my,
+      fullWidth,
+      fullHeight,
+      as,
+      asChild = false,
+      sx,
+      children,
+      ...rest
+    } = props;
+
+    const classes = cn(
+      boxVariants({
+        variant, color, elevation, rounded,
+        p, px, py, m, mx, my,
+        fullWidth, fullHeight,
+      }),
+      sx,
+    );
+
+    if (asChild) {
+      return (
+        <Slot ref={ref} className={classes} {...rest}>
+          {children as ReactElement}
+        </Slot>
+      );
+    }
+
+    const Tag = (as ?? 'div') as ElementType;
+    return (
+      <Tag ref={ref as never} className={classes} {...rest}>
+        {children}
+      </Tag>
+    );
+  },
+);
+
+Box.displayName = 'Box';

package/src/components/Box/box.types.ts

@@ -0,0 +1,61 @@
+import type { ElementType, HTMLAttributes } from 'react';
+import type { BoxVariants } from './box.variants.js';
+
+/**
+ * Props for `<Box>` — the surface primitive.
+ *
+ * What lives in props (typed, ergonomic):
+ *   • Surface          — variant, color, elevation, rounded
+ *   • Spacing          — p, px, py, m, mx, my (token-scale steps)
+ *   • Sizing           — fullWidth, fullHeight
+ *   • Polymorphism     — as, asChild
+ *   • Override escape  — sx (utility string, merged via tailwind-merge)
+ *
+ * What does NOT live here (deliberate, see Box.tsx header):
+ *   • display / flex / grid / gap   → use Stack or Grid
+ *   • position / top / z-index      → use sx
+ *   • overflow / cursor             → use sx
+ *   • animation / transition        → use sx
+ *
+ * Native attribute overrides:
+ *   • `className` is omitted in favour of `sx` (string of utilities,
+ *     resolved by tailwind-merge so consumer wins over variant defaults)
+ *     — same convention as Button/TextField/Checkbox/Switch.
+ *   • `color` is omitted: collides with the deprecated HTML4 `color`
+ *     attribute. Our typed `color` (intent) is the right one.
+ */
+export interface BoxProps
+  extends Omit<HTMLAttributes<HTMLDivElement>, 'className' | 'color'>,
+          Pick<BoxVariants,
+            'variant' | 'color' | 'elevation' | 'rounded'
+            | 'p' | 'px' | 'py' | 'm' | 'mx' | 'my'
+            | 'fullWidth' | 'fullHeight'> {
+  /**
+   * Override the rendered HTML tag. Defaults to `'div'`. Useful when
+   * the surface should also carry semantic meaning — `<Box as="section">`
+   * for a page section, `<Box as="article">` for a card-shaped article.
+   *
+   * Ignored when `asChild` is true.
+   */
+  as?: ElementType;
+
+  /**
+   * Render via Radix `Slot` — the Box styles paint onto the single
+   * React child instead of wrapping it in our own element. Useful for
+   * `<Box asChild><Link>...</Link></Box>` to get a styled router link
+   * with no extra DOM wrapper.
+   *
+   * Mutually exclusive with `as` (when both are passed, `asChild` wins
+   * — see Box.tsx for the reasoning).
+   */
+  asChild?: boolean;
+
+  /**
+   * Utility classes appended to the variant chain. Resolved via
+   * `tailwind-merge` so the consumer's classes always win over the
+   * variant defaults. Use for one-off overrides AND for utility
+   * dimensions Box deliberately doesn't expose as props (overflow,
+   * position, animation, etc.).
+   */
+  sx?: string;
+}