Add description to the Theme prop in storybook (#1230)

Update theme docs in storybook

libs/@guardian/source-react-components/src/@types/Icons.ts

@@ -4,6 +4,14 @@ export type IconSize = 'xsmall' | 'small' | 'medium';
 
 export interface IconProps {
 	size?: IconSize;
+	/**
+	 * Partial or complete theme to override the component's colour palette.
+	 * The sanctioned colours have have been set out by the design system team.
+	 * The colours which can be changed are:
+	 *
+	 *  `fill`
+	 *
+	 */
 	theme?: Partial<ThemeIcon>;
 	isAnnouncedByScreenReader?: boolean;
 }

libs/@guardian/source-react-components/src/accordion/Accordion.tsx

@@ -21,6 +21,19 @@ export interface AccordionProps extends Props {
 	 */
 	hideToggleLabel?: boolean;
 	children: ReactElement[];
+	/**
+	 * Partial or complete theme to override the component's colour palette.
+	 * Sanctioned colours to change have been set out by the design system team.
+	 *
+	 *  The theme colours available to change are:
+	 *
+	 *  `textLabel`<br>
+	 *  `textBody`<br>
+	 *  `textCta`<br>
+	 *  `border`<br>
+	 *  `iconFill`
+	 *
+	 */
 	theme?: Partial<ThemeAccordion>;
 }
 

libs/@guardian/source-react-components/src/accordion/AccordionRow.tsx

@@ -48,7 +48,16 @@ export interface AccordionRowProps
 	 */
 	hideToggleLabel?: boolean;
 	/**
-	 * Overriding of partial or entire Accordion Row theme.
+	 * Partial or complete theme to override the component's colour palette.
+	 * The sanctioned colours have been set out by the design system team.
+	 * The colours which can be changed are:
+	 *
+	 *  `textLabel`<br>
+	 *  `textBody`<br>
+	 *  `textCta`<br>
+	 *  `border`<br>
+	 *  `iconFill`
+	 *
 	 */
 	theme?: Partial<ThemeAccordion>;
 }

libs/@guardian/source-react-components/src/button/@types/SharedButtonProps.ts

@@ -44,7 +44,21 @@ export interface SharedButtonProps extends Props {
 	 */
 	loadingAnnouncement?: string;
 	/**
-	 * Overriding of partial or entire button theme.
+	 * Partial or complete theme to override the component's colour palette.
+	 * The sanctioned colours have been set out by the design system team.
+	 * The colours which can be changed are:
+	 *
+	 *  `textPrimary`<br>
+	 *  `backgroundPrimary`<br>
+	 *  `backgroundPrimaryHover`<br>
+	 *  `textSecondary`<br>
+	 *  `backgroundSecondary`<br>
+	 *  `backgroundSecondaryHover`<br>
+	 *  `textTertiary`<br>
+	 *  `backgroundTertiaryHover`<br>
+	 *  `borderTertiary`<br>
+	 *  `textSubdued`<br>
+	 *
 	 */
 	theme?: Partial<ThemeButton>;
 }

libs/@guardian/source-react-components/src/checkbox/Checkbox.tsx

@@ -58,7 +58,20 @@ export interface CheckboxProps
 	 */
 	error?: boolean;
 	/**
-	 * A component level theme to override the colour palette of the choice card component
+	 * Partial or complete theme to override the component's colour palette.
+	 * The sanctioned colours have been set out by the design system team.
+	 * The colours which can be changed are:
+	 *
+	 *  `borderUnselected`<br>
+	 *  `borderHover`<br>
+	 *  `borderSelected`<br>
+	 *  `borderError`<br>
+	 *  `fillSelected`<br>
+	 *  `fillUnselected`<br>
+	 *  `textLabel`<br>
+	 *  `textSupporting`<br>
+	 *  `textIndeterminate`
+	 *
 	 */
 	theme?: Partial<ThemeCheckbox>;
 }

libs/@guardian/source-react-components/src/checkbox/CheckboxGroup.stories.tsx

@@ -4,11 +4,8 @@ import { useState } from 'react';
 import { Checkbox } from './Checkbox';
 import CheckboxStories from './Checkbox.stories';
 import { CheckboxGroup } from './CheckboxGroup';
-import {
-	ThemeCheckbox,
-	themeCheckboxBrand,
-	themeCheckboxGroupBrand,
-} from './theme';
+import type { ThemeCheckbox } from './theme';
+import { themeCheckboxBrand, themeCheckboxGroupBrand } from './theme';
 
 const meta: Meta<typeof CheckboxGroup> = {
 	title: 'CheckboxGroup',

libs/@guardian/source-react-components/src/checkbox/CheckboxGroup.tsx

@@ -35,6 +35,18 @@ export interface CheckboxGroupProps extends Props {
 	 */
 	error?: string;
 	children: JSX.Element | JSX.Element[];
+	/**
+	 * Partial or complete theme to override the component's colour palette.
+	 * The sanctioned colours have been set out by the design system team.
+	 * The colours which can be changed are:
+	 *
+	 *  `textLabel`<br>
+	 *  `textOptional`<br>
+	 *  `textSupporting`<br>
+	 *  `textError`<br>
+	 *  `textSuccess`<br>
+	 *
+	 */
 	theme?: Partial<ThemeCheckboxGroup>;
 }
 

libs/@guardian/source-react-components/src/choice-card/ChoiceCard.tsx

@@ -56,7 +56,23 @@ export interface ChoiceCardProps
 	 */
 	type?: 'radio' | 'checkbox';
 	/**
-	 * A component level theme to override the colour palette of the choice card component
+	 * A component level theme to override the theme.
+	 * The sanctioned colours have been set out by the design system team.
+	 * The colours which can be changed are:
+	 *
+	 *  `textUnselected` <br>
+	 *  `textSelected` <br>
+	 *  `textHover` <br>
+	 *  `textError` <br>
+	 *  `borderUnselected` <br>
+	 *  `borderSelected` <br>
+	 *  `borderHover` <br>
+	 *  `borderError` <br>
+	 *  `backgroundUnselected` <br>
+	 *  `backgroundHover` <br>
+	 *  `backgroundSelected` <br>
+	 *  `backgroundTick` <br>
+	 *
 	 */
 	theme?: Partial<ThemeChoiceCard>;
 }

libs/@guardian/source-react-components/src/choice-card/ChoiceCardGroup.stories.tsx

@@ -4,7 +4,7 @@ import { useState } from 'react';
 import { ChoiceCard } from './ChoiceCard';
 import ChoiceCardStories from './ChoiceCard.stories';
 import { ChoiceCardGroup } from './ChoiceCardGroup';
-import { ThemeChoiceCard } from './theme';
+import type { ThemeChoiceCard } from './theme';
 
 const meta: Meta<typeof ChoiceCardGroup> = {
 	title: 'ChoiceCardGroup',

libs/@guardian/source-react-components/src/choice-card/ChoiceCardGroup.tsx

@@ -51,6 +51,18 @@ export interface ChoiceCardGroupProps
 	 */
 	columns?: ChoiceCardColumns;
 	children: JSX.Element | JSX.Element[];
+	/**
+	 * A component level theme to override the theme.
+	 * The sanctioned colours have been set out by the design system team.
+	 * The colours which can be changed are:
+	 *
+	 *  `textLabel`<br>
+	 *  `textOptional`<br>
+	 *  `textSupporting`<br>
+	 *  `textError`<br>
+	 *  `textSuccess`<br>
+	 *
+	 */
 	theme?: Partial<ThemeChoiceCardGroup>;
 }
 

libs/@guardian/source-react-components/src/icons/Icons.stories.tsx

@@ -265,6 +265,37 @@ type IconChromaticStoryArgs = {
 
 const meta: Meta<IconChromaticStoryArgs> = {
 	title: 'Icons',
+	args: {
+		theme: undefined,
+		isAnnouncedByScreenReader: false,
+		size: 'small',
+	},
+	argTypes: {
+		theme: {
+			description:
+				" Partial or complete theme to override the component's colour palette.\n" +
+				'The sanctioned colours have have been set out by the design system team.\n',
+			table: {
+				type: {
+					summary: 'Partial<ThemeIcon>',
+					detail: '{\n' + '\tfill?: string;\n' + '}',
+				},
+			},
+		},
+		size: {
+			control: 'select',
+			options: ['xsmall', 'small', 'medium'],
+			description: 'The size of the Icon',
+			table: {
+				type: { summary: 'xsmall | small | medium' },
+			},
+		},
+		icons: {
+			table: {
+				disable: true,
+			},
+		},
+	},
 };
 
 export default meta;

libs/@guardian/source-react-components/src/label/@types/LabelProps.ts

@@ -29,5 +29,16 @@ export interface LabelProps
 	size?: InputSize;
 	cssOverrides?: SerializedStyles | SerializedStyles[];
 	children?: ReactNode;
+	/**
+	 * Partial or complete theme to override the component's colour palette.
+	 * The sanctioned colours have been set out by the design system team.
+	 * The colours which can be changed are:
+	 *
+	 *  `textLabel`<br>
+	 *  `textOptional`<br>
+	 *  `textSupporting`<br>
+	 *  `textError`<br>
+	 *  `textSuccess`<br>
+	 */
 	theme?: Partial<ThemeLabel>;
 }

libs/@guardian/source-react-components/src/label/@types/LegendProps.ts

@@ -21,5 +21,16 @@ export interface LegendProps extends HTMLAttributes<HTMLLegendElement>, Props {
 	 */
 	hideLabel?: boolean;
 	cssOverrides?: SerializedStyles | SerializedStyles[];
+	/**
+	 * Partial or complete theme to override the component's colour palette.
+	 * The sanctioned colours have been set out by the design system team.
+	 * The colours which can be changed are:
+	 *
+	 *  `textLabel`<br>
+	 *  `textOptional`<br>
+	 *  `textSupporting`<br>
+	 *  `textError`<br>
+	 *  `textSuccess`<br>
+	 */
 	theme?: Partial<ThemeLabel>;
 }

libs/@guardian/source-react-components/src/link/@types/SharedLinkProps.ts

@@ -26,5 +26,16 @@ export interface SharedLinkProps extends Props {
 	 */
 	iconSide?: IconSide;
 	children?: ReactNode;
+	/**
+	 * Partial or complete theme to override the component's colour palette.
+	 * The sanctioned colours have been set out by the design system team.
+	 * The colours which can be changed are:
+	 *
+	 *  `textPrimary`<br>
+	 *  `textPrimaryHover`<br>
+	 *  `textSecondary`<br>
+	 *  `textSecondaryHover`<br>
+	 *
+	 */
 	theme?: Partial<ThemeLink>;
 }

libs/@guardian/source-react-components/src/radio/Radio.stories.tsx

@@ -1,8 +1,8 @@
+import { palette } from '@guardian/source-foundations';
 import type { Meta, StoryFn } from '@storybook/react';
 import { Radio } from './Radio';
 import type { RadioProps } from './Radio';
 import { themeRadioBrand } from './theme';
-import { palette } from '@guardian/source-foundations';
 
 const meta: Meta<typeof Radio> = {
 	title: 'Radio',

libs/@guardian/source-react-components/src/radio/Radio.tsx

@@ -46,7 +46,18 @@ export interface RadioProps
 	 */
 	supporting?: string | ReactNode;
 	/**
-	 * Partial or complete theme to override radio button's colour palette
+	 * Partial or complete theme to override the component's colour palette.
+	 * The sanctioned colours have been set out by the design system team.
+	 * The colours which can be changed are:
+	 *
+	 *  `borderSelected`<br>
+	 *  `borderUnselected`<br>
+	 *  `borderHover`<br>
+	 *  `borderError`<br>
+	 *  `fillSelected`<br>
+	 *  `fillUnselected`<br>
+	 *  `textLabel`<br>
+	 *  `textSupporting`<br>
 	 */
 	theme?: Partial<ThemeRadio>;
 }

libs/@guardian/source-react-components/src/radio/RadioGroup.tsx

@@ -40,7 +40,17 @@ export interface RadioGroupProps
 	 */
 	error?: string;
 	/**
-	 * Partial or complete theme to override radio button's colour palette
+	 * Partial or complete theme to override the component's colour palette.
+	 * The sanctioned colours have been set out by the design system team.
+	 * The colours which can be changed are:
+	 *
+	 *  `textLabel`<br>
+	 *  `textOptional`<br>
+	 *  `textSupporting`<br>
+	 *  `textError`<br>
+	 *  `textSuccess`<br>
+	 *  `borderHover`<br>
+	 *  `borderError`<br>
 	 */
 	theme?: Partial<ThemeRadioGroup>;
 }

libs/@guardian/source-react-components/src/select/Select.tsx

@@ -50,6 +50,25 @@ export interface SelectProps
 	 */
 	success?: string;
 	children: JSX.Element | JSX.Element[];
+	/**
+	 * Partial or complete theme to override the component's colour palette.
+	 * The sanctioned colours have been set out by the design system team.
+	 * The colours which can be changed are:
+	 *
+	 *  `textUserInput`<br>
+	 *  `textLabel`<br>
+	 *  `textOptional`<br>
+	 *  `textSupporting`<br>
+	 *  `textError`<br>
+	 *  `textSuccess`<br>
+	 *  `backgroundInput`<br>
+	 *  `border`<br>
+	 *  `borderActive`<br>
+	 *  `borderError`<br>
+	 *  `borderSuccess`<br>
+	 *  `iconFill`<br>
+	 *
+	 */
 	theme?: Partial<ThemeSelect>;
 }
 

libs/@guardian/source-react-components/src/text-area/TextArea.tsx

@@ -1,6 +1,7 @@
 import type { EmotionJSX } from '@emotion/react/types/jsx-namespace';
 import { descriptionId, generateSourceId } from '@guardian/source-foundations';
 import type { InputHTMLAttributes } from 'react';
+import type { InputSize } from '../@types/InputSize';
 import type { Props } from '../@types/Props';
 import { Label } from '../label/Label';
 import { InlineError } from '../user-feedback/InlineError';
@@ -14,8 +15,8 @@ import {
 	textArea,
 	widthFluid,
 } from './styles';
-import { InputSize } from '../@types/InputSize';
-import { ThemeTextArea, themeTextArea } from './theme';
+import type { ThemeTextArea } from './theme';
+import { themeTextArea } from './theme';
 
 export interface TextAreaProps
 	extends Omit<InputHTMLAttributes<HTMLTextAreaElement>, 'size'>,
@@ -61,7 +62,21 @@ export interface TextAreaProps
 	 */
 	rows?: number;
 	/**
-	 * Partial or complete theme to override text area's colour palette
+	 * Partial or complete theme to override the component's colour palette.
+	 * The sanctioned colours have been set out by the design system team.
+	 * The colours which can be changed are:
+	 *
+	 *  `textUserInput`<br>
+	 *  `textLabel`<br>
+	 *  `textOptional`<br>
+	 *  `textSupporting`<br>
+	 *  `textError`<br>
+	 *  `textSuccess`<br>
+	 *  `backgroundInput`<br>
+	 *  `border`<br>
+	 *  `borderError`<br>
+	 *  `borderSuccess`<br>
+	 *
 	 */
 	theme?: Partial<ThemeTextArea>;
 }
@@ -152,7 +167,7 @@ export const TextArea = ({
 				id={textAreaId}
 				aria-required={!optional}
 				aria-invalid={!!error}
-				aria-describedby={error || success ? descriptionId(textAreaId) : ''}
+				aria-describedby={error ?? success ? descriptionId(textAreaId) : ''}
 				required={!optional}
 				rows={rows}
 				className={getClassName()}