@syscore/ui-library 1.25.0 → 2.0.0

package/client/ui/Layout.stories.tsx

@@ -0,0 +1,1481 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Stack, Grid, Columns, Container, Section, AppShell, AppShellHeader, AppShellSidebar, AppShellMain, Show, Hide, Positioned, Spacer } from "../components/ui/layout";
+import { Card, CardHeader, CardTitle, CardContent } from "../components/ui/card";
+import { Button } from "../components/ui/button";
+import { Text } from "../components/ui/typography";
+import { Badge } from "../components/ui/badge";
+
+const meta = {
+  title: "Layout/Primitives",
+  component: Stack,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component: [
+          "Layout primitives that replace raw `<div>` wrappers. No `className` needed — intent is prop-driven.",
+          "",
+          "---",
+          "",
+          "## Why layout components?",
+          "",
+          "Raw divs with Tailwind work fine on day one. Six weeks later, no one knows what this means:",
+          "",
+          "```tsx",
+          "// ❌ What is this? A row? A column? Why flex-wrap?",
+          `<div className="flex flex-col gap-4 items-start justify-between flex-wrap">`,
+          `  <div className="grid grid-cols-3 gap-6 w-full max-w-5xl mx-auto px-4">`,
+          "    …",
+          "  </div>",
+          "</div>",
+          "```",
+          "",
+          "With layout components, the code reads like what it **is**:",
+          "",
+          "```tsx",
+          "// ✅ Reads like a layout description",
+          "<Stack gap={4} align=\"start\" justify=\"between\" wrap>",
+          "  <Grid cols={3} gap={6}>",
+          "    …",
+          "  </Grid>",
+          "</Stack>",
+          "```",
+          "",
+          "---",
+          "",
+          "## Import",
+          "",
+          "```tsx",
+          `import {`,
+          `  Stack, Grid, Columns, Container, Section,`,
+          `  AppShell, AppShellHeader, AppShellSidebar, AppShellMain, AppShellFooter,`,
+          `  Show, Hide, Positioned, Spacer,`,
+          `} from "@syscore/ui-library"`,
+          "```",
+          "",
+          "---",
+          "",
+          "## Which component do I reach for?",
+          "",
+          "| Situation | Use |",
+          "|-----------|-----|",
+          "| Vertical list of items | `Stack` |",
+          "| Horizontal row of items | `Stack direction=\"horizontal\"` |",
+          "| Equal-width grid of cards | `Grid` |",
+          "| Sidebar + content (different widths) | `Columns` |",
+          "| Center content with max-width | `Container` |",
+          "| Vertical padding between page sections | `Section` |",
+          "| Full app frame (header + sidebar + main) | `AppShell` |",
+          "| Show or hide at a breakpoint | `Show` / `Hide` |",
+          "| Pin a badge or overlay to a parent | `Positioned` |",
+          "| Fixed whitespace gap | `Spacer` |",
+          "",
+          "---",
+          "",
+          "## Grid vs Columns — the most important decision",
+          "",
+          "This is where most confusion happens:",
+          "",
+          "```tsx",
+          "// ❌ Wrong: both columns are equal (50 / 50)",
+          "<Grid cols={2}>",
+          "  <Sidebar />   {/* 50% wide — too wide */}",
+          "  <Main />      {/* 50% wide — too narrow */}",
+          "</Grid>",
+          "",
+          "// ✅ Right: sidebar is fixed, content is fluid",
+          `<Columns preset="sidebar">   {/* 280px fixed | 1fr fluid */}`,
+          "  <Sidebar />",
+          "  <Main />",
+          "</Columns>",
+          "```",
+          "",
+          "> **Rule:** Equal widths → `Grid`. Different widths → `Columns`.",
+        ].join("\n"),
+      },
+      source: { type: "code" },
+    },
+  },
+} satisfies Meta<typeof Stack>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// Demo box — only used for visual presentation inside Storybook canvas
+const Box = ({ label, tall }: { label?: string; tall?: boolean }) => (
+  <div
+    style={{ minHeight: tall ? 96 : 56 }}
+    className="flex items-center justify-center rounded-lg border border-dashed border-cyan-400 bg-cyan-50 text-cyan-800 text-sm font-medium"
+  >
+    {label ?? "Item"}
+  </div>
+);
+
+// ---------------------------------------------------------------------------
+// Stack
+// ---------------------------------------------------------------------------
+
+export const StackVertical: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: [
+          "**Stack** is the workhorse of layout. Use it whenever items need to be arranged in a line — vertical or horizontal — with consistent spacing between them.",
+          "",
+          "**The problem:**",
+          "```tsx",
+          "// ❌ Hard to scan at a glance — is this a row or column? What's the gap?",
+          `<div className="flex flex-col gap-6 items-center justify-between">`,
+          "  …",
+          "</div>",
+          "```",
+          "",
+          "**The solution:**",
+          "```tsx",
+          "// ✅ Intent is obvious",
+          `<Stack direction="vertical" gap={6} align="center" justify="between">`,
+          "  …",
+          "</Stack>",
+          "```",
+          "",
+          "**Key props:**",
+          "",
+          "| Prop | Values | Default | Effect |",
+          "|------|--------|---------|--------|",
+          "| `direction` | `\"vertical\"` \\| `\"horizontal\"` | `\"vertical\"` | Column vs row |",
+          "| `gap` | number (Tailwind scale) | `4` (1rem) | Space between items |",
+          "| `align` | `\"start\"` \\| `\"center\"` \\| `\"end\"` \\| `\"stretch\"` \\| `\"baseline\"` | — | Cross-axis alignment |",
+          "| `justify` | `\"start\"` \\| `\"center\"` \\| `\"end\"` \\| `\"between\"` \\| `\"around\"` \\| `\"evenly\"` | — | Main-axis distribution |",
+          "| `wrap` | `boolean` | `false` | Allow items to wrap to the next line |",
+          "| `as` | HTML tag | `\"div\"` | Render as `nav`, `ul`, `header`, etc. |",
+          "",
+          "**Gap scale:** `gap={4}` = 1rem (16px). Follows Tailwind: 1 unit = 4px. So `gap={6}` = 1.5rem, `gap={8}` = 2rem.",
+          "",
+          "**Common mistake:** Using Stack for sidebar + content layouts. Stack gives equal space to all children. If you need a fixed-width sidebar next to fluid content, use `Columns` instead.",
+        ].join("\n"),
+      },
+      source: {
+        code: `import { Stack } from "@syscore/ui-library"
+
+<Stack gap={4}>
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+</Stack>`,
+      },
+    },
+  },
+  render: () => (
+    <Stack gap={4} className="max-w-sm w-full">
+      <Box label="Item 1" />
+      <Box label="Item 2" />
+      <Box label="Item 3" />
+    </Stack>
+  ),
+};
+
+export const StackHorizontal: Story = {
+  parameters: {
+    docs: {
+      source: {
+        code: `import { Stack } from "@syscore/ui-library"
+
+<Stack direction="horizontal" gap={4} align="center">
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+</Stack>`,
+      },
+    },
+  },
+  render: () => (
+    <Stack direction="horizontal" gap={4} align="center">
+      <Box label="Item 1" />
+      <Box label="Item 2" />
+      <Box label="Item 3" />
+    </Stack>
+  ),
+};
+
+export const StackSpaceBetween: Story = {
+  parameters: {
+    docs: {
+      source: {
+        code: `import { Stack } from "@syscore/ui-library"
+import { Button, Text } from "@syscore/ui-library"
+
+<Stack direction="horizontal" justify="between" align="center">
+  <Text variant="heading-xxsmall">Page Title</Text>
+  <Stack direction="horizontal" gap={2}>
+    <Button variant="secondary-light" size="large">Cancel</Button>
+    <Button variant="primary-dark" size="large">Save</Button>
+  </Stack>
+</Stack>`,
+      },
+    },
+  },
+  render: () => (
+    <Stack direction="horizontal" justify="between" align="center" className="w-full max-w-2xl border rounded-xl p-4">
+      <Text variant="heading-xxsmall">Page Title</Text>
+      <Stack direction="horizontal" gap={2}>
+        <Button variant="secondary-light" size="large">Cancel</Button>
+        <Button variant="primary-dark" size="large">Save</Button>
+      </Stack>
+    </Stack>
+  ),
+};
+
+export const StackWrap: Story = {
+  parameters: {
+    docs: {
+      source: {
+        code: `import { Stack } from "@syscore/ui-library"
+import { Badge } from "@syscore/ui-library"
+
+<Stack direction="horizontal" gap={3} wrap>
+  <Badge>Design</Badge>
+  <Badge>Engineering</Badge>
+  <Badge>Product</Badge>
+</Stack>`,
+      },
+    },
+  },
+  render: () => (
+    <Stack direction="horizontal" gap={3} wrap className="max-w-md">
+      {["Design", "Engineering", "Product", "Marketing", "Research", "Data"].map((tag) => (
+        <Badge key={tag}>{tag}</Badge>
+      ))}
+    </Stack>
+  ),
+};
+
+export const StackForm: Story = {
+  name: "Stack — form layout",
+  parameters: {
+    docs: {
+      source: {
+        code: `import { Stack } from "@syscore/ui-library"
+import { Card, CardHeader, CardTitle, CardContent } from "@syscore/ui-library"
+import { Button, Text, Input, Textarea } from "@syscore/ui-library"
+
+<Card>
+  <CardHeader>
+    <CardTitle>Create project</CardTitle>
+  </CardHeader>
+  <CardContent>
+    <Stack gap={6}>
+      <Stack gap={2}>
+        <Text variant="overline-small">Project name</Text>
+        <Input placeholder="My project" />
+      </Stack>
+      <Stack gap={2}>
+        <Text variant="overline-small">Description</Text>
+        <Textarea placeholder="Describe your project..." />
+      </Stack>
+      <Stack direction="horizontal" gap={3} justify="end">
+        <Button variant="secondary-light" size="large">Cancel</Button>
+        <Button variant="primary-dark" size="large">Create</Button>
+      </Stack>
+    </Stack>
+  </CardContent>
+</Card>`,
+      },
+    },
+  },
+  render: () => (
+    <Card className="w-full max-w-md">
+      <CardHeader>
+        <CardTitle>Create project</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <Stack gap={6}>
+          <Stack gap={2}>
+            <Text variant="overline-small" className="text-gray-500">Project name</Text>
+            <input className="border border-gray-200 rounded-md px-3 py-2 text-sm w-full" placeholder="My project" />
+          </Stack>
+          <Stack gap={2}>
+            <Text variant="overline-small" className="text-gray-500">Description</Text>
+            <textarea className="border border-gray-200 rounded-md px-3 py-2 text-sm w-full" rows={3} placeholder="Describe your project..." />
+          </Stack>
+          <Stack direction="horizontal" gap={3} justify="end">
+            <Button variant="secondary-light" size="large">Cancel</Button>
+            <Button variant="primary-dark" size="large">Create</Button>
+          </Stack>
+        </Stack>
+      </CardContent>
+    </Card>
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// Grid
+// ---------------------------------------------------------------------------
+
+export const GridTwoColumns: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: [
+          "**Grid** creates equal-width columns. Use it when all columns should be the same size — metric cards, feature lists, project tiles, gallery items.",
+          "",
+          "**The problem:**",
+          "```tsx",
+          "// ❌ Class soup — the responsive intent is buried",
+          `<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-6">`,
+          "  …",
+          "</div>",
+          "```",
+          "",
+          "**The solution:**",
+          "```tsx",
+          "// ✅ Props read like a layout description",
+          "<Grid cols={1} colsSm={2} colsLg={3} gap={6}>",
+          "  …",
+          "</Grid>",
+          "```",
+          "",
+          "**Key props:**",
+          "",
+          "| Prop | Values | Default | Effect |",
+          "|------|--------|---------|--------|",
+          "| `cols` | `1 \\| 2 \\| 3 \\| 4 \\| 6 \\| 12` | `1` | Columns at base (mobile) size |",
+          "| `colsSm` | same | — | Columns at 640px+ |",
+          "| `colsMd` | same | — | Columns at 768px+ |",
+          "| `colsLg` | same | — | Columns at 1024px+ |",
+          "| `gap` | number | `4` | Gap between all cells |",
+          "| `rowGap` | number | — | Gap between rows only |",
+          "| `colGap` | number | — | Gap between columns only |",
+          "",
+          "**Grid vs Columns — the key distinction:**",
+          "",
+          "`Grid` makes all columns equal width. If you need unequal widths (sidebar + main content), use `Columns`.",
+          "",
+          "```tsx",
+          "// Equal cards → Grid",
+          "<Grid cols={3} gap={6}><Card /><Card /><Card /></Grid>",
+          "",
+          "// Fixed sidebar + fluid content → Columns",
+          `<Columns preset="sidebar"><Nav /><Main /></Columns>`,
+          "```",
+        ].join("\n"),
+      },
+      source: {
+        code: `import { Grid } from "@syscore/ui-library"
+
+<Grid cols={1} colsMd={2} gap={4}>
+  <div>One</div>
+  <div>Two</div>
+  <div>Three</div>
+  <div>Four</div>
+</Grid>`,
+      },
+    },
+  },
+  render: () => (
+    <Grid cols={1} colsMd={2} gap={4} className="w-full max-w-2xl">
+      {["One", "Two", "Three", "Four"].map((n) => (
+        <Box key={n} label={n} tall />
+      ))}
+    </Grid>
+  ),
+};
+
+export const GridThreeColumns: Story = {
+  parameters: {
+    docs: {
+      source: {
+        code: `import { Grid } from "@syscore/ui-library"
+
+// 1 col on mobile → 2 on sm → 3 on lg
+<Grid cols={1} colsSm={2} colsLg={3} gap={6}>
+  <div>Alpha</div>
+  <div>Beta</div>
+  <div>Gamma</div>
+</Grid>`,
+      },
+    },
+  },
+  render: () => (
+    <Grid cols={1} colsSm={2} colsLg={3} gap={6} className="w-full max-w-4xl">
+      {["Alpha", "Beta", "Gamma", "Delta", "Epsilon", "Zeta"].map((n) => (
+        <Box key={n} label={n} tall />
+      ))}
+    </Grid>
+  ),
+};
+
+export const GridFourColumns: Story = {
+  parameters: {
+    docs: {
+      source: {
+        code: `import { Grid } from "@syscore/ui-library"
+
+<Grid cols={2} colsMd={4} gap={4}>
+  <div>Q1</div>
+  <div>Q2</div>
+  <div>Q3</div>
+  <div>Q4</div>
+</Grid>`,
+      },
+    },
+  },
+  render: () => (
+    <Grid cols={2} colsMd={4} gap={4} className="w-full max-w-4xl">
+      {["Q1", "Q2", "Q3", "Q4", "Q5", "Q6", "Q7", "Q8"].map((n) => (
+        <Box key={n} label={n} />
+      ))}
+    </Grid>
+  ),
+};
+
+export const GridMetrics: Story = {
+  name: "Grid — metric cards",
+  parameters: {
+    docs: {
+      source: {
+        code: `import { Grid, Stack } from "@syscore/ui-library"
+import { Card, CardMetric } from "@syscore/ui-library"
+
+<Grid cols={1} colsSm={2} colsLg={4} gap={4}>
+  <Card variant="outlined">
+    <CardMetric value="2,847" label="Total projects" trend="up" trendValue="12% this month" />
+  </Card>
+  <Card variant="outlined">
+    <CardMetric value="94%" label="Compliance score" trend="up" trendValue="3% vs last quarter" />
+  </Card>
+</Grid>`,
+      },
+    },
+  },
+  render: () => (
+    <Grid cols={1} colsSm={2} colsLg={4} gap={4} className="w-full max-w-5xl">
+      {[
+        { label: "Total projects", value: "2,847", trend: "+12%" },
+        { label: "Compliance score", value: "94%", trend: "+3%" },
+        { label: "Open issues", value: "18", trend: "-5" },
+        { label: "Active users", value: "1,204", trend: "+8%" },
+      ].map((item) => (
+        <Card key={item.label} variant="outlined">
+          <Text variant="overline-small" className="text-gray-500">{item.label}</Text>
+          <Stack direction="horizontal" align="baseline" gap={2}>
+            <Text variant="number-large" className="text-gray-900">{item.value}</Text>
+            <Text variant="body-small" className="text-green-600">{item.trend}</Text>
+          </Stack>
+        </Card>
+      ))}
+    </Grid>
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// Container
+// ---------------------------------------------------------------------------
+
+export const ContainerBasic: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: [
+          "**Container** centers content horizontally and constrains its max-width. Every page should wrap its content in a Container — it prevents text and cards from stretching to full viewport width on large monitors.",
+          "",
+          "**The problem:**",
+          "```tsx",
+          "// ❌ On a 4K monitor, content stretches to ~2500px wide — unreadable",
+          "<section>",
+          "  <h1>Page title</h1>",
+          "</section>",
+          "",
+          "// ❌ Custom max-width copy-pasted on every page",
+          `<div className="max-w-5xl mx-auto px-4 sm:px-6 lg:px-8">`,
+          "  …",
+          "</div>",
+          "```",
+          "",
+          "**The solution:**",
+          "```tsx",
+          "// ✅ One prop, consistent across the whole app",
+          `<Container size="xl">`,
+          "  <h1>Page title</h1>",
+          "</Container>",
+          "```",
+          "",
+          "**Size reference:**",
+          "",
+          "| Size | Max-width | Use for |",
+          "|------|-----------|---------|",
+          "| `\"sm\"` | 640px | Auth forms, modal body content |",
+          "| `\"md\"` | 768px | Reading content, blog posts |",
+          "| `\"lg\"` | 1024px | Standard page layouts |",
+          "| `\"xl\"` | 1280px | Wide dashboards (default) |",
+          "| `\"2xl\"` | 1536px | Full-width tables, data-heavy pages |",
+          "| `\"full\"` | none | Edge-to-edge, no constraint |",
+          "",
+          "**Always pair Section (vertical rhythm) with Container (horizontal constraint):**",
+          "```tsx",
+          `<Section padding="lg">`,
+          `  <Container size="xl">`,
+          "    {/* Your content here */}",
+          "  </Container>",
+          "</Section>",
+          "```",
+        ].join("\n"),
+      },
+      source: {
+        code: `import { Container } from "@syscore/ui-library"
+
+// Centers content, adds responsive horizontal padding
+<Container size="xl">
+  <h1>Page content</h1>
+</Container>
+
+// Sizes: "sm" (640px) · "md" (768px) · "lg" (1024px) · "xl" (1280px) · "2xl" (1536px) · "full"`,
+      },
+    },
+  },
+  render: () => (
+    <Container size="lg" className="border border-dashed border-cyan-400 bg-cyan-50 py-6 rounded-lg">
+      <Text variant="body-small" className="text-cyan-800 font-medium text-center">
+        Container size="lg" — max-width 1024px, centered, padded
+      </Text>
+    </Container>
+  ),
+};
+
+export const ContainerSizes: Story = {
+  parameters: {
+    docs: {
+      source: {
+        code: `import { Container } from "@syscore/ui-library"
+
+<Container size="sm">640px max-width</Container>
+<Container size="md">768px max-width</Container>
+<Container size="lg">1024px max-width</Container>
+<Container size="xl">1280px max-width</Container>
+<Container size="2xl">1536px max-width</Container>`,
+      },
+    },
+  },
+  render: () => (
+    <Stack gap={4}>
+      {(["sm", "md", "lg", "xl", "2xl"] as const).map((size) => (
+        <Container key={size} size={size} className="border border-dashed border-cyan-400 bg-cyan-50 py-3 rounded-lg">
+          <Text variant="body-small" className="text-cyan-800 font-medium text-center">
+            size="{size}" — {{ sm: "640px", md: "768px", lg: "1024px", xl: "1280px", "2xl": "1536px" }[size]}
+          </Text>
+        </Container>
+      ))}
+    </Stack>
+  ),
+};
+
+export const ContainerPageLayout: Story = {
+  name: "Container — page layout",
+  parameters: {
+    docs: {
+      source: {
+        code: `import { Container, Stack, Grid } from "@syscore/ui-library"
+import { Text, Button, Card } from "@syscore/ui-library"
+
+<Container size="lg">
+  <Stack gap={8}>
+    <Stack direction="horizontal" justify="between" align="center">
+      <Stack gap={1}>
+        <Text variant="heading-small">Dashboard</Text>
+        <Text variant="body-base">Welcome back</Text>
+      </Stack>
+      <Button variant="primary-dark" size="large">New project</Button>
+    </Stack>
+
+    <Grid cols={1} colsSm={3} gap={4}>
+      <Card variant="outlined">…</Card>
+      <Card variant="outlined">…</Card>
+      <Card variant="outlined">…</Card>
+    </Grid>
+  </Stack>
+</Container>`,
+      },
+    },
+  },
+  render: () => (
+    <div className="w-full bg-gray-50 rounded-xl overflow-hidden">
+      <Container size="lg" padded>
+        <Stack gap={8} className="py-8">
+          <Stack direction="horizontal" justify="between" align="center">
+            <Stack gap={1}>
+              <Text variant="heading-small">Dashboard</Text>
+              <Text variant="body-base" className="text-gray-500">Welcome back, User</Text>
+            </Stack>
+            <Button variant="primary-dark" size="large">New project</Button>
+          </Stack>
+          <Grid cols={1} colsSm={3} gap={4}>
+            {["2,847 Projects", "94% Compliance", "18 Issues"].map((item) => (
+              <Card key={item} variant="outlined">
+                <Text variant="body-base">{item}</Text>
+              </Card>
+            ))}
+          </Grid>
+        </Stack>
+      </Container>
+    </div>
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// Section
+// ---------------------------------------------------------------------------
+
+export const SectionBasic: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: [
+          "**Section** adds consistent vertical padding between major page sections. Use it to create breathing room between a hero, a features row, a metrics block, and a footer — without magic numbers.",
+          "",
+          "**The problem:**",
+          "```tsx",
+          "// ❌ Different padding on every section — inconsistent rhythm",
+          `<div className="py-12 md:py-20">Hero</div>`,
+          `<div className="py-8 md:py-16">Features</div>`,
+          `<div className="py-6 md:py-12">Metrics</div>`,
+          "```",
+          "",
+          "**The solution:**",
+          "```tsx",
+          "// ✅ Named scale, responsive built-in",
+          `<Section padding="xl">Hero</Section>`,
+          `<Section padding="lg">Features</Section>`,
+          `<Section padding="md">Metrics</Section>`,
+          "```",
+          "",
+          "**Padding scale:**",
+          "",
+          "| Value | Mobile | Desktop (768px+) | Use for |",
+          "|-------|--------|-----------------|---------|",
+          "| `\"sm\"` | 2rem | 3rem | Tight sections, secondary content |",
+          "| `\"md\"` | 3rem | 4rem | Standard content sections |",
+          "| `\"lg\"` | 4rem | 6rem | Main page sections (default) |",
+          "| `\"xl\"` | 6rem | 8rem | Hero sections, major separations |",
+          "| `\"none\"` | 0 | 0 | No padding (you control it) |",
+          "",
+          "**Standard pattern — Section wraps Container:**",
+          "```tsx",
+          "{/* Section = vertical rhythm. Container = horizontal constraint. */}",
+          `<Section padding="lg">`,
+          `  <Container size="xl">`,
+          "    <Grid cols={1} colsSm={3} gap={6}>",
+          "      <Card>…</Card>",
+          "    </Grid>",
+          "  </Container>",
+          "</Section>",
+          "```",
+          "",
+          "**Use `as` to render semantic HTML:**",
+          "```tsx",
+          `<Section as="article" padding="md">…</Section>`,
+          `<Section as="footer" padding="sm">…</Section>`,
+          "```",
+        ].join("\n"),
+      },
+      source: {
+        code: `import { Section, Container } from "@syscore/ui-library"
+
+// Always pair Section (vertical padding) with Container (max-width)
+<Section padding="lg">
+  <Container size="xl">
+    <h1>Section content</h1>
+  </Container>
+</Section>
+
+// Paddings: "none" · "sm" (2rem) · "md" (3rem) · "lg" (4rem) · "xl" (6rem)`,
+      },
+    },
+  },
+  render: () => (
+    <Section padding="lg" className="border border-dashed border-cyan-400 bg-cyan-50 rounded-lg w-full max-w-2xl">
+      <Text variant="body-small" className="text-cyan-800 font-medium text-center">
+        Section padding="lg" — 4rem top/bottom (6rem on md+)
+      </Text>
+    </Section>
+  ),
+};
+
+export const SectionPaddings: Story = {
+  parameters: {
+    docs: {
+      source: {
+        code: `import { Section } from "@syscore/ui-library"
+
+<Section padding="sm">…</Section>   {/* 2rem / 3rem on md+ */}
+<Section padding="md">…</Section>   {/* 3rem / 4rem on md+ */}
+<Section padding="lg">…</Section>   {/* 4rem / 6rem on md+ */}
+<Section padding="xl">…</Section>   {/* 6rem / 8rem on md+ */}`,
+      },
+    },
+  },
+  render: () => (
+    <Stack gap={2} className="w-full max-w-2xl">
+      {(["sm", "md", "lg", "xl"] as const).map((padding) => (
+        <Section key={padding} padding={padding} className="border border-dashed border-cyan-400 bg-cyan-50 rounded-lg">
+          <Text variant="body-small" className="text-cyan-800 font-medium text-center">
+            padding="{padding}"
+          </Text>
+        </Section>
+      ))}
+    </Stack>
+  ),
+};
+
+export const SectionLandingPage: Story = {
+  name: "Section — landing page",
+  parameters: {
+    docs: {
+      source: {
+        code: `import { Section, Container, Stack, Grid } from "@syscore/ui-library"
+import { Text, Button, Card } from "@syscore/ui-library"
+
+{/* Dark hero section */}
+<Section padding="lg">
+  <Container size="lg">
+    <Stack gap={4} align="center">
+      <Text variant="heading-medium">One unified standard</Text>
+      <Text variant="body-large">The design system that powers every WELL project.</Text>
+      <Stack direction="horizontal" gap={3}>
+        <Button variant="primary-gradient" size="large">Get started</Button>
+        <Button variant="tertiary-light" size="large">Learn more</Button>
+      </Stack>
+    </Stack>
+  </Container>
+</Section>
+
+{/* Content section */}
+<Section padding="md">
+  <Container size="lg">
+    <Grid cols={1} colsSm={2} colsLg={3} gap={6}>
+      <Card variant="default">…</Card>
+    </Grid>
+  </Container>
+</Section>`,
+      },
+    },
+  },
+  render: () => (
+    <div className="w-full bg-white rounded-xl border border-gray-100 overflow-hidden">
+      <Section padding="lg" className="bg-gray-900">
+        <Container size="lg" padded>
+          <Stack gap={4} align="center" className="text-center">
+            <Text variant="heading-medium" className="text-white">One unified standard</Text>
+            <Text variant="body-large" className="text-gray-300 max-w-lg">
+              The design system that powers every WELL-certified project.
+            </Text>
+            <Stack direction="horizontal" gap={3}>
+              <Button variant="primary-gradient" size="large">Get started</Button>
+              <Button variant="tertiary-light" size="large">Learn more</Button>
+            </Stack>
+          </Stack>
+        </Container>
+      </Section>
+      <Section padding="md">
+        <Container size="lg" padded>
+          <Grid cols={1} colsSm={2} colsLg={3} gap={6}>
+            {["Air", "Water", "Light"].map((concept) => (
+              <Card key={concept} variant="default">
+                <Text variant="overline-large">{concept.toUpperCase()}</Text>
+                <Text variant="body-base" className="text-gray-600">
+                  Improve wellbeing through {concept.toLowerCase()} quality standards.
+                </Text>
+              </Card>
+            ))}
+          </Grid>
+        </Container>
+      </Section>
+    </div>
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// Spacer
+// ---------------------------------------------------------------------------
+
+export const SpacerDemo: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: [
+          "**Spacer** adds a fixed-size blank area between elements. Use it when you need one specific gap that doesn't belong to a Stack or Grid — like a visual break between a header and a form, or extra whitespace before a footer.",
+          "",
+          "```tsx",
+          "{/* Vertical spacer — default */}",
+          "<Spacer size={8} />    {/* 2rem height */}",
+          "<Spacer size={4} />    {/* 1rem height */}",
+          "",
+          "{/* Horizontal spacer — inside a row */}",
+          `<Stack direction="horizontal">`,
+          "  <Button>Left</Button>",
+          `  <Spacer axis="horizontal" size={4} />`,
+          "  <Button>Right</Button>",
+          "</Stack>",
+          "```",
+          "",
+          "**When to use Spacer vs Stack gap:**",
+          "",
+          "Use `Stack gap` for even spacing between *all* siblings. Use `Spacer` for one *specific* extra gap that is larger or different from the rest.",
+          "",
+          "```tsx",
+          "{/* Stack gap: uniform spacing */}",
+          "<Stack gap={4}><A /><B /><C /></Stack>",
+          "",
+          "{/* Spacer: A and B are close, B and C have extra space */}",
+          "<Stack gap={4}>",
+          "  <A />",
+          "  <B />",
+          "  <Spacer size={8} />",
+          "  <C />",
+          "</Stack>",
+          "```",
+        ].join("\n"),
+      },
+      source: {
+        code: `import { Spacer } from "@syscore/ui-library"
+
+{/* Vertical spacer — adds height between elements */}
+<Text variant="heading-small">Above</Text>
+<Spacer size={8} />
+<Text variant="body-base">Below (2rem gap)</Text>
+
+{/* Horizontal spacer — adds width inside a row */}
+<Stack direction="horizontal">
+  <Button>Left</Button>
+  <Spacer axis="horizontal" size={4} />
+  <Button>Right</Button>
+</Stack>`,
+      },
+    },
+  },
+  render: () => (
+    <div className="max-w-sm border border-dashed border-gray-300 rounded-xl p-4">
+      <Box label="Above" />
+      <Spacer size={8} />
+      <Box label="size={8} gap below (2rem)" />
+      <Spacer size={4} />
+      <Box label="size={4} gap below (1rem)" />
+    </div>
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// Columns
+// ---------------------------------------------------------------------------
+
+export const ColumnsSidebar: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story: [
+          "**Columns** creates asymmetric two-column layouts. Use it when your columns need *different* widths — sidebar + content, form + preview, label + input.",
+          "",
+          "**Why not Grid?**",
+          "",
+          "`Grid cols={2}` gives both columns 50% width. `Columns` lets one column be fixed (`280px`) while the other fills the remaining space (`1fr`).",
+          "",
+          "```tsx",
+          "// ❌ Grid splits 50/50 — sidebar is too wide",
+          "<Grid cols={2}><Sidebar /><Main /></Grid>",
+          "",
+          "// ✅ Columns: fixed sidebar, fluid main",
+          `<Columns preset="sidebar"><Sidebar /><Main /></Columns>`,
+          "```",
+          "",
+          "**Available presets:**",
+          "",
+          "| Preset | Template | Use when |",
+          "|--------|----------|----------|",
+          "| `\"sidebar\"` | `280px 1fr` | Standard left nav |",
+          "| `\"sidebar-right\"` | `1fr 280px` | Right panel / inspector |",
+          "| `\"wide-sidebar\"` | `360px 1fr` | Wide nav or filter panel |",
+          "| `\"narrow-sidebar\"` | `200px 1fr` | Compact navigation |",
+          "| `\"split\"` | `1fr 1fr` | Equal halves |",
+          "| `\"1-2\"` | `1fr 2fr` | Narrow label + wide content |",
+          "| `\"2-1\"` | `2fr 1fr` | Wide content + narrow metadata |",
+          "| `\"1-3\"` | `1fr 3fr` | Form label + input area |",
+          "| `\"3-1\"` | `3fr 1fr` | Main content + slim sidebar |",
+          "",
+          "**Custom template (3+ columns):**",
+          "```tsx",
+          `<Columns template="200px 1fr 320px" gap={4}>`,
+          "  <LeftNav />",
+          "  <MainContent />",
+          "  <RightPanel />",
+          "</Columns>",
+          "```",
+          "",
+          "**Responsive collapse:**",
+          "```tsx",
+          "{/* Stacks to a single column below 768px */}",
+          `<Columns preset="sidebar" collapse="md">`,
+          "  <Sidebar />",
+          "  <Main />",
+          "</Columns>",
+          "```",
+        ].join("\n"),
+      },
+      source: {
+        code: `import { Columns } from "@syscore/ui-library"
+
+{/* Fixed 280px sidebar + fluid content */}
+<Columns preset="sidebar">
+  <nav>Sidebar</nav>
+  <main>Main content</main>
+</Columns>
+
+{/* Sidebar on right */}
+<Columns preset="sidebar-right">
+  <main>Main content</main>
+  <aside>Sidebar</aside>
+</Columns>
+
+{/* Presets: "sidebar" | "sidebar-right" | "wide-sidebar" | "narrow-sidebar"
+           | "split" | "1-2" | "2-1" | "1-3" | "3-1" */}`,
+      },
+    },
+  },
+  render: () => (
+    <Columns preset="sidebar" gap={4} className="w-full max-w-4xl">
+      <Box label="Sidebar (280px)" tall />
+      <Box label="Main content (1fr)" tall />
+    </Columns>
+  ),
+};
+
+export const ColumnsPresets: Story = {
+  parameters: {
+    docs: {
+      source: {
+        code: `import { Columns } from "@syscore/ui-library"
+
+<Columns preset="1-2" gap={6}>
+  <aside>Narrow (1fr)</aside>
+  <main>Wide (2fr)</main>
+</Columns>
+
+<Columns preset="2-1" gap={6}>
+  <main>Wide (2fr)</main>
+  <aside>Narrow (1fr)</aside>
+</Columns>`,
+      },
+    },
+  },
+  render: () => (
+    <Stack gap={4} className="w-full max-w-4xl">
+      {(["sidebar", "wide-sidebar", "split", "1-2", "2-1"] as const).map((preset) => (
+        <Stack gap={1} key={preset}>
+          <Text variant="overline-small" className="text-gray-400">preset="{preset}"</Text>
+          <Columns preset={preset} gap={3}>
+            <Box label="Col A" />
+            <Box label="Col B" />
+          </Columns>
+        </Stack>
+      ))}
+    </Stack>
+  ),
+};
+
+export const ColumnsCollapse: Story = {
+  name: "Columns — collapse on mobile",
+  parameters: {
+    docs: {
+      source: {
+        code: `import { Columns } from "@syscore/ui-library"
+
+{/* Stacks to single column below md (768px) */}
+<Columns preset="sidebar" collapse="md">
+  <nav>Sidebar</nav>
+  <main>Content</main>
+</Columns>`,
+      },
+    },
+  },
+  render: () => (
+    <Columns preset="sidebar" collapse="md" gap={4} className="w-full max-w-4xl">
+      <Box label="Sidebar — stacks below md" tall />
+      <Box label="Main content" tall />
+    </Columns>
+  ),
+};
+
+export const ColumnsCustomTemplate: Story = {
+  name: "Columns — custom template",
+  parameters: {
+    docs: {
+      source: {
+        code: `import { Columns } from "@syscore/ui-library"
+
+{/* Full control via CSS grid-template-columns string */}
+<Columns template="200px 1fr 300px" gap={4}>
+  <nav>Left nav</nav>
+  <main>Content</main>
+  <aside>Right panel</aside>
+</Columns>`,
+      },
+    },
+  },
+  render: () => (
+    <Columns template="200px 1fr 300px" gap={4} className="w-full max-w-5xl">
+      <Box label="Left (200px)" tall />
+      <Box label="Content (1fr)" tall />
+      <Box label="Right (300px)" tall />
+    </Columns>
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// AppShell
+// ---------------------------------------------------------------------------
+
+export const AppShellBasic: Story = {
+  name: "AppShell — basic",
+  parameters: {
+    docs: {
+      description: {
+        story: [
+          "**AppShell** is the full-page frame for apps with a persistent header and sidebar. It handles sticky header, fixed sidebar, and scrollable main area — using CSS grid with named areas.",
+          "",
+          "**The problem:**",
+          "```tsx",
+          "// ❌ Brittle CSS, magic calc() heights, easy to break scroll behavior",
+          `<div className="min-h-screen flex flex-col">`,
+          `  <header className="h-16 sticky top-0 z-50 bg-white border-b">…</header>`,
+          `  <div className="flex flex-1">`,
+          `    <aside className="w-[280px] sticky top-16 h-[calc(100vh-4rem)] overflow-y-auto">…</aside>`,
+          `    <main className="flex-1 overflow-y-auto">…</main>`,
+          "  </div>",
+          "</div>",
+          "```",
+          "",
+          "**The solution:**",
+          "```tsx",
+          "// ✅ Declarative. Dimensions via props, behavior built-in.",
+          "<AppShell>",
+          "  <AppShellHeader>…</AppShellHeader>",
+          "  <AppShellSidebar>…</AppShellSidebar>",
+          "  <AppShellMain>…</AppShellMain>",
+          "</AppShell>",
+          "```",
+          "",
+          "**Sub-components:**",
+          "",
+          "| Component | Renders as | Behavior |",
+          "|-----------|------------|----------|",
+          "| `AppShellHeader` | `<header>` | Sticky, full-width, sits above the sidebar |",
+          "| `AppShellSidebar` | `<aside>` | Fixed width, sticky under the header, scrollable |",
+          "| `AppShellMain` | `<main>` | Fills remaining space, independently scrollable |",
+          "| `AppShellFooter` | `<footer>` | Spans the full width below sidebar + main |",
+          "",
+          "**Customizing dimensions:**",
+          "```tsx",
+          "{/* Numbers → converted to px. Strings → used as-is. */}",
+          "<AppShell sidebarWidth={240} headerHeight={56}>…</AppShell>",
+          `<AppShell sidebarWidth="20rem" headerHeight="3.5rem">…</AppShell>`,
+          "```",
+          "",
+          "**Without a sidebar:**",
+          "```tsx",
+          "{/* Omit AppShellSidebar — AppShellMain fills the full width */}",
+          "<AppShell>",
+          "  <AppShellHeader>…</AppShellHeader>",
+          "  <AppShellMain>…</AppShellMain>",
+          "</AppShell>",
+          "```",
+        ].join("\n"),
+      },
+      source: {
+        code: `import { AppShell, AppShellHeader, AppShellSidebar, AppShellMain } from "@syscore/ui-library"
+import { Stack, Text, Button } from "@syscore/ui-library"
+
+<AppShell>
+  <AppShellHeader>
+    <Stack direction="horizontal" justify="between" align="center">
+      <Text variant="heading-xxsmall">My App</Text>
+      <Button variant="primary-dark" size="large">Sign in</Button>
+    </Stack>
+  </AppShellHeader>
+
+  <AppShellSidebar>
+    <Stack gap={2}>
+      <Button variant="transparent-tertiary" size="large">Dashboard</Button>
+      <Button variant="transparent-tertiary" size="large">Projects</Button>
+      <Button variant="transparent-tertiary" size="large">Settings</Button>
+    </Stack>
+  </AppShellSidebar>
+
+  <AppShellMain>
+    <Container size="xl">
+      <Text variant="heading-small">Page content</Text>
+    </Container>
+  </AppShellMain>
+</AppShell>`,
+      },
+    },
+  },
+  render: () => (
+    <div className="w-full rounded-xl overflow-hidden border border-gray-200" style={{ height: 480 }}>
+      <AppShell style={{ minHeight: "100%", height: "100%" }}>
+        <AppShellHeader>
+          <Stack direction="horizontal" justify="between" align="center" className="w-full">
+            <Text variant="heading-xxsmall">My App</Text>
+            <Button variant="primary-dark" size="large">Sign in</Button>
+          </Stack>
+        </AppShellHeader>
+        <AppShellSidebar className="p-4">
+          <Stack gap={1}>
+            {["Dashboard", "Projects", "Reports", "Settings"].map((item) => (
+              <div key={item} className="px-3 py-2 rounded-lg text-sm text-gray-700 hover:bg-gray-100 cursor-pointer">{item}</div>
+            ))}
+          </Stack>
+        </AppShellSidebar>
+        <AppShellMain className="p-6">
+          <Stack gap={4}>
+            <Text variant="heading-small">Dashboard</Text>
+            <Grid cols={1} colsSm={3} gap={4}>
+              {["2,847 Projects", "94% Score", "18 Issues"].map((m) => (
+                <Card key={m} variant="outlined"><Text variant="body-base">{m}</Text></Card>
+              ))}
+            </Grid>
+          </Stack>
+        </AppShellMain>
+      </AppShell>
+    </div>
+  ),
+};
+
+export const AppShellCustomWidth: Story = {
+  name: "AppShell — custom sidebar width",
+  parameters: {
+    docs: {
+      source: {
+        code: `import { AppShell, AppShellHeader, AppShellSidebar, AppShellMain } from "@syscore/ui-library"
+
+{/* Custom sidebar width and header height */}
+<AppShell sidebarWidth={240} headerHeight={56}>
+  <AppShellHeader>…</AppShellHeader>
+  <AppShellSidebar>…</AppShellSidebar>
+  <AppShellMain>…</AppShellMain>
+</AppShell>
+
+{/* String values also work */}
+<AppShell sidebarWidth="20rem" headerHeight="3.5rem">
+  …
+</AppShell>`,
+      },
+    },
+  },
+  render: () => (
+    <div className="w-full rounded-xl overflow-hidden border border-gray-200" style={{ height: 360 }}>
+      <AppShell sidebarWidth={200} headerHeight={52} style={{ minHeight: "100%", height: "100%" }}>
+        <AppShellHeader>
+          <Text variant="heading-xxsmall">Narrow sidebar (200px)</Text>
+        </AppShellHeader>
+        <AppShellSidebar className="p-3">
+          <Stack gap={1}>
+            {["Home", "Docs", "API"].map((item) => (
+              <div key={item} className="px-3 py-2 rounded-lg text-sm text-gray-700 hover:bg-gray-100 cursor-pointer">{item}</div>
+            ))}
+          </Stack>
+        </AppShellSidebar>
+        <AppShellMain className="p-6">
+          <Text variant="body-base" className="text-gray-500">Main content area</Text>
+        </AppShellMain>
+      </AppShell>
+    </div>
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// Show / Hide
+// ---------------------------------------------------------------------------
+
+export const ShowHideDemo: Story = {
+  name: "Show / Hide — resize to see changes",
+  parameters: {
+    docs: {
+      description: {
+        story: [
+          "**Show** and **Hide** control visibility at breakpoints — without writing CSS media queries by hand.",
+          "",
+          "**The problem:**",
+          "```tsx",
+          "// ❌ Tailwind visibility classes duplicated everywhere, easy to mismatch",
+          `<div className="hidden md:block">Desktop only</div>`,
+          `<div className="block md:hidden">Mobile only</div>`,
+          "```",
+          "",
+          "**The solution:**",
+          "```tsx",
+          "// ✅ Readable, consistent, no CSS strings",
+          `<Show above="md">Desktop only</Show>`,
+          `<Show below="md">Mobile only</Show>`,
+          "```",
+          "",
+          "**Props:**",
+          "",
+          "| Prop | Effect |",
+          "|------|--------|",
+          "| `above=\"md\"` | Visible at 768px and wider |",
+          "| `below=\"md\"` | Visible below 768px |",
+          "| `Hide above=\"md\"` | Hidden at 768px and wider |",
+          "| `Hide below=\"md\"` | Hidden below 768px |",
+          "",
+          "**Breakpoints:** `\"sm\"` = 640px · `\"md\"` = 768px · `\"lg\"` = 1024px · `\"xl\"` = 1280px",
+          "",
+          "**Common patterns:**",
+          "```tsx",
+          "{/* Sidebar only on desktop */}",
+          `<Show above="lg">`,
+          "  <AppShellSidebar>…</AppShellSidebar>",
+          "</Show>",
+          "",
+          "{/* Hamburger menu only on mobile */}",
+          `<Show below="md">`,
+          "  <MobileNavTrigger />",
+          "</Show>",
+          "",
+          "{/* Switch between table (desktop) and cards (mobile) */}",
+          `<Show above="md"><DataTable /></Show>`,
+          `<Show below="md"><CardList /></Show>`,
+          "```",
+          "",
+          "**Use `as` to avoid an extra wrapper div:**",
+          "```tsx",
+          `<Show above="md" as="nav">`,
+          "  <DesktopMenu />",
+          "</Show>",
+          "```",
+          "",
+          "> Resize your browser window to see the stories below appear and disappear.",
+        ].join("\n"),
+      },
+      source: {
+        code: `import { Show, Hide } from "@syscore/ui-library"
+
+{/* Show only on desktop (md and above) */}
+<Show above="md">
+  <Sidebar />
+</Show>
+
+{/* Show only on mobile (below md) */}
+<Show below="md">
+  <MobileNav />
+</Show>
+
+{/* Hide on mobile */}
+<Hide below="md">
+  <DesktopMenu />
+</Hide>
+
+{/* Breakpoints: "sm" (640px) · "md" (768px) · "lg" (1024px) · "xl" (1280px) */}`,
+      },
+    },
+  },
+  render: () => (
+    <Stack gap={3} className="w-full max-w-lg">
+      <Show above="md">
+        <Box label="Show above='md' — visible on 768px+" />
+      </Show>
+      <Show below="md">
+        <Box label="Show below='md' — visible below 768px" />
+      </Show>
+      <Hide above="lg">
+        <Box label="Hide above='lg' — hidden on 1024px+" />
+      </Hide>
+      <Hide below="sm">
+        <Box label="Hide below='sm' — hidden below 640px" />
+      </Hide>
+    </Stack>
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// Positioned
+// ---------------------------------------------------------------------------
+
+export const PositionedDemo: Story = {
+  name: "Positioned — absolute overlay",
+  parameters: {
+    docs: {
+      description: {
+        story: [
+          "**Positioned** is a semantic wrapper for `position: absolute/relative/fixed/sticky`. Use it when you need to layer elements — badges on cards, overlays on images, sticky toolbars.",
+          "",
+          "**The problem:**",
+          "```tsx",
+          "// ❌ Position CSS mixed into className, intent unclear",
+          `<div className="relative">`,
+          `  <span className="absolute top-3 right-3 z-10">Badge</span>`,
+          "</div>",
+          "```",
+          "",
+          "**The solution:**",
+          "```tsx",
+          "// ✅ Props express intent",
+          `<Positioned position="relative">`,
+          `  <Positioned position="absolute" top={3} right={3} zIndex={10}>`,
+          "    <Badge>New</Badge>",
+          "  </Positioned>",
+          "</Positioned>",
+          "```",
+          "",
+          "**Props:**",
+          "",
+          "| Prop | Type | Effect |",
+          "|------|------|--------|",
+          "| `position` | `\"relative\" \\| \"absolute\" \\| \"fixed\" \\| \"sticky\"` | CSS position value |",
+          "| `top / right / bottom / left` | number or string | Offset from that edge |",
+          "| `inset` | number or string | All four sides at once |",
+          "| `fill` | `boolean` | Sets `inset: 0` — covers the entire parent |",
+          "| `zIndex` | number | Stack order |",
+          "",
+          "**Number offsets follow the spacing scale:** `top={4}` = `top: 1rem`, `top={2}` = `top: 0.5rem`",
+          "",
+          "**Full overlay pattern:**",
+          "```tsx",
+          `<Positioned position="relative">`,
+          "  <img src={src} alt={alt} />",
+          `  <Positioned position="absolute" fill zIndex={10}>`,
+          `    <Stack align="center" justify="center">`,
+          "      Overlay content",
+          "    </Stack>",
+          "  </Positioned>",
+          "</Positioned>",
+          "```",
+          "",
+          "**Most important rule:** An absolutely-positioned child escapes to the nearest *positioned* ancestor. Always set `position=\"relative\"` on the parent, or the badge/overlay will float to the viewport instead of the card.",
+        ].join("\n"),
+      },
+      source: {
+        code: `import { Positioned } from "@syscore/ui-library"
+import { Badge } from "@syscore/ui-library"
+
+{/* Badge pinned to top-right of a card */}
+<Positioned position="relative">
+  <Card variant="outlined">
+    <Positioned position="absolute" top={3} right={3}>
+      <Badge>New</Badge>
+    </Positioned>
+    <CardContent>Card with badge</CardContent>
+  </Positioned>
+</Positioned>
+
+{/* Full overlay — covers the entire parent */}
+<Positioned position="relative">
+  <img src="..." />
+  <Positioned position="absolute" fill zIndex={10}>
+    <Stack align="center" justify="center">
+      Overlay content
+    </Stack>
+  </Positioned>
+</Positioned>`,
+      },
+    },
+  },
+  render: () => (
+    <Stack gap={6} className="max-w-md">
+      <Positioned position="relative">
+        <Card variant="outlined" className="w-full">
+          <Positioned position="absolute" top={3} right={3}>
+            <Badge variant="default">New</Badge>
+          </Positioned>
+          <Text variant="body-base" className="pt-4">Card with absolute badge pinned top-right</Text>
+        </Card>
+      </Positioned>
+
+      <Positioned position="relative" className="w-full h-32 rounded-xl overflow-hidden bg-gray-900">
+        <Positioned position="absolute" fill zIndex={10} className="flex items-center justify-center">
+          <Text variant="body-base" className="text-white">fill overlay (inset: 0)</Text>
+        </Positioned>
+      </Positioned>
+    </Stack>
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// All together
+// ---------------------------------------------------------------------------
+
+export const FullPageExample: Story = {
+  name: "All together — full page",
+  parameters: {
+    docs: {
+      source: {
+        code: `import { Stack, Grid, Container, Section } from "@syscore/ui-library"
+import { Text, Button, Card } from "@syscore/ui-library"
+
+{/* App shell */}
+<Stack gap={0}>
+
+  {/* Top nav */}
+  <Stack direction="horizontal" justify="between" align="center">
+    <Text variant="heading-xxsmall">WELL Design System</Text>
+    <Stack direction="horizontal" gap={2}>
+      <Button variant="secondary-light" size="large">Docs</Button>
+      <Button variant="primary-dark" size="large">Sign in</Button>
+    </Stack>
+  </Stack>
+
+  {/* Hero */}
+  <Section padding="lg">
+    <Container size="xl">
+      <Stack gap={4} align="center">
+        <Text variant="heading-large">Build better spaces</Text>
+        <Text variant="body-large">Component-driven design for healthier environments.</Text>
+      </Stack>
+    </Container>
+  </Section>
+
+  {/* Metrics */}
+  <Section padding="md">
+    <Container size="xl">
+      <Grid cols={1} colsSm={2} colsLg={4} gap={4}>
+        <Card variant="outlined">…</Card>
+      </Grid>
+    </Container>
+  </Section>
+
+</Stack>`,
+      },
+    },
+  },
+  render: () => (
+    <div className="w-full bg-gray-50 rounded-xl overflow-hidden border border-gray-100">
+      <div className="bg-white border-b border-gray-100 px-6 py-4">
+        <Stack direction="horizontal" justify="between" align="center">
+          <Text variant="heading-xxsmall">WELL Design System</Text>
+          <Stack direction="horizontal" gap={2}>
+            <Button variant="secondary-light" size="large">Docs</Button>
+            <Button variant="primary-dark" size="large">Sign in</Button>
+          </Stack>
+        </Stack>
+      </div>
+      <Section padding="lg" className="bg-gray-900">
+        <Container size="xl" padded>
+          <Stack gap={4} align="center" className="text-center">
+            <Text variant="heading-large" className="text-white">Build better spaces</Text>
+            <Text variant="body-large" className="text-gray-400">
+              Component-driven design for healthier environments.
+            </Text>
+          </Stack>
+        </Container>
+      </Section>
+      <Section padding="md">
+        <Container size="xl" padded>
+          <Grid cols={1} colsSm={2} colsLg={4} gap={4}>
+            {["2,847 Projects", "94% Score", "18 Issues", "1,204 Users"].map((m) => (
+              <Card key={m} variant="outlined">
+                <Text variant="body-base" className="font-semibold">{m}</Text>
+              </Card>
+            ))}
+          </Grid>
+        </Container>
+      </Section>
+    </div>
+  ),
+};