@dashforge/tw 0.1.0-beta → 0.2.1-beta

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;
+}

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

@@ -0,0 +1,211 @@
+import { tv, type VariantProps } from 'tailwind-variants';
+
+/**
+ * `boxVariants` — the surface primitive for @dashforge/tw.
+ *
+ * Architectural choice (planned with the user — F9 deep dive):
+ *
+ *   Box replaces FOUR overlapping concepts from MUI in one component:
+ *     • Box        (typed div)
+ *     • Paper      (surface with elevation)
+ *     • Card       (Paper specialisation)
+ *     • Surface    (Joy UI's outlined / soft / solid / plain variants)
+ *
+ *   The reason for the consolidation: in MUI you have to compose two or
+ *   three of these to express even basic intent ("an outlined card with
+ *   warning tone"). Here, one `<Box variant="outlined" color="warning">`
+ *   says exactly that.
+ *
+ * Variant taxonomy (5 axes, intentionally non-overlapping with Stack/Grid):
+ *
+ *   • plain     — bare div + padding + radius. The escape hatch.
+ *   • outlined  — 1px border + subtle bg tint. The "card lite".
+ *   • elevated  — bg surface + shadow scale (0-5). The "floating panel".
+ *   • soft      — semi-transparent intent bg + intent text. The "callout".
+ *   • solid     — solid intent bg + contrasting text. The "CTA banner".
+ *
+ *   `color` applies to outlined/soft/solid (each gets the 7 intent
+ *   variants). `elevated` is color-agnostic (always neutral surface +
+ *   shadow scale). `plain` is everything-agnostic.
+ *
+ * Spacing axes (p/px/py/m/mx/my): mapped explicitly to the 11 token
+ * steps from @dashforge/tw-tokens (0, 0.5, 1, 2, 3, 4, 6, 8, 12, 16, 24).
+ * Tailwind JIT requires literal class strings — building them dynamically
+ * with template literals would purge them. The verbosity below is the
+ * cost of keeping the bundle CSS-pure and rebuild-free.
+ *
+ * What this does NOT do (deliberate, see component docs):
+ *   • No display / flex / grid props      → use Stack or Grid
+ *   • No position / overflow / z-index    → use `sx`
+ *   • No animation / transition           → use `sx`
+ *
+ * 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 — exactly the failure mode this
+ * primitive exists to prevent.
+ */
+export const boxVariants = tv({
+  base: 'block',
+
+  variants: {
+    /*
+     * Surface variant. Compound with `color` for outlined / soft / solid;
+     * standalone for plain / elevated.
+     */
+    variant: {
+      plain:    '',
+      outlined: 'border',
+      elevated: 'bg-white dark:bg-neutral-900',
+      soft:     '',
+      solid:    '',
+    },
+
+    /*
+     * Intent color. Only meaningful when variant is outlined / soft /
+     * solid (resolved via compoundVariants below). For plain / elevated
+     * this axis is ignored at the visual level — but kept in the type
+     * so the prop is always available without conditional typing.
+     */
+    color: {
+      primary:   '',
+      secondary: '',
+      success:   '',
+      warning:   '',
+      danger:    '',
+      info:      '',
+      neutral:   '',
+    },
+
+    /*
+     * Shadow scale — relevant for `variant='elevated'`. We keep elevation
+     * as a separate axis (not folded into `variant`) so consumers can
+     * dial it up/down without changing the variant. Default `0` = no
+     * shadow (consistent with MUI's elevation=0).
+     */
+    elevation: {
+      0: 'shadow-none',
+      1: 'shadow-sm',
+      2: 'shadow',
+      3: 'shadow-md',
+      4: 'shadow-lg',
+      5: 'shadow-xl',
+    },
+
+    rounded: {
+      none: 'rounded-none',
+      sm:   'rounded-sm',
+      md:   'rounded-md',
+      lg:   'rounded-lg',
+      xl:   'rounded-xl',
+      '2xl':'rounded-2xl',
+      full: 'rounded-full',
+    },
+
+    /*
+     * Spacing — six axes (p/px/py/m/mx/my), 11 token steps each.
+     * Literals enumerated explicitly so Tailwind's JIT scanner finds
+     * every class. Token steps mirror @dashforge/tw-tokens spacing scale.
+     */
+    p: {
+      0:    'p-0',    '0.5': 'p-0.5', 1:  'p-1',  2:  'p-2',  3:  'p-3',
+      4:    'p-4',    6:     'p-6',   8:  'p-8',  12: 'p-12', 16: 'p-16',
+      24:   'p-24',
+    },
+    px: {
+      0:    'px-0',   '0.5': 'px-0.5', 1:  'px-1',  2:  'px-2',  3:  'px-3',
+      4:    'px-4',   6:     'px-6',   8:  'px-8',  12: 'px-12', 16: 'px-16',
+      24:   'px-24',
+    },
+    py: {
+      0:    'py-0',   '0.5': 'py-0.5', 1:  'py-1',  2:  'py-2',  3:  'py-3',
+      4:    'py-4',   6:     'py-6',   8:  'py-8',  12: 'py-12', 16: 'py-16',
+      24:   'py-24',
+    },
+    m: {
+      0:    'm-0',    '0.5': 'm-0.5', 1:  'm-1',  2:  'm-2',  3:  'm-3',
+      4:    'm-4',    6:     'm-6',   8:  'm-8',  12: 'm-12', 16: 'm-16',
+      24:   'm-24',
+    },
+    mx: {
+      0:    'mx-0',   '0.5': 'mx-0.5', 1:  'mx-1',  2:  'mx-2',  3:  'mx-3',
+      4:    'mx-4',   6:     'mx-6',   8:  'mx-8',  12: 'mx-12', 16: 'mx-16',
+      24:   'mx-24',
+    },
+    my: {
+      0:    'my-0',   '0.5': 'my-0.5', 1:  'my-1',  2:  'my-2',  3:  'my-3',
+      4:    'my-4',   6:     'my-6',   8:  'my-8',  12: 'my-12', 16: 'my-16',
+      24:   'my-24',
+    },
+
+    fullWidth:  { true: 'w-full' },
+    fullHeight: { true: 'h-full' },
+  },
+
+  /*
+   * Compound variants — where surface × color get their actual visual.
+   * Twenty-one entries: 7 (outlined) + 7 (soft) + 7 (solid).
+   * `plain` and `elevated` don't appear here (no color contribution).
+   *
+   * Dark-mode pair is baked in: light-mode picks the 50-300 steps,
+   * dark-mode picks the 800-950 steps — both reactive to setMode()
+   * via the @dashforge/tw-theme CSS variables.
+   */
+  compoundVariants: [
+    // ─── outlined × color ─────────────────────────────────────────────
+    { variant: 'outlined', color: 'primary',
+      class: 'border-primary-300 bg-primary-50/40 dark:border-primary-800 dark:bg-primary-950/30' },
+    { variant: 'outlined', color: 'secondary',
+      class: 'border-secondary-300 bg-secondary-50/40 dark:border-secondary-800 dark:bg-secondary-950/30' },
+    { variant: 'outlined', color: 'success',
+      class: 'border-success-300 bg-success-50/40 dark:border-success-800 dark:bg-success-950/30' },
+    { variant: 'outlined', color: 'warning',
+      class: 'border-warning-300 bg-warning-50/40 dark:border-warning-800 dark:bg-warning-950/30' },
+    { variant: 'outlined', color: 'danger',
+      class: 'border-danger-300 bg-danger-50/40 dark:border-danger-800 dark:bg-danger-950/30' },
+    { variant: 'outlined', color: 'info',
+      class: 'border-info-300 bg-info-50/40 dark:border-info-800 dark:bg-info-950/30' },
+    { variant: 'outlined', color: 'neutral',
+      class: 'border-neutral-200 bg-white dark:border-neutral-700 dark:bg-neutral-900' },
+
+    // ─── soft × color ─────────────────────────────────────────────────
+    { variant: 'soft', color: 'primary',
+      class: 'bg-primary-100 text-primary-900 dark:bg-primary-950/50 dark:text-primary-100' },
+    { variant: 'soft', color: 'secondary',
+      class: 'bg-secondary-100 text-secondary-900 dark:bg-secondary-950/50 dark:text-secondary-100' },
+    { variant: 'soft', color: 'success',
+      class: 'bg-success-100 text-success-900 dark:bg-success-950/50 dark:text-success-100' },
+    { variant: 'soft', color: 'warning',
+      class: 'bg-warning-100 text-warning-900 dark:bg-warning-950/50 dark:text-warning-100' },
+    { variant: 'soft', color: 'danger',
+      class: 'bg-danger-100 text-danger-900 dark:bg-danger-950/50 dark:text-danger-100' },
+    { variant: 'soft', color: 'info',
+      class: 'bg-info-100 text-info-900 dark:bg-info-950/50 dark:text-info-100' },
+    { variant: 'soft', color: 'neutral',
+      class: 'bg-neutral-100 text-neutral-900 dark:bg-neutral-800 dark:text-neutral-100' },
+
+    // ─── solid × color ────────────────────────────────────────────────
+    { variant: 'solid', color: 'primary',
+      class: 'bg-primary-600 text-white dark:bg-primary-500' },
+    { variant: 'solid', color: 'secondary',
+      class: 'bg-secondary-600 text-white dark:bg-secondary-500' },
+    { variant: 'solid', color: 'success',
+      class: 'bg-success-600 text-white dark:bg-success-500' },
+    { variant: 'solid', color: 'warning',
+      class: 'bg-warning-500 text-white dark:bg-warning-600' },
+    { variant: 'solid', color: 'danger',
+      class: 'bg-danger-600 text-white dark:bg-danger-500' },
+    { variant: 'solid', color: 'info',
+      class: 'bg-info-600 text-white dark:bg-info-500' },
+    { variant: 'solid', color: 'neutral',
+      class: 'bg-neutral-900 text-white dark:bg-neutral-100 dark:text-neutral-900' },
+  ],
+
+  defaultVariants: {
+    variant:   'plain',
+    color:     'neutral',
+    elevation: 0,
+    rounded:   'none',
+  },
+});
+
+export type BoxVariants = VariantProps<typeof boxVariants>;

package/src/components/Button/Button.tsx

@@ -109,6 +109,15 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button
     sx
   );
 
+  /*
+   * `aria-busy` announces the loading state to assistive tech.
+   * `disabled` alone hides the reason (perm-denied vs loading vs
+   * intrinsic), so SR users only hear "dimmed/inactive" without
+   * knowing why. Adding `aria-busy={true}` while loading distinguishes
+   * "wait for the action to finish" from "you can't do this".
+   */
+  const ariaBusy = loading ? true : undefined;
+
   // `asChild` renders through Radix Slot: the immediate child element
   // gets the resolved className, no extra Button DOM is emitted.
   if (asChild) {
@@ -118,6 +127,7 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button
         className={classes}
         data-disabled={effectiveDisabled || undefined}
         aria-disabled={effectiveDisabled || undefined}
+        aria-busy={ariaBusy}
       >
         {children}
       </Slot>
@@ -129,6 +139,7 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(function Button
       ref={ref}
       type={rest.type ?? 'button'}
       disabled={effectiveDisabled}
+      aria-busy={ariaBusy}
       className={classes}
       {...rest}
     >

package/src/components/Checkbox/Checkbox.tsx

@@ -193,11 +193,35 @@ export function Checkbox(props: CheckboxProps) {
         ref={registration?.ref as React.Ref<HTMLButtonElement> | undefined}
         className={cn(v.control(), slotProps?.control?.className)}
       >
+        {/*
+         * Radix.Indicator natively mounts only when `data-state` is
+         * `checked` or `indeterminate` — i.e. it tracks Radix's
+         * internal state directly, no React state dependency.
+         *
+         * The previous implementation used `forceMount` + a React
+         * conditional `{resolvedChecked === true ? <CheckIcon /> : null}`,
+         * which broke standalone uncontrolled mode: Radix would flip
+         * its internal `data-state` on click (turning the control blue
+         * via `data-[state=checked]:bg-primary-500`) but the React
+         * snapshot for `resolvedChecked` stayed stale, so the
+         * `<CheckIcon />` never mounted. Result: blue box with no
+         * tick after user interaction.
+         *
+         * Dropping forceMount + the conditional defers the mount
+         * decision to Radix (the single source of truth in all three
+         * modes — controlled, uncontrolled, bridge). Indicator mounts
+         * exactly when the checkbox is checked OR indeterminate.
+         *
+         * Indeterminate caveat: this renders the check glyph for
+         * BOTH checked AND indeterminate states. Previously
+         * indeterminate rendered nothing inside the blue square
+         * (same level of broken). A future improvement would render
+         * a dash for indeterminate — out of scope here.
+         */}
         <RadixCheckbox.Indicator
           className={cn(v.indicator(), slotProps?.indicator?.className)}
-          forceMount
         >
-          {resolvedChecked === true ? <CheckIcon className="h-full w-full" /> : null}
+          <CheckIcon className="h-full w-full" />
         </RadixCheckbox.Indicator>
       </RadixCheckbox.Root>
 

package/src/components/Container/Container.test.tsx

@@ -0,0 +1,209 @@
+// @vitest-environment jsdom
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/react';
+import { Container } from './Container.js';
+
+describe('<Container>', () => {
+  // ─── Default rendering ──────────────────────────────────────────────
+  describe('default rendering', () => {
+    it('renders a <div> by default', () => {
+      const { container } = render(<Container>x</Container>);
+      expect(container.firstElementChild?.tagName).toBe('DIV');
+    });
+
+    it('has mx-auto + w-full baseline', () => {
+      const { container } = render(<Container>x</Container>);
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('mx-auto');
+      expect(cls).toContain('w-full');
+    });
+
+    it('default size is xl (max-w-screen-xl)', () => {
+      const { container } = render(<Container>x</Container>);
+      expect(container.firstElementChild?.className).toContain('max-w-screen-xl');
+    });
+
+    it('default px is true — responsive padding ramp', () => {
+      const { container } = render(<Container>x</Container>);
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('px-4');
+      expect(cls).toContain('sm:px-6');
+      expect(cls).toContain('lg:px-8');
+    });
+
+    it('default centerContent is false — no flex column', () => {
+      const { container } = render(<Container>x</Container>);
+      const cls = container.firstElementChild?.className ?? '';
+      // baseline doesn't include flex
+      expect(cls.split(' ')).not.toContain('flex');
+    });
+  });
+
+  // ─── Size axis ──────────────────────────────────────────────────────
+  describe('size', () => {
+    it('size="sm"', () => {
+      const { container } = render(<Container size="sm">x</Container>);
+      expect(container.firstElementChild?.className).toContain('max-w-screen-sm');
+    });
+
+    it('size="lg"', () => {
+      const { container } = render(<Container size="lg">x</Container>);
+      expect(container.firstElementChild?.className).toContain('max-w-screen-lg');
+    });
+
+    it('size="2xl"', () => {
+      const { container } = render(<Container size="2xl">x</Container>);
+      expect(container.firstElementChild?.className).toContain('max-w-screen-2xl');
+    });
+
+    it('size="fluid" emits no max-w-* class', () => {
+      const { container } = render(<Container size="fluid">x</Container>);
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).not.toContain('max-w-screen');
+      // still mx-auto + w-full baseline
+      expect(cls).toContain('mx-auto');
+    });
+  });
+
+  // ─── Padding axis ───────────────────────────────────────────────────
+  describe('padding', () => {
+    it('px={false} skips the responsive padding ramp', () => {
+      const { container } = render(<Container px={false}>x</Container>);
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).not.toContain('px-4');
+      expect(cls).not.toContain('sm:px-6');
+    });
+  });
+
+  // ─── Center content ─────────────────────────────────────────────────
+  describe('centerContent', () => {
+    it('centerContent turns into flex column items-center', () => {
+      const { container } = render(<Container centerContent>x</Container>);
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('flex');
+      expect(cls).toContain('flex-col');
+      expect(cls).toContain('items-center');
+    });
+  });
+
+  // ─── Override semantics ─────────────────────────────────────────────
+  describe('override', () => {
+    it('sx wins over default size via tailwind-merge', () => {
+      const { container } = render(
+        <Container sx="max-w-3xl">x</Container>,
+      );
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('max-w-3xl');
+      // tailwind-merge collapses the conflicting max-w-screen-xl
+      expect(cls).not.toContain('max-w-screen-xl');
+    });
+
+    it('sx can add vertical padding (Container does not expose it)', () => {
+      const { container } = render(<Container sx="py-12">x</Container>);
+      expect(container.firstElementChild?.className).toContain('py-12');
+    });
+  });
+
+  // ─── Polymorphism ───────────────────────────────────────────────────
+  describe('polymorphism', () => {
+    it('as="main" renders <main> with Container chrome', () => {
+      const { container } = render(<Container as="main">x</Container>);
+      const el = container.firstElementChild;
+      expect(el?.tagName).toBe('MAIN');
+      expect(el?.className).toContain('mx-auto');
+    });
+
+    it('asChild paints onto the child element', () => {
+      const { container } = render(
+        <Container size="lg" asChild>
+          <article>x</article>
+        </Container>,
+      );
+      const el = container.firstElementChild;
+      expect(el?.tagName).toBe('ARTICLE');
+      expect(el?.className).toContain('max-w-screen-lg');
+    });
+
+    it('asChild wins over as when both are passed', () => {
+      const { container } = render(
+        <Container as="main" asChild>
+          <section>x</section>
+        </Container>,
+      );
+      expect(container.firstElementChild?.tagName).toBe('SECTION');
+    });
+  });
+
+  // ─── Pass-through ────────────────────────────────────────────────────
+  describe('pass-through', () => {
+    it('forwards data-* + aria-*', () => {
+      const { container } = render(
+        <Container data-testid="c" aria-label="page">x</Container>,
+      );
+      const el = container.firstElementChild;
+      expect(el?.getAttribute('data-testid')).toBe('c');
+      expect(el?.getAttribute('aria-label')).toBe('page');
+    });
+  });
+
+  // ─── F11-bis edge cases ─────────────────────────────────────────────
+  describe('axis coexistence', () => {
+    it('size + centerContent + px=true (all three combine)', () => {
+      const { container } = render(
+        <Container size="md" centerContent px>x</Container>,
+      );
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('max-w-screen-md');
+      expect(cls).toContain('flex');
+      expect(cls).toContain('flex-col');
+      expect(cls).toContain('items-center');
+      expect(cls).toContain('px-4');
+    });
+
+    it('fluid + centerContent (full-bleed centered hero pattern)', () => {
+      const { container } = render(
+        <Container size="fluid" centerContent>x</Container>,
+      );
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).not.toContain('max-w-screen');
+      expect(cls).toContain('flex-col');
+      expect(cls).toContain('items-center');
+    });
+
+    it('fluid + px=false (full-bleed edge-to-edge — hero image pattern)', () => {
+      const { container } = render(
+        <Container size="fluid" px={false}>x</Container>,
+      );
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).not.toContain('max-w-screen');
+      expect(cls).not.toContain('px-4');
+      // still has mx-auto + w-full baseline
+      expect(cls).toContain('mx-auto');
+    });
+  });
+
+  describe('nested fluid-outer + capped-inner pattern', () => {
+    it('outer fluid colored band + inner capped content renders both', () => {
+      const { container } = render(
+        <Container size="fluid" px={false} sx="bg-primary-50 py-16">
+          <Container size="lg">
+            <p>inner</p>
+          </Container>
+        </Container>,
+      );
+      const outer = container.firstElementChild;
+      const inner = outer?.querySelector('div');
+      expect(outer?.className).toContain('bg-primary-50');
+      expect(outer?.className).not.toContain('max-w-screen');
+      expect(inner?.className).toContain('max-w-screen-lg');
+    });
+  });
+
+  describe('every size value', () => {
+    const SIZES = ['sm', 'md', 'lg', 'xl', '2xl'] as const;
+    it.each(SIZES)('size="%s" emits max-w-screen-%s', (s) => {
+      const { container } = render(<Container size={s}>x</Container>);
+      expect(container.firstElementChild?.className).toContain(`max-w-screen-${s}`);
+    });
+  });
+});