Restructure docs for simple descriptions (#2870)

Author: alex-page

packages/ui-extensions/src/surfaces/admin/components/Banner/shared.ts

@@ -1,25 +1,33 @@
 const shared = {
   name: 'Banner',
-  description: `
-  Use \`s-banner\` to communicate important status updates or required actions that users must take. Banners will automatically adjust their design to match the context in which they are used.
-
-#### Outside of a section
-Banners placed outside of a section will display in their own card and should be located at the top of the page.
-They're useful for conveying messages that apply to the entire page or areas not visible within the viewport, such as validation errors further down the page.
-
-#### In a section
-Banners placed inside a section will have styles applied contextually. They're useful for conveying messages relevant to a specific section or piece of content.
-
-#### Best practices
-- Seeing these banners can be stressful, so use them sparingly to avoid overwhelming users.
+  description:
+    'Use `s-banner` to communicate important status updates or required actions that users must take. Banners will automatically adjust their design to match the context in which they are used.',
+  thumbnail: '/assets/templated-apis-screenshots/admin/components/banner.png',
+  isVisualComponent: true,
+  subSections: [
+    {
+      title: 'Outside of a section',
+      type: 'Generic' as const,
+      anchorLink: 'outside-of-a-section',
+      sectionContent: `Banners placed outside of a section will display in their own card and should be located at the top of the page. They're useful for conveying messages that apply to the entire page or areas not visible within the viewport, such as validation errors further down the page.`,
+    },
+    {
+      title: 'In a section',
+      type: 'Generic' as const,
+      anchorLink: 'in-a-section',
+      sectionContent: `Banners placed inside a section will have styles applied contextually. They're useful for conveying messages relevant to a specific section or piece of content.`,
+    },
+    {
+      title: 'Best practices',
+      type: 'Generic' as const,
+      anchorLink: 'best-practices',
+      sectionContent: `- Seeing these banners can be stressful, so use them sparingly to avoid overwhelming users.
 - Focus on a single piece of information or required action to avoid overwhelming users.
 - Make the message concise and scannable. Users shouldn’t need to spend a lot of time figuring out what they need to know and do.
 - Info, Warning and Critical banners should contain a call to action and clear next steps. Users should know what to do after seeing the banner.
-- Avoid banners that can't be dismissed unless the user is required to take action.
-
-  `,
-  thumbnail: '/assets/templated-apis-screenshots/admin/components/banner.png',
-  isVisualComponent: true,
+- Avoid banners that can't be dismissed unless the user is required to take action.`,
+    },
+  ],
   definitions: [
     {
       title: 'Properties',

packages/ui-extensions/src/surfaces/admin/components/Box/shared.ts

@@ -1,15 +1,19 @@
 const shared = {
   name: 'Box',
-  description: `
-  Use \`s-box\` to build custom interfaces with your own design language.
-
-  #### Useful for:
-  - Creating custom designs when you can't build what you need with the existing components.
-  - Setting up specific stylings such as background colors, paddings, and borders.
-  - Nesting with other components.
-    `,
+  description:
+    'Use `s-box` to build custom interfaces with your own design language.',
   thumbnail: '/assets/templated-apis-screenshots/admin/components/box.png',
   isVisualComponent: true,
+  subSections: [
+    {
+      title: 'Useful for',
+      type: 'Generic' as const,
+      anchorLink: 'useful-for',
+      sectionContent: `- Creating custom designs when you can't build what you need with the existing components.
+  - Setting up specific stylings such as background colors, paddings, and borders.
+  - Nesting with other components.`,
+    },
+  ],
   definitions: [
     {
       title: 'Properties',

packages/ui-extensions/src/surfaces/admin/components/Divider/shared.ts

@@ -1,13 +1,16 @@
 const shared = {
   name: 'Divider',
-  description: `
-  Use \`s-divider\` to create a clear visual separation between different elements in your user interface.
-
-  #### Useful for:
-  - Separating elements inside sections.
-  - Visually grouping related content in forms and lists.
-  `,
-
+  description:
+    'Use `s-divider` to create a clear visual separation between different elements in your user interface.',
+  subSections: [
+    {
+      title: 'Useful for',
+      type: 'Generic' as const,
+      anchorLink: 'useful-for',
+      sectionContent: `- Separating elements inside sections.
+- Visually grouping related content in forms and lists.`,
+    },
+  ],
   thumbnail: '/assets/templated-apis-screenshots/admin/components/divider.png',
   isVisualComponent: true,
   definitions: [

packages/ui-extensions/src/surfaces/admin/components/Grid/shared.ts

@@ -1,18 +1,24 @@
 const shared = {
   name: 'Grid',
-  description: `
-  Use \`s-grid\` to organize your content in a matrix of rows and columns and make responsive layouts for pages. Grid follows the same pattern as the [CSS grid layout](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout).
-
-  #### Useful for:
-  - Organizing content into a grid-like layout with columns and rows with consistent alignment and spacing.
-  - Creating responsive layouts with consistent spacing.
-
-  #### Considerations
-  - Grid doesn't include any padding by default. If you need padding around your grid, use \`base\` to apply the default padding.
-  - Grid will allow children to overflow unless template rows/columns are properly set.
-  - Grid will always wrap children to a new line. If you need to control the wrapping behavior, use \`s-stack\` or \`s-box\`.
- `,
-
+  description:
+    'Use `s-grid` to organize your content in a matrix of rows and columns and make responsive layouts for pages. Grid follows the same pattern as the [CSS grid layout](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout).',
+  subSections: [
+    {
+      title: 'Useful for',
+      type: 'Generic' as const,
+      anchorLink: 'useful-for',
+      sectionContent: `- Organizing content into a grid-like layout with columns and rows with consistent alignment and spacing.
+- Creating responsive layouts with consistent spacing.`,
+    },
+    {
+      title: 'Considerations',
+      type: 'Generic' as const,
+      anchorLink: 'considerations',
+      sectionContent: `- Grid doesn't include any padding by default. If you need padding around your grid, use \`base\` to apply the default padding.
+- Grid will allow children to overflow unless template rows/columns are properly set.
+- Grid will always wrap children to a new line. If you need to control the wrapping behavior, use \`s-stack\` or \`s-box\`.`,
+    },
+  ],
   thumbnail: '/assets/templated-apis-screenshots/admin/components/grid.png',
   isVisualComponent: true,
   definitions: [

packages/ui-extensions/src/surfaces/admin/components/Heading/shared.ts

@@ -1,26 +1,35 @@
 const shared = {
   name: 'Heading',
-  description: `
-  Use \`s-heading\` to create hierarchical titles similar to HTML's \`h1-h6\` elements.
-
-  #### Useful for:
-  - Creating titles and subtitles for your content that are consistent across your app.
-  - Helping users with visual impairments navigate through content effectively using assistive technologies like screen readers.
-
-  #### Considerations
-  - The level of the heading is automatically determined by how deeply it's nested inside other components, starting from h2.
-  - Default to using the \`heading\` property in \`s-section\`. The \`s-heading\` component should only be used if you need to implement a custom layout for your heading in the UI.
-
-  #### Best practices
-  - Use short headings to make your content scannable.
-  - Use plain and clear terms.
-  - Don't use jargon or technical language.
-  - Don't use different terms to describe the same thing.
-  - Don't duplicate content.
-
-  `,
+  description:
+    "Use `s-heading` to create hierarchical titles similar to HTML's `h1-h6` elements.",
   thumbnail: '/assets/templated-apis-screenshots/admin/components/heading.png',
   isVisualComponent: true,
+  subSections: [
+    {
+      title: 'Useful for',
+      type: 'Generic' as const,
+      anchorLink: 'useful-for',
+      sectionContent: `- Creating titles and subtitles for your content that are consistent across your app.
+- Helping users with visual impairments navigate through content effectively using assistive technologies like screen readers.`,
+    },
+    {
+      title: 'Considerations',
+      type: 'Generic' as const,
+      anchorLink: 'considerations',
+      sectionContent: `- The level of the heading is automatically determined by how deeply it's nested inside other components, starting from h2.
+- Default to using the \`heading\` property in \`s-section\`. The \`s-heading\` component should only be used if you need to implement a custom layout for your heading in the UI.`,
+    },
+    {
+      title: 'Best practices',
+      type: 'Generic' as const,
+      anchorLink: 'best-practices',
+      sectionContent: `- Use short headings to make your content scannable.
+- Use plain and clear terms.
+- Don't use jargon or technical language.
+- Don't use different terms to describe the same thing.
+- Don't duplicate content.`,
+    },
+  ],
   definitions: [
     {
       title: 'Properties',

packages/ui-extensions/src/surfaces/admin/components/Image/shared.ts

@@ -1,19 +1,24 @@
 const shared = {
   name: 'Image',
-  description: `
-  Use \`s-image\` to display images in your app.
-
-  #### Useful for:
-  - Adding illustrations and photos.
-
-  #### Best practices
-  - Use high-resolution images to ensure a professional and high-quality experience.
-  - Use optimized images so your app loads as fast as possible.
-  - Use images intentionally, these should add clarity and lead users to the next step.
-
-  `,
+  description: 'Use `s-image` to display images in your app.',
   thumbnail: '/assets/templated-apis-screenshots/admin/components/image.png',
   isVisualComponent: true,
+  subSections: [
+    {
+      title: 'Useful for',
+      type: 'Generic' as const,
+      anchorLink: 'useful-for',
+      sectionContent: `- Adding illustrations and photos.`,
+    },
+    {
+      title: 'Best practices',
+      type: 'Generic' as const,
+      anchorLink: 'best-practices',
+      sectionContent: `- Use high-resolution images to ensure a professional and high-quality experience.
+- Use optimized images so your app loads as fast as possible.
+- Use images intentionally, these should add clarity and lead users to the next step.`,
+    },
+  ],
   definitions: [
     {
       title: 'Properties',

packages/ui-extensions/src/surfaces/admin/components/Paragraph/shared.ts

@@ -1,23 +1,29 @@
 const shared = {
   name: 'Paragraph',
-  description: `
-  Use \`s-paragraph\` to display a block of text similar to the \`<p>\` tag in HTML. This component can also contain other elements such as buttons, links, or text.
-
-  #### Useful for:
-  - Displaying text content in a paragraph format.
-  - Grouping elements with the same style. For instance, icons inside a paragraph will automatically adopt the paragraph's tone.
-
-  #### Best practices
-  - Use short paragraphs to make your content scannable.
-  - Use plain and clear terms.
-  - Don't use jargon or technical language.
-  - Don't use different terms to describe the same thing.
-  - Don't duplicate content.
-
-  `,
+  description:
+    'Use `s-paragraph` to display a block of text similar to the `<p>` tag in HTML. This component can also contain other elements such as buttons, links, or text.',
   thumbnail:
     '/assets/templated-apis-screenshots/admin/components/paragraph.png',
   isVisualComponent: true,
+  subSections: [
+    {
+      title: 'Useful for',
+      type: 'Generic' as const,
+      anchorLink: 'useful-for',
+      sectionContent: `- Displaying text content in a paragraph format.
+- Grouping elements with the same style. For instance, icons inside a paragraph will automatically adopt the paragraph's tone.`,
+    },
+    {
+      title: 'Best practices',
+      type: 'Generic' as const,
+      anchorLink: 'best-practices',
+      sectionContent: `- Use short paragraphs to make your content scannable.
+- Use plain and clear terms.
+- Don't use jargon or technical language.
+- Don't use different terms to describe the same thing.
+- Don't duplicate content.`,
+    },
+  ],
   definitions: [
     {
       title: 'Properties',

packages/ui-extensions/src/surfaces/admin/components/Section/shared.ts

@@ -1,23 +1,27 @@
 const shared = {
   name: 'Section',
-  description: `
-Use \`s-section\` to organize your page content. Sections have defined styling, and will display differently depending on how deeply they are nested in the page.
-
-- **Level 1:** Display as responsive cards with background color, rounded corners, and shadow effects. Includes outer padding that can be removed when content like \`s-table\` needs to expand to the full width of the section.
-- **Nested sections:** Don't have any background color or effects by default.
-
-#### Useful for:
-- Organizing your page in a logical structure based on nesting levels.
-- Creating consistency across pages.
-
-#### Considerations
-- When adding headings inside sections they automatically use a specific style, which helps keep the content organized and clear.
-- Built-in spacing is added between nested sections, as well as between heading and content.
-
-    `,
-
+  description:
+    'Use `s-section` to organize your page content. Sections have defined styling, and will display differently depending on how deeply they are nested in the page.',
   isVisualComponent: true,
   thumbnail: '/assets/templated-apis-screenshots/admin/components/section.png',
+  subSections: [
+    {
+      title: 'Useful for',
+      type: 'Generic' as const,
+      anchorLink: 'useful-for',
+      sectionContent: `- Organizing your page in a logical structure based on nesting levels.
+- Creating consistency across pages.`,
+    },
+    {
+      title: 'Considerations',
+      type: 'Generic' as const,
+      anchorLink: 'considerations',
+      sectionContent: `- When adding headings inside sections they automatically use a specific style, which helps keep the content organized and clear.
+- Built-in spacing is added between nested sections, as well as between heading and content.
+- **Level 1:** Display as responsive cards with background color, rounded corners, and shadow effects. Includes outer padding that can be removed when content like \`s-table\` needs to expand to the full width of the section.
+- **Nested sections:** Don't have any background color or effects by default.`,
+    },
+  ],
   definitions: [
     {
       title: 'Properties',

packages/ui-extensions/src/surfaces/admin/components/Stack/shared.ts

@@ -1,22 +1,32 @@
 const shared = {
   name: 'Stack',
-  description: `
-  Use \`s-stack\` to organize elements along the [block or inline axes](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_display/Block_and_inline_layout_in_normal_flow) of the page.
-
-  #### Useful for:
-  - Placing items in rows or columns when sections don't work for your layout.
-  - Controlling the spacing between elements.
-
-  #### Considerations
-  - Stack doesn't add any padding by default. If you want padding around your stacked elements, use \`base\` to apply the default padding.
-  - When spacing becomes limited, Stack will always wrap children to a new line.
-
-  #### Best practices
-  - Use smaller gaps between small elements and larger gaps between big ones.
-  - Maintain consistent spacing in stacks across all pages of your app.
-  `,
+  description:
+    'Use `s-stack` to organize elements along the [block or inline axes](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_display/Block_and_inline_layout_in_normal_flow) of the page.',
   thumbnail: '/assets/templated-apis-screenshots/admin/components/stack.png',
   isVisualComponent: true,
+  subSections: [
+    {
+      title: 'Useful for',
+      type: 'Generic' as const,
+      anchorLink: 'useful-for',
+      sectionContent: `- Placing items in rows or columns when sections don't work for your layout.
+- Controlling the spacing between elements.`,
+    },
+    {
+      title: 'Considerations',
+      type: 'Generic' as const,
+      anchorLink: 'considerations',
+      sectionContent: `- Stack doesn't add any padding by default. If you want padding around your stacked elements, use \`base\` to apply the default padding.
+- When spacing becomes limited, Stack will always wrap children to a new line.`,
+    },
+    {
+      title: 'Best practices',
+      type: 'Generic' as const,
+      anchorLink: 'best-practices',
+      sectionContent: `- Use smaller gaps between small elements and larger gaps between big ones.
+- Maintain consistent spacing in stacks across all pages of your app.`,
+    },
+  ],
   definitions: [
     {
       title: 'Properties',