Docs/ppdsc 2552 content updates (#557)

* docs(PPDSC-2552): block component page updates * docs(PPDSC-2552): divider changes * docs(PPDSC-2552): drawer page * docs(PPDSC-2552): fieldset page * docs(PPDSC-2552): grid layout * docs(PPDSC-2552): modal content changes * docs(PPDSC-2552): popover content updates * docs(PPDSC-2552): structured list changes * docs(PPDSC-2552): visibility changes * docs(PPDSC-2552): correct inline message * docs(PPDSC-2552): content updates * docs(PPDSC-2552): final changes
newscorp-ghfb · Jan 17, 2023 · 134e862 · 134e862
1 parent 04fe911
commit 134e862
Show file tree

Hide file tree

Showing 15 changed files with 575 additions and 856 deletions.
diff --git a/site/components/component-api/common-logical-props.tsx b/site/components/component-api/common-logical-props.tsx
@@ -6,65 +6,65 @@ export const logicalMarginOverrideProps: OverridesRowsProps[] = [
   {
     attribute: 'marginInline',
     type: 'MQ<string>',
-    description: `Can take one space token to specify the logical inline start and end margin of the container. Can be used on breakpoints`,
+    description: `Takes one space token to specify the logical inline start and end margin of the container. Can be used on breakpoints`,
   },
   {
     attribute: 'marginInlineStart',
     type: 'MQ<string>',
-    description: `Can take one space token to specify the logical inline start margin of the container. Can be used on breakpoints`,
+    description: `Takes one space token to specify the logical inline start margin of the container. Can be used on breakpoints`,
   },
   {
     attribute: 'marginInlineEnd',
     type: 'MQ<string>',
-    description: `Can take one space token to specify the logical inline end margin of the container. Can be used on breakpoints`,
+    description: `Takes one space token to specify the logical inline end margin of the container. Can be used on breakpoints`,
   },
   {
     attribute: 'marginBlock',
     type: 'MQ<string>',
-    description: `Can take one space token to specify the logical block start and end margin of the container. Can be used on breakpoints`,
+    description: `Takes one space token to specify the logical block start and end margin of the container. Can be used on breakpoints`,
   },
   {
     attribute: 'marginBlockStart',
     type: 'MQ<string>',
-    description: `Can take one space token to specify the logical block start margin of the container. Can be used on breakpoints`,
+    description: `Takes one space token to specify the logical block start margin of the container. Can be used on breakpoints`,
   },
   {
     attribute: 'marginBlockEnd',
     type: 'MQ<string>',
-    description: `Can take one space token to specify the logical block end margin of the container. Can be used on breakpoints`,
+    description: `Takes one space token to specify the logical block end margin of the container. Can be used on breakpoints`,
   },
 ];
 
 export const logicalPaddingOverrideProps: OverridesRowsProps[] = [
   {
     attribute: 'paddingInline',
     type: 'MQ<string>',
-    description: `Can take one space token to specify the logical inline start and end padding of the container. Can be used on breakpoints`,
+    description: `Takes one space token to specify the logical inline start and end padding of the container. Can be used on breakpoints`,
   },
   {
     attribute: 'paddingInlineStart',
     type: 'MQ<string>',
-    description: `Can take one space token to specify the logical inline start padding of the container. Can be used on breakpoints`,
+    description: `Takes one space token to specify the logical inline start padding of the container. Can be used on breakpoints`,
   },
   {
     attribute: 'paddingInlineEnd',
     type: 'MQ<string>',
-    description: `Can take one space token to specify the logical inline end padding of the container. Can be used on breakpoints`,
+    description: `Takes one space token to specify the logical inline end padding of the container. Can be used on breakpoints`,
   },
   {
     attribute: 'paddingBlock',
     type: 'MQ<string>',
-    description: `Can take one space token to specify the logical block start and end padding of the container. Can be used on breakpoints`,
+    description: `Takes one space token to specify the logical block start and end padding of the container. Can be used on breakpoints`,
   },
   {
     attribute: 'paddingBlockStart',
     type: 'MQ<string>',
-    description: `Can take one space token to specify the logical block start padding of the container. Can be used on breakpoints`,
+    description: `Takes one space token to specify the logical block start padding of the container. Can be used on breakpoints`,
   },
   {
     attribute: 'paddingBlockEnd',
     type: 'MQ<string>',
-    description: `It can take Can take one space token to specify the logical block end padding of the container. Can be used on breakpoints`,
+    description: `Takes one space token to specify the logical block end padding of the container. Can be used on breakpoints`,
   },
 ];
 

diff --git a/site/pages/components/accordion.tsx b/site/pages/components/accordion.tsx
@@ -313,7 +313,7 @@ const AccordionComponent = (layoutProps: LayoutProps) => (
       },
     }}
     seo={{
-      title: 'SEO Considerations',
+      title: 'SEO considerations',
       introduction: (
         <UnorderedList
           markerAlign="start"

diff --git a/site/pages/components/banner.tsx b/site/pages/components/banner.tsx
@@ -428,7 +428,7 @@ const BannerComponent = (layoutProps: LayoutProps) => (
       },
     }}
     seo={{
-      title: 'SEO Considerations',
+      title: 'SEO considerations',
       introduction: 'There are no SEO considerations for this component.',
     }}
     componentAPI={{

diff --git a/site/pages/components/block.tsx b/site/pages/components/block.tsx
@@ -22,7 +22,7 @@ const BlockComponent = (layoutProps: LayoutProps) => (
     headTags={{
       title: 'Block',
       description:
-        'The Block is a simple container component that style and space can be applied to. This is the equivalent to a frame in Figma.',
+        'Blocks are simple container components that you can apply style and space to. They’re the equivalent of frames in Figma.',
     }}
     layoutProps={layoutProps}
     pageIntroduction={{
@@ -32,7 +32,7 @@ const BlockComponent = (layoutProps: LayoutProps) => (
         illustration: 'components/block-illustration',
       },
       introduction:
-        'The Block is a simple container component that style and space can be applied to. This is the equivalent to a frame in Figma.',
+        'Blocks are simple container components that you can apply style and space to. They’re the equivalent of frames in Figma.',
     }}
     componentDefaultsKey="Block"
     meta={{
@@ -45,7 +45,7 @@ const BlockComponent = (layoutProps: LayoutProps) => (
     }}
     interactiveDemo={{
       introduction:
-        'This demo allows you to preview the Block component, its variations, and configuration options.',
+        'This demo lets you preview the block component, its variations and configuration options.',
       playground: {
         componentName: 'Block',
         component: (props: BlockProps) => (
@@ -135,7 +135,7 @@ const BlockComponent = (layoutProps: LayoutProps) => (
       },
     }}
     anatomy={{
-      introduction: 'The Block contains one element.',
+      introduction: 'The block contains one required element.',
       rows: [
         {
           name: 'Block',
@@ -147,52 +147,58 @@ const BlockComponent = (layoutProps: LayoutProps) => (
       }),
     }}
     options={{
-      introduction:
-        'The Block has options that can be used to provide an appropriate experience for different use cases.',
+      introduction: 'The block has options for different use cases:',
       cards: [
         {
           title: 'Render as',
-          description:
-            'By using Render as, the block can be converted to a ‘span’.',
+          description: 'Convert the block to a ‘span’.',
           media: getIllustrationComponent('components/block/render-as'),
         },
         {
           title: 'Style',
-          description:
-            'Styling can be applied to the block by using style presets.',
+          description: (
+            <>
+              Apply styling to the block with{' '}
+              <Link href="https://www.newskit.co.uk/theme/presets/style-presets/">
+                style presets
+              </Link>{' '}
+              .
+            </>
+          ),
           media: getIllustrationComponent('components/block/style'),
         },
         {
           title: 'Spacing',
           description:
-            'Three types of spacing can be applied to the block; spaceInline, spaceStack, and spaceInset.',
+            'Apply three types of spacing to the block: space inline, space stack and space inset.',
           media: getIllustrationComponent('components/block/spacing'),
         },
       ],
     }}
     usage={{
-      introduction:
-        'The following guidance describes how and when to appropriately use the Block.',
+      introduction: 'Here’s how and when to use the block:',
       cards: [
         {
+          title: 'Use the block to apply spacing and style presets',
           description:
-            'Use the Block as a container to easily apply spacing and style presets around other elements.',
+            'Use the block as a container to easily apply spacing and style presets around other elements.',
           kind: UsageKind.DO,
           media: getIllustrationComponent('components/block/do-01'),
         },
         {
+          title: 'Don’t use for equal spacing on multiple elements',
           description: (
             <>
-              Avoid using the Block component when equal spacing needs to be
-              applied to multiple elements. In this case, the{' '}
+              Avoid using the block when you need to apply equal spacing to
+              multiple elements. Use{' '}
               <Link href="https://www.newskit.co.uk/components/stack/">
-                Stack
-              </Link>
-              component, or the{' '}
+                stack
+              </Link>{' '}
+              or{' '}
               <Link href="https://www.newskit.co.uk/components/grid/">
-                Grid{' '}
+                grid{' '}
               </Link>
-              component should be used.
+              instead.
             </>
           ),
           kind: UsageKind.DONT,
@@ -203,21 +209,21 @@ const BlockComponent = (layoutProps: LayoutProps) => (
     accessibility={{
       introduction: (
         <>
-          As this is an HTML element, this component can utilise any aria
-          attribute, such as region. See more details{' '}
+          The block is an HTML element, so you can use any ARIA attribute (e.g.
+          region).{' '}
           <Link href="https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA">
-            here
+            Learn more ARIA at MDN Web Docs
           </Link>
           .
         </>
       ),
     }}
     seo={{
-      title: 'SEO Considerations',
-      introduction: 'There are no SEO considerations for this component.',
+      title: 'SEO considerations',
+      introduction: 'There are no SEO considerations for the block.',
     }}
     componentAPI={{
-      introduction: `The Block has a range of props that can be used to define an appropriate experience for different use cases.`,
+      introduction: `The block has a range of props to define the experience in different use cases.`,
       components: [
         {
           title: 'Block',
@@ -226,39 +232,39 @@ const BlockComponent = (layoutProps: LayoutProps) => (
               name: ' as',
               type: 'string',
               default: 'div',
-              description: `If provided, renders the Block as this element. e.g span.`,
+              description: `If provided, renders the block as this element (e.g span)`,
             },
             {
               name: 'stylePreset',
               type: 'MQ<string>',
-              description: `If provided, applies style on the Block.`,
+              description: `If provided, applies style on the block`,
             },
             {
               name: 'spaceInline(deprecated)',
               type: 'MQ<string>',
-              description: `Use marginInlineEnd instead. Set the spacing which is applied as a margin on the right of the Block.`,
+              description: `Use marginInlineEnd instead. Set the spacing which is applied as a margin on the right of the block`,
             },
             {
               name: 'spaceStack(deprecated)',
               type: 'MQ<string>',
-              description: `Use marginBlockEnd instead. This is a spacing preset token which is applied as a margin on the bottom of the Block. Use this to space stacking content down the page.`,
+              description: `Use marginBlockEnd instead. This is a spacing preset token which is applied as a margin on the bottom of the block. Use to space stack content down the page`,
             },
             {
               name: 'spaceInset(deprecated)',
               type: 'MQ<string>',
-              description: `Use paddingBlock and paddingInline instead. Apply space inset to the Block.`,
+              description: `Use paddingBlock and paddingInline instead. Apply spaceInset to the block`,
             },
             {
               name: 'transitionPreset',
               type: 'TransitionToken | TransitionToken[]',
               default: 'backgroundColorChange',
-              description: `Apply transitionPreset to the Block component.`,
+              description: `Apply transitionPreset to the block`,
             },
             ...(commonLogicalProps('propsRow') as PropsRowsProps[]),
           ],
           propsFooter: (
             <InlineMessage>
-              The Block can utilise any valid{' '}
+              The block can utilise any valid{' '}
               <Link href="https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes">
                 HTML attribute.
               </Link>