@dashforge/tw 0.1.0-beta → 0.2.1-beta

package/src/components/Stack/Stack.tsx

@@ -0,0 +1,115 @@
+import {
+  Children,
+  Fragment,
+  cloneElement,
+  forwardRef,
+  isValidElement,
+  type ElementType,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import { Slot } from '@radix-ui/react-slot';
+import { cn } from '../../utils/cn.js';
+import { stackVariants } from './stack.variants.js';
+import type { StackProps } from './stack.types.js';
+
+/**
+ * Walk the children, inserting `divider` BETWEEN every consecutive pair.
+ *
+ * Implementation notes:
+ *   • `React.Children.toArray` assigns auto-keys but does NOT recursively
+ *     flatten Fragments — it treats them as opaque single children. So
+ *     `<Stack><><a/><b/></><c/></Stack>` is 2 boundaries (fragment + c),
+ *     yielding ONE divider. Hoist items out of the fragment when you
+ *     need a divider between them. Documented + asserted in the tests.
+ *   • Dividers are wrapped in `<Fragment>` with a deterministic key
+ *     derived from the boundary index — stable across re-renders so
+ *     React reconciles correctly when children re-order.
+ *   • If `divider` is a valid element, we `cloneElement` once per
+ *     boundary (cheaper than re-rendering the JSX expression N-1 times).
+ *     For string/number dividers we wrap in a span automatically.
+ */
+function interleaveDividers(children: ReactNode, divider: ReactNode): ReactNode[] {
+  const items = Children.toArray(children);
+  if (items.length <= 1) return items;
+
+  const result: ReactNode[] = [];
+  items.forEach((child, i) => {
+    result.push(child);
+    if (i < items.length - 1) {
+      const key = `df-stack-divider-${i}`;
+      if (isValidElement(divider)) {
+        result.push(cloneElement(divider as ReactElement<{ key?: string }>, { key }));
+      } else {
+        result.push(<Fragment key={key}>{divider}</Fragment>);
+      }
+    }
+  });
+  return result;
+}
+
+/**
+ * `<Stack>` — flex container 1D, the layout primitive.
+ *
+ * This is the ONLY component in @dashforge/tw that does flex. Box
+ * doesn't, Grid does CSS Grid (not flex). The strict naming → engine
+ * mapping is the whole point: when you read `<Stack>` in a JSX tree,
+ * you instantly know it's flex. No `<Box display="flex" ...>` traps.
+ *
+ * Direction defaults to `'col'` (vertical stack) — the most common
+ * case for forms, sidebars, settings panels. Pass `direction="row"`
+ * for horizontal layouts (toolbars, button rows, breadcrumbs).
+ *
+ * The `divider` prop is the runtime-only piece: TV can't encode the
+ * "render this between each child" logic as a class, so we walk the
+ * children at render time. The walk is O(n); for n ≤ ~10 (typical
+ * Stack content) the cost is negligible. For very long Stacks (1000+
+ * items), prefer to render dividers as part of each child instead.
+ *
+ * When `asChild` is true, the divider prop is silently ignored — Slot
+ * requires a single child, and the N-1 insertion has nowhere to act.
+ */
+export const Stack = forwardRef<HTMLElement, StackProps>(
+  function Stack(props, ref) {
+    const {
+      direction,
+      align,
+      justify,
+      gap,
+      wrap,
+      fullWidth,
+      fullHeight,
+      divider,
+      as,
+      asChild = false,
+      sx,
+      children,
+      ...rest
+    } = props;
+
+    const classes = cn(
+      stackVariants({ direction, align, justify, gap, wrap, fullWidth, fullHeight }),
+      sx,
+    );
+
+    if (asChild) {
+      // Slot expects a single child; divider has no place here.
+      return (
+        <Slot ref={ref} className={classes} {...rest}>
+          {children as ReactElement}
+        </Slot>
+      );
+    }
+
+    const Tag = (as ?? 'div') as ElementType;
+    const content = divider != null ? interleaveDividers(children, divider) : children;
+
+    return (
+      <Tag ref={ref as never} className={classes} {...rest}>
+        {content}
+      </Tag>
+    );
+  },
+);
+
+Stack.displayName = 'Stack';

package/src/components/Stack/stack.types.ts

@@ -0,0 +1,68 @@
+import type { ElementType, HTMLAttributes, ReactNode } from 'react';
+import type { StackVariants } from './stack.variants.js';
+
+/**
+ * Props for `<Stack>` — flex container 1D, the layout primitive.
+ *
+ * Axes:
+ *   • direction              — flex-direction (default 'col')
+ *   • align                  — items-* (cross-axis)
+ *   • justify                — justify-* (main-axis)
+ *   • gap                    — token-scale spacing step
+ *   • wrap                   — flex-wrap
+ *   • fullWidth/fullHeight   — w-full / h-full
+ *   • divider                — node rendered N-1 times between children
+ *
+ * Polymorphism:
+ *   • as            — override the HTML tag (default 'div')
+ *   • asChild       — render via Radix Slot onto the single child
+ *
+ * What Stack does NOT do (route to other primitives):
+ *   • Surface chrome (border, bg, shadow)   → wrap in <Box>
+ *   • 2D layout (rows AND columns)          → use <Grid>
+ *   • Text styling                          → <Typography>
+ */
+export interface StackProps
+  extends Omit<HTMLAttributes<HTMLDivElement>, 'className'>,
+          Pick<StackVariants,
+            'direction' | 'align' | 'justify' | 'gap' | 'wrap'
+            | 'fullWidth' | 'fullHeight'> {
+  /**
+   * Node rendered N-1 times BETWEEN children — mirror of MUI Stack's
+   * divider prop. Useful for visual separators (a `<hr>`, a thin
+   * `<Box variant="outlined" sx="h-px border-0 border-t">`, an
+   * `<svg>` glyph) that need to follow the flex direction.
+   *
+   * The node is cloned for each insertion via `cloneElement`; pass a
+   * stable element (not a function) for best React reconciliation.
+   * `React.Children.toArray` flattens fragments before the walk, so
+   * `<Stack divider={...}><><...></></Stack>` works as expected.
+   */
+  divider?: ReactNode;
+
+  /**
+   * Override the rendered HTML tag. Defaults to `'div'`. Use when the
+   * Stack also has semantic meaning — `<Stack as="nav">` for a nav
+   * bar, `<Stack as="ul">` for a list (children become `<li>` via
+   * native HTML, not by us).
+   *
+   * Ignored when `asChild` is true.
+   */
+  as?: ElementType;
+
+  /**
+   * Render via Radix `Slot` — the Stack styles paint onto the single
+   * React child instead of wrapping it. Mutually exclusive with `as`
+   * (when both are passed, `asChild` wins). The `divider` prop is
+   * ignored when `asChild` is true (the Slot pattern wraps a single
+   * node, so the N-1 insertion logic has no place to act).
+   */
+  asChild?: boolean;
+
+  /**
+   * Utility classes appended to the variant chain. Resolved via
+   * `tailwind-merge` so the consumer's classes always win over the
+   * variant defaults.
+   */
+  sx?: string;
+}

package/src/components/Stack/stack.variants.ts

@@ -0,0 +1,80 @@
+import { tv, type VariantProps } from 'tailwind-variants';
+
+/**
+ * `stackVariants` — flex container 1D, the layout primitive of @dashforge/tw.
+ *
+ * Architectural role (planned with the user — F9 deep dive):
+ *
+ *   Stack is the ONLY way to do flex in this library. Box is the
+ *   surface (border / bg / shadow); Stack is the arrangement (direction
+ *   / align / justify / gap). Two primitives, two responsibilities,
+ *   zero overlap.
+ *
+ *   This rules out the MUI failure mode where every `<Box display="flex"
+ *   gap={2}>` quietly becomes the de-facto flex container, drowning
+ *   the surface vs layout distinction. Here, if you see `<Stack>` in
+ *   the JSX, you KNOW it's flex; if you see `<Box>`, you KNOW it's
+ *   not. The component name carries the intent.
+ *
+ * Axes:
+ *   • direction         — row / col (+ reverse variants)
+ *   • align / justify   — cross-axis / main-axis alignment
+ *   • gap               — token-scale step (mirror Box spacing scale)
+ *   • wrap              — flex-wrap
+ *   • divider           — runtime-only (handled in Stack.tsx, not here)
+ *
+ * Sizing (`fullWidth`, `fullHeight`) is duplicated from Box because
+ * Stack often plays the role of a full-width strip / full-height
+ * column — re-typing `sx="w-full"` every time would be friction.
+ */
+export const stackVariants = tv({
+  base: 'flex',
+
+  variants: {
+    direction: {
+      row:           'flex-row',
+      col:           'flex-col',
+      'row-reverse': 'flex-row-reverse',
+      'col-reverse': 'flex-col-reverse',
+    },
+
+    align: {
+      start:    'items-start',
+      center:   'items-center',
+      end:      'items-end',
+      stretch:  'items-stretch',
+      baseline: 'items-baseline',
+    },
+
+    justify: {
+      start:   'justify-start',
+      center:  'justify-center',
+      end:     'justify-end',
+      between: 'justify-between',
+      around:  'justify-around',
+      evenly:  'justify-evenly',
+    },
+
+    /*
+     * `gap` — explicit literal mapping for the 11 token-scale steps.
+     * Same set as Box's spacing axes (p, m, etc.) so muscle memory
+     * carries over: `<Stack gap={4}>` aligns visually with `<Box p={4}>`.
+     */
+    gap: {
+      0:    'gap-0',    '0.5': 'gap-0.5', 1:  'gap-1',  2:  'gap-2',  3:  'gap-3',
+      4:    'gap-4',    6:     'gap-6',   8:  'gap-8',  12: 'gap-12', 16: 'gap-16',
+      24:   'gap-24',
+    },
+
+    wrap: { true: 'flex-wrap' },
+
+    fullWidth:  { true: 'w-full' },
+    fullHeight: { true: 'h-full' },
+  },
+
+  defaultVariants: {
+    direction: 'col',
+  },
+});
+
+export type StackVariants = VariantProps<typeof stackVariants>;

package/src/components/Typography/Typography.test.tsx

@@ -0,0 +1,230 @@
+// @vitest-environment jsdom
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/react';
+import { Typography } from './Typography.js';
+
+/**
+ * Suite mirrors the Button.test.tsx shape (rendering · variants · color ·
+ * override · polymorphism) so the test surface is uniform across the
+ * package.
+ *
+ * Strategy: render → query → assert on `tagName` (for HTML-element
+ * resolution) and `className` (for variant resolution). We deliberately
+ * DON'T snapshot: snapshots churn on every variant-class edit and offer
+ * no signal on the actual contract — the contract is "this variant
+ * emits THESE specific Tailwind utility classes", which we assert
+ * positively below.
+ */
+describe('<Typography>', () => {
+  // ─── Rendering / default tag mapping ────────────────────────────────
+  describe('default tag mapping', () => {
+    it('renders <p> for body1 by default', () => {
+      const { container } = render(<Typography>hello</Typography>);
+      expect(container.firstElementChild?.tagName).toBe('P');
+    });
+
+    it('renders <h1> for variant="h1"', () => {
+      const { container } = render(<Typography variant="h1">title</Typography>);
+      expect(container.firstElementChild?.tagName).toBe('H1');
+    });
+
+    it('renders <h3> for variant="h3"', () => {
+      const { container } = render(<Typography variant="h3">title</Typography>);
+      expect(container.firstElementChild?.tagName).toBe('H3');
+    });
+
+    it('renders <span> for variant="caption"', () => {
+      const { container } = render(<Typography variant="caption">note</Typography>);
+      expect(container.firstElementChild?.tagName).toBe('SPAN');
+    });
+
+    it('renders <span> for variant="overline"', () => {
+      const { container } = render(<Typography variant="overline">label</Typography>);
+      expect(container.firstElementChild?.tagName).toBe('SPAN');
+    });
+  });
+
+  // ─── Variant classes ────────────────────────────────────────────────
+  describe('variant → utility chain', () => {
+    it('h1 has text-5xl + font-bold', () => {
+      const { container } = render(<Typography variant="h1">x</Typography>);
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('text-5xl');
+      expect(cls).toContain('font-bold');
+    });
+
+    it('body2 has text-sm', () => {
+      const { container } = render(<Typography variant="body2">x</Typography>);
+      expect(container.firstElementChild?.className).toContain('text-sm');
+    });
+
+    it('overline has uppercase + tracking', () => {
+      const { container } = render(<Typography variant="overline">x</Typography>);
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('uppercase');
+      expect(cls).toMatch(/tracking-\[/);
+    });
+  });
+
+  // ─── Color intent ───────────────────────────────────────────────────
+  describe('color', () => {
+    it('color="primary" emits text-primary-* with dark variant', () => {
+      const { container } = render(<Typography color="primary">x</Typography>);
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('text-primary-700');
+      expect(cls).toContain('dark:text-primary-400');
+    });
+
+    it('color="danger" emits text-danger-*', () => {
+      const { container } = render(<Typography color="danger">x</Typography>);
+      expect(container.firstElementChild?.className).toContain('text-danger-700');
+    });
+
+    it('color="inherit" emits text-inherit', () => {
+      const { container } = render(<Typography color="inherit">x</Typography>);
+      expect(container.firstElementChild?.className).toContain('text-inherit');
+    });
+  });
+
+  // ─── Override semantics ─────────────────────────────────────────────
+  describe('override', () => {
+    it('sx wins over variant defaults via tailwind-merge', () => {
+      const { container } = render(
+        <Typography variant="h1" color="primary" sx="text-pink-500">x</Typography>,
+      );
+      const cls = container.firstElementChild?.className ?? '';
+      // tailwind-merge collapses the conflicting `text-*` colour to the last one
+      expect(cls).toContain('text-pink-500');
+      expect(cls).not.toContain('text-primary-700');
+    });
+
+    it('weight prop overrides variant default weight', () => {
+      const { container } = render(<Typography variant="h1" weight="normal">x</Typography>);
+      const cls = container.firstElementChild?.className ?? '';
+      // h1's default `font-bold` is dropped by tailwind-merge, replaced by font-normal
+      expect(cls).toContain('font-normal');
+      expect(cls).not.toContain('font-bold');
+    });
+
+    it('truncate adds the truncate utility', () => {
+      const { container } = render(<Typography truncate>x</Typography>);
+      expect(container.firstElementChild?.className).toContain('truncate');
+    });
+
+    it('gutterBottom adds mb-3', () => {
+      const { container } = render(<Typography gutterBottom>x</Typography>);
+      expect(container.firstElementChild?.className).toContain('mb-3');
+    });
+  });
+
+  // ─── Polymorphism — `as` and `asChild` ───────────────────────────────
+  describe('polymorphism', () => {
+    it('as="section" overrides the variant-default tag', () => {
+      const { container } = render(
+        <Typography variant="h1" as="section">x</Typography>,
+      );
+      expect(container.firstElementChild?.tagName).toBe('SECTION');
+    });
+
+    it('asChild renders the single child element with merged className', () => {
+      const { container } = render(
+        <Typography variant="h2" color="primary" asChild>
+          <a href="#">link</a>
+        </Typography>,
+      );
+      const el = container.firstElementChild;
+      expect(el?.tagName).toBe('A');
+      expect(el?.className).toContain('text-4xl');
+      expect(el?.className).toContain('text-primary-700');
+      expect(el?.getAttribute('href')).toBe('#');
+    });
+
+    it('asChild wins over `as` when both are passed', () => {
+      const { container } = render(
+        <Typography variant="h1" as="section" asChild>
+          <article>x</article>
+        </Typography>,
+      );
+      // Slot renders the child element, ignoring `as`
+      expect(container.firstElementChild?.tagName).toBe('ARTICLE');
+    });
+  });
+
+  // ─── Pass-through ────────────────────────────────────────────────────
+  describe('pass-through props', () => {
+    it('forwards data-* attributes', () => {
+      const { container } = render(
+        <Typography data-testid="typo">x</Typography>,
+      );
+      expect(container.firstElementChild?.getAttribute('data-testid')).toBe('typo');
+    });
+
+    it('forwards aria-label', () => {
+      const { container } = render(
+        <Typography aria-label="heading">x</Typography>,
+      );
+      expect(container.firstElementChild?.getAttribute('aria-label')).toBe('heading');
+    });
+  });
+
+  // ─── F11-bis edge cases ─────────────────────────────────────────────
+  describe('multi-axis combinations', () => {
+    it('variant=h2 + color=primary + weight=normal + align=center + truncate + gutterBottom', () => {
+      const { container } = render(
+        <Typography
+          variant="h2"
+          color="primary"
+          weight="normal"
+          align="center"
+          truncate
+          gutterBottom
+        >
+          x
+        </Typography>,
+      );
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('text-4xl');           // h2 size
+      expect(cls).toContain('text-primary-700');   // color intent
+      expect(cls).toContain('font-normal');        // weight override (vs h2 default font-bold)
+      expect(cls).not.toContain('font-bold');      // overridden
+      expect(cls).toContain('text-center');        // align
+      expect(cls).toContain('truncate');           // truncate
+      expect(cls).toContain('mb-3');               // gutterBottom
+    });
+
+    it('noWrap + truncate: truncate wins (later in chain, tailwind-merge collapses whitespace-nowrap)', () => {
+      const { container } = render(<Typography noWrap truncate>x</Typography>);
+      // truncate utility already includes whitespace-nowrap — tailwind-merge
+      // collapses the redundant nowrap from noWrap
+      expect(container.firstElementChild?.className).toContain('truncate');
+    });
+
+    it('every variant maps to its expected default tag', () => {
+      const cases: Array<[Parameters<typeof Typography>[0]['variant'], string]> = [
+        ['h1', 'H1'], ['h2', 'H2'], ['h3', 'H3'], ['h4', 'H4'], ['h5', 'H5'], ['h6', 'H6'],
+        ['subtitle1', 'P'], ['subtitle2', 'P'],
+        ['body1', 'P'], ['body2', 'P'],
+        ['caption', 'SPAN'], ['overline', 'SPAN'],
+      ];
+      cases.forEach(([variant, tag]) => {
+        const { container } = render(<Typography variant={variant}>x</Typography>);
+        expect(container.firstElementChild?.tagName).toBe(tag);
+      });
+    });
+  });
+
+  describe('color edge cases', () => {
+    const INTENTS = ['primary', 'secondary', 'success', 'warning', 'danger', 'info', 'muted'] as const;
+    it.each(INTENTS)('color="%s" emits the right text-* + dark pair', (color) => {
+      const { container } = render(<Typography color={color}>x</Typography>);
+      const cls = container.firstElementChild?.className ?? '';
+      if (color === 'muted') {
+        expect(cls).toContain('text-neutral-600');
+        expect(cls).toContain('dark:text-neutral-400');
+      } else {
+        expect(cls).toContain(`text-${color}-700`);
+        expect(cls).toContain(`dark:text-${color}-400`);
+      }
+    });
+  });
+});

package/src/components/Typography/Typography.tsx

@@ -0,0 +1,112 @@
+import { forwardRef, type ElementType, type ReactElement } from 'react';
+import { Slot } from '@radix-ui/react-slot';
+import { cn } from '../../utils/cn.js';
+import { typographyVariants } from './typography.variants.js';
+import type { TypographyProps } from './typography.types.js';
+
+/**
+ * Default HTML tag per variant. Headings get their semantic level (h1→h1
+ * etc.); subtitle/body get `<p>` (block, paragraph semantics);
+ * caption/overline get `<span>` (inline, no implicit block break).
+ *
+ * Override per-instance via the `as` prop — useful when the semantic
+ * heading level should differ from the visual scale (e.g. a hero
+ * rendered as `<h2>` but visually styled `h1`).
+ */
+const VARIANT_TO_TAG: Record<NonNullable<TypographyProps['variant']>, ElementType> = {
+  h1:        'h1',
+  h2:        'h2',
+  h3:        'h3',
+  h4:        'h4',
+  h5:        'h5',
+  h6:        'h6',
+  subtitle1: 'p',
+  subtitle2: 'p',
+  body1:     'p',
+  body2:     'p',
+  caption:   'span',
+  overline:  'span',
+};
+
+/**
+ * `<Typography>` — semantic typed text, the foundation of every readable
+ * surface in @dashforge/tw.
+ *
+ * Why this exists:
+ *   Tailwind ships a typographic scale (`text-xl`, `font-bold`,
+ *   `leading-relaxed`) but leaves the SEMANTIC HTML tag and the
+ *   intent-coloured palette to the consumer. That's fine for one-off
+ *   marketing surfaces, but at app scale it means every `<h2>` and every
+ *   body paragraph re-derives its own utility chain — and they drift.
+ *
+ *   Typography moves that decision into a typed prop set: the visual
+ *   scale, the intent colour, the alignment, the truncation all live in
+ *   `tailwind-variants` and resolve to the same utility chain everywhere
+ *   in the app. The default HTML tag is inferred from `variant` so the
+ *   semantic layer follows the visual layer; `as` and `asChild` are the
+ *   two escape hatches when you need something else.
+ *
+ * Layering:
+ *   • Sits BENEATH every component that renders text — `<Button>`'s
+ *     label, `<TextField>`'s helper text, MDX prose in our own docs.
+ *   • Composes ON TOP of `@dashforge/tw-tokens` colour scales (so
+ *     `color="primary"` paints `text-primary-700` in light, `-400` in dark,
+ *     reactive to `setMode()`).
+ *   • Polymorphic via Radix Slot — pairs cleanly with router `<Link>`,
+ *     `<button>`, or `<a>` without injecting an extra wrapper element.
+ *
+ * Polymorphism rules — `as` vs `asChild`:
+ *   • `as` swaps the rendered tag (we still render the element ourselves).
+ *   • `asChild` removes our element entirely — the single React child
+ *     becomes the rendered tag, with our className/ref merged onto it.
+ *     This is the Radix Slot pattern; use when you need a router Link
+ *     to style as a heading.
+ *   When BOTH are passed, `asChild` wins. We considered making this a
+ *   compile-time error via discriminated unions, but the API surface
+ *   already has 8 axes and adding one more dimension to the props type
+ *   would inflate IntelliSense suggestions for marginal benefit. The
+ *   runtime preference is documented; the test asserts it.
+ */
+export const Typography = forwardRef<HTMLElement, TypographyProps>(
+  function Typography(props, ref) {
+    const {
+      variant = 'body1',
+      color,
+      weight,
+      align,
+      truncate,
+      noWrap,
+      gutterBottom,
+      as,
+      asChild = false,
+      sx,
+      children,
+      ...rest
+    } = props;
+
+    const classes = cn(
+      typographyVariants({ variant, color, weight, align, truncate, noWrap, gutterBottom }),
+      sx,
+    );
+
+    // asChild wins over `as` when both are passed (see component header).
+    if (asChild) {
+      return (
+        <Slot ref={ref} className={classes} {...rest}>
+          {children as ReactElement}
+        </Slot>
+      );
+    }
+
+    // Resolve the rendered tag: explicit `as` > variant default > fallback.
+    const Tag = (as ?? VARIANT_TO_TAG[variant] ?? 'span') as ElementType;
+
+    return (
+      <Tag ref={ref as never} className={classes} {...rest}>
+        {children}
+      </Tag>
+    );
+  },
+);
+
+Typography.displayName = 'Typography';

package/src/components/Typography/typography.types.ts

@@ -0,0 +1,65 @@
+import type { ElementType, HTMLAttributes } from 'react';
+import type { TypographyVariants } from './typography.variants.js';
+
+/**
+ * Props for `<Typography>`.
+ *
+ * Composition with native `HTMLAttributes`:
+ *   • `className` is omitted in favour of `sx` (string of utility classes)
+ *     — same convention as Button/TextField/Checkbox/Switch in this
+ *     package. `sx` is merged via `tailwind-merge`, so the consumer's
+ *     classes always win over variant defaults.
+ *   • `color` is omitted because the native HTML attribute (the
+ *     deprecated `color="red"` from HTML4) collides with our intent
+ *     prop — TypeScript would otherwise widen to a confusing union.
+ *
+ * Variant axes picked from `TypographyVariants`:
+ *   • `variant`  — the type scale (h1–h6, subtitle1/2, body1/2, caption, overline)
+ *   • `color`    — the intent (primary, secondary, success, warning, danger, info, neutral, muted, inherit)
+ *   • `weight`   — overrides the variant's default font-weight
+ *   • `align`    — text-align
+ *   • `truncate` — one-line ellipsis
+ *   • `noWrap`   — one-line without ellipsis
+ *   • `gutterBottom` — adds mb-3 (mirror of MUI's same prop)
+ *
+ * Polymorphism:
+ *   • `as` — override the HTML tag while keeping the variant's visual
+ *            style (e.g. `<Typography variant="h1" as="h2">` renders an
+ *            `<h2>` styled like h1 — useful when the semantic heading
+ *            level matters more than the type scale).
+ *   • `asChild` — render as the single child element via Radix Slot
+ *            (so the styles paint onto a `<Link>`, `<a>`, etc.).
+ *            Mutually exclusive with `as` — see component header for
+ *            the rationale.
+ */
+export interface TypographyProps
+  extends Omit<HTMLAttributes<HTMLElement>, 'className' | 'color'>,
+          Pick<TypographyVariants, 'variant' | 'color' | 'weight' | 'align' | 'truncate' | 'noWrap' | 'gutterBottom'> {
+  /**
+   * Override the HTML tag. Defaults to a sensible mapping per variant
+   * (h1→h1, …, body1→p, caption→span, overline→span). Use when the
+   * semantic heading level should differ from the visual scale —
+   * e.g. a "hero" rendered as an `<h2>` but styled like `h1`.
+   *
+   * Ignored when `asChild` is true.
+   */
+  as?: ElementType;
+
+  /**
+   * Render via Radix `Slot` — the Typography styles paint onto the
+   * single React child instead of wrapping it in our own tag. Useful
+   * for `<Typography asChild><Link>...</Link></Typography>` to get a
+   * styled router link with no extra DOM.
+   *
+   * Mutually exclusive with `as` (when both are passed, `asChild` wins
+   * and `as` is ignored — see Typography.tsx for the reason).
+   */
+  asChild?: boolean;
+
+  /**
+   * Utility classes appended to the variant chain. Resolved via
+   * `tailwind-merge` so the consumer's classes always win over the
+   * variant defaults — e.g. `sx="text-pink-500"` overrides `color="primary"`.
+   */
+  sx?: string;
+}