@shohojdhara/atomix 0.2.1 → 0.2.3

package/src/layouts/Grid/Grid.stories.tsx

@@ -4,6 +4,9 @@ import { Container } from './Container';
 import { Grid } from './Grid';
 import { GridCol } from './GridCol';
 import { Row } from './Row';
+import { Button } from '../../components/Button';
+import { Card } from '../../components/Card';
+import { Callout } from '../../components/Callout';
 
 const meta: Meta<typeof Grid> = {
   title: 'Layouts/Grid',
@@ -19,7 +22,7 @@ const meta: Meta<typeof Grid> = {
   },
   decorators: [
     Story => (
-      <div style={{ padding: '1rem' }}>
+      <div className="u-p-4">
         <Story />
       </div>
     ),
@@ -29,46 +32,54 @@ const meta: Meta<typeof Grid> = {
 export default meta;
 type Story = StoryObj<typeof Grid>;
 
-// Modern demo components with better visual hierarchy
+// Modern demo components with better visual hierarchy using Atomix components
 const DemoCard: React.FC<{
   children: React.ReactNode;
   variant?: 'primary' | 'secondary' | 'accent';
   height?: 'auto' | 'sm' | 'md' | 'lg';
 }> = ({ children, variant = 'primary', height = 'auto' }) => {
   const heightStyles = {
-    auto: '60px',
-    sm: '50px',
-    md: '75px',
-    lg: '100px',
+    auto: undefined,
+    sm: '80px',
+    md: '120px',
+    lg: '160px',
   };
-  const variantClasses = {
-    primary: 'u-bg-brand-subtle u-border-brand-subtle',
-    secondary: 'u-bg-success-subtle u-border-success-subtle',
-    accent: 'u-bg-info-subtle u-border-info-subtle',
-  };
-  const variantTextClasses = {
-    primary: 'u-text-brand-emphasis',
-    secondary: 'u-text-success-emphasis',
-    accent: 'u-text-info-emphasis',
+
+  const variantMap = {
+    primary: { cardVariant: 'default' as const, badgeVariant: 'primary' as const },
+    secondary: { cardVariant: 'success' as const, badgeVariant: 'success' as const },
+    accent: { cardVariant: 'info' as const, badgeVariant: 'info' as const },
   };
 
+  const { cardVariant, badgeVariant } = variantMap[variant];
+
   return (
-    <div
-      className={`u-p-4 u-rounded u-border u-text-center u-d-flex u-align-items-center u-justify-content-center ${variantClasses[variant]}`}
-      style={{ minHeight: heightStyles[height] }}
+    <Card
+      className={`u-h-100 ${variant === 'primary' ? 'u-bg-brand-subtle' : ''} ${
+        variant === 'secondary' ? 'u-bg-success-subtle' : ''
+      } ${variant === 'accent' ? 'u-bg-info-subtle' : ''}`}
     >
-      <div className={`${variantTextClasses[variant]} u-fw-medium`}>{children}</div>
-    </div>
+      <div 
+        className="u-d-flex u-flex-column u-h-100"
+        style={{ minHeight: heightStyles[height] }}
+      >
+        <div className="u-flex-grow-1 u-d-flex u-align-items-center u-justify-content-center">
+          <div className="u-text-center">{children}</div>
+        </div>
+      </div>
+    </Card>
   );
 };
 
 const CodeSnippet: React.FC<{ children: React.ReactNode }> = ({ children }) => (
-  <pre
-    className="u-bg-dark-subtle u-text-error-emphasis u-p-3 u-rounded u-fs-sm u-fw-normal"
-    style={{ fontFamily: 'monospace' }}
-  >
-    {children}
-  </pre>
+  <Card className="u-mb-4">
+    <pre
+      className="u-bg-dark u-text-light u-p-3 u-rounded u-fs-sm u-fw-normal u-overflow-auto"
+      style={{ fontFamily: 'monospace' }}
+    >
+      {children}
+    </pre>
+  </Card>
 );
 
 /**
@@ -80,12 +91,22 @@ const CodeSnippet: React.FC<{ children: React.ReactNode }> = ({ children }) => (
 export const GettingStarted: Story = {
   render: () => (
     <div className="u-mb-8">
-      <h2 className="u-mb-1 u-text-brand-emphasis">Basic Grid Layout</h2>
-      <p className="u-mb-6 u-text-secondary-emphasis">
+      <div className="u-mb-6">
+        <h1 className="u-mb-3 u-text-brand-emphasis">Grid System</h1>
+        <p className="u-mb-4 u-text-secondary-emphasis u-fs-lg">
+          A responsive 12-column grid system for creating flexible layouts.
+        </p>
+        <Callout variant="info" className="u-mb-4">
+          Resize your browser window to see how the columns adapt to different screen sizes.
+        </Callout>
+      </div>
+
+      <h2 className="u-mb-4 u-text-brand-emphasis u-border-bottom u-pb-2">Basic Grid Layout</h2>
+      <p className="u-mb-4 u-text-secondary-emphasis">
         Equal columns that stack on mobile and expand on larger screens:
       </p>
 
-      <Grid className="u-mb-6">
+      <Grid className="u-mb-4">
         <GridCol xs={12} md={4}>
           <DemoCard>Column 1</DemoCard>
         </GridCol>
@@ -99,19 +120,19 @@ export const GettingStarted: Story = {
 
       <CodeSnippet>
         {`<Grid>
-  <GridCol xs={12} md={4}> Column 1 </GridCol>
-  <GridCol xs={12} md={4}> Column 2 </GridCol>
-  <GridCol xs={12} md={4}> Column 3 </GridCol>
+  <GridCol xs={12} md={4}>Column 1</GridCol>
+  <GridCol xs={12} md={4}>Column 2</GridCol>
+  <GridCol xs={12} md={4}>Column 3</GridCol>
 </Grid>`}
       </CodeSnippet>
 
-      <div className="u-mt-8">
-        <h3 className="u-mb-1 u-text-brand-emphasis">Responsive Behavior</h3>
+      <div className="u-mt-6">
+        <h3 className="u-mb-4 u-text-brand-emphasis">Responsive Behavior</h3>
         <p className="u-mb-4 u-text-secondary-emphasis">
           Columns automatically adjust at different screen sizes:
         </p>
 
-        <Grid className="u-mb-6">
+        <Grid className="u-mb-4">
           <GridCol xs={12} sm={6} md={4} lg={3}>
             <DemoCard variant="secondary">
               <div>Mobile: Full width</div>
@@ -149,66 +170,90 @@ export const GettingStarted: Story = {
 export const LayoutPatterns: Story = {
   render: () => (
     <div className="u-mb-8">
-      <h2 className="u-mb-6 u-text-brand-emphasis">Common Layout Patterns</h2>
+      <h1 className="u-mb-6 u-text-brand-emphasis u-border-bottom u-pb-2">Common Layout Patterns</h1>
 
       {/* Sidebar Layout */}
       <div className="u-mb-8">
-        <h3 className="u-mb-1 u-text-brand-emphasis">Sidebar Layout</h3>
-        <p className="u-mb-4">Perfect for dashboards and admin interfaces:</p>
+        <h2 className="u-mb-4 u-text-brand-emphasis">Sidebar Layout</h2>
+        <p className="u-mb-4 u-text-secondary-emphasis">
+          Perfect for dashboards and admin interfaces:
+        </p>
 
-        <Grid className="u-mb-6">
+        <Grid className="u-mb-4">
           <GridCol xs={12} md={3}>
             <DemoCard variant="accent" height="lg">
-              <div>Sidebar</div>
-              <div className="u-fs-sm ">Navigation, filters, etc.</div>
+              <div className="u-fs-lg u-fw-bold">Sidebar</div>
+              <div className="u-fs-sm u-mt-2">Navigation, filters, etc.</div>
             </DemoCard>
           </GridCol>
           <GridCol xs={12} md={9}>
             <DemoCard height="lg">
-              <div>Main Content</div>
-              <div className="u-fs-sm">Primary content area</div>
+              <div className="u-fs-lg u-fw-bold">Main Content</div>
+              <div className="u-fs-sm u-mt-2">Primary content area</div>
             </DemoCard>
           </GridCol>
         </Grid>
+
+        <Card className="u-mb-6">
+          <div className="u-d-flex u-flex-wrap u-gap-2">
+            <Button variant="primary">Save Changes</Button>
+            <Button variant="secondary">Cancel</Button>
+          </div>
+        </Card>
       </div>
 
       {/* Hero + Features */}
       <div className="u-mb-8">
-        <h3 className="u-mb-1 u-text-brand-emphasis">Hero + Features</h3>
-        <p className="u-mb-4 ">Landing page layout with hero section and feature cards:</p>
+        <h2 className="u-mb-4 u-text-brand-emphasis">Hero + Features</h2>
+        <p className="u-mb-4 u-text-secondary-emphasis">
+          Landing page layout with hero section and feature cards:
+        </p>
 
         <Grid className="u-mb-4">
           <GridCol xs={12}>
             <DemoCard variant="accent" height="md">
-              <div>Hero Section</div>
-              <div className="u-fs-sm">Full-width banner</div>
+              <div className="u-fs-lg u-fw-bold">Hero Section</div>
+              <div className="u-fs-sm u-mt-2">Full-width banner</div>
             </DemoCard>
           </GridCol>
         </Grid>
 
-        <Grid className="u-mb-6">
+        <Grid className="u-mb-4">
           <GridCol xs={12} sm={6} lg={4}>
-            <DemoCard variant="secondary">Feature 1</DemoCard>
+            <DemoCard variant="secondary">
+              <div className="u-fs-md u-fw-bold">Feature 1</div>
+              <div className="u-fs-sm u-mt-2">Description of feature 1</div>
+            </DemoCard>
           </GridCol>
           <GridCol xs={12} sm={6} lg={4}>
-            <DemoCard variant="secondary">Feature 2</DemoCard>
+            <DemoCard variant="secondary">
+              <div className="u-fs-md u-fw-bold">Feature 2</div>
+              <div className="u-fs-sm u-mt-2">Description of feature 2</div>
+            </DemoCard>
           </GridCol>
           <GridCol xs={12} sm={12} lg={4}>
-            <DemoCard variant="secondary">Feature 3</DemoCard>
+            <DemoCard variant="secondary">
+              <div className="u-fs-md u-fw-bold">Feature 3</div>
+              <div className="u-fs-sm u-mt-2">Description of feature 3</div>
+            </DemoCard>
           </GridCol>
         </Grid>
       </div>
 
       {/* Article Layout */}
       <div className="u-mb-8">
-        <h3 className="u-mb-1 u-text-brand-emphasis">Article Layout</h3>
-        <p className="u-mb-4 u-text-secondary-emphasis">Centered content with optional sidebar:</p>
+        <h2 className="u-mb-4 u-text-brand-emphasis">Article Layout</h2>
+        <p className="u-mb-4 u-text-secondary-emphasis">
+          Centered content with optional sidebar:
+        </p>
 
-        <Grid className="u-mb-6">
+        <Grid className="u-mb-4">
           <GridCol xs={12} md={8} offsetMd={2}>
             <DemoCard height="lg">
-              <div>Article Content</div>
-              <div className="u-fs-sm u-text-secondary-emphasis">Centered, readable width</div>
+              <div className="u-fs-lg u-fw-bold">Article Content</div>
+              <div className="u-fs-sm u-text-secondary-emphasis u-mt-2">
+                Centered, readable width
+              </div>
             </DemoCard>
           </GridCol>
         </Grid>
@@ -225,12 +270,14 @@ export const LayoutPatterns: Story = {
 export const ColumnSizing: Story = {
   render: () => (
     <div className="u-mb-8">
-      <h2 className="u-mb-6 u-text-brand-emphasis">Column Sizing Options</h2>
+      <h1 className="u-mb-6 u-text-brand-emphasis u-border-bottom u-pb-2">Column Sizing Options</h1>
 
       {/* Fixed Sizes */}
       <div className="u-mb-8">
-        <h3 className="u-mb-1 u-text-brand-emphasis">Fixed Column Sizes</h3>
-        <p className="u-mb-4 u-text-secondary-emphasis">Specify exact column widths (1-12):</p>
+        <h2 className="u-mb-4 u-text-brand-emphasis">Fixed Column Sizes</h2>
+        <p className="u-mb-4 u-text-secondary-emphasis">
+          Specify exact column widths (1-12):
+        </p>
 
         <Grid className="u-mb-4">
           <GridCol xs={2}>
@@ -250,7 +297,7 @@ export const ColumnSizing: Story = {
           </GridCol>
         </Grid>
 
-        <Grid className="u-mb-6">
+        <Grid className="u-mb-4">
           <GridCol xs={6}>
             <DemoCard variant="secondary">6 cols</DemoCard>
           </GridCol>
@@ -262,7 +309,7 @@ export const ColumnSizing: Story = {
 
       {/* Auto Sizing */}
       <div className="u-mb-8">
-        <h3 className="u-mb-1 u-text-brand-emphasis">Auto-Sizing Columns</h3>
+        <h2 className="u-mb-4 u-text-brand-emphasis">Auto-Sizing Columns</h2>
         <p className="u-mb-4 u-text-secondary-emphasis">
           Columns that automatically size based on content:
         </p>
@@ -279,7 +326,7 @@ export const ColumnSizing: Story = {
           </GridCol>
         </Grid>
 
-        <Grid className="u-mb-6">
+        <Grid className="u-mb-4">
           <GridCol xs={4}>
             <DemoCard variant="secondary">Fixed (4 cols)</DemoCard>
           </GridCol>
@@ -294,28 +341,28 @@ export const ColumnSizing: Story = {
 
       {/* Mixed Sizes */}
       <div className="u-mb-8">
-        <h3 className="u-mb-1 u-text-brand-emphasis">Mixed Sizing</h3>
+        <h2 className="u-mb-4 u-text-brand-emphasis">Mixed Sizing</h2>
         <p className="u-mb-4 u-text-secondary-emphasis">
           Combine fixed and auto sizing for flexible layouts:
         </p>
 
-        <Grid className="u-mb-6">
+        <Grid className="u-mb-4">
           <GridCol xs={12} sm={6} md={4} lg="auto">
             <DemoCard variant="secondary">
               <div>Responsive</div>
-              <div className="u-fs-sm">xs=12, sm=6, md=4, lg=auto</div>
+              <div className="u-fs-sm u-mt-2">xs=12, sm=6, md=4, lg=auto</div>
             </DemoCard>
           </GridCol>
           <GridCol xs={12} sm={6} md={4} lg="auto">
             <DemoCard variant="secondary">
               <div>Responsive</div>
-              <div className="u-fs-sm">xs=12, sm=6, md=4, lg=auto</div>
+              <div className="u-fs-sm u-mt-2">xs=12, sm=6, md=4, lg=auto</div>
             </DemoCard>
           </GridCol>
           <GridCol xs={12} sm={12} md={4} lg="auto">
             <DemoCard variant="secondary">
               <div>Responsive</div>
-              <div className="u-fs-sm">xs=12, sm=12, md=4, lg=auto</div>
+              <div className="u-fs-sm u-mt-2">xs=12, sm=12, md=4, lg=auto</div>
             </DemoCard>
           </GridCol>
         </Grid>
@@ -332,12 +379,14 @@ export const ColumnSizing: Story = {
 export const ColumnOffsets: Story = {
   render: () => (
     <div className="u-mb-8">
-      <h2 className="u-mb-6 u-text-brand-emphasis">Column Offsets</h2>
+      <h1 className="u-mb-6 u-text-brand-emphasis u-border-bottom u-pb-2">Column Offsets</h1>
 
       {/* Basic Offsets */}
       <div className="u-mb-8">
-        <h3 className="u-mb-1 u-text-brand-emphasis">Basic Offsets</h3>
-        <p className="u-mb-4 u-text-secondary-emphasis">Push columns to the right using offsets:</p>
+        <h2 className="u-mb-4 u-text-brand-emphasis">Basic Offsets</h2>
+        <p className="u-mb-4 u-text-secondary-emphasis">
+          Push columns to the right using offsets:
+        </p>
 
         <Grid className="u-mb-4">
           <GridCol xs={4}>
@@ -348,7 +397,7 @@ export const ColumnOffsets: Story = {
           </GridCol>
         </Grid>
 
-        <Grid className="u-mb-6">
+        <Grid className="u-mb-4">
           <GridCol xs={3} offsetXs={3}>
             <DemoCard variant="secondary">3 cols, offset 3</DemoCard>
           </GridCol>
@@ -360,8 +409,10 @@ export const ColumnOffsets: Story = {
 
       {/* Centering */}
       <div className="u-mb-8">
-        <h3 className="u-mb-1 u-text-brand-emphasis">Centering Content</h3>
-        <p className="u-mb-4 u-text-secondary-emphasis">Center columns using equal offsets:</p>
+        <h2 className="u-mb-4 u-text-brand-emphasis">Centering Content</h2>
+        <p className="u-mb-4 u-text-secondary-emphasis">
+          Center columns using equal offsets:
+        </p>
 
         <Grid className="u-mb-4">
           <GridCol xs={6} offsetXs={3}>
@@ -369,7 +420,7 @@ export const ColumnOffsets: Story = {
           </GridCol>
         </Grid>
 
-        <Grid className="u-mb-6">
+        <Grid className="u-mb-4">
           <GridCol xs={8} offsetXs={2}>
             <DemoCard variant="accent">Centered (8 cols, offset 2)</DemoCard>
           </GridCol>
@@ -378,16 +429,16 @@ export const ColumnOffsets: Story = {
 
       {/* Responsive Offsets */}
       <div className="u-mb-8">
-        <h3 className="u-mb-1 u-text-brand-emphasis">Responsive Offsets</h3>
+        <h2 className="u-mb-4 u-text-brand-emphasis">Responsive Offsets</h2>
         <p className="u-mb-4 u-text-secondary-emphasis">
           Different offsets at different screen sizes:
         </p>
 
-        <Grid className="u-mb-6">
+        <Grid className="u-mb-4">
           <GridCol xs={12} sm={6} offsetSm={3} md={4} offsetMd={4} lg={3} offsetLg={3}>
             <DemoCard variant="secondary">
-              <div>Responsive Offsets</div>
-              <div className="u-fs-sm">Changes at each breakpoint</div>
+              <div className="u-fs-md u-fw-bold">Responsive Offsets</div>
+              <div className="u-fs-sm u-mt-2">Changes at each breakpoint</div>
             </DemoCard>
           </GridCol>
         </Grid>
@@ -404,45 +455,55 @@ export const ColumnOffsets: Story = {
 export const Containers: Story = {
   render: () => (
     <div className="u-mb-8">
-      <h2 className="u-mb-6 u-text-brand-emphasis">Container Types</h2>
+      <h1 className="u-mb-6 u-text-brand-emphasis u-border-bottom u-pb-2">Container Types</h1>
 
       {/* Default Container */}
       <div className="u-mb-8">
-        <h3 className="u-mb-1 u-text-brand-emphasis">Default Container</h3>
+        <h2 className="u-mb-4 u-text-brand-emphasis">Default Container</h2>
         <p className="u-mb-4 u-text-secondary-emphasis">
           Responsive container with max-width at each breakpoint:
         </p>
 
-        <Container className="u-mb-6">
+        <Container className="u-mb-4">
           <DemoCard variant="accent" height="md">
-            <div>Default Container</div>
-            <div className="u-fs-sm u-text-secondary-emphasis">Responsive max-width, centered</div>
+            <div className="u-fs-lg u-fw-bold">Default Container</div>
+            <div className="u-fs-sm u-text-secondary-emphasis u-mt-2">
+              Responsive max-width, centered
+            </div>
           </DemoCard>
         </Container>
       </div>
 
       {/* Fluid Container */}
       <div className="u-mb-8">
-        <h3 className="u-mb-1 u-text-brand-emphasis">Fluid Container</h3>
+        <h2 className="u-mb-4 u-text-brand-emphasis">Fluid Container</h2>
         <p className="u-mb-4 u-text-secondary-emphasis">
           Full-width container that spans the entire viewport:
         </p>
 
-        <Container type="fluid" className="u-mb-6">
+        <Container type="fluid" className="u-mb-4">
           <DemoCard variant="secondary" height="md">
-            <div>Fluid Container</div>
-            <div className="u-fs-sm u-text-secondary-emphasis">Full viewport width</div>
+            <div className="u-fs-lg u-fw-bold">Fluid Container</div>
+            <div className="u-fs-sm u-text-secondary-emphasis u-mt-2">
+              Full viewport width
+            </div>
           </DemoCard>
         </Container>
       </div>
 
       {/* Breakpoint Containers */}
       <div className="u-mb-8">
-        <h3 className="u-mb-1 u-text-brand-emphasis">Breakpoint Containers</h3>
+        <h2 className="u-mb-4 u-text-brand-emphasis">Breakpoint Containers</h2>
         <p className="u-mb-4 u-text-secondary-emphasis">
           Containers with max-width at specific breakpoints:
         </p>
 
+        <div className="u-mb-4">
+          <Callout variant="info" className="u-mb-4">
+            Each container below has a different max-width based on its type.
+          </Callout>
+        </div>
+
         <Container type="sm" className="u-mb-4">
           <DemoCard variant="secondary">Small Container (max-width: sm)</DemoCard>
         </Container>
@@ -458,12 +519,12 @@ export const Containers: Story = {
 
       {/* Container with Grid */}
       <div className="u-mb-8">
-        <h3 className="u-mb-1 u-text-brand-emphasis">Container with Grid</h3>
+        <h2 className="u-mb-4 u-text-brand-emphasis">Container with Grid</h2>
         <p className="u-mb-4 u-text-secondary-emphasis">
           Combine containers with grids for structured layouts:
         </p>
 
-        <Container className="u-mb-6">
+        <Container className="u-mb-4">
           <Grid>
             <GridCol xs={12} md={4}>
               <DemoCard>Column 1</DemoCard>
@@ -489,18 +550,18 @@ export const Containers: Story = {
 export const AlignmentAndSpacing: Story = {
   render: () => (
     <div className="u-mb-8">
-      <h2 className="u-mb-6 u-text-brand-emphasis">Alignment & Spacing</h2>
+      <h1 className="u-mb-6 u-text-brand-emphasis u-border-bottom u-pb-2">Alignment & Spacing</h1>
 
       {/* Horizontal Alignment */}
       <div className="u-mb-8">
-        <h3 className="u-mb-1 u-text-brand-emphasis">Horizontal Alignment</h3>
+        <h2 className="u-mb-4 u-text-brand-emphasis">Horizontal Alignment</h2>
         <p className="u-mb-4 u-text-secondary-emphasis">
           Control how columns are distributed horizontally:
         </p>
 
-        <div className="u-mb-4">
-          <h4 className="u-mb-3 u-text-secondary-emphasis u-fw-medium">justify-content="start"</h4>
-          <Row justifyContent="start" className="u-mb-4">
+        <div className="u-mb-6">
+          <h3 className="u-mb-3 u-text-secondary-emphasis u-fw-medium">justify-content="start"</h3>
+          <Row justifyContent="start" className="u-mb-4 u-p-3 u-bg-brand-subtle u-rounded">
             <GridCol xs={3}>
               <DemoCard variant="secondary">Col 1</DemoCard>
             </GridCol>
@@ -510,9 +571,9 @@ export const AlignmentAndSpacing: Story = {
           </Row>
         </div>
 
-        <div className="u-mb-4">
-          <h4 className="u-mb-3 u-text-secondary-emphasis u-fw-medium">justify-content="center"</h4>
-          <Row justifyContent="center" className="u-mb-4">
+        <div className="u-mb-6">
+          <h3 className="u-mb-3 u-text-secondary-emphasis u-fw-medium">justify-content="center"</h3>
+          <Row justifyContent="center" className="u-mb-4 u-p-3 u-bg-brand-subtle u-rounded">
             <GridCol xs={3}>
               <DemoCard variant="secondary">Col 1</DemoCard>
             </GridCol>
@@ -522,11 +583,11 @@ export const AlignmentAndSpacing: Story = {
           </Row>
         </div>
 
-        <div className="u-mb-4">
-          <h4 className="u-mb-3 u-text-secondary-emphasis u-fw-medium">
+        <div className="u-mb-6">
+          <h3 className="u-mb-3 u-text-secondary-emphasis u-fw-medium">
             justify-content="between"
-          </h4>
-          <Row justifyContent="between" className="u-mb-4">
+          </h3>
+          <Row justifyContent="between" className="u-mb-4 u-p-3 u-bg-brand-subtle u-rounded">
             <GridCol xs={3}>
               <DemoCard variant="secondary">Col 1</DemoCard>
             </GridCol>
@@ -537,8 +598,8 @@ export const AlignmentAndSpacing: Story = {
         </div>
 
         <div className="u-mb-6">
-          <h4 className="u-mb-3 u-text-secondary-emphasis u-fw-medium">justify-content="around"</h4>
-          <Row justifyContent="around" className="u-mb-4">
+          <h3 className="u-mb-3 u-text-secondary-emphasis u-fw-medium">justify-content="around"</h3>
+          <Row justifyContent="around" className="u-mb-4 u-p-3 u-bg-brand-subtle u-rounded">
             <GridCol xs={3}>
               <DemoCard variant="secondary">Col 1</DemoCard>
             </GridCol>
@@ -551,17 +612,17 @@ export const AlignmentAndSpacing: Story = {
 
       {/* Vertical Alignment */}
       <div className="u-mb-8">
-        <h3 className="u-mb-1 u-text-brand-emphasis">Vertical Alignment</h3>
+        <h2 className="u-mb-4 u-text-brand-emphasis">Vertical Alignment</h2>
         <p className="u-mb-4 u-text-secondary-emphasis">
           Control how columns align vertically when they have different heights:
         </p>
 
-        <div className="u-mb-4">
-          <h4 className="u-mb-3 u-text-secondary-emphasis u-fw-medium">align-items="start"</h4>
+        <div className="u-mb-6">
+          <h3 className="u-mb-3 u-text-secondary-emphasis u-fw-medium">align-items="start"</h3>
           <Row
             alignItems="start"
-            className="u-mb-4 u-bg-brand-subtle"
-            style={{ minHeight: '150px' }}
+            className="u-mb-4 u-bg-brand-subtle u-rounded u-p-3"
+            style={{ minHeight: '180px' }}
           >
             <GridCol xs={4}>
               <DemoCard height="sm">Short</DemoCard>
@@ -575,12 +636,12 @@ export const AlignmentAndSpacing: Story = {
           </Row>
         </div>
 
-        <div className="u-mb-4">
-          <h4 className="u-mb-3 u-text-secondary-emphasis u-fw-medium">align-items="center"</h4>
+        <div className="u-mb-6">
+          <h3 className="u-mb-3 u-text-secondary-emphasis u-fw-medium">align-items="center"</h3>
           <Row
             alignItems="center"
-            className="u-mb-4 u-bg-brand-subtle"
-            style={{ minHeight: '150px' }}
+            className="u-mb-4 u-bg-brand-subtle u-rounded u-p-3"
+            style={{ minHeight: '180px' }}
           >
             <GridCol xs={4}>
               <DemoCard height="sm">Short</DemoCard>
@@ -595,8 +656,12 @@ export const AlignmentAndSpacing: Story = {
         </div>
 
         <div className="u-mb-6">
-          <h4 className="u-mb-3 u-text-secondary-emphasis u-fw-medium">align-items="end"</h4>
-          <Row alignItems="end" className="u-mb-4 u-bg-brand-subtle" style={{ minHeight: '150px' }}>
+          <h3 className="u-mb-3 u-text-secondary-emphasis u-fw-medium">align-items="end"</h3>
+          <Row
+            alignItems="end"
+            className="u-mb-4 u-bg-brand-subtle u-rounded u-p-3"
+            style={{ minHeight: '180px' }}
+          >
             <GridCol xs={4}>
               <DemoCard height="sm">Short</DemoCard>
             </GridCol>
@@ -612,12 +677,14 @@ export const AlignmentAndSpacing: Story = {
 
       {/* No Gutters */}
       <div className="u-mb-8">
-        <h3 className="u-mb-1 u-text-brand-emphasis">No Gutters</h3>
-        <p className="u-mb-4 u-text-secondary-emphasis">Remove spacing between columns:</p>
+        <h2 className="u-mb-4 u-text-brand-emphasis">No Gutters</h2>
+        <p className="u-mb-4 u-text-secondary-emphasis">
+          Remove spacing between columns:
+        </p>
 
-        <div className="u-mb-4">
-          <h4 className="u-mb-3 u-text-secondary-emphasis u-fw-medium">With gutters (default)</h4>
-          <Row className="u-mb-4">
+        <div className="u-mb-6">
+          <h3 className="u-mb-3 u-text-secondary-emphasis u-fw-medium">With gutters (default)</h3>
+          <Row className="u-mb-4 u-p-3 u-bg-brand-subtle u-rounded">
             <GridCol xs={4}>
               <DemoCard variant="secondary">Column 1</DemoCard>
             </GridCol>
@@ -631,8 +698,8 @@ export const AlignmentAndSpacing: Story = {
         </div>
 
         <div className="u-mb-6">
-          <h4 className="u-mb-3 u-text-secondary-emphasis u-fw-medium">No gutters</h4>
-          <Row noGutters className="u-mb-4">
+          <h3 className="u-mb-3 u-text-secondary-emphasis u-fw-medium">No gutters</h3>
+          <Row noGutters className="u-mb-4 u-p-3 u-bg-brand-subtle u-rounded">
             <GridCol xs={4}>
               <DemoCard variant="accent">Column 1</DemoCard>
             </GridCol>
@@ -657,16 +724,16 @@ export const AlignmentAndSpacing: Story = {
 export const NestedGrids: Story = {
   render: () => (
     <div className="u-mb-8">
-      <h2 className="u-mb-6 u-text-brand-emphasis">Nested Grids</h2>
+      <h1 className="u-mb-6 u-text-brand-emphasis u-border-bottom u-pb-2">Nested Grids</h1>
       <p className="u-mb-6 u-text-secondary-emphasis">
         Create complex layouts by nesting grids within columns. Each nested grid starts fresh with
         12 columns.
       </p>
 
-      <Grid>
+      <Grid className="u-mb-6">
         <GridCol xs={12} md={6}>
-          <div className="u-p-4 u-border u-rounded u-bg-info-subtle u-mb-4">
-            <h4 className="u-mb-4 u-text-info-emphasis">Left Section</h4>
+          <Card className="u-mb-4 u-bg-info-subtle">
+            <h3 className="u-mb-4 u-text-info-emphasis">Left Section</h3>
             <Grid>
               <GridCol xs={12} className="u-mb-4">
                 <DemoCard variant="secondary">Nested Full Width</DemoCard>
@@ -678,12 +745,12 @@ export const NestedGrids: Story = {
                 <DemoCard variant="secondary">Nested 1/2</DemoCard>
               </GridCol>
             </Grid>
-          </div>
+          </Card>
         </GridCol>
 
         <GridCol xs={12} md={6}>
-          <div className="u-p-4 u-border u-rounded u-bg-success-subtle u-mb-4">
-            <h4 className="u-mb-4 u-text-success-emphasis">Right Section</h4>
+          <Card className="u-mb-4 u-bg-success-subtle">
+            <h3 className="u-mb-4 u-text-success-emphasis">Right Section</h3>
             <Grid>
               <GridCol xs={4}>
                 <DemoCard variant="accent">1/3</DemoCard>
@@ -695,20 +762,20 @@ export const NestedGrids: Story = {
                 <DemoCard variant="accent">1/3</DemoCard>
               </GridCol>
             </Grid>
-          </div>
+          </Card>
         </GridCol>
       </Grid>
 
       <div className="u-mt-8">
-        <h3 className="u-mb-1 u-text-brand-emphasis">Complex Nested Example</h3>
+        <h2 className="u-mb-4 u-text-brand-emphasis">Complex Nested Example</h2>
         <p className="u-mb-4 u-text-brand-emphasis">
           Dashboard-style layout with multiple levels of nesting:
         </p>
 
         <Grid>
           <GridCol xs={12}>
-            <div className="u-p-4 u-border u-rounded u-bg-warning-subtle u-mb-4">
-              <h4 className="u-mb-4 u-text-warning-emphasis">Header</h4>
+            <Card className="u-mb-4 u-bg-warning-subtle">
+              <h3 className="u-mb-4 u-text-warning-emphasis">Header</h3>
               <Grid>
                 <GridCol xs={12} sm={6} md={8}>
                   <DemoCard variant="secondary">Logo & Navigation</DemoCard>
@@ -717,12 +784,12 @@ export const NestedGrids: Story = {
                   <DemoCard variant="secondary">User Actions</DemoCard>
                 </GridCol>
               </Grid>
-            </div>
+            </Card>
           </GridCol>
 
           <GridCol xs={12} md={3}>
-            <div className="u-p-4 u-border u-rounded u-bg-info-subtle u-mb-4">
-              <h4 className="u-mb-4 u-text-info-emphasis">Sidebar</h4>
+            <Card className="u-mb-4 u-bg-info-subtle">
+              <h3 className="u-mb-4 u-text-info-emphasis">Sidebar</h3>
               <Grid>
                 <GridCol xs={12} className="u-mb-2">
                   <DemoCard variant="accent" height="sm">
@@ -740,12 +807,12 @@ export const NestedGrids: Story = {
                   </DemoCard>
                 </GridCol>
               </Grid>
-            </div>
+            </Card>
           </GridCol>
 
           <GridCol xs={12} md={9}>
-            <div className="u-p-4 u-border u-rounded u-bg-success-subtle">
-              <h4 className="u-mb-4 u-text-success-emphasis">Main Content</h4>
+            <Card className="u-bg-success-subtle">
+              <h3 className="u-mb-4 u-text-success-emphasis">Main Content</h3>
               <Grid>
                 <GridCol xs={12} className="u-mb-4">
                   <DemoCard height="sm">Content Header</DemoCard>
@@ -760,7 +827,7 @@ export const NestedGrids: Story = {
                   <DemoCard variant="secondary">Widget 3</DemoCard>
                 </GridCol>
               </Grid>
-            </div>
+            </Card>
           </GridCol>
         </Grid>
       </div>
@@ -776,36 +843,36 @@ export const NestedGrids: Story = {
 export const BreakpointReference: Story = {
   render: () => (
     <div className="u-mb-8">
-      <h2 className="u-mb-6 u-text-brand-emphasis">Breakpoint Reference</h2>
+      <h1 className="u-mb-6 u-text-brand-emphasis u-border-bottom u-pb-2">Breakpoint Reference</h1>
       <p className="u-mb-6 u-text-secondary-emphasis">
         The grid system uses these breakpoints. Resize your browser to see how columns adapt.
       </p>
 
-      <div className="u-mb-6 u-p-4 u-border u-rounded u-bg-brand-subtle">
-        <h4 className="u-mb-4 u-text-brand-emphasis">Breakpoint Sizes</h4>
+      <Card className="u-mb-6">
+        <h3 className="u-mb-4 u-text-brand-emphasis">Breakpoint Sizes</h3>
         <ul className="u-text-secondary-emphasis">
-          <li>
+          <li className="u-mb-2">
             <strong>xs:</strong> 0px and up (all devices)
           </li>
-          <li>
+          <li className="u-mb-2">
             <strong>sm:</strong> 576px and up (tablets)
           </li>
-          <li>
+          <li className="u-mb-2">
             <strong>md:</strong> 768px and up (small laptops)
           </li>
-          <li>
+          <li className="u-mb-2">
             <strong>lg:</strong> 992px and up (large laptops)
           </li>
-          <li>
+          <li className="u-mb-2">
             <strong>xl:</strong> 1200px and up (desktops)
           </li>
           <li>
             <strong>xxl:</strong> 1440px and up (large desktops)
           </li>
         </ul>
-      </div>
+      </Card>
 
-      <h3 className="u-mb-1 u-text-brand-emphasis">Responsive Behavior Demo</h3>
+      <h2 className="u-mb-4 u-text-brand-emphasis">Responsive Behavior Demo</h2>
       <p className="u-mb-4 u-text-secondary-emphasis">
         These columns show different layouts at each breakpoint:
       </p>
@@ -814,48 +881,48 @@ export const BreakpointReference: Story = {
         <GridCol xs={12} sm={6} md={4} lg={3} xl={2}>
           <DemoCard variant="secondary">
             <div className="u-fw-bold">Column 1</div>
-            <div className="u-fs-sm">xs=12, sm=6, md=4, lg=3, xl=2</div>
+            <div className="u-fs-sm u-mt-2">xs=12, sm=6, md=4, lg=3, xl=2</div>
           </DemoCard>
         </GridCol>
         <GridCol xs={12} sm={6} md={4} lg={3} xl={2}>
           <DemoCard variant="secondary">
             <div className="u-fw-bold">Column 2</div>
-            <div className="u-fs-sm">xs=12, sm=6, md=4, lg=3, xl=2</div>
+            <div className="u-fs-sm u-mt-2">xs=12, sm=6, md=4, lg=3, xl=2</div>
           </DemoCard>
         </GridCol>
         <GridCol xs={12} sm={6} md={4} lg={3} xl={2}>
           <DemoCard variant="secondary">
             <div className="u-fw-bold">Column 3</div>
-            <div className="u-fs-sm">xs=12, sm=6, md=4, lg=3, xl=2</div>
+            <div className="u-fs-sm u-mt-2">xs=12, sm=6, md=4, lg=3, xl=2</div>
           </DemoCard>
         </GridCol>
         <GridCol xs={12} sm={6} md={4} lg={3} xl={2}>
           <DemoCard variant="secondary">
             <div className="u-fw-bold">Column 4</div>
-            <div className="u-fs-sm">xs=12, sm=6, md=4, lg=3, xl=2</div>
+            <div className="u-fs-sm u-mt-2">xs=12, sm=6, md=4, lg=3, xl=2</div>
           </DemoCard>
         </GridCol>
         <GridCol xs={12} sm={6} md={4} lg={3} xl={2}>
           <DemoCard variant="secondary">
             <div className="u-fw-bold">Column 5</div>
-            <div className="u-fs-sm">xs=12, sm=6, md=4, lg=3, xl=2</div>
+            <div className="u-fs-sm u-mt-2">xs=12, sm=6, md=4, lg=3, xl=2</div>
           </DemoCard>
         </GridCol>
         <GridCol xs={12} sm={6} md={4} lg={3} xl={2}>
           <DemoCard variant="secondary">
             <div className="u-fw-bold">Column 6</div>
-            <div className="u-fs-sm">xs=12, sm=6, md=4, lg=3, xl=2</div>
+            <div className="u-fs-sm u-mt-2">xs=12, sm=6, md=4, lg=3, xl=2</div>
           </DemoCard>
         </GridCol>
       </Grid>
 
-      <div className="u-p-4 u-border u-rounded u-bg-warning-subtle">
-        <h4 className="u-mb-3 u-text-brand-emphasis">Current Breakpoint</h4>
+      <Card>
+        <h3 className="u-mb-3 u-text-brand-emphasis">Current Breakpoint</h3>
         <p className="u-text-secondary-emphasis u-mb-0">
           Resize your browser window to see how the columns above adapt to different screen sizes.
           The grid system automatically adjusts the layout based on the available space.
         </p>
-      </div>
+      </Card>
     </div>
   ),
 };