@hubspot/cms-component-library 0.1.0 → 0.2.0

package/components/componentLibrary/Grid/stories/Grid.stories.tsx

@@ -1,5 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react';
-import Grid from '../index.js';
+import Grid, { GridItem } from '../index.js';
 import { GridProps } from '../types.js';
 import { withGridStyles } from './GridDecorator.js';
 import { SBContainer } from '@sb-utils/SBContainer.js';
@@ -29,12 +29,12 @@ export const Default: Story = {
     gap: '16px',
     children: (
       <>
-        <SBDemoBox>Box 1</SBDemoBox>
-        <SBDemoBox>Box 2</SBDemoBox>
-        <SBDemoBox>Box 3</SBDemoBox>
-        <SBDemoBox>Box 4</SBDemoBox>
-        <SBDemoBox>Box 5</SBDemoBox>
-        <SBDemoBox>Box 6</SBDemoBox>
+        <GridItem as={SBDemoBox}>Box 1</GridItem>
+        <GridItem as={SBDemoBox}>Box 2</GridItem>
+        <GridItem as={SBDemoBox}>Box 3</GridItem>
+        <GridItem as={SBDemoBox}>Box 4</GridItem>
+        <GridItem as={SBDemoBox}>Box 5</GridItem>
+        <GridItem as={SBDemoBox}>Box 6</GridItem>
       </>
     ),
   },
@@ -48,12 +48,12 @@ export const TemplateColumns: Story = {
         <h4>Equal Columns (repeat)</h4>
         <p>3 equal columns using repeat(3, 1fr)</p>
         <Grid templateColumns="repeat(3, 1fr)" gap="16px">
-          <SBDemoBox>1</SBDemoBox>
-          <SBDemoBox>2</SBDemoBox>
-          <SBDemoBox>3</SBDemoBox>
-          <SBDemoBox>4</SBDemoBox>
-          <SBDemoBox>5</SBDemoBox>
-          <SBDemoBox>6</SBDemoBox>
+          <GridItem as={SBDemoBox}>1</GridItem>
+          <GridItem as={SBDemoBox}>2</GridItem>
+          <GridItem as={SBDemoBox}>3</GridItem>
+          <GridItem as={SBDemoBox}>4</GridItem>
+          <GridItem as={SBDemoBox}>5</GridItem>
+          <GridItem as={SBDemoBox}>6</GridItem>
         </Grid>
       </SBContainer>
 
@@ -61,9 +61,9 @@ export const TemplateColumns: Story = {
         <h4>Fixed and Flexible Columns</h4>
         <p>200px, auto, 1fr - fixed, content-fit, and flexible</p>
         <Grid templateColumns="200px auto 1fr" gap="16px">
-          <SBDemoBox>200px</SBDemoBox>
-          <SBDemoBox>Auto</SBDemoBox>
-          <SBDemoBox>1fr</SBDemoBox>
+          <GridItem as={SBDemoBox}>200px</GridItem>
+          <GridItem as={SBDemoBox}>Auto</GridItem>
+          <GridItem as={SBDemoBox}>1fr</GridItem>
         </Grid>
       </SBContainer>
 
@@ -71,11 +71,11 @@ export const TemplateColumns: Story = {
         <h4>Responsive Columns (auto-fit)</h4>
         <p>Automatically fits columns, minimum 150px each</p>
         <Grid templateColumns="repeat(auto-fit, minmax(150px, 1fr))" gap="16px">
-          <SBDemoBox>1</SBDemoBox>
-          <SBDemoBox>2</SBDemoBox>
-          <SBDemoBox>3</SBDemoBox>
-          <SBDemoBox>4</SBDemoBox>
-          <SBDemoBox>5</SBDemoBox>
+          <GridItem as={SBDemoBox}>1</GridItem>
+          <GridItem as={SBDemoBox}>2</GridItem>
+          <GridItem as={SBDemoBox}>3</GridItem>
+          <GridItem as={SBDemoBox}>4</GridItem>
+          <GridItem as={SBDemoBox}>5</GridItem>
         </Grid>
       </SBContainer>
 
@@ -86,9 +86,9 @@ export const TemplateColumns: Story = {
           templateColumns="repeat(auto-fill, minmax(100px, 1fr))"
           gap="16px"
         >
-          <SBDemoBox>1</SBDemoBox>
-          <SBDemoBox>2</SBDemoBox>
-          <SBDemoBox>3</SBDemoBox>
+          <GridItem as={SBDemoBox}>1</GridItem>
+          <GridItem as={SBDemoBox}>2</GridItem>
+          <GridItem as={SBDemoBox}>3</GridItem>
         </Grid>
       </SBContainer>
     </SBContainer>
@@ -107,12 +107,12 @@ export const TemplateRows: Story = {
           templateRows="repeat(2, 100px)"
           gap="16px"
         >
-          <SBDemoBox>1</SBDemoBox>
-          <SBDemoBox>2</SBDemoBox>
-          <SBDemoBox>3</SBDemoBox>
-          <SBDemoBox>4</SBDemoBox>
-          <SBDemoBox>5</SBDemoBox>
-          <SBDemoBox>6</SBDemoBox>
+          <GridItem as={SBDemoBox}>1</GridItem>
+          <GridItem as={SBDemoBox}>2</GridItem>
+          <GridItem as={SBDemoBox}>3</GridItem>
+          <GridItem as={SBDemoBox}>4</GridItem>
+          <GridItem as={SBDemoBox}>5</GridItem>
+          <GridItem as={SBDemoBox}>6</GridItem>
         </Grid>
       </SBContainer>
 
@@ -125,9 +125,9 @@ export const TemplateRows: Story = {
           gap="16px"
           style={{ height: '300px' }}
         >
-          <SBDemoBox>Header</SBDemoBox>
-          <SBDemoBox>Main Content (fills space)</SBDemoBox>
-          <SBDemoBox>Footer</SBDemoBox>
+          <GridItem as={SBDemoBox}>Header</GridItem>
+          <GridItem as={SBDemoBox}>Main Content (fills space)</GridItem>
+          <GridItem as={SBDemoBox}>Footer</GridItem>
         </Grid>
       </SBContainer>
     </SBContainer>
@@ -142,11 +142,11 @@ export const AutoFlow: Story = {
         <h4>Row Flow (Default)</h4>
         <p>Items flow horizontally across rows</p>
         <Grid templateColumns="repeat(3, 1fr)" autoFlow="row" gap="16px">
-          <SBDemoBox>1</SBDemoBox>
-          <SBDemoBox>2</SBDemoBox>
-          <SBDemoBox>3</SBDemoBox>
-          <SBDemoBox>4</SBDemoBox>
-          <SBDemoBox>5</SBDemoBox>
+          <GridItem as={SBDemoBox}>1</GridItem>
+          <GridItem as={SBDemoBox}>2</GridItem>
+          <GridItem as={SBDemoBox}>3</GridItem>
+          <GridItem as={SBDemoBox}>4</GridItem>
+          <GridItem as={SBDemoBox}>5</GridItem>
         </Grid>
       </SBContainer>
 
@@ -154,11 +154,11 @@ export const AutoFlow: Story = {
         <h4>Column Flow</h4>
         <p>Items flow vertically down columns</p>
         <Grid templateRows="repeat(3, 1fr)" autoFlow="column" gap="16px">
-          <SBDemoBox>1</SBDemoBox>
-          <SBDemoBox>2</SBDemoBox>
-          <SBDemoBox>3</SBDemoBox>
-          <SBDemoBox>4</SBDemoBox>
-          <SBDemoBox>5</SBDemoBox>
+          <GridItem as={SBDemoBox}>1</GridItem>
+          <GridItem as={SBDemoBox}>2</GridItem>
+          <GridItem as={SBDemoBox}>3</GridItem>
+          <GridItem as={SBDemoBox}>4</GridItem>
+          <GridItem as={SBDemoBox}>5</GridItem>
         </Grid>
       </SBContainer>
 
@@ -166,11 +166,15 @@ export const AutoFlow: Story = {
         <h4>Dense Packing</h4>
         <p>Fills gaps with smaller items</p>
         <Grid templateColumns="repeat(4, 1fr)" autoFlow="row dense" gap="16px">
-          <SBDemoBox style={{ gridColumn: 'span 2' }}>1 (spans 2)</SBDemoBox>
-          <SBDemoBox>2</SBDemoBox>
-          <SBDemoBox>3</SBDemoBox>
-          <SBDemoBox>4</SBDemoBox>
-          <SBDemoBox style={{ gridColumn: 'span 2' }}>5 (spans 2)</SBDemoBox>
+          <GridItem as={SBDemoBox} gridColumn="span 2">
+            1 (spans 2)
+          </GridItem>
+          <GridItem as={SBDemoBox}>2</GridItem>
+          <GridItem as={SBDemoBox}>3</GridItem>
+          <GridItem as={SBDemoBox}>4</GridItem>
+          <GridItem as={SBDemoBox} gridColumn="span 2">
+            5 (spans 2)
+          </GridItem>
         </Grid>
       </SBContainer>
     </SBContainer>
@@ -190,9 +194,9 @@ export const AlignItems: Story = {
           alignItems="stretch"
           gap="16px"
         >
-          <SBDemoBox>1</SBDemoBox>
-          <SBDemoBox>2</SBDemoBox>
-          <SBDemoBox>3</SBDemoBox>
+          <GridItem as={SBDemoBox}>1</GridItem>
+          <GridItem as={SBDemoBox}>2</GridItem>
+          <GridItem as={SBDemoBox}>3</GridItem>
         </Grid>
       </SBContainer>
 
@@ -205,9 +209,11 @@ export const AlignItems: Story = {
           alignItems="start"
           gap="16px"
         >
-          <SBDemoBox>1</SBDemoBox>
-          <SBDemoBox tall>2</SBDemoBox>
-          <SBDemoBox>3</SBDemoBox>
+          <GridItem as={SBDemoBox}>1</GridItem>
+          <GridItem as={SBDemoBox} tall>
+            2
+          </GridItem>
+          <GridItem as={SBDemoBox}>3</GridItem>
         </Grid>
       </SBContainer>
 
@@ -220,9 +226,11 @@ export const AlignItems: Story = {
           alignItems="center"
           gap="16px"
         >
-          <SBDemoBox>1</SBDemoBox>
-          <SBDemoBox tall>2</SBDemoBox>
-          <SBDemoBox>3</SBDemoBox>
+          <GridItem as={SBDemoBox}>1</GridItem>
+          <GridItem as={SBDemoBox} tall>
+            2
+          </GridItem>
+          <GridItem as={SBDemoBox}>3</GridItem>
         </Grid>
       </SBContainer>
 
@@ -235,9 +243,11 @@ export const AlignItems: Story = {
           alignItems="end"
           gap="16px"
         >
-          <SBDemoBox>1</SBDemoBox>
-          <SBDemoBox tall>2</SBDemoBox>
-          <SBDemoBox>3</SBDemoBox>
+          <GridItem as={SBDemoBox}>1</GridItem>
+          <GridItem as={SBDemoBox} tall>
+            2
+          </GridItem>
+          <GridItem as={SBDemoBox}>3</GridItem>
         </Grid>
       </SBContainer>
     </SBContainer>
@@ -256,9 +266,9 @@ export const JustifyContent: Story = {
           gap="16px"
           style={{ border: '2px dashed #ccc', padding: '16px' }}
         >
-          <SBDemoBox>1</SBDemoBox>
-          <SBDemoBox>2</SBDemoBox>
-          <SBDemoBox>3</SBDemoBox>
+          <GridItem as={SBDemoBox}>1</GridItem>
+          <GridItem as={SBDemoBox}>2</GridItem>
+          <GridItem as={SBDemoBox}>3</GridItem>
         </Grid>
       </SBContainer>
 
@@ -270,9 +280,9 @@ export const JustifyContent: Story = {
           gap="16px"
           style={{ border: '2px dashed #ccc', padding: '16px' }}
         >
-          <SBDemoBox>1</SBDemoBox>
-          <SBDemoBox>2</SBDemoBox>
-          <SBDemoBox>3</SBDemoBox>
+          <GridItem as={SBDemoBox}>1</GridItem>
+          <GridItem as={SBDemoBox}>2</GridItem>
+          <GridItem as={SBDemoBox}>3</GridItem>
         </Grid>
       </SBContainer>
 
@@ -284,9 +294,9 @@ export const JustifyContent: Story = {
           gap="16px"
           style={{ border: '2px dashed #ccc', padding: '16px' }}
         >
-          <SBDemoBox>1</SBDemoBox>
-          <SBDemoBox>2</SBDemoBox>
-          <SBDemoBox>3</SBDemoBox>
+          <GridItem as={SBDemoBox}>1</GridItem>
+          <GridItem as={SBDemoBox}>2</GridItem>
+          <GridItem as={SBDemoBox}>3</GridItem>
         </Grid>
       </SBContainer>
 
@@ -298,9 +308,9 @@ export const JustifyContent: Story = {
           gap="16px"
           style={{ border: '2px dashed #ccc', padding: '16px' }}
         >
-          <SBDemoBox>1</SBDemoBox>
-          <SBDemoBox>2</SBDemoBox>
-          <SBDemoBox>3</SBDemoBox>
+          <GridItem as={SBDemoBox}>1</GridItem>
+          <GridItem as={SBDemoBox}>2</GridItem>
+          <GridItem as={SBDemoBox}>3</GridItem>
         </Grid>
       </SBContainer>
 
@@ -312,9 +322,9 @@ export const JustifyContent: Story = {
           gap="16px"
           style={{ border: '2px dashed #ccc', padding: '16px' }}
         >
-          <SBDemoBox>1</SBDemoBox>
-          <SBDemoBox>2</SBDemoBox>
-          <SBDemoBox>3</SBDemoBox>
+          <GridItem as={SBDemoBox}>1</GridItem>
+          <GridItem as={SBDemoBox}>2</GridItem>
+          <GridItem as={SBDemoBox}>3</GridItem>
         </Grid>
       </SBContainer>
 
@@ -326,9 +336,9 @@ export const JustifyContent: Story = {
           gap="16px"
           style={{ border: '2px dashed #ccc', padding: '16px' }}
         >
-          <SBDemoBox>1</SBDemoBox>
-          <SBDemoBox>2</SBDemoBox>
-          <SBDemoBox>3</SBDemoBox>
+          <GridItem as={SBDemoBox}>1</GridItem>
+          <GridItem as={SBDemoBox}>2</GridItem>
+          <GridItem as={SBDemoBox}>3</GridItem>
         </Grid>
       </SBContainer>
     </SBContainer>
@@ -342,48 +352,48 @@ export const Gaps: Story = {
       <SBContainer addBackground>
         <h4>No Gap</h4>
         <Grid templateColumns="repeat(3, 1fr)">
-          <SBDemoBox>1</SBDemoBox>
-          <SBDemoBox>2</SBDemoBox>
-          <SBDemoBox>3</SBDemoBox>
-          <SBDemoBox>4</SBDemoBox>
-          <SBDemoBox>5</SBDemoBox>
-          <SBDemoBox>6</SBDemoBox>
+          <GridItem as={SBDemoBox}>1</GridItem>
+          <GridItem as={SBDemoBox}>2</GridItem>
+          <GridItem as={SBDemoBox}>3</GridItem>
+          <GridItem as={SBDemoBox}>4</GridItem>
+          <GridItem as={SBDemoBox}>5</GridItem>
+          <GridItem as={SBDemoBox}>6</GridItem>
         </Grid>
       </SBContainer>
 
       <SBContainer addBackground>
         <h4>8px Gap</h4>
         <Grid templateColumns="repeat(3, 1fr)" gap="8px">
-          <SBDemoBox>1</SBDemoBox>
-          <SBDemoBox>2</SBDemoBox>
-          <SBDemoBox>3</SBDemoBox>
-          <SBDemoBox>4</SBDemoBox>
-          <SBDemoBox>5</SBDemoBox>
-          <SBDemoBox>6</SBDemoBox>
+          <GridItem as={SBDemoBox}>1</GridItem>
+          <GridItem as={SBDemoBox}>2</GridItem>
+          <GridItem as={SBDemoBox}>3</GridItem>
+          <GridItem as={SBDemoBox}>4</GridItem>
+          <GridItem as={SBDemoBox}>5</GridItem>
+          <GridItem as={SBDemoBox}>6</GridItem>
         </Grid>
       </SBContainer>
 
       <SBContainer addBackground>
         <h4>16px Gap</h4>
         <Grid templateColumns="repeat(3, 1fr)" gap="16px">
-          <SBDemoBox>1</SBDemoBox>
-          <SBDemoBox>2</SBDemoBox>
-          <SBDemoBox>3</SBDemoBox>
-          <SBDemoBox>4</SBDemoBox>
-          <SBDemoBox>5</SBDemoBox>
-          <SBDemoBox>6</SBDemoBox>
+          <GridItem as={SBDemoBox}>1</GridItem>
+          <GridItem as={SBDemoBox}>2</GridItem>
+          <GridItem as={SBDemoBox}>3</GridItem>
+          <GridItem as={SBDemoBox}>4</GridItem>
+          <GridItem as={SBDemoBox}>5</GridItem>
+          <GridItem as={SBDemoBox}>6</GridItem>
         </Grid>
       </SBContainer>
 
       <SBContainer addBackground>
         <h4>24px Gap</h4>
         <Grid templateColumns="repeat(3, 1fr)" gap="24px">
-          <SBDemoBox>1</SBDemoBox>
-          <SBDemoBox>2</SBDemoBox>
-          <SBDemoBox>3</SBDemoBox>
-          <SBDemoBox>4</SBDemoBox>
-          <SBDemoBox>5</SBDemoBox>
-          <SBDemoBox>6</SBDemoBox>
+          <GridItem as={SBDemoBox}>1</GridItem>
+          <GridItem as={SBDemoBox}>2</GridItem>
+          <GridItem as={SBDemoBox}>3</GridItem>
+          <GridItem as={SBDemoBox}>4</GridItem>
+          <GridItem as={SBDemoBox}>5</GridItem>
+          <GridItem as={SBDemoBox}>6</GridItem>
         </Grid>
       </SBContainer>
     </SBContainer>
@@ -397,26 +407,26 @@ export const SemanticElements: Story = {
       <SBContainer addBackground>
         <h4>As Section</h4>
         <Grid as="section" templateColumns="repeat(3, 1fr)" gap="16px">
-          <SBDemoBox>Item 1</SBDemoBox>
-          <SBDemoBox>Item 2</SBDemoBox>
-          <SBDemoBox>Item 3</SBDemoBox>
+          <GridItem as={SBDemoBox}>Item 1</GridItem>
+          <GridItem as={SBDemoBox}>Item 2</GridItem>
+          <GridItem as={SBDemoBox}>Item 3</GridItem>
         </Grid>
       </SBContainer>
 
       <SBContainer addBackground>
         <h4>As Nav</h4>
         <Grid as="nav" templateColumns="repeat(3, 1fr)" gap="16px">
-          <SBDemoBox>Home</SBDemoBox>
-          <SBDemoBox>About</SBDemoBox>
-          <SBDemoBox>Contact</SBDemoBox>
+          <GridItem as={SBDemoBox}>Home</GridItem>
+          <GridItem as={SBDemoBox}>About</GridItem>
+          <GridItem as={SBDemoBox}>Contact</GridItem>
         </Grid>
       </SBContainer>
 
       <SBContainer addBackground>
         <h4>As Article</h4>
         <Grid as="article" templateColumns="1fr 2fr" gap="16px">
-          <SBDemoBox>Sidebar</SBDemoBox>
-          <SBDemoBox>Main Content</SBDemoBox>
+          <GridItem as={SBDemoBox}>Sidebar</GridItem>
+          <GridItem as={SBDemoBox}>Main Content</GridItem>
         </Grid>
       </SBContainer>
     </SBContainer>
@@ -430,10 +440,10 @@ export const InlineGrid: Story = {
       <SBContainer addBackground>
         <h4>Regular Grid (Block Level)</h4>
         <p>Before grid container</p>
-        <Grid templateColumns="repeat(3, 1fr)" gap="8px">
-          <SBDemoBox>1</SBDemoBox>
-          <SBDemoBox>2</SBDemoBox>
-          <SBDemoBox>3</SBDemoBox>
+        <Grid templateColumns="repeat(3, 1fr)" gap="8px" marginBlock="16px">
+          <GridItem as={SBDemoBox}>1</GridItem>
+          <GridItem as={SBDemoBox}>2</GridItem>
+          <GridItem as={SBDemoBox}>3</GridItem>
         </Grid>
         <p>After grid container</p>
       </SBContainer>
@@ -443,9 +453,9 @@ export const InlineGrid: Story = {
         <p>
           Before grid container{' '}
           <Grid inline templateColumns="repeat(3, 1fr)" gap="8px">
-            <SBDemoBox>1</SBDemoBox>
-            <SBDemoBox>2</SBDemoBox>
-            <SBDemoBox>3</SBDemoBox>
+            <GridItem as={SBDemoBox}>1</GridItem>
+            <GridItem as={SBDemoBox}>2</GridItem>
+            <GridItem as={SBDemoBox}>3</GridItem>
           </Grid>{' '}
           after grid container
         </p>
@@ -467,10 +477,14 @@ export const LayoutExamples: Story = {
           gap="16px"
           style={{ height: '400px' }}
         >
-          <SBDemoBox style={{ gridColumn: '1 / -1' }}>Header</SBDemoBox>
-          <SBDemoBox>Sidebar</SBDemoBox>
-          <SBDemoBox>Main Content</SBDemoBox>
-          <SBDemoBox style={{ gridColumn: '1 / -1' }}>Footer</SBDemoBox>
+          <GridItem as={SBDemoBox} gridColumn="1 / -1">
+            Header
+          </GridItem>
+          <GridItem as={SBDemoBox}>Sidebar</GridItem>
+          <GridItem as={SBDemoBox}>Main Content</GridItem>
+          <GridItem as={SBDemoBox} gridColumn="1 / -1">
+            Footer
+          </GridItem>
         </Grid>
       </SBContainer>
 
@@ -482,13 +496,13 @@ export const LayoutExamples: Story = {
           templateRows="repeat(2, 150px)"
           gap="16px"
         >
-          <SBDemoBox style={{ gridColumn: 'span 2', gridRow: 'span 2' }}>
+          <GridItem as={SBDemoBox} gridColumn="span 2" gridRow="span 2">
             Featured Article
-          </SBDemoBox>
-          <SBDemoBox>Article 2</SBDemoBox>
-          <SBDemoBox>Article 3</SBDemoBox>
-          <SBDemoBox>Article 4</SBDemoBox>
-          <SBDemoBox>Article 5</SBDemoBox>
+          </GridItem>
+          <GridItem as={SBDemoBox}>Article 2</GridItem>
+          <GridItem as={SBDemoBox}>Article 3</GridItem>
+          <GridItem as={SBDemoBox}>Article 4</GridItem>
+          <GridItem as={SBDemoBox}>Article 5</GridItem>
         </Grid>
       </SBContainer>
     </SBContainer>
@@ -514,12 +528,12 @@ export const ResponsiveGrid: Story = {
           templateColumnsLg="repeat(3, 1fr)"
           gap="16px"
         >
-          <SBDemoBox>Item 1</SBDemoBox>
-          <SBDemoBox>Item 2</SBDemoBox>
-          <SBDemoBox>Item 3</SBDemoBox>
-          <SBDemoBox>Item 4</SBDemoBox>
-          <SBDemoBox>Item 5</SBDemoBox>
-          <SBDemoBox>Item 6</SBDemoBox>
+          <GridItem as={SBDemoBox}>Item 1</GridItem>
+          <GridItem as={SBDemoBox}>Item 2</GridItem>
+          <GridItem as={SBDemoBox}>Item 3</GridItem>
+          <GridItem as={SBDemoBox}>Item 4</GridItem>
+          <GridItem as={SBDemoBox}>Item 5</GridItem>
+          <GridItem as={SBDemoBox}>Item 6</GridItem>
         </Grid>
       </SBContainer>
 
@@ -532,12 +546,12 @@ export const ResponsiveGrid: Story = {
           gapMd="16px"
           gapLg="24px"
         >
-          <SBDemoBox>1</SBDemoBox>
-          <SBDemoBox>2</SBDemoBox>
-          <SBDemoBox>3</SBDemoBox>
-          <SBDemoBox>4</SBDemoBox>
-          <SBDemoBox>5</SBDemoBox>
-          <SBDemoBox>6</SBDemoBox>
+          <GridItem as={SBDemoBox}>1</GridItem>
+          <GridItem as={SBDemoBox}>2</GridItem>
+          <GridItem as={SBDemoBox}>3</GridItem>
+          <GridItem as={SBDemoBox}>4</GridItem>
+          <GridItem as={SBDemoBox}>5</GridItem>
+          <GridItem as={SBDemoBox}>6</GridItem>
         </Grid>
       </SBContainer>
 
@@ -552,11 +566,11 @@ export const ResponsiveGrid: Story = {
           autoFlowLg="row"
           gap="16px"
         >
-          <SBDemoBox>1</SBDemoBox>
-          <SBDemoBox>2</SBDemoBox>
-          <SBDemoBox>3</SBDemoBox>
-          <SBDemoBox>4</SBDemoBox>
-          <SBDemoBox>5</SBDemoBox>
+          <GridItem as={SBDemoBox}>1</GridItem>
+          <GridItem as={SBDemoBox}>2</GridItem>
+          <GridItem as={SBDemoBox}>3</GridItem>
+          <GridItem as={SBDemoBox}>4</GridItem>
+          <GridItem as={SBDemoBox}>5</GridItem>
         </Grid>
       </SBContainer>
 
@@ -571,9 +585,9 @@ export const ResponsiveGrid: Story = {
           alignItemsLg="start"
           gap="16px"
         >
-          <SBDemoBox>1</SBDemoBox>
-          <SBDemoBox>2</SBDemoBox>
-          <SBDemoBox>3</SBDemoBox>
+          <GridItem as={SBDemoBox}>1</GridItem>
+          <GridItem as={SBDemoBox}>2</GridItem>
+          <GridItem as={SBDemoBox}>3</GridItem>
         </Grid>
       </SBContainer>
 
@@ -586,16 +600,304 @@ export const ResponsiveGrid: Story = {
           templateColumns="1fr"
           templateColumnsMd="200px 1fr"
           templateColumnsLg="250px 1fr"
-          templateRows="auto 1fr auto"
+          templateRows="auto auto auto auto"
+          templateRowsMd="auto 1fr auto"
           gap="12px"
           gapMd="16px"
           gapLg="24px"
           style={{ height: '400px' }}
         >
-          <SBDemoBox style={{ gridColumn: '1 / -1' }}>Header</SBDemoBox>
-          <SBDemoBox>Sidebar</SBDemoBox>
-          <SBDemoBox>Main Content</SBDemoBox>
-          <SBDemoBox style={{ gridColumn: '1 / -1' }}>Footer</SBDemoBox>
+          <GridItem as={SBDemoBox} gridColumn="1 / -1">
+            Header
+          </GridItem>
+          <GridItem as={SBDemoBox}>Sidebar</GridItem>
+          <GridItem as={SBDemoBox} style={{ paddingBottom: '32px' }}>
+            Main Content
+          </GridItem>
+          <GridItem as={SBDemoBox} gridColumn="1 / -1">
+            Footer
+          </GridItem>
+        </Grid>
+      </SBContainer>
+    </SBContainer>
+  ),
+};
+
+export const GridItemPlacement: Story = {
+  name: 'GridItem - Column & Row Placement',
+  render: () => (
+    <SBContainer flex direction="column" gap="extralarge" minWidth="600px">
+      <SBContainer addBackground>
+        <h4>Column Spanning</h4>
+        <p>Use gridColumn prop to span multiple columns</p>
+        <Grid templateColumns="repeat(4, 1fr)" gap="16px">
+          <GridItem as={SBDemoBox} gridColumn="span 2">
+            Spans 2 columns
+          </GridItem>
+          <GridItem as={SBDemoBox}>Auto</GridItem>
+          <GridItem as={SBDemoBox}>Auto</GridItem>
+          <GridItem as={SBDemoBox} gridColumn="span 3">
+            Spans 3 columns
+          </GridItem>
+          <GridItem as={SBDemoBox}>Auto</GridItem>
+        </Grid>
+      </SBContainer>
+
+      <SBContainer addBackground>
+        <h4>Explicit Placement</h4>
+        <p>Use gridColumn and gridRow to place items at specific positions</p>
+        <Grid
+          templateColumns="repeat(3, 1fr)"
+          templateRows="repeat(3, 100px)"
+          gap="16px"
+        >
+          <GridItem as={SBDemoBox} gridColumn="1" gridRow="1">
+            1,1
+          </GridItem>
+          <GridItem as={SBDemoBox} gridColumn="3" gridRow="1">
+            3,1
+          </GridItem>
+          <GridItem as={SBDemoBox} gridColumn="2" gridRow="2">
+            2,2 (center)
+          </GridItem>
+          <GridItem as={SBDemoBox} gridColumn="1" gridRow="3">
+            1,3
+          </GridItem>
+          <GridItem as={SBDemoBox} gridColumn="3" gridRow="3">
+            3,3
+          </GridItem>
+        </Grid>
+      </SBContainer>
+
+      <SBContainer addBackground>
+        <h4>Line-Based Placement</h4>
+        <p>Use line numbers for precise control</p>
+        <Grid
+          templateColumns="repeat(4, 1fr)"
+          templateRows="repeat(2, 100px)"
+          gap="16px"
+        >
+          <GridItem as={SBDemoBox} gridColumn="1 / 3" gridRow="1">
+            Columns 1-3
+          </GridItem>
+          <GridItem as={SBDemoBox} gridColumn="3 / 5" gridRow="1 / 3">
+            Columns 3-5, Rows 1-3
+          </GridItem>
+          <GridItem as={SBDemoBox} gridColumn="1 / 3" gridRow="2">
+            Columns 1-3, Row 2
+          </GridItem>
+        </Grid>
+      </SBContainer>
+    </SBContainer>
+  ),
+};
+
+export const GridItemAlignment: Story = {
+  name: 'GridItem - Individual Alignment',
+  render: () => (
+    <SBContainer flex direction="column" gap="extralarge" minWidth="600px">
+      <SBContainer addBackground>
+        <h4>Align Self</h4>
+        <p>Override grid-level alignment for individual items</p>
+        <Grid
+          templateColumns="repeat(3, 1fr)"
+          templateRows="150px"
+          alignItems="stretch"
+          gap="16px"
+        >
+          <GridItem as={SBDemoBox} alignSelf="start">
+            Start
+          </GridItem>
+          <GridItem as={SBDemoBox} alignSelf="center">
+            Center
+          </GridItem>
+          <GridItem as={SBDemoBox} alignSelf="end">
+            End
+          </GridItem>
+        </Grid>
+      </SBContainer>
+
+      <SBContainer addBackground>
+        <h4>Justify Self</h4>
+        <p>Control horizontal alignment within grid cell</p>
+        <Grid templateColumns="repeat(3, 200px)" gap="16px">
+          <GridItem as={SBDemoBox} justifySelf="start">
+            Start
+          </GridItem>
+          <GridItem as={SBDemoBox} justifySelf="center">
+            Center
+          </GridItem>
+          <GridItem as={SBDemoBox} justifySelf="end">
+            End
+          </GridItem>
+        </Grid>
+      </SBContainer>
+
+      <SBContainer addBackground>
+        <h4>Combined Alignment</h4>
+        <p>Use both alignSelf and justifySelf together</p>
+        <Grid templateColumns="repeat(3, 1fr)" templateRows="150px" gap="16px">
+          <GridItem as={SBDemoBox} alignSelf="start" justifySelf="start">
+            Top Left
+          </GridItem>
+          <GridItem as={SBDemoBox} alignSelf="center" justifySelf="center">
+            Center
+          </GridItem>
+          <GridItem as={SBDemoBox} alignSelf="end" justifySelf="end">
+            Bottom Right
+          </GridItem>
+        </Grid>
+      </SBContainer>
+    </SBContainer>
+  ),
+};
+
+export const GridItemResponsive: Story = {
+  name: 'GridItem - Responsive Positioning',
+  render: () => (
+    <SBContainer flex direction="column" gap="extralarge" minWidth="600px">
+      <SBContainer addBackground>
+        <h4>Responsive Spanning</h4>
+        <p>
+          Mobile: full width | Tablet: spans 2 cols | Desktop: single column
+        </p>
+        <p style={{ fontSize: '12px', color: '#666' }}>
+          Resize browser to see changes
+        </p>
+        <Grid
+          templateColumns="1fr"
+          templateColumnsMd="repeat(3, 1fr)"
+          templateColumnsLg="repeat(4, 1fr)"
+          gap="16px"
+        >
+          <GridItem
+            as={SBDemoBox}
+            gridColumn="1"
+            gridColumnMd="span 2"
+            gridColumnLg="span 1"
+          >
+            Responsive Span
+          </GridItem>
+          <GridItem as={SBDemoBox}>Item 2</GridItem>
+          <GridItem as={SBDemoBox}>Item 3</GridItem>
+          <GridItem as={SBDemoBox}>Item 4</GridItem>
+        </Grid>
+      </SBContainer>
+
+      <SBContainer addBackground>
+        <h4>Responsive Position Changes</h4>
+        <p>Items change position at different breakpoints</p>
+        <Grid
+          templateColumns="1fr"
+          templateColumnsMd="repeat(2, 1fr)"
+          templateColumnsLg="repeat(3, 1fr)"
+          gap="16px"
+        >
+          <GridItem
+            as={SBDemoBox}
+            gridColumn="1"
+            gridColumnMd="2"
+            gridColumnLg="1"
+          >
+            Position changes
+          </GridItem>
+          <GridItem
+            as={SBDemoBox}
+            gridColumn="1"
+            gridColumnMd="1"
+            gridColumnLg="3"
+          >
+            Also repositions
+          </GridItem>
+          <GridItem as={SBDemoBox}>Auto placed</GridItem>
+        </Grid>
+      </SBContainer>
+
+      <SBContainer addBackground>
+        <h4>Responsive Alignment</h4>
+        <p>Alignment changes at different breakpoints</p>
+        <Grid templateColumns="repeat(3, 1fr)" templateRows="120px" gap="16px">
+          <GridItem
+            as={SBDemoBox}
+            alignSelf="start"
+            alignSelfMd="center"
+            alignSelfLg="end"
+          >
+            Changes alignment
+          </GridItem>
+          <GridItem
+            as={SBDemoBox}
+            justifySelf="start"
+            justifySelfMd="center"
+            justifySelfLg="end"
+          >
+            Shifts horizontally
+          </GridItem>
+          <GridItem as={SBDemoBox}>Regular item</GridItem>
+        </Grid>
+      </SBContainer>
+    </SBContainer>
+  ),
+};
+
+export const GridItemWithComponents: Story = {
+  name: 'GridItem - With Components (as prop)',
+  render: () => (
+    <SBContainer flex direction="column" gap="extralarge" minWidth="600px">
+      <SBContainer addBackground>
+        <h4>GridItem as Semantic Elements</h4>
+        <p>Use the `as` prop to render GridItem as different HTML elements</p>
+        <Grid as="section" templateColumns="repeat(2, 1fr)" gap="16px">
+          <GridItem as="article">
+            <div
+              style={{
+                padding: '16px',
+                background: '#f0f0f0',
+                borderRadius: '4px',
+              }}
+            >
+              Article element
+            </div>
+          </GridItem>
+          <GridItem as="aside">
+            <div
+              style={{
+                padding: '16px',
+                background: '#f0f0f0',
+                borderRadius: '4px',
+              }}
+            >
+              Aside element
+            </div>
+          </GridItem>
+          <GridItem as="header" gridColumn="1 / -1">
+            <div
+              style={{
+                padding: '16px',
+                background: '#f0f0f0',
+                borderRadius: '4px',
+              }}
+            >
+              Header element (full width)
+            </div>
+          </GridItem>
+        </Grid>
+      </SBContainer>
+
+      <SBContainer addBackground>
+        <h4>GridItem as Component</h4>
+        <p>Use GridItem with `as` prop to render as SBDemoBox component</p>
+        <Grid templateColumns="repeat(3, 1fr)" gap="16px">
+          <GridItem as={SBDemoBox} gridColumn="span 2">
+            GridItem as SBDemoBox (spans 2 columns)
+          </GridItem>
+          <GridItem as={SBDemoBox}>
+            GridItem as SBDemoBox (auto-placed)
+          </GridItem>
+          <GridItem as={SBDemoBox}>GridItem as SBDemoBox</GridItem>
+          <GridItem as={SBDemoBox} gridColumn="2 / 4">
+            GridItem as SBDemoBox (columns 2-4)
+          </GridItem>
         </Grid>
       </SBContainer>
     </SBContainer>