Improve consistency and terseness, follow guidelines

documentation/storybook.md

@@ -38,6 +38,7 @@ Be sure to follow these guidelines when you do:
 
 1. Add a `description` field instead of a JSDoc comment for native HTML attributes.
    Use terse sentences that end with a full stop.
+   When adding a prop, check for an corresponding existing prop and copy its description.
 2. When mentioning a component, write its name in title case, e.g. ‘Card’ or ‘Form Field’.
    This represents the component more strongly and helps users recognise them as such.
 3. For props offering five options or less, use radio buttons rather than a select.

packages/react/src/Accordion/AccordionSection.tsx

@@ -12,9 +12,9 @@ import { getHeadingElement } from '../Heading/getHeadingElement'
 import { Icon } from '../Icon/Icon'
 
 export type AccordionSectionProps = {
-  /** The heading for this section of the accordion. */
+  /** The heading text. */
   label: string
-  /** Whether the section initially shows its content. */
+  /** Whether the content is displayed initially. */
   expanded?: boolean
 } & PropsWithChildren<HTMLAttributes<HTMLElement>>
 

packages/react/src/Alert/Alert.tsx

@@ -15,7 +15,7 @@ import { IconButton } from '../IconButton'
 export type AlertProps = {
   /** Whether the user can dismiss the Alert. Adds a button to its top right. */
   closeable?: boolean
-  /** The hierarchical level of the Heading within the document. */
+  /** The hierarchical level of the Alert’s Heading within the document. */
   headingLevel?: HeadingProps['level']
   /** A function to run when dismissing. */
   onClose?: () => void

packages/react/src/Blockquote/Blockquote.tsx

@@ -8,7 +8,7 @@ import { forwardRef } from 'react'
 import type { BlockquoteHTMLAttributes, ForwardedRef, PropsWithChildren } from 'react'
 
 export type BlockquoteProps = {
-  /** Changes the text color for readability on a dark background. */
+  /** Changes the text colour for readability on a dark background. */
   inverseColor?: boolean
 } & PropsWithChildren<BlockquoteHTMLAttributes<HTMLQuoteElement>>
 

packages/react/src/Breadcrumb/BreadcrumbItem.tsx

@@ -8,7 +8,7 @@ import { forwardRef } from 'react'
 import type { ForwardedRef, HTMLAttributes, PropsWithChildren } from 'react'
 
 export type BreadcrumbItemProps = {
-  /** The url for the link on this breadcrumb item. */
+  /** The url for the link. */
   href: string
 } & PropsWithChildren<HTMLAttributes<HTMLLIElement>>
 

packages/react/src/DescriptionList/DescriptionList.tsx

@@ -10,7 +10,7 @@ import { DescriptionListDetails } from './DescriptionListDetails'
 import { DescriptionListTerm } from './DescriptionListTerm'
 
 export type DescriptionListProps = {
-  /** Changes the text color for readability on a dark background. */
+  /** Changes the text colour for readability on a dark background. */
   inverseColor?: boolean
 } & PropsWithChildren<HTMLAttributes<HTMLDListElement>>
 

packages/react/src/Dialog/Dialog.tsx

@@ -10,7 +10,7 @@ import { Heading } from '../Heading'
 import { IconButton } from '../IconButton'
 
 export type DialogProps = {
-  /** The list of buttons for this dialog. Start with a primary button. */
+  /** The list of buttons. Start with a primary button. */
   actions?: ReactNode
 } & PropsWithChildren<DialogHTMLAttributes<HTMLDialogElement>>
 

packages/react/src/FormFieldCharacterCounter/FormFieldCharacterCounter.tsx

@@ -8,9 +8,9 @@ import { forwardRef } from 'react'
 import type { ForwardedRef, HTMLAttributes } from 'react'
 
 export type FormFieldCharacterCounterProps = HTMLAttributes<HTMLDivElement> & {
-  /** The current length of the field’s content. */
+  /** The current length of the field’s value. */
   length: number
-  /** The maximum length of the field’s content. */
+  /** The maximum length of the field’s value. */
   maxLength: number
 }
 

packages/react/src/Grid/Grid.tsx

@@ -21,20 +21,20 @@ export type GridPaddingSize = 'small' | 'medium' | 'large'
 type GridPaddingVerticalProp = {
   paddingBottom?: never
   paddingTop?: never
-  /** The amount of vertical white space above and below. */
+  /** The amount of space above and below. */
   paddingVertical?: GridPaddingSize
 }
 
 type GridPaddingTopAndBottomProps = {
-  /** The amount of vertical white space below. */
+  /** The amount of space below. */
   paddingBottom?: GridPaddingSize
-  /** The amount of vertical white space above. */
+  /** The amount of space above. */
   paddingTop?: GridPaddingSize
   paddingVertical?: never
 }
 
 export type GridProps = {
-  /** The amount of vertical white space between rows. */
+  /** The amount of space between rows. */
   gapVertical?: 'none' | 'small' | 'large'
 } & (GridPaddingVerticalProp | GridPaddingTopAndBottomProps) &
   PropsWithChildren<HTMLAttributes<HTMLDivElement>>

packages/react/src/Heading/Heading.tsx

@@ -13,12 +13,12 @@ export type HeadingLevel = 1 | 2 | 3 | 4
 type HeadingSize = 'level-1' | 'level-2' | 'level-3' | 'level-4' | 'level-5' | 'level-6'
 
 export type HeadingProps = {
-  /** The hierarchical level of the heading. */
+  /** Changes the text colour for readability on a dark background. */
+  inverseColor?: boolean
+  /** The hierarchical level within the document. */
   level?: HeadingLevel
-  /** Makes the title larger or smaller without changing its position in the heading hierarchy. */
+  /** Uses larger or smaller text without changing its position in the heading hierarchy. */
   size?: HeadingSize
-  /** Changes the text color for readability on a dark background. */
-  inverseColor?: boolean
 } & PropsWithChildren<HTMLAttributes<HTMLHeadingElement>>
 
 export const Heading = forwardRef(

packages/react/src/IconButton/IconButton.tsx

@@ -13,7 +13,7 @@ import { VisuallyHidden } from '../VisuallyHidden'
 export type IconButtonProps = {
   /** The accessible text for the icon. Will be read out by screen readers. Should describe the button’s action. */
   label: string
-  /** The background colour on which the icon button sits. Allows the icon to provide visual contrast. */
+  /** Describes the underlying background colour. Allows the icon to provide visual contrast. */
   onBackground?: 'light' | 'dark'
   /** The size of the icon. Corresponds with the text levels. */
   size?: 'level-3' | 'level-4' | 'level-5' | 'level-6'

packages/react/src/Link/Link.tsx

@@ -11,7 +11,7 @@ type LinkOnBackground = 'default' | 'light' | 'dark'
 type LinkVariant = 'standalone' | 'inline'
 
 export type LinkProps = {
-  /** The background colour on which the link sits. Allows the text to provide visual contrast. */
+  /** Describes the underlying background colour. Allows the text to provide visual contrast. */
   onBackground?: LinkOnBackground
   /** Whether the link is inline or stands alone. */
   variant?: LinkVariant

packages/react/src/LinkList/LinkListLink.tsx

@@ -12,13 +12,13 @@ import { Icon } from '../Icon'
 type BackgroundName = 'default' | 'light' | 'dark'
 
 export type LinkListLinkProps = {
-  /** The target url for the link. */
+  /** The url for the link. */
   href: string
   /** An icon to display instead of the default chevron. Don’t mix custom icons with chevrons in one list. */
   icon?: Function
-  /** Whether the link sits on a dark background. */
+  /** Describes the underlying background colour. Allows the text to provide visual contrast. */
   onBackground?: BackgroundName
-  /** The text size for the link. Use the same size for all items in the list. */
+  /** The size of the text. Use the same size for all items in the list. */
   size?: 'small' | 'large'
 } & PropsWithChildren<AnchorHTMLAttributes<HTMLAnchorElement>>
 

packages/react/src/OrderedList/OrderedList.tsx

@@ -9,11 +9,11 @@ import type { ForwardedRef, OlHTMLAttributes, PropsWithChildren } from 'react'
 import { OrderedListItem } from './OrderedListItem'
 
 export type OrderedListProps = {
-  /** Changes the text color for readability on a dark background. */
+  /** Changes the text colour for readability on a dark background. */
   inverseColor?: boolean
   /** Whether the list items show a marker. */
   markers?: boolean
-  /** The text size for the ordered list */
+  /** The size of the text. */
   size?: 'small'
 } & PropsWithChildren<OlHTMLAttributes<HTMLOListElement>>
 

packages/react/src/PageHeading/PageHeading.tsx

@@ -8,7 +8,7 @@ import { forwardRef } from 'react'
 import type { ForwardedRef, HTMLAttributes, PropsWithChildren } from 'react'
 
 export type PageHeadingProps = {
-  /** Changes the text color for readability on a dark background. */
+  /** Changes the text colour for readability on a dark background. */
   inverseColor?: boolean
 } & PropsWithChildren<HTMLAttributes<HTMLHeadingElement>>
 

packages/react/src/Paragraph/Paragraph.tsx

@@ -9,10 +9,10 @@ import { forwardRef } from 'react'
 import type { ForwardedRef, HTMLAttributes, PropsWithChildren } from 'react'
 
 export type ParagraphProps = {
-  /** The text size for the paragraph. */
-  size?: 'small' | 'large'
-  /** Changes the text color for readability on a dark background. */
+  /** Changes the text colour for readability on a dark background. */
   inverseColor?: boolean
+  /** The size of the text. */
+  size?: 'small' | 'large'
 } & PropsWithChildren<HTMLAttributes<HTMLParagraphElement>>
 
 export const Paragraph = forwardRef(

packages/react/src/TextArea/TextArea.tsx

@@ -8,7 +8,7 @@ import { forwardRef } from 'react'
 import type { ForwardedRef, TextareaHTMLAttributes } from 'react'
 
 export type TextAreaProps = TextareaHTMLAttributes<HTMLTextAreaElement> & {
-  /** Allows the user to resize the text box. The default enables resizing in both directions. */
+  /** Allows the user to resize the text box. The default is resizing in both directions. */
   resize?: 'none' | 'horizontal' | 'vertical'
 }
 

packages/react/src/UnorderedList/UnorderedList.tsx

@@ -9,11 +9,11 @@ import type { ForwardedRef, HTMLAttributes, PropsWithChildren } from 'react'
 import { UnorderedListItem } from './UnorderedListItem'
 
 export type UnorderedListProps = {
-  /** Changes the text color for readability on a dark background. */
+  /** Changes the text colour for readability on a dark background. */
   inverseColor?: boolean
   /** Whether the list items show a marker. */
   markers?: boolean
-  /** The text size for the unordered list. */
+  /** The size of the text. */
   size?: 'small'
 } & PropsWithChildren<HTMLAttributes<HTMLUListElement>>
 

storybook/src/components/Blockquote/Blockquote.stories.tsx

@@ -19,7 +19,7 @@ const meta = {
   },
   argTypes: {
     children: {
-      description: 'The text of the quote.',
+      description: 'The text for the quote.',
       table: { disable: false },
     },
   },