Merge pull request #32572 from backstage/ui-docs-restore-decorative-box-layout-examples

docs(ui): restore DecorativeBox for layout component examples

docs-ui/src/app/components/box/components.tsx

@@ -2,11 +2,12 @@
 
 import { Box } from '../../../../../packages/ui/src/components/Box/Box';
 import { Flex } from '../../../../../packages/ui/src/components/Flex/Flex';
+import { DecorativeBox } from '@/components/DecorativeBox';
 
 export const Default = () => {
   return (
-    <Box p="4" surface="1">
-      Hello World
+    <Box width="64px" height="64px">
+      <DecorativeBox />
     </Box>
   );
 };
@@ -36,7 +37,7 @@ export const Responsive = () => {
       p={{ initial: '2', md: '4' }}
       display={{ initial: 'block', md: 'flex' }}
     >
-      Hello World
+      <DecorativeBox>Resize to see change</DecorativeBox>
     </Box>
   );
 };

docs-ui/src/app/components/box/page.mdx

@@ -41,7 +41,7 @@ avoid collapsing margins but both are available.
 
 ### Surface
 
-Here's a view when boxes have different surface levels.
+Use surface levels to create visual hierarchy.
 
 <Snippet preview={<Surface />} code={boxSurfaceSnippet} layout="side-by-side" />
 

docs-ui/src/app/components/box/snippets.ts

@@ -4,8 +4,8 @@ export const snippetUsage = `import { Box } from '@backstage/ui';
   Content with padding and background
 </Box>`;
 
-export const defaultSnippet = `<Box p="4" surface="1">
-  Hello World
+export const defaultSnippet = `<Box width="64px" height="64px">
+  <DecorativeBox />
 </Box>`;
 
 export const boxSurfaceSnippet = `<Flex direction="column" gap="4">
@@ -19,5 +19,5 @@ export const boxResponsiveSnippet = `<Box
   p={{ initial: '2', md: '4' }}
   display={{ initial: 'block', md: 'flex' }}
 >
-  Hello World
+  Content
 </Box>`;

docs-ui/src/app/components/container/components.tsx

@@ -1,33 +1,20 @@
 'use client';
 
 import { Container } from '../../../../../packages/ui/src/components/Container/Container';
-import { Box } from '../../../../../packages/ui/src/components/Box/Box';
-import { Text } from '../../../../../packages/ui/src/components/Text/Text';
+import { DecorativeBox } from '@/components/DecorativeBox';
 
-export const Preview = () => {
-  return (
-    <Container py="4">
-      <Text>Content is centered with max-width</Text>
-    </Container>
-  );
-};
-
-export const BasicUsagePreview = () => {
+export const Default = () => {
   return (
     <Container>
-      <Box>Hello World</Box>
-      <Box>Hello World</Box>
-      <Box>Hello World</Box>
+      <DecorativeBox>Page content goes here</DecorativeBox>
     </Container>
   );
 };
 
-export const ResponsiveSpacingPreview = () => {
+export const ResponsiveSpacing = () => {
   return (
-    <Container py={{ initial: '2', md: '4' }}>
-      <Box>Hello World</Box>
-      <Box>Hello World</Box>
-      <Box>Hello World</Box>
+    <Container py={{ initial: '4', md: '8' }}>
+      <DecorativeBox>Content with vertical spacing</DecorativeBox>
     </Container>
   );
 };

docs-ui/src/app/components/container/page.mdx

@@ -4,15 +4,10 @@ import { Snippet } from '@/components/Snippet';
 import { containerPropDefs } from './props-definition';
 import {
   containerUsageSnippet,
-  previewSnippet,
-  containerSimpleSnippet,
+  defaultSnippet,
   containerResponsiveSnippet,
 } from './snippets';
-import {
-  Preview,
-  BasicUsagePreview,
-  ResponsiveSpacingPreview,
-} from './components';
+import { Default, ResponsiveSpacing } from './components';
 import { PageTitle } from '@/components/PageTitle';
 import { Theming } from '@/components/Theming';
 import { ContainerDefinition } from '../../../utils/definitions';
@@ -21,38 +16,30 @@ import { ChangelogComponent } from '@/components/ChangelogComponent';
 <PageTitle
   type="Layout"
   title="Container"
-  description="A centered layout wrapper with max-width and vertical spacing props."
+  description="A page wrapper that centers content and constrains its maximum width."
 />
 
-<Snippet py={4} preview={<Preview />} code={previewSnippet} />
+<Snippet preview={<Default />} code={defaultSnippet} />
 
 ## Usage
 
 <CodeBlock code={containerUsageSnippet} />
 
-## API reference
+## Core Concepts
+
+Container provides the standard page layout for plugin content. It constrains content to a maximum width, centers it horizontally, and adds consistent horizontal gutters. Use it once per page to wrap your main content area.
+
+## API Reference
 
 <PropsTable data={containerPropDefs} />
 
 ## Examples
 
-### Basic Usage
+### Responsive spacing
 
-<Snippet
-  preview={<BasicUsagePreview />}
-  code={containerSimpleSnippet}
-  layout="side-by-side"
-/>
+Vertical spacing props accept breakpoint objects.
 
-### Responsive Spacing
-
-Spacing props accept breakpoint objects for responsive behavior.
-
-<Snippet
-  preview={<ResponsiveSpacingPreview />}
-  code={containerResponsiveSnippet}
-  layout="side-by-side"
-/>
+<Snippet preview={<ResponsiveSpacing />} code={containerResponsiveSnippet} />
 
 <Theming definition={ContainerDefinition} />
 

docs-ui/src/app/components/container/snippets.ts

@@ -1,19 +1,13 @@
 export const containerUsageSnippet = `import { Container } from "@backstage/ui";
 
-<Container>Hello World!</Container>`;
-
-export const previewSnippet = `<Container py="4">
-  Content is centered with max-width
+<Container>
+  {/* Your plugin's main content */}
 </Container>`;
 
-export const containerSimpleSnippet = `<Container>
-  <Box>Hello World</Box>
-  <Box>Hello World</Box>
-  <Box>Hello World</Box>
+export const defaultSnippet = `<Container>
+  <DecorativeBox>Page content goes here</DecorativeBox>
 </Container>`;
 
-export const containerResponsiveSnippet = `<Container py={{ initial: '2', md: '4' }}>
-  <Box>Hello World</Box>
-  <Box>Hello World</Box>
-  <Box>Hello World</Box>
+export const containerResponsiveSnippet = `<Container py={{ initial: '4', md: '8' }}>
+  <DecorativeBox>Content with vertical spacing</DecorativeBox>
 </Container>`;

docs-ui/src/app/components/flex/components.tsx

@@ -1,29 +1,14 @@
 'use client';
 
 import { Flex } from '../../../../../packages/ui/src/components/Flex/Flex';
-import { Box } from '../../../../../packages/ui/src/components/Box/Box';
-
-const boxStyle = {
-  width: '64px',
-  height: '64px',
-  background: '#eaf2fd',
-  border: '1px solid #2563eb',
-  borderRadius: '4px',
-};
-
-const smallBoxStyle = {
-  padding: '8px 12px',
-  background: '#eaf2fd',
-  border: '1px solid #2563eb',
-  borderRadius: '4px',
-};
+import { DecorativeBox } from '@/components/DecorativeBox';
 
 export const Default = () => {
   return (
     <Flex gap="4">
-      <Box style={boxStyle} />
-      <Box style={boxStyle} />
-      <Box style={boxStyle} />
+      <DecorativeBox />
+      <DecorativeBox />
+      <DecorativeBox />
     </Flex>
   );
 };
@@ -31,9 +16,9 @@ export const Default = () => {
 export const DirectionExample = () => {
   return (
     <Flex direction="column" gap="2">
-      <Box style={smallBoxStyle}>First</Box>
-      <Box style={smallBoxStyle}>Second</Box>
-      <Box style={smallBoxStyle}>Third</Box>
+      <DecorativeBox>First</DecorativeBox>
+      <DecorativeBox>Second</DecorativeBox>
+      <DecorativeBox>Third</DecorativeBox>
     </Flex>
   );
 };
@@ -41,9 +26,9 @@ export const DirectionExample = () => {
 export const ResponsiveExample = () => {
   return (
     <Flex gap={{ initial: '2', md: '4' }}>
-      <Box style={smallBoxStyle}>Item 1</Box>
-      <Box style={smallBoxStyle}>Item 2</Box>
-      <Box style={smallBoxStyle}>Item 3</Box>
+      <DecorativeBox>1</DecorativeBox>
+      <DecorativeBox>2</DecorativeBox>
+      <DecorativeBox>3</DecorativeBox>
     </Flex>
   );
 };
@@ -51,9 +36,9 @@ export const ResponsiveExample = () => {
 export const AlignExample = () => {
   return (
     <Flex align="center" justify="between" gap="4" style={{ width: '300px' }}>
-      <Box style={smallBoxStyle}>Start</Box>
-      <Box style={smallBoxStyle}>Middle</Box>
-      <Box style={smallBoxStyle}>End</Box>
+      <DecorativeBox>Start</DecorativeBox>
+      <DecorativeBox>Middle</DecorativeBox>
+      <DecorativeBox>End</DecorativeBox>
     </Flex>
   );
 };

docs-ui/src/app/components/flex/snippets.ts

@@ -7,25 +7,25 @@ export const flexUsageSnippet = `import { Flex } from '@backstage/ui';
 </Flex>`;
 
 export const defaultSnippet = `<Flex gap="4">
-  <Box style={{ width: '64px', height: '64px' }} />
-  <Box style={{ width: '64px', height: '64px' }} />
-  <Box style={{ width: '64px', height: '64px' }} />
+  <DecorativeBox />
+  <DecorativeBox />
+  <DecorativeBox />
 </Flex>`;
 
 export const flexDirectionSnippet = `<Flex direction="column" gap="2">
-  <Box>First</Box>
-  <Box>Second</Box>
-  <Box>Third</Box>
+  <DecorativeBox>First</DecorativeBox>
+  <DecorativeBox>Second</DecorativeBox>
+  <DecorativeBox>Third</DecorativeBox>
 </Flex>`;
 
 export const flexResponsiveSnippet = `<Flex gap={{ initial: '2', md: '4' }}>
-  <Box>Item 1</Box>
-  <Box>Item 2</Box>
-  <Box>Item 3</Box>
+  <DecorativeBox>1</DecorativeBox>
+  <DecorativeBox>2</DecorativeBox>
+  <DecorativeBox>3</DecorativeBox>
 </Flex>`;
 
 export const flexAlignSnippet = `<Flex align="center" justify="between" gap="4">
-  <Box>Start</Box>
-  <Box>Middle</Box>
-  <Box>End</Box>
+  <DecorativeBox>Start</DecorativeBox>
+  <DecorativeBox>Middle</DecorativeBox>
+  <DecorativeBox>End</DecorativeBox>
 </Flex>`;

docs-ui/src/app/components/grid/components.tsx

@@ -1,31 +1,17 @@
 'use client';
 
 import { Grid } from '../../../../../packages/ui/src/components/Grid/Grid';
-import { Box } from '../../../../../packages/ui/src/components/Box/Box';
-
-const boxStyle = {
-  height: '64px',
-  background: '#eaf2fd',
-  border: '1px solid #2563eb',
-  borderRadius: '4px',
-};
-
-const labelBoxStyle = {
-  padding: '8px 12px',
-  background: '#eaf2fd',
-  border: '1px solid #2563eb',
-  borderRadius: '4px',
-};
+import { DecorativeBox } from '@/components/DecorativeBox';
 
 export const Default = () => {
   return (
     <Grid.Root columns="3" gap="4">
-      <Box style={boxStyle} />
-      <Box style={boxStyle} />
-      <Box style={boxStyle} />
-      <Box style={boxStyle} />
-      <Box style={boxStyle} />
-      <Box style={boxStyle} />
+      <DecorativeBox />
+      <DecorativeBox />
+      <DecorativeBox />
+      <DecorativeBox />
+      <DecorativeBox />
+      <DecorativeBox />
     </Grid.Root>
   );
 };
@@ -33,10 +19,10 @@ export const Default = () => {
 export const ResponsiveExample = () => {
   return (
     <Grid.Root columns={{ initial: '2', md: '4' }} gap="4">
-      <Box style={labelBoxStyle}>1</Box>
-      <Box style={labelBoxStyle}>2</Box>
-      <Box style={labelBoxStyle}>3</Box>
-      <Box style={labelBoxStyle}>4</Box>
+      <DecorativeBox>1</DecorativeBox>
+      <DecorativeBox>2</DecorativeBox>
+      <DecorativeBox>3</DecorativeBox>
+      <DecorativeBox>4</DecorativeBox>
     </Grid.Root>
   );
 };
@@ -44,11 +30,11 @@ export const ResponsiveExample = () => {
 export const GridItemExample = () => {
   return (
     <Grid.Root columns="4" gap="4">
-      <Grid.Item colSpan="2" style={labelBoxStyle}>
-        Spans 2 columns
+      <Grid.Item colSpan="2">
+        <DecorativeBox>Spans 2 columns</DecorativeBox>
       </Grid.Item>
-      <Box style={labelBoxStyle}>1 column</Box>
-      <Box style={labelBoxStyle}>1 column</Box>
+      <DecorativeBox>1 column</DecorativeBox>
+      <DecorativeBox>1 column</DecorativeBox>
     </Grid.Root>
   );
 };

docs-ui/src/app/components/grid/snippets.ts

@@ -7,23 +7,25 @@ export const gridUsageSnippet = `import { Grid } from '@backstage/ui';
 </Grid.Root>`;
 
 export const defaultSnippet = `<Grid.Root columns="3" gap="4">
-  <Box style={{ height: '64px' }} />
-  <Box style={{ height: '64px' }} />
-  <Box style={{ height: '64px' }} />
-  <Box style={{ height: '64px' }} />
-  <Box style={{ height: '64px' }} />
-  <Box style={{ height: '64px' }} />
+  <DecorativeBox />
+  <DecorativeBox />
+  <DecorativeBox />
+  <DecorativeBox />
+  <DecorativeBox />
+  <DecorativeBox />
 </Grid.Root>`;
 
 export const gridResponsiveSnippet = `<Grid.Root columns={{ initial: '2', md: '4' }} gap="4">
-  <Box>1</Box>
-  <Box>2</Box>
-  <Box>3</Box>
-  <Box>4</Box>
+  <DecorativeBox>1</DecorativeBox>
+  <DecorativeBox>2</DecorativeBox>
+  <DecorativeBox>3</DecorativeBox>
+  <DecorativeBox>4</DecorativeBox>
 </Grid.Root>`;
 
 export const gridItemSnippet = `<Grid.Root columns="4" gap="4">
-  <Grid.Item colSpan="2">Spans 2 columns</Grid.Item>
-  <Grid.Item>1 column</Grid.Item>
-  <Grid.Item>1 column</Grid.Item>
+  <Grid.Item colSpan="2">
+    <DecorativeBox>Spans 2 columns</DecorativeBox>
+  </Grid.Item>
+  <DecorativeBox>1 column</DecorativeBox>
+  <DecorativeBox>1 column</DecorativeBox>
 </Grid.Root>`;

docs-ui/src/components/DecorativeBox/index.tsx

@@ -1,5 +1,17 @@
+'use client';
+
+import { CSSProperties, ReactNode } from 'react';
 import styles from './styles.module.css';
 
-export const DecorativeBox = () => {
-  return <div className={styles.box} />;
+interface DecorativeBoxProps {
+  children?: ReactNode;
+  style?: CSSProperties;
+}
+
+export const DecorativeBox = ({ children, style }: DecorativeBoxProps) => {
+  return (
+    <div className={styles.box} style={style}>
+      {children}
+    </div>
+  );
 };

docs-ui/src/components/DecorativeBox/styles.module.css

@@ -1,8 +1,14 @@
 .box {
   min-width: 64px;
   min-height: 64px;
+  padding: 8px 12px;
   background-color: #eaf2fd;
   border-radius: 4px;
   box-shadow: 0 0 0 1px #2563eb;
   background-image: url("data:image/svg+xml,%3Csvg width='6' height='6' viewBox='0 0 6 6' xmlns='http://www.w3.org/2000/svg'%3E%3Cg fill='%232563eb' fill-opacity='0.3' fill-rule='evenodd'%3E%3Cpath d='M5 0h1L0 6V5zM6 5v1H5z'/%3E%3C/g%3E%3C/svg%3E");
+  color: #2563eb;
+  font-weight: 500;
+  display: flex;
+  align-items: center;
+  justify-content: center;
 }