@dashforge/tw 0.1.0-beta → 0.2.0-beta

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/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}`);
+    });
+  });
+});

package/src/components/Container/Container.tsx

@@ -0,0 +1,74 @@
+import { forwardRef, type ElementType, type ReactElement } from 'react';
+import { Slot } from '@radix-ui/react-slot';
+import { cn } from '../../utils/cn.js';
+import { containerVariants } from './container.variants.js';
+import type { ContainerProps } from './container.types.js';
+
+/**
+ * `<Container>` — centered max-width wrapper for page-level layouts.
+ *
+ * The pattern is universal: every page-root `<div>` in a non-trivial
+ * web app boils down to "mx-auto + max-w-X + responsive horizontal
+ * padding". Container collapses that into a typed prop set so the
+ * decision lives in ONE place per app section (the Container size),
+ * not scattered as utility chains across every page file.
+ *
+ * Default size is `'xl'` (1280px) — comfortable for full app shells
+ * with a left nav + main + optional right rail. Drop to `'lg'` (1024px)
+ * for content-heavy docs/marketing, jump to `'2xl'` (1536px) for wide
+ * dashboards.
+ *
+ * Composition pattern — Container at the page root, Stack/Grid inside:
+ *
+ *   <Container size="lg" as="main">
+ *     <Stack gap={8}>
+ *       <Typography variant="h1">Page title</Typography>
+ *       <Grid container spacing={6}>
+ *         <Grid xs={12} md={6}>...</Grid>
+ *       </Grid>
+ *     </Stack>
+ *   </Container>
+ *
+ * Container handles the page chrome (centered, padded, capped width);
+ * Stack/Grid handle the actual layout of children. Two concerns, two
+ * primitives.
+ *
+ * Polymorphism rule (same as Typography/Box/Stack/Grid): when both
+ * `as` and `asChild` are passed, `asChild` wins.
+ */
+export const Container = forwardRef<HTMLElement, ContainerProps>(
+  function Container(props, ref) {
+    const {
+      size,
+      px,
+      centerContent,
+      as,
+      asChild = false,
+      sx,
+      children,
+      ...rest
+    } = props;
+
+    const classes = cn(
+      containerVariants({ size, px, centerContent }),
+      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>
+    );
+  },
+);
+
+Container.displayName = 'Container';

package/src/components/Container/container.types.ts

@@ -0,0 +1,45 @@
+import type { ElementType, HTMLAttributes } from 'react';
+import type { ContainerVariants } from './container.variants.js';
+
+/**
+ * Props for `<Container>` — page-level centered max-width wrapper.
+ *
+ * Use at the page-root level (or section-root) to constrain content
+ * width and apply the canonical responsive horizontal padding ramp.
+ * Compose Stack/Grid INSIDE Container for the actual layout work.
+ *
+ * Native attribute overrides:
+ *   • `className` omitted in favour of `sx` (utility string, merged
+ *     via tailwind-merge — same convention as Box/Stack/Grid/Typography).
+ */
+export interface ContainerProps
+  extends Omit<HTMLAttributes<HTMLDivElement>, 'className'>,
+          Pick<ContainerVariants, 'size' | 'px' | 'centerContent'> {
+  /**
+   * Override the rendered HTML tag. Defaults to `'div'`. Use
+   * `as="main"` for the primary content region of a page,
+   * `as="section"` for a named section, `as="article"` for a
+   * self-contained article shell.
+   *
+   * Ignored when `asChild` is true.
+   */
+  as?: ElementType;
+
+  /**
+   * Render via Radix `Slot` — the Container styles paint onto the
+   * single React child instead of wrapping it. Useful for letting a
+   * router `<main>` element receive the Container chrome without
+   * adding an intermediate `<div>` in the tree.
+   *
+   * Mutually exclusive with `as` (when both are passed, `asChild` wins).
+   */
+  asChild?: boolean;
+
+  /**
+   * Utility classes appended to the variant chain. Resolved via
+   * `tailwind-merge` so the consumer's classes always win over the
+   * variant defaults — useful for one-off vertical padding (`sx="py-8"`),
+   * custom max-width (`sx="max-w-3xl"`), etc.
+   */
+  sx?: string;
+}

package/src/components/Container/container.variants.ts

@@ -0,0 +1,81 @@
+import { tv, type VariantProps } from 'tailwind-variants';
+
+/**
+ * `containerVariants` — centered max-width wrapper for page layouts.
+ *
+ * Architectural role:
+ *
+ *   Every web app has the same pattern at the page-root level: a div
+ *   that's `mx-auto`, capped at some `max-w-*`, with responsive
+ *   horizontal padding. Without Container, every page rewrites:
+ *
+ *     <div className="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8">
+ *
+ *   Container collapses that into one typed prop set, with size names
+ *   that mirror Tailwind's breakpoint vocabulary so the muscle memory
+ *   carries over (`size="lg"` ↔ `max-w-screen-lg`).
+ *
+ * Size axis — maps to Tailwind's `max-w-screen-*` aliases:
+ *   • sm     → max-w-screen-sm     (640px)
+ *   • md     → max-w-screen-md     (768px)
+ *   • lg     → max-w-screen-lg     (1024px) — most common doc/content cap
+ *   • xl     → max-w-screen-xl     (1280px) — default; comfortable for full apps
+ *   • 2xl    → max-w-screen-2xl    (1536px) — wide dashboards
+ *   • fluid  → no max-width at all (full bleed, padding still applies)
+ *
+ * Padding axis (`px`):
+ *   • true (default) — responsive horizontal padding (px-4 sm:px-6 lg:px-8)
+ *     The canonical Tailwind responsive padding ramp. Designed to keep
+ *     edges from kissing the viewport on mobile and breathing more on
+ *     larger screens.
+ *   • false — no padding. Use when the consumer wants full bleed AND
+ *     handles edge padding inside (e.g. a hero section with its own
+ *     internal spacing scale).
+ *
+ * Center content axis (`centerContent`):
+ *   • true  — turns the Container into a flex column with items-center
+ *     so the page content stacks centered horizontally. Common for
+ *     marketing pages, sign-in flows, "single artifact" layouts.
+ *   • false (default) — children flow normally (block stacking).
+ */
+export const containerVariants = tv({
+  base: 'mx-auto w-full',
+
+  variants: {
+    size: {
+      sm:    'max-w-screen-sm',
+      md:    'max-w-screen-md',
+      lg:    'max-w-screen-lg',
+      xl:    'max-w-screen-xl',
+      '2xl': 'max-w-screen-2xl',
+      fluid: '',
+    },
+
+    /*
+     * Responsive padding ramp. `false` skips it entirely so the
+     * consumer can supply custom padding via `sx` when needed.
+     */
+    px: {
+      true:  'px-4 sm:px-6 lg:px-8',
+      false: '',
+    },
+
+    /*
+     * Stacks children centered. Mutually compatible with all sizes —
+     * a fluid container with centerContent is the canonical "marketing
+     * hero" layout.
+     */
+    centerContent: {
+      true:  'flex flex-col items-center',
+      false: '',
+    },
+  },
+
+  defaultVariants: {
+    size: 'xl',
+    px: true,
+    centerContent: false,
+  },
+});
+
+export type ContainerVariants = VariantProps<typeof containerVariants>;