@ds-mo/ui 0.1.0

package/src/components/ButtonGroup/ButtonGroup.stories.tsx

@@ -0,0 +1,384 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import React from 'react';
+import { ButtonGroup } from './ButtonGroup';
+import { Button } from '@/components/Button';
+import type { ButtonContrast, ButtonIntent } from '@/components/Button';
+import type { IconComponent } from '@/types/icons';
+
+const PlaceholderIcon: IconComponent = ({ size = 20 }) => (
+  <svg width={size} height={size} viewBox="0 0 20 20" fill="currentColor">
+    <circle cx="10" cy="10" r="6" />
+  </svg>
+);
+
+interface PlaygroundArgs {
+  variant:   'primary' | 'secondary';
+  elevation: 'elevated' | 'flat' | 'none' | 'floating';
+  intent:    ButtonIntent;
+  contrast:  ButtonContrast;
+  size:      'xs' | 'sm' | 'md' | 'lg';
+  rounded:   boolean;
+  showIcon:  boolean;
+}
+
+const meta: Meta<typeof ButtonGroup> = {
+  title: 'Primitives (Reviewed)/ButtonGroup',
+  component: ButtonGroup,
+  args: {
+    variant:   'primary',
+    elevation: 'elevated',
+    intent:    'brand',
+    contrast:  'bold',
+    size:      'md',
+    rounded:   false,
+    showIcon:  false,
+  } as PlaygroundArgs,
+  argTypes: {
+    variant:   { control: 'select', options: ['primary', 'secondary'] },
+    elevation: { control: 'select', options: ['elevated', 'flat', 'none', 'floating'] },
+    intent:    { control: 'select', options: ['none', 'neutral', 'brand', 'ai', 'negative', 'warning', 'caution', 'positive'] },
+    contrast:  { control: 'select', options: ['strong', 'bold', 'medium', 'faint'] },
+    size:      { control: 'select', options: ['lg', 'md', 'sm', 'xs'] },
+    rounded:   { control: 'boolean' },
+    showIcon:  { control: 'boolean' },
+  } as Record<string, unknown>,
+};
+
+export default meta;
+type Story = StoryObj<typeof ButtonGroup>;
+
+// ─── Shared layout helpers ────────────────────────────────────────────────────
+
+const col: React.CSSProperties = { display: 'flex', flexDirection: 'column', gap: 16, alignItems: 'flex-start' };
+const row: React.CSSProperties = { display: 'flex', gap: 16, alignItems: 'center' };
+const lbl: React.CSSProperties = { fontSize: 10, fontFamily: 'monospace', color: '#888', minWidth: 120, flexShrink: 0 };
+const section = (text: string) => (
+  <div style={{ fontSize: 11, fontWeight: 600, letterSpacing: '0.05em', textTransform: 'uppercase', color: '#555', marginTop: 4 }}>
+    {text}
+  </div>
+);
+const divider = <hr style={{ border: 'none', borderTop: '1px solid #e0e0e0', margin: '4px 0 12px' }} />;
+
+// ─── Playground ──────────────────────────────────────────────────────────────
+
+export const Playground: Story = {
+  render: (args) => {
+    const a = args as unknown as PlaygroundArgs;
+    const labels = ['First', 'Second', 'Third'];
+    return (
+      <ButtonGroup>
+        {labels.map(label => (
+          <Button
+            key={label}
+            variant={a.variant}
+            elevation={a.elevation}
+            intent={a.intent}
+            contrast={a.contrast}
+            size={a.size}
+            rounded={a.rounded}
+            icon={a.showIcon ? PlaceholderIcon : undefined}
+            label={label}
+          />
+        ))}
+      </ButtonGroup>
+    );
+  },
+};
+
+// ─── Matrix ───────────────────────────────────────────────────────────────────
+
+export const Matrix: Story = {
+  parameters: { layout: 'padded' },
+  render: () => (
+    <div style={{ ...col, fontFamily: 'sans-serif', gap: 0 }}>
+
+      {/* ── Variants & elevation ── */}
+      {section('Elevation — full-height vs short divider')}
+      {divider}
+      <div style={col}>
+        <div style={row}>
+          <span style={lbl}>secondary / flat</span>
+          <ButtonGroup>
+            <Button variant="secondary" elevation="flat" label="Day" />
+            <Button variant="secondary" elevation="flat" label="Week" />
+            <Button variant="secondary" elevation="flat" label="Month" />
+          </ButtonGroup>
+        </div>
+        <div style={row}>
+          <span style={lbl}>secondary / elevated</span>
+          <ButtonGroup>
+            <Button variant="secondary" elevation="elevated" label="Day" />
+            <Button variant="secondary" elevation="elevated" label="Week" />
+            <Button variant="secondary" elevation="elevated" label="Month" />
+          </ButtonGroup>
+        </div>
+        <div style={row}>
+          <span style={lbl}>primary / none intent</span>
+          <ButtonGroup>
+            <Button variant="primary" intent="none" label="Day" />
+            <Button variant="primary" intent="none" label="Week" />
+            <Button variant="primary" intent="none" label="Month" />
+          </ButtonGroup>
+        </div>
+        <div style={row}>
+          <span style={lbl}>secondary / none ↓ short</span>
+          <ButtonGroup>
+            <Button variant="secondary" elevation="none" label="Day" />
+            <Button variant="secondary" elevation="none" label="Week" />
+            <Button variant="secondary" elevation="none" label="Month" />
+          </ButtonGroup>
+        </div>
+      </div>
+
+      {/* ── Ghost: short divider at each size ── */}
+      {section('Ghost (elevation=none) — short divider scales with size')}
+      {divider}
+      <div style={col}>
+        {(['lg', 'md', 'sm', 'xs'] as const).map(size => (
+          <div key={size} style={row}>
+            <span style={lbl}>{size}</span>
+            <ButtonGroup>
+              <Button variant="secondary" elevation="none" size={size} label="One" />
+              <Button variant="secondary" elevation="none" size={size} label="Two" />
+              <Button variant="secondary" elevation="none" size={size} label="Three" />
+            </ButtonGroup>
+          </div>
+        ))}
+      </div>
+
+      {/* ── Primary intents ── */}
+      {section('Primary — homogeneous intent + contrast (on-bg divider)')}
+      {divider}
+      <div style={col}>
+        {([
+          { intent: 'brand',    contrast: 'bold'   },
+          { intent: 'negative', contrast: 'bold'   },
+          { intent: 'positive', contrast: 'bold'   },
+          { intent: 'brand',    contrast: 'medium' },
+          { intent: 'brand',    contrast: 'faint'  },
+        ] as { intent: ButtonIntent; contrast: ButtonContrast }[]).map(({ intent, contrast }) => (
+          <div key={`${intent}-${contrast}`} style={row}>
+            <span style={lbl}>{intent} / {contrast}</span>
+            <ButtonGroup>
+              <Button variant="primary" intent={intent} contrast={contrast} label="Save" />
+              <Button variant="primary" intent={intent} contrast={contrast} label="Copy" />
+              <Button variant="primary" intent={intent} contrast={contrast} label="Export" />
+            </ButtonGroup>
+          </div>
+        ))}
+      </div>
+
+      {/* ── Sizes ── */}
+      {section('Sizes — secondary / flat')}
+      {divider}
+      <div style={col}>
+        {(['lg', 'md', 'sm', 'xs'] as const).map(size => (
+          <div key={size} style={row}>
+            <span style={lbl}>{size}</span>
+            <ButtonGroup>
+              <Button variant="secondary" size={size} label="One" />
+              <Button variant="secondary" size={size} label="Two" />
+              <Button variant="secondary" size={size} label="Three" />
+            </ButtonGroup>
+          </div>
+        ))}
+      </div>
+
+      {/* ── With Icons ── */}
+      {section('With Icons')}
+      {divider}
+      <div style={col}>
+        <div style={row}>
+          <span style={lbl}>icon + label</span>
+          <ButtonGroup>
+            <Button variant="secondary" icon={PlaceholderIcon} label="Grid" />
+            <Button variant="secondary" icon={PlaceholderIcon} label="List" />
+            <Button variant="secondary" icon={PlaceholderIcon} label="Table" />
+          </ButtonGroup>
+        </div>
+        <div style={row}>
+          <span style={lbl}>icon only</span>
+          <ButtonGroup>
+            <Button variant="secondary" icon={PlaceholderIcon} aria-label="Grid" />
+            <Button variant="secondary" icon={PlaceholderIcon} aria-label="List" />
+            <Button variant="secondary" icon={PlaceholderIcon} aria-label="Table" />
+          </ButtonGroup>
+        </div>
+        <div style={row}>
+          <span style={lbl}>ghost icon</span>
+          <ButtonGroup>
+            <Button variant="secondary" elevation="none" icon={PlaceholderIcon} aria-label="Grid" />
+            <Button variant="secondary" elevation="none" icon={PlaceholderIcon} aria-label="List" />
+            <Button variant="secondary" elevation="none" icon={PlaceholderIcon} aria-label="Table" />
+          </ButtonGroup>
+        </div>
+      </div>
+
+      {/* ── Rounded ── */}
+      {section('Rounded — outer pill padding, inner base padding')}
+      {divider}
+      <div style={col}>
+        <div style={row}>
+          <span style={lbl}>secondary / flat</span>
+          <ButtonGroup>
+            <Button variant="secondary" label="Day" rounded />
+            <Button variant="secondary" label="Week" rounded />
+            <Button variant="secondary" label="Month" rounded />
+          </ButtonGroup>
+        </div>
+        <div style={row}>
+          <span style={lbl}>ghost</span>
+          <ButtonGroup>
+            <Button variant="secondary" elevation="none" label="Day" rounded />
+            <Button variant="secondary" elevation="none" label="Week" rounded />
+            <Button variant="secondary" elevation="none" label="Month" rounded />
+          </ButtonGroup>
+        </div>
+        <div style={row}>
+          <span style={lbl}>icon + label</span>
+          <ButtonGroup>
+            <Button variant="secondary" icon={PlaceholderIcon} label="Grid" rounded />
+            <Button variant="secondary" icon={PlaceholderIcon} label="List" rounded />
+            <Button variant="secondary" icon={PlaceholderIcon} label="Table" rounded />
+          </ButtonGroup>
+        </div>
+        <div style={row}>
+          <span style={lbl}>icon only</span>
+          <ButtonGroup>
+            <Button variant="secondary" icon={PlaceholderIcon} rounded aria-label="Grid" />
+            <Button variant="secondary" icon={PlaceholderIcon} rounded aria-label="List" />
+            <Button variant="secondary" icon={PlaceholderIcon} rounded aria-label="Table" />
+          </ButtonGroup>
+        </div>
+        {(['lg', 'md', 'sm'] as const).map(size => (
+          <div key={size} style={row}>
+            <span style={lbl}>rounded {size}</span>
+            <ButtonGroup>
+              <Button variant="secondary" size={size} label="One" rounded />
+              <Button variant="secondary" size={size} label="Two" rounded />
+              <Button variant="secondary" size={size} label="Three" rounded />
+            </ButtonGroup>
+          </div>
+        ))}
+      </div>
+
+      {/* ── States ── */}
+      {section('States')}
+      {divider}
+      <div style={col}>
+        <div style={row}>
+          <span style={lbl}>with inactive</span>
+          <ButtonGroup>
+            <Button variant="secondary" label="One" />
+            <Button variant="secondary" label="Two" inactive />
+            <Button variant="secondary" label="Three" />
+          </ButtonGroup>
+        </div>
+        <div style={row}>
+          <span style={lbl}>two items</span>
+          <ButtonGroup>
+            <Button variant="secondary" label="Left" />
+            <Button variant="secondary" label="Right" />
+          </ButtonGroup>
+        </div>
+      </div>
+
+    </div>
+  ),
+};
+
+// ─── Individual stories ───────────────────────────────────────────────────────
+
+export const Secondary: Story = {
+  render: () => (
+    <ButtonGroup>
+      <Button variant="secondary" label="Day" />
+      <Button variant="secondary" label="Week" />
+      <Button variant="secondary" label="Month" />
+    </ButtonGroup>
+  ),
+};
+
+export const Ghost: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 12, alignItems: 'flex-start' }}>
+      {(['lg', 'md', 'sm', 'xs'] as const).map(size => (
+        <ButtonGroup key={size}>
+          <Button variant="secondary" elevation="none" size={size} label="Grid" />
+          <Button variant="secondary" elevation="none" size={size} label="List" />
+          <Button variant="secondary" elevation="none" size={size} label="Table" />
+        </ButtonGroup>
+      ))}
+    </div>
+  ),
+};
+
+export const PrimaryIntents: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 12, alignItems: 'flex-start' }}>
+      <ButtonGroup>
+        <Button variant="primary" intent="brand" label="Save" />
+        <Button variant="primary" intent="brand" label="Duplicate" />
+        <Button variant="primary" intent="brand" label="Export" />
+      </ButtonGroup>
+      <ButtonGroup>
+        <Button variant="primary" intent="negative" label="Delete" />
+        <Button variant="primary" intent="negative" label="Archive" />
+      </ButtonGroup>
+      <ButtonGroup>
+        <Button variant="primary" intent="brand" contrast="medium" label="Save" />
+        <Button variant="primary" intent="brand" contrast="medium" label="Duplicate" />
+        <Button variant="primary" intent="brand" contrast="medium" label="Export" />
+      </ButtonGroup>
+      <ButtonGroup>
+        <Button variant="primary" intent="brand" contrast="faint" label="Save" />
+        <Button variant="primary" intent="brand" contrast="faint" label="Duplicate" />
+        <Button variant="primary" intent="brand" contrast="faint" label="Export" />
+      </ButtonGroup>
+    </div>
+  ),
+};
+
+export const Rounded: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 12, alignItems: 'flex-start' }}>
+      <ButtonGroup>
+        <Button variant="secondary" label="Day" rounded />
+        <Button variant="secondary" label="Week" rounded />
+        <Button variant="secondary" label="Month" rounded />
+      </ButtonGroup>
+      <ButtonGroup>
+        <Button variant="secondary" elevation="none" label="Day" rounded />
+        <Button variant="secondary" elevation="none" label="Week" rounded />
+        <Button variant="secondary" elevation="none" label="Month" rounded />
+      </ButtonGroup>
+      <ButtonGroup>
+        <Button variant="secondary" icon={PlaceholderIcon} label="Grid" rounded />
+        <Button variant="secondary" icon={PlaceholderIcon} label="List" rounded />
+        <Button variant="secondary" icon={PlaceholderIcon} label="Table" rounded />
+      </ButtonGroup>
+      <ButtonGroup>
+        <Button variant="secondary" icon={PlaceholderIcon} rounded aria-label="Grid" />
+        <Button variant="secondary" icon={PlaceholderIcon} rounded aria-label="List" />
+        <Button variant="secondary" icon={PlaceholderIcon} rounded aria-label="Table" />
+      </ButtonGroup>
+    </div>
+  ),
+};
+
+export const IconOnly: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 12, alignItems: 'flex-start' }}>
+      <ButtonGroup>
+        <Button variant="secondary" icon={PlaceholderIcon} aria-label="Grid view" />
+        <Button variant="secondary" icon={PlaceholderIcon} aria-label="List view" />
+        <Button variant="secondary" icon={PlaceholderIcon} aria-label="Table view" />
+      </ButtonGroup>
+      <ButtonGroup>
+        <Button variant="secondary" elevation="none" icon={PlaceholderIcon} aria-label="Grid view" />
+        <Button variant="secondary" elevation="none" icon={PlaceholderIcon} aria-label="List view" />
+        <Button variant="secondary" elevation="none" icon={PlaceholderIcon} aria-label="Table view" />
+      </ButtonGroup>
+    </div>
+  ),
+};

package/src/components/ButtonGroup/ButtonGroup.tsx

@@ -0,0 +1,122 @@
+import React from 'react';
+import { cn } from '@/utils/cn';
+import styles from './ButtonGroup.module.css';
+
+export interface ButtonGroupProps {
+  children: React.ReactNode;
+  className?: string;
+}
+
+/**
+ * Renders Button children flush side-by-side with a 1px divider between them.
+ * Outer corners keep the button's own border-radius; inner corners are flattened.
+ *
+ * Individual button chrome (shadow/border) is suppressed — the group container
+ * carries the elevation so it wraps the whole control as one visual unit.
+ *
+ * Divider behaviour by variant:
+ *   secondary / primary+none — full-height color-border-tertiary line
+ *   primary (with intent)    — color-border-tertiary-on-{contrast}-background
+ *   ghost (secondary+none)   — short centred line (icon/text height)
+ *
+ * Rounded groups: outer edges keep pill padding; inner edges revert to base padding.
+ * Mix of intents is only valid when variant="secondary"; primary groups must be
+ * homogeneous (same intent + contrast on all items).
+ */
+export const ButtonGroup = ({ children, className }: ButtonGroupProps) => {
+  const items = React.Children.toArray(children).filter(React.isValidElement);
+  const count = items.length;
+
+  // Read elevation + rounded from first child to drive the group container style.
+  const firstEl    = items[0] as React.ReactElement<Record<string, unknown>> | undefined;
+  const firstProps = firstEl?.props as { variant?: string; elevation?: string; rounded?: boolean } | undefined;
+  const firstVariant    = firstProps?.variant ?? 'secondary';
+  const firstElevation  = firstProps?.elevation ?? (firstVariant === 'primary' ? 'none' : 'flat');
+  const groupRounded    = !!firstProps?.rounded;
+  const groupElevKey    = firstElevation.charAt(0).toUpperCase() + firstElevation.slice(1);
+
+  return (
+    <div
+      className={cn(
+        styles.group,
+        (styles as Record<string, string>)[`group${groupElevKey}`],
+        groupRounded && styles.groupRounded,
+        className,
+      )}
+      role="group"
+    >
+      {items.map((child, i) => {
+        const el = child as React.ReactElement<Record<string, unknown>>;
+        const p = el.props as {
+          className?: string;
+          variant?: string;
+          elevation?: string;
+          size?: string;
+          intent?: string;
+          contrast?: string;
+          rounded?: boolean;
+          icon?: unknown;
+          label?: unknown;
+        };
+
+        const isFirst = i === 0;
+        const isLast  = i === count - 1;
+        const isMid   = !isFirst && !isLast;
+
+        const variant    = p.variant  ?? 'secondary';
+        const size       = (p.size    ?? 'md') as 'xs' | 'sm' | 'md' | 'lg';
+        const contrast   = p.contrast ?? 'bold';
+        const intent     = p.intent   ?? 'brand';
+        const isRounded  = !!p.rounded;
+        const isIconOnly = !!p.icon && !p.label;
+        // Ghost: secondary button with elevation='none' (replaces old tertiary variant)
+        const isGhost    = variant === 'secondary' && (p.elevation ?? 'flat') === 'none';
+        const isPrimary  = variant === 'primary' && intent !== 'none';
+
+        // Contrast class suffix — capitalised first letter
+        const contrastKey = contrast.charAt(0).toUpperCase() + contrast.slice(1);
+
+        // Size suffix for rounded padding correction — uppercase
+        // XS rounded has no extra padding in Button so needs no correction
+        const sizeKey = size.toUpperCase() as 'MD' | 'SM' | 'LG' | 'XS';
+        const needsRoundedCorrection = isRounded && !isIconOnly && size !== 'xs';
+
+        // Divider injected as a separate element so it's never affected by
+        // the adjacent button's opacity (e.g. disabled state).
+        const dividerClasses = cn(
+          styles.divider,
+          isGhost && styles.dividerGhost,
+          isGhost && size === 'xs' && styles.dividerGhostXS,
+          isGhost && size === 'sm' && styles.dividerGhostSM,
+          isGhost && size === 'lg' && styles.dividerGhostLG,
+          isPrimary && (styles as Record<string, string>)[`divider${contrastKey}`],
+        );
+
+        return (
+          <React.Fragment key={i}>
+            {i > 0 && <div className={dividerClasses} aria-hidden="true" />}
+            {React.cloneElement(el, {
+              className: cn(
+                p.className,
+                styles.item,
+                isFirst && styles.first,
+                isLast  && styles.last,
+                isMid   && styles.middle,
+
+                // Ghost (secondary+elevation=none): ::after overlay gets 4px radius treatment
+                isGhost && styles.itemShort,
+
+                // Rounded: revert inner-edge padding to base (non-pill) value
+                needsRoundedCorrection && isFirst && (styles as Record<string, string>)[`roundedFirst${sizeKey}`],
+                needsRoundedCorrection && isLast  && (styles as Record<string, string>)[`roundedLast${sizeKey}`],
+                needsRoundedCorrection && isMid   && (styles as Record<string, string>)[`roundedMid${sizeKey}`],
+              ),
+            })}
+          </React.Fragment>
+        );
+      })}
+    </div>
+  );
+};
+
+ButtonGroup.displayName = 'ButtonGroup';

package/src/components/ButtonGroup/index.ts

@@ -0,0 +1,2 @@
+export { ButtonGroup } from './ButtonGroup';
+export type { ButtonGroupProps } from './ButtonGroup';

package/src/components/Card/Card.module.css

@@ -0,0 +1,36 @@
+/**
+ * Card — structured container with optional header/footer.
+ * Uses TokoMo tokens directly (not built on Surface).
+ */
+
+.card {
+  box-sizing: border-box;
+  background-color: var(--color-background-primary);
+  overflow: hidden;
+}
+
+/* Elevation */
+.elevationFlat { box-shadow: var(--effect-elevation-elevated-none); }
+.elevationElevated { box-shadow: var(--effect-elevation-elevated-sm); }
+.elevationFloating { box-shadow: var(--effect-elevation-elevated-floating); }
+
+/* Radius */
+.radiusSm { border-radius: var(--dimension-radius-075); }
+.radiusMd { border-radius: var(--dimension-radius-100); }
+.radiusLg { border-radius: var(--dimension-radius-125); }
+.radiusXl { border-radius: var(--dimension-radius-175); }
+
+/* Sections */
+.header {
+  padding: var(--dimension-space-150) var(--dimension-space-200);
+  border-bottom: var(--dimension-stroke-width-015) solid var(--color-border-primary);
+}
+
+.body {
+  padding: var(--dimension-space-200);
+}
+
+.footer {
+  padding: var(--dimension-space-150) var(--dimension-space-200);
+  border-top: var(--dimension-stroke-width-015) solid var(--color-border-primary);
+}

package/src/components/Card/Card.stories.tsx

@@ -0,0 +1,78 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Card } from './Card';
+
+const meta: Meta<typeof Card> = {
+  title: 'Components/Card',
+  component: Card,
+  argTypes: {
+    elevation: {
+      control: 'select',
+      options: ['flat', 'elevated', 'floating'],
+    },
+    radius: {
+      control: 'select',
+      options: ['sm', 'md', 'lg', 'xl'],
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Card>;
+
+export const Default: Story = {
+  args: {
+    children: 'Card body content goes here.',
+    style: { width: 360 },
+  },
+};
+
+export const WithHeader: Story = {
+  args: {
+    header: <strong>Account Settings</strong>,
+    children: 'Form fields and content go here.',
+    style: { width: 360 },
+  },
+};
+
+export const WithHeaderAndFooter: Story = {
+  args: {
+    header: <strong>Edit Profile</strong>,
+    children: (
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 12 }}>
+        <div>Name: Zain Adeel</div>
+        <div>Email: zain@example.com</div>
+      </div>
+    ),
+    footer: (
+      <div style={{ display: 'flex', justifyContent: 'flex-end', gap: 8 }}>
+        <button>Cancel</button>
+        <button>Save</button>
+      </div>
+    ),
+    style: { width: 360 },
+  },
+};
+
+export const Elevations: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: 24, padding: 24 }}>
+      {(['flat', 'elevated', 'floating'] as const).map(elevation => (
+        <Card key={elevation} elevation={elevation} style={{ width: 200 }}>
+          {elevation}
+        </Card>
+      ))}
+    </div>
+  ),
+};
+
+export const Radii: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: 24, padding: 24 }}>
+      {(['sm', 'md', 'lg', 'xl'] as const).map(radius => (
+        <Card key={radius} radius={radius} style={{ width: 160 }}>
+          radius: {radius}
+        </Card>
+      ))}
+    </div>
+  ),
+};

package/src/components/Card/Card.tsx

@@ -0,0 +1,53 @@
+import React, { forwardRef } from 'react';
+import styles from './Card.module.css';
+import { cn } from '@/utils/cn';
+
+export type CardElevation = 'flat' | 'elevated' | 'floating';
+export type CardRadius = 'sm' | 'md' | 'lg' | 'xl';
+
+export interface CardProps {
+  children: React.ReactNode;
+  /** Optional header content — rendered with a bottom divider. */
+  header?: React.ReactNode;
+  /** Optional footer content — rendered with a top divider. */
+  footer?: React.ReactNode;
+  /** Elevation level. Defaults to 'elevated'. */
+  elevation?: CardElevation;
+  /** Corner radius. Defaults to 'lg'. */
+  radius?: CardRadius;
+  /** Additional CSS classes. */
+  className?: string;
+  /** Inline styles. */
+  style?: React.CSSProperties;
+}
+
+const elevationClassMap: Record<CardElevation, string> = {
+  flat: styles.elevationFlat,
+  elevated: styles.elevationElevated,
+  floating: styles.elevationFloating,
+};
+
+const radiusClassMap: Record<CardRadius, string> = {
+  sm: styles.radiusSm,
+  md: styles.radiusMd,
+  lg: styles.radiusLg,
+  xl: styles.radiusXl,
+};
+
+export const Card = forwardRef<HTMLDivElement, CardProps>(
+  ({ children, header, footer, elevation = 'elevated', radius = 'lg', className, style }, ref) => {
+    return (
+      <div
+        ref={ref}
+        className={cn(styles.card, elevationClassMap[elevation], radiusClassMap[radius], className)}
+        style={style}
+      >
+        {header && <div className={styles.header}>{header}</div>}
+        <div className={styles.body}>{children}</div>
+        {footer && <div className={styles.footer}>{footer}</div>}
+      </div>
+    );
+  }
+);
+
+Card.displayName = 'Card';