docs(ui): improve Container documentation

Improves Container documentation to better explain its purpose as
a page-level wrapper for plugin content.

- Added Core Concepts section explaining centering, max-width, and gutters
- Removed redundant Basic Usage example
- Updated examples to use DecorativeBox
- Improved PageTitle description

Signed-off-by: Johan Persson <johanopersson@gmail.com>

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>`;