diff --git a/documentation/storybook.md b/documentation/storybook.md index 326fdc61ea..b554b2785b 100644 --- a/documentation/storybook.md +++ b/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. diff --git a/packages/react/src/Accordion/AccordionSection.tsx b/packages/react/src/Accordion/AccordionSection.tsx index eeb845c3e7..fa6b8b36e3 100644 --- a/packages/react/src/Accordion/AccordionSection.tsx +++ b/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> diff --git a/packages/react/src/Alert/Alert.tsx b/packages/react/src/Alert/Alert.tsx index 4dccb992b7..e1dc58fbef 100644 --- a/packages/react/src/Alert/Alert.tsx +++ b/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 diff --git a/packages/react/src/Blockquote/Blockquote.tsx b/packages/react/src/Blockquote/Blockquote.tsx index 661b39ee8c..69acda9776 100644 --- a/packages/react/src/Blockquote/Blockquote.tsx +++ b/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> diff --git a/packages/react/src/Breadcrumb/BreadcrumbItem.tsx b/packages/react/src/Breadcrumb/BreadcrumbItem.tsx index 741c655fb7..b2b47fa776 100644 --- a/packages/react/src/Breadcrumb/BreadcrumbItem.tsx +++ b/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> diff --git a/packages/react/src/DescriptionList/DescriptionList.tsx b/packages/react/src/DescriptionList/DescriptionList.tsx index f3afc8d9d8..638f85beca 100644 --- a/packages/react/src/DescriptionList/DescriptionList.tsx +++ b/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> diff --git a/packages/react/src/Dialog/Dialog.tsx b/packages/react/src/Dialog/Dialog.tsx index 217817cbe0..97ac4815a5 100644 --- a/packages/react/src/Dialog/Dialog.tsx +++ b/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> diff --git a/packages/react/src/FormFieldCharacterCounter/FormFieldCharacterCounter.tsx b/packages/react/src/FormFieldCharacterCounter/FormFieldCharacterCounter.tsx index 11733ed3ad..36650e59cc 100644 --- a/packages/react/src/FormFieldCharacterCounter/FormFieldCharacterCounter.tsx +++ b/packages/react/src/FormFieldCharacterCounter/FormFieldCharacterCounter.tsx @@ -8,9 +8,9 @@ import { forwardRef } from 'react' import type { ForwardedRef, HTMLAttributes } from 'react' export type FormFieldCharacterCounterProps = HTMLAttributes & { - /** 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 } diff --git a/packages/react/src/Grid/Grid.tsx b/packages/react/src/Grid/Grid.tsx index 0b33f42881..666d6fdf46 100644 --- a/packages/react/src/Grid/Grid.tsx +++ b/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> diff --git a/packages/react/src/Heading/Heading.tsx b/packages/react/src/Heading/Heading.tsx index a26603d7c9..5dbf27cfb1 100644 --- a/packages/react/src/Heading/Heading.tsx +++ b/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> export const Heading = forwardRef( diff --git a/packages/react/src/IconButton/IconButton.tsx b/packages/react/src/IconButton/IconButton.tsx index 71fe8d031c..616b5034de 100644 --- a/packages/react/src/IconButton/IconButton.tsx +++ b/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' diff --git a/packages/react/src/Link/Link.tsx b/packages/react/src/Link/Link.tsx index c6d1fec864..9a75bc0f36 100644 --- a/packages/react/src/Link/Link.tsx +++ b/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 diff --git a/packages/react/src/LinkList/LinkListLink.tsx b/packages/react/src/LinkList/LinkListLink.tsx index e37ec0aa85..67ece1ce61 100644 --- a/packages/react/src/LinkList/LinkListLink.tsx +++ b/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> diff --git a/packages/react/src/OrderedList/OrderedList.tsx b/packages/react/src/OrderedList/OrderedList.tsx index 9e8b6852c5..f18e47f91c 100644 --- a/packages/react/src/OrderedList/OrderedList.tsx +++ b/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> diff --git a/packages/react/src/PageHeading/PageHeading.tsx b/packages/react/src/PageHeading/PageHeading.tsx index 6b7759b077..e4c12bc8cc 100644 --- a/packages/react/src/PageHeading/PageHeading.tsx +++ b/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> diff --git a/packages/react/src/Paragraph/Paragraph.tsx b/packages/react/src/Paragraph/Paragraph.tsx index 59ba865876..02a6c6cdcb 100644 --- a/packages/react/src/Paragraph/Paragraph.tsx +++ b/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> export const Paragraph = forwardRef( diff --git a/packages/react/src/TextArea/TextArea.tsx b/packages/react/src/TextArea/TextArea.tsx index 85c878588d..2c9d4c6516 100644 --- a/packages/react/src/TextArea/TextArea.tsx +++ b/packages/react/src/TextArea/TextArea.tsx @@ -8,7 +8,7 @@ import { forwardRef } from 'react' import type { ForwardedRef, TextareaHTMLAttributes } from 'react' export type TextAreaProps = TextareaHTMLAttributes & { - /** 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' } diff --git a/packages/react/src/UnorderedList/UnorderedList.tsx b/packages/react/src/UnorderedList/UnorderedList.tsx index 7d05804418..b75f325ee3 100644 --- a/packages/react/src/UnorderedList/UnorderedList.tsx +++ b/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> diff --git a/storybook/src/components/Blockquote/Blockquote.stories.tsx b/storybook/src/components/Blockquote/Blockquote.stories.tsx index ef7454ea73..f407545bdc 100644 --- a/storybook/src/components/Blockquote/Blockquote.stories.tsx +++ b/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 }, }, },