From 07c5295f884ecbb71bf1b72582540bd3c50d3859 Mon Sep 17 00:00:00 2001
From: Michael Taranto <michaeltaranto@users.noreply.github.com>
Date: Mon, 1 Jul 2024 15:23:54 +1000
Subject: [PATCH] site: Update layout guide content (#1528)

---
 .../src/lib/components/Bleed/Bleed.docs.tsx   | 192 +++++++++-----
 .../src/lib/components/Card/Card.docs.tsx     |   2 +-
 .../App/routes/foundations/layout/layout.tsx  | 241 +++++++++---------
 3 files changed, 252 insertions(+), 183 deletions(-)

diff --git a/packages/braid-design-system/src/lib/components/Bleed/Bleed.docs.tsx b/packages/braid-design-system/src/lib/components/Bleed/Bleed.docs.tsx
index 86181bd1da6..a71723bcd8b 100644
--- a/packages/braid-design-system/src/lib/components/Bleed/Bleed.docs.tsx
+++ b/packages/braid-design-system/src/lib/components/Bleed/Bleed.docs.tsx
@@ -1,14 +1,15 @@
 import React from 'react';
 import type { ComponentDocs } from 'site/types';
-import { Box, Bleed, Stack, Text, Strong, TextLink, Tiles } from '../';
+import { Box, Bleed, Stack, Text, Strong, TextLink, Tiles, Toggle } from '../';
 import { Placeholder } from '../../playroom/components';
 import source from '@braid-design-system/source.macro';
+import { vars } from '../../themes/vars.css';
 
 const docs: ComponentDocs = {
   category: 'Layout',
   Example: () =>
     source(
-      <Box padding="large" background="surface">
+      <Box marginX="large" boxShadow="borderNeutral">
         <Stack space="medium">
           <Placeholder height={40} />
           <Bleed horizontal="large">
@@ -66,14 +67,23 @@ const docs: ComponentDocs = {
       ),
       Example: () =>
         source(
-          <Box
-            padding="large"
-            boxShadow="borderNeutralLight"
-            background="surface"
-          >
-            <Bleed vertical="large">
+          <Box marginY="large" boxShadow="borderNeutral">
+            <Tiles space="medium" columns={3}>
               <Placeholder height={100} />
-            </Bleed>
+              <Bleed vertical="large">
+                <Box
+                  boxShadow="borderPromoteLight"
+                  background="promoteLight"
+                  height="full"
+                >
+                  <Placeholder
+                    height={`calc(100px + (${vars.space.large} * 2))`}
+                    label="vertical"
+                  />
+                </Box>
+              </Bleed>
+              <Placeholder height={100} />
+            </Tiles>
           </Box>,
         ),
     },
@@ -87,14 +97,16 @@ const docs: ComponentDocs = {
       ),
       Example: () =>
         source(
-          <Box
-            padding="large"
-            boxShadow="borderNeutralLight"
-            background="surface"
-          >
-            <Bleed horizontal="large">
-              <Placeholder height={100} />
-            </Bleed>
+          <Box marginX="large" boxShadow="borderNeutral">
+            <Stack space="medium">
+              <Placeholder height={40} />
+              <Bleed horizontal="large">
+                <Box boxShadow="borderPromoteLight" background="promoteLight">
+                  <Placeholder height={40} label="horizontal" />
+                </Box>
+              </Bleed>
+              <Placeholder height={40} />
+            </Stack>
           </Box>,
         ),
     },
@@ -110,41 +122,71 @@ const docs: ComponentDocs = {
       Example: () =>
         source(
           <Tiles columns={2} space="gutter">
-            <Box
-              padding="large"
-              boxShadow="borderNeutralLight"
-              background="surface"
-            >
-              <Bleed top="large">
-                <Placeholder height={80} label="top" />
-              </Bleed>
+            <Box marginTop="large" boxShadow="borderNeutral">
+              <Tiles space="medium" columns={3}>
+                <Placeholder height={100} />
+                <Bleed top="large">
+                  <Box
+                    boxShadow="borderPromoteLight"
+                    background="promoteLight"
+                    height="full"
+                  >
+                    <Placeholder
+                      height={`calc(100px + ${vars.space.large})`}
+                      label="top"
+                    />
+                  </Box>
+                </Bleed>
+                <Placeholder height={100} />
+              </Tiles>
             </Box>
-            <Box
-              padding="large"
-              boxShadow="borderNeutralLight"
-              background="surface"
-            >
-              <Bleed bottom="large">
-                <Placeholder height={80} label="bottom" />
-              </Bleed>
+            <Box marginBottom="large" boxShadow="borderNeutral">
+              <Tiles space="medium" columns={3}>
+                <Placeholder height={100} />
+                <Bleed bottom="large">
+                  <Box
+                    boxShadow="borderPromoteLight"
+                    background="promoteLight"
+                    height="full"
+                  >
+                    <Placeholder
+                      height={`calc(100px + ${vars.space.large})`}
+                      label="bottom"
+                    />
+                  </Box>
+                </Bleed>
+                <Placeholder height={100} />
+              </Tiles>
             </Box>
-            <Box
-              padding="large"
-              boxShadow="borderNeutralLight"
-              background="surface"
-            >
-              <Bleed left="large">
-                <Placeholder height={80} label="left" />
-              </Bleed>
+            <Box marginLeft="large" boxShadow="borderNeutral">
+              <Stack space="small">
+                <Placeholder height={30} />
+                <Bleed left="large">
+                  <Box
+                    boxShadow="borderPromoteLight"
+                    background="promoteLight"
+                    height="full"
+                  >
+                    <Placeholder height={40} label="left" />
+                  </Box>
+                </Bleed>
+                <Placeholder height={30} />
+              </Stack>
             </Box>
-            <Box
-              padding="large"
-              boxShadow="borderNeutralLight"
-              background="surface"
-            >
-              <Bleed right="large">
-                <Placeholder height={80} label="right" />
-              </Bleed>
+            <Box marginRight="large" boxShadow="borderNeutral">
+              <Stack space="small">
+                <Placeholder height={30} />
+                <Bleed right="large">
+                  <Box
+                    boxShadow="borderPromoteLight"
+                    background="promoteLight"
+                    height="full"
+                  >
+                    <Placeholder height={40} label="right" />
+                  </Box>
+                </Bleed>
+                <Placeholder height={30} />
+              </Stack>
             </Box>
           </Tiles>,
         ),
@@ -157,17 +199,49 @@ const docs: ComponentDocs = {
           using the <Strong>space</Strong> prop.
         </Text>
       ),
-      Example: () =>
+      Example: ({ setDefaultState, getState, toggleState }) =>
         source(
-          <Box
-            padding="large"
-            boxShadow="borderNeutralLight"
-            background="surface"
-          >
-            <Bleed space="large">
-              <Placeholder height={100} />
-            </Bleed>
-          </Box>,
+          <>
+            {setDefaultState('bleed', true)}
+            <Stack space="large">
+              <Toggle
+                align="right"
+                label="Toggle bleed"
+                id="all-directions"
+                bleedY
+                on={getState('bleed')}
+                onChange={() => toggleState('bleed')}
+              />
+
+              <Box position="relative" marginX="large">
+                <Stack space="large">
+                  <Placeholder height={40} />
+                  <Box position="relative">
+                    <Bleed space={getState('bleed') ? 'large' : 'none'}>
+                      <Box
+                        boxShadow="borderPromoteLight"
+                        background="promoteLight"
+                      >
+                        <Placeholder
+                          height={
+                            getState('bleed')
+                              ? `calc(40px + (${vars.space.large} * 2))`
+                              : 40
+                          }
+                          label="all directions"
+                        />
+                      </Box>
+                    </Bleed>
+                    <Box position="absolute" inset={0}>
+                      <Placeholder height={40} label=" " />
+                    </Box>
+                  </Box>
+                  <Placeholder height={40} />
+                </Stack>
+                <Box position="absolute" inset={0} boxShadow="borderNeutral" />
+              </Box>
+            </Stack>
+          </>,
         ),
     },
   ],
diff --git a/packages/braid-design-system/src/lib/components/Card/Card.docs.tsx b/packages/braid-design-system/src/lib/components/Card/Card.docs.tsx
index 6e1b33b64b5..937b35a0376 100644
--- a/packages/braid-design-system/src/lib/components/Card/Card.docs.tsx
+++ b/packages/braid-design-system/src/lib/components/Card/Card.docs.tsx
@@ -6,7 +6,7 @@ import source from '@braid-design-system/source.macro';
 import { validCardComponents } from './Card';
 
 const docs: ComponentDocs = {
-  category: 'Layout',
+  category: 'Content',
   Example: () =>
     source(
       <Card rounded>
diff --git a/site/src/App/routes/foundations/layout/layout.tsx b/site/src/App/routes/foundations/layout/layout.tsx
index 953af3fdf8f..88df00e38b4 100644
--- a/site/src/App/routes/foundations/layout/layout.tsx
+++ b/site/src/App/routes/foundations/layout/layout.tsx
@@ -102,10 +102,10 @@ const page: DocsPage = {
 
       <List>
         <Text>
-          <TextLink href="#box">Box</TextLink>
+          <TextLink href="#spacing">Spacing</TextLink>
         </Text>
         <Text>
-          <TextLink href="#card">Card</TextLink>
+          <TextLink href="#box">Box</TextLink>
         </Text>
         <Text>
           <TextLink href="#stack">Stack</TextLink>
@@ -142,28 +142,58 @@ const page: DocsPage = {
         this scale rather than generating custom spacing rules.
       </Text>
       <Stack space="small">
-        {spaceScale.map((space) => (
-          <Columns key={space} space="xsmall" alignY="center">
-            <Column width="content">
-              <Box style={{ width: 100 }}>
-                <Text baseline={false}>{space}</Text>
-              </Box>
-            </Column>
-            <Column>
-              <Box display="flex">
-                <ThemedExample transparent>
-                  <Box
-                    background="formAccent"
-                    paddingLeft={space}
-                    paddingTop="medium"
-                  />
-                </ThemedExample>
-              </Box>
-            </Column>
-          </Columns>
-        ))}
+        {spaceScale
+          .filter((s) => s !== 'gutter')
+          .map((space) => (
+            <Columns key={space} space="xsmall" alignY="center">
+              <Column width="content">
+                <Box style={{ width: 100 }}>
+                  <Text baseline={false}>{space}</Text>
+                </Box>
+              </Column>
+              <Column>
+                <Box display="flex">
+                  <ThemedExample transparent>
+                    <Box
+                      background="formAccent"
+                      paddingLeft={space}
+                      paddingTop="medium"
+                    />
+                  </ThemedExample>
+                </Box>
+              </Column>
+            </Columns>
+          ))}
       </Stack>
 
+      <Text>
+        In addition to the scale, Braid has a semantic value{' '}
+        <Strong>gutter</Strong> — used to maintain consistent insets across
+        components, e.g. <TextLink href="/components/Card">Card</TextLink>,{' '}
+        <TextLink href="/components/Alert">Alert</TextLink>,{' '}
+        <TextLink href="/components/Button">Button</TextLink>, etc. This value
+        should only be used for aligning to this concept.
+      </Text>
+
+      <Columns space="xsmall" alignY="center">
+        <Column width="content">
+          <Box style={{ width: 100 }}>
+            <Text baseline={false}>gutter</Text>
+          </Box>
+        </Column>
+        <Column>
+          <Box display="flex">
+            <ThemedExample transparent>
+              <Box
+                background="formAccent"
+                paddingLeft="gutter"
+                paddingTop="medium"
+              />
+            </ThemedExample>
+          </Box>
+        </Column>
+      </Columns>
+
       <Divider />
 
       <LinkableHeading>Box</LinkableHeading>
@@ -238,23 +268,6 @@ const page: DocsPage = {
 
       <Divider />
 
-      <LinkableHeading>Card</LinkableHeading>
-      <Text>
-        Rather than nesting content in arbitrary{' '}
-        <TextLink href="#box">Box</TextLink> elements, you may prefer to use
-        standard <TextLink href="/components/Card">Card</TextLink> elements
-        instead.
-      </Text>
-      <Code>
-        {source(
-          <Card>
-            <Text>Lorem ipsum dolor sit amet.</Text>
-          </Card>,
-        )}
-      </Code>
-
-      <Divider />
-
       <LinkableHeading>Stack</LinkableHeading>
       <Text>
         The most common white space on screen is between elements stacked
@@ -270,13 +283,11 @@ const page: DocsPage = {
       </Text>
       <Code>
         {source(
-          <Card>
-            <Stack space="large">
-              <Heading level="3">Heading</Heading>
-              <Text>{lipsum1}</Text>
-              <Text>{lipsum2}</Text>
-            </Stack>
-          </Card>,
+          <Stack space="large">
+            <Heading level="3">Heading</Heading>
+            <Text>{lipsum1}</Text>
+            <Text>{lipsum2}</Text>
+          </Stack>,
         )}
       </Code>
       <Text>
@@ -285,13 +296,11 @@ const page: DocsPage = {
       </Text>
       <Code>
         {source(
-          <Card>
-            <Stack space={{ mobile: 'medium', tablet: 'large' }}>
-              <Heading level="3">Heading</Heading>
-              <Text>{lipsum1}</Text>
-              <Text>{lipsum2}</Text>
-            </Stack>
-          </Card>,
+          <Stack space={{ mobile: 'medium', tablet: 'large' }}>
+            <Heading level="3">Heading</Heading>
+            <Text>{lipsum1}</Text>
+            <Text>{lipsum2}</Text>
+          </Stack>,
         )}
       </Code>
       <Text>
@@ -302,13 +311,11 @@ const page: DocsPage = {
       </Text>
       <Code>
         {source(
-          <Card>
-            <Stack space="gutter" dividers={true}>
-              <Heading level="3">Heading</Heading>
-              <Text>{lipsum1}</Text>
-              <Text>{lipsum2}</Text>
-            </Stack>
-          </Card>,
+          <Stack space="large" dividers={true}>
+            <Heading level="3">Heading</Heading>
+            <Text>{lipsum1}</Text>
+            <Text>{lipsum2}</Text>
+          </Stack>,
         )}
       </Code>
       <Text>
@@ -318,26 +325,24 @@ const page: DocsPage = {
       </Text>
       <Code>
         {source(
-          <Card>
-            <Stack space="gutter">
-              <Heading level="3">Heading</Heading>
-              <Text>{lipsum1}</Text>
-              <Divider />
-              <Text>{lipsum2}</Text>
-            </Stack>
-          </Card>,
+          <Stack space="large">
+            <Heading level="3">Heading</Heading>
+            <Text>{lipsum1}</Text>
+            <Divider />
+            <Text>{lipsum2}</Text>
+          </Stack>,
         )}
       </Code>
       <Text>
         Multiple <TextLink href="/components/Stack">Stack</TextLink> components
         can be nested to create more complex white space rules. For example, if
         you wanted to create multiple grouped blocks of text like you might see
-        on a job summary card:
+        in a <TextLink href="/components/Card">Card</TextLink>:
       </Text>
       <Code>
         {source(
           <Card>
-            <Stack space="gutter">
+            <Stack space="large">
               <Heading level="4">Heading</Heading>
               <Stack space="small">
                 <Text>Line 1</Text>
@@ -355,23 +360,21 @@ const page: DocsPage = {
       </Code>
       <Text>
         <TextLink href="/components/Stack">Stack</TextLink> also supports
-        horizontal alignment. For example, if you wanted to centre align all
-        content within a card:
+        horizontal alignment. For example, if you wanted to centre align all of
+        its content:
       </Text>
       <Code>
         {source(
-          <Card>
-            <Stack space="medium" align="center">
-              <IconPromote tone="promote" />
-              <Badge tone="promote">Badge</Badge>
-              <Heading align="center" level="4">
-                Heading Text
-              </Heading>
-              <Text align="center" tone="secondary">
-                Lorem ipsum dolor sit amet.
-              </Text>
-            </Stack>
-          </Card>,
+          <Stack space="medium" align="center">
+            <IconPromote tone="promote" />
+            <Badge tone="promote">Badge</Badge>
+            <Heading align="center" level="4">
+              Heading Text
+            </Heading>
+            <Text align="center" tone="secondary">
+              Lorem ipsum dolor sit amet.
+            </Text>
+          </Stack>,
         )}
       </Code>
       <Text>
@@ -382,15 +385,13 @@ const page: DocsPage = {
       </Text>
       <Code>
         {source(
-          <Card>
-            <Stack space="medium" align="center">
-              <Text>Item 1</Text>
-              <Hidden below="tablet">
-                <Text>Item 2</Text>
-              </Hidden>
-              <Text>Item 3</Text>
-            </Stack>
-          </Card>,
+          <Stack space="medium" align="center">
+            <Text>Item 1</Text>
+            <Hidden below="tablet">
+              <Text>Item 2</Text>
+            </Hidden>
+            <Text>Item 3</Text>
+          </Stack>,
         )}
       </Code>
 
@@ -405,19 +406,17 @@ const page: DocsPage = {
 
       <Code>
         {source(
-          <Card>
-            <Inline space="small">
-              <Badge>Lorem ipsum</Badge>
-              <Badge>Dolor</Badge>
-              <Badge>Sit amet</Badge>
-              <Badge>Consectetur</Badge>
-              <Badge>Adipiscing elit</Badge>
-              <Badge>Suspendisse dignissim</Badge>
-              <Badge>Dapibus elit</Badge>
-              <Badge>Vel egestas felis</Badge>
-              <Badge>Pharetra non</Badge>
-            </Inline>
-          </Card>,
+          <Inline space="small">
+            <Badge>Lorem ipsum</Badge>
+            <Badge>Dolor</Badge>
+            <Badge>Sit amet</Badge>
+            <Badge>Consectetur</Badge>
+            <Badge>Adipiscing elit</Badge>
+            <Badge>Suspendisse dignissim</Badge>
+            <Badge>Dapibus elit</Badge>
+            <Badge>Vel egestas felis</Badge>
+            <Badge>Pharetra non</Badge>
+          </Inline>,
         )}
       </Code>
 
@@ -429,19 +428,17 @@ const page: DocsPage = {
 
       <Code>
         {source(
-          <Card>
-            <Inline space="small" align="center">
-              <Badge>Lorem ipsum</Badge>
-              <Badge>Dolor</Badge>
-              <Badge>Sit amet</Badge>
-            </Inline>
-          </Card>,
+          <Inline space="small" align="center">
+            <Badge>Lorem ipsum</Badge>
+            <Badge>Dolor</Badge>
+            <Badge>Sit amet</Badge>
+          </Inline>,
         )}
       </Code>
 
       <Text>
-        If you’d like the columns to stack vertically on smaller screens, you
-        can provide the{' '}
+        If you’d like the items to stack vertically on smaller screens, you can
+        provide the{' '}
         <TextLink href="/components/Inline#collapsing-across-breakpoints">
           collapseBelow
         </TextLink>{' '}
@@ -453,12 +450,10 @@ const page: DocsPage = {
       </Text>
       <Code>
         {source(
-          <Card>
-            <Inline space="small" collapseBelow="tablet">
-              <Button>Submit</Button>
-              <Button variant="ghost">Cancel</Button>
-            </Inline>
-          </Card>,
+          <Inline space="small" collapseBelow="tablet">
+            <Button>Submit</Button>
+            <Button variant="ghost">Cancel</Button>
+          </Inline>,
         )}
       </Code>
 
@@ -913,7 +908,7 @@ const page: DocsPage = {
       <Code>
         {source(
           <Card>
-            <Stack space="gutter">
+            <Stack space="large">
               <Placeholder height={200} label="Header Image" />
               <Heading level="3">Heading</Heading>
               <Text>Text content</Text>
@@ -935,7 +930,7 @@ const page: DocsPage = {
       <Code>
         {source(
           <Card>
-            <Stack space="gutter">
+            <Stack space="large">
               <Bleed horizontal="gutter" top="gutter">
                 <Placeholder height={200} label="Header Image" />
               </Bleed>