@utilitywarehouse/hearth-react-native 0.2.0 → 0.3.0

package/src/components/DescriptionList/DescriptionList.stories.tsx

@@ -0,0 +1,154 @@
+import { Meta, StoryObj } from '@storybook/react-vite';
+import { DescriptionList, DescriptionListItem } from '.';
+import { VariantTitle } from '../../../docs/components';
+import { Flex } from '../Flex';
+
+const meta: Meta<typeof DescriptionList> = {
+  title: 'Stories / DescriptionList',
+  component: DescriptionList,
+  parameters: { layout: 'centered' },
+  argTypes: {
+    direction: {
+      control: 'select',
+      options: ['row', 'column'],
+      description: 'Orientation of heading & description pairs',
+    },
+    itemHeadingWidth: {
+      control: 'number',
+      description: 'Override width (px) for heading column when direction is row',
+    },
+    heading: {
+      control: 'text',
+      description:
+        'Optional overall heading (renders a SectionHeader). Playground only – prefer SectionHeader directly when composing.',
+    },
+    helperText: {
+      control: 'text',
+      description: 'Supporting text shown under heading (Playground only).',
+    },
+    linkText: { control: 'text', description: 'Header link text (Playground only).' },
+    linkHref: { control: 'text', description: 'Header link href (web).' },
+    linkIconPosition: {
+      control: 'select',
+      options: ['left', 'right'],
+      description: 'Header link icon position.',
+    },
+    linkShowIcon: { control: 'boolean', description: 'Show header link icon.' },
+    linkTarget: {
+      control: 'select',
+      options: ['_blank', '_self', '_parent', '_top'],
+      description: 'Header link target (web).',
+    },
+  },
+  args: {
+    direction: 'column',
+    heading: 'Account details',
+    helperText: 'Static account metadata',
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const sampleData = [
+  { heading: 'Account Number', description: '123456789' },
+  { heading: 'Sort Code', description: '12-34-56' },
+  { heading: 'Status', description: 'Active' },
+];
+
+export const Playground: Story = {
+  render: args => (
+    <DescriptionList {...args}>
+      {sampleData.map(item => (
+        <DescriptionListItem
+          key={item.heading}
+          heading={item.heading}
+          description={item.description}
+        />
+      ))}
+    </DescriptionList>
+  ),
+};
+
+export const Row: Story = {
+  args: { direction: 'row' },
+  render: args => (
+    <DescriptionList {...args}>
+      {sampleData.map(item => (
+        <DescriptionListItem
+          key={item.heading}
+          heading={item.heading}
+          description={item.description}
+        />
+      ))}
+    </DescriptionList>
+  ),
+};
+
+export const Column: Story = {
+  args: { direction: 'column' },
+  render: args => (
+    <DescriptionList {...args}>
+      {sampleData.map(item => (
+        <DescriptionListItem
+          key={item.heading}
+          heading={item.heading}
+          description={item.description}
+        />
+      ))}
+    </DescriptionList>
+  ),
+};
+
+export const KitchenSink: Story = {
+  parameters: { controls: { include: [] } },
+  render: () => (
+    <Flex direction="column" space="lg" style={{ width: '100%' }}>
+      <VariantTitle title="Row direction">
+        <DescriptionList direction="row">
+          {sampleData.map(item => (
+            <DescriptionListItem
+              key={item.heading}
+              heading={item.heading}
+              description={item.description}
+            />
+          ))}
+        </DescriptionList>
+      </VariantTitle>
+      <VariantTitle title="Column direction">
+        <DescriptionList direction="column">
+          {sampleData.map(item => (
+            <DescriptionListItem
+              key={item.heading}
+              heading={item.heading}
+              description={item.description}
+            />
+          ))}
+        </DescriptionList>
+      </VariantTitle>
+    </Flex>
+  ),
+};
+
+export const WithLinks: Story = {
+  parameters: { controls: { include: ['direction', 'itemHeadingWidth'] } },
+  args: { direction: 'row' },
+  render: args => (
+    <DescriptionList {...args}>
+      <DescriptionListItem
+        heading="Account Number"
+        description="123456789"
+        linkText="Manage"
+        linkHref="https://example.com/account"
+        linkShowIcon
+      />
+      <DescriptionListItem
+        heading="Status"
+        description="Active"
+        linkText="Change"
+        linkHref="https://example.com/status"
+      />
+      <DescriptionListItem heading="Region" description="United Kingdom" />
+    </DescriptionList>
+  ),
+};

package/src/components/DescriptionList/DescriptionList.tsx

@@ -0,0 +1,64 @@
+import { useMemo } from 'react';
+import { View } from 'react-native';
+import { StyleSheet } from 'react-native-unistyles';
+import { SectionHeader } from '../SectionHeader';
+import { DescriptionListContext } from './DescriptionList.context';
+import type DescriptionListProps from './DescriptionList.props';
+
+const DescriptionList = ({
+  direction = 'column',
+  itemHeadingWidth,
+  heading,
+  helperText,
+  linkText,
+  linkHref,
+  linkIcon,
+  linkIconPosition,
+  linkOnPress,
+  linkTarget,
+  linkShowIcon,
+  children,
+  style,
+  ...props
+}: DescriptionListProps) => {
+  styles.useVariants({ direction });
+  const value = useMemo(() => ({ direction, itemHeadingWidth }), [direction, itemHeadingWidth]);
+
+  return (
+    <DescriptionListContext.Provider value={value}>
+      <View accessibilityRole="list" {...props} style={[styles.container, style]}>
+        {heading ? (
+          <SectionHeader
+            heading={heading}
+            helperText={helperText}
+            linkText={linkText}
+            linkHref={linkHref}
+            linkIcon={linkIcon}
+            linkIconPosition={linkIconPosition}
+            linkOnPress={linkOnPress}
+            linkTarget={linkTarget}
+            linkShowIcon={linkShowIcon}
+          />
+        ) : null}
+        {children}
+      </View>
+    </DescriptionListContext.Provider>
+  );
+};
+
+DescriptionList.displayName = 'DescriptionList';
+
+const styles = StyleSheet.create(theme => ({
+  container: {
+    width: theme.space.full,
+    gap: theme.components.descriptionList.gap,
+    variants: {
+      direction: {
+        row: {},
+        column: {},
+      },
+    },
+  },
+}));
+
+export default DescriptionList;

package/src/components/DescriptionList/DescriptionListItem.props.ts

@@ -0,0 +1,19 @@
+import type { ComponentType, ReactNode } from 'react';
+import type { ViewProps } from 'react-native';
+
+export interface DescriptionListItemProps extends ViewProps {
+  /** Heading / label part */
+  heading: ReactNode;
+  /** Description / value part */
+  description: ReactNode;
+  headingWidth?: number;
+  linkText?: string;
+  linkHref?: string;
+  linkIcon?: ComponentType;
+  linkIconPosition?: 'left' | 'right';
+  linkOnPress?: () => void;
+  linkTarget?: '_blank' | '_self' | '_parent' | '_top';
+  linkShowIcon?: boolean;
+}
+
+export default DescriptionListItemProps;

package/src/components/DescriptionList/DescriptionListItem.tsx

@@ -0,0 +1,101 @@
+import { View } from 'react-native';
+import { StyleSheet } from 'react-native-unistyles';
+import { useTheme } from '../../hooks';
+import { BodyText } from '../BodyText';
+import { Link } from '../Link';
+import { useDescriptionListContext } from './DescriptionList.context';
+import type DescriptionListItemProps from './DescriptionListItem.props';
+
+const DescriptionListItem = ({
+  heading,
+  description,
+  headingWidth,
+  linkText,
+  linkHref,
+  linkIcon,
+  linkIconPosition,
+  linkOnPress,
+  linkTarget,
+  linkShowIcon,
+  style,
+  ...props
+}: DescriptionListItemProps) => {
+  const { components } = useTheme();
+  const { direction, itemHeadingWidth = components.descriptionList.item.row.headingWidth } =
+    useDescriptionListContext();
+  styles.useVariants({ direction });
+  const headingIsText = typeof heading === 'string' || typeof heading === 'number';
+  const descIsText = typeof description === 'string' || typeof description === 'number';
+  const combinedLabel = headingIsText && descIsText ? `${heading}: ${description}` : undefined;
+  const hideDescendants = !!combinedLabel;
+  return (
+    <View
+      accessibilityRole="text"
+      accessible={!!combinedLabel}
+      accessibilityLabel={combinedLabel}
+      {...props}
+      style={[styles.item, style]}
+    >
+      <View
+        style={styles.textWrap}
+        importantForAccessibility={hideDescendants ? 'no-hide-descendants' : undefined}
+        accessibilityElementsHidden={hideDescendants || undefined}
+      >
+        <View style={[direction === 'row' && { width: headingWidth || itemHeadingWidth }]}>
+          {headingIsText ? <BodyText style={styles.headingText}>{heading}</BodyText> : heading}
+        </View>
+        <View style={styles.descriptionWrapper}>
+          {descIsText ? <BodyText>{description}</BodyText> : description}
+        </View>
+      </View>
+      {linkText ? (
+        <Link
+          href={linkHref}
+          onPress={linkOnPress}
+          target={linkTarget}
+          showIcon={linkShowIcon}
+          icon={linkIcon}
+          iconPosition={linkIconPosition}
+          accessibilityRole="link"
+        >
+          {linkText}
+        </Link>
+      ) : null}
+    </View>
+  );
+};
+
+DescriptionListItem.displayName = 'DescriptionListItem';
+
+const styles = StyleSheet.create(theme => ({
+  item: {
+    width: theme.space.full,
+    flexDirection: 'row',
+    alignItems: 'flex-start',
+    gap: theme.components.descriptionList.item.gap,
+  },
+  textWrap: {
+    flex: 1,
+    variants: {
+      direction: {
+        row: {
+          flexDirection: 'row',
+          alignItems: 'flex-start',
+          gap: theme.components.descriptionList.item.row.gap,
+        },
+        column: {
+          flexDirection: 'column',
+          gap: theme.components.descriptionList.item.column.gap,
+        },
+      },
+    },
+  },
+  headingText: {
+    color: theme.color.text.secondary,
+  },
+  descriptionWrapper: {
+    flex: 1,
+  },
+}));
+
+export default DescriptionListItem;

package/src/components/DescriptionList/index.ts

@@ -0,0 +1,4 @@
+export { default as DescriptionList } from './DescriptionList';
+export type { default as DescriptionListProps } from './DescriptionList.props';
+export { default as DescriptionListItem } from './DescriptionListItem';
+export type { default as DescriptionListItemProps } from './DescriptionListItem.props';

package/src/components/Divider/Divider.props.ts

@@ -1,9 +1,9 @@
 import type { DimensionValue, ViewProps } from 'react-native';
-import type { ColorValue } from '../../types';
+import type { ColorValue, SpacingValues } from '../../types';
 
 interface DividerProps extends Omit<ViewProps, 'children'> {
   color?: ColorValue;
-  space?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+  space?: SpacingValues;
   orientation?: 'horizontal' | 'vertical';
   height?: DimensionValue;
   width?: DimensionValue;

package/src/components/Divider/Divider.stories.tsx

@@ -1,7 +1,7 @@
-import { Divider } from '.';
 import { Meta, StoryObj } from '@storybook/react-vite';
-import { Box } from '../Box';
+import { Divider } from '.';
 import { coloursAsArray } from '../../utils';
+import { Box } from '../Box';
 
 const meta = {
   title: 'Stories / Divider',
@@ -21,7 +21,7 @@ const meta = {
       description: 'Color of the divider',
     },
     space: {
-      options: ['none', 'xs', 'sm', 'md', 'lg', 'xl'],
+      options: ['none', '2xs', 'xs', 'sm', 'md', 'lg', 'xl', '2xl'],
       control: 'select',
       description: 'Space between the divider',
     },

package/src/components/Divider/Divider.tsx

@@ -44,11 +44,13 @@ const styles = StyleSheet.create(theme => ({
       },
       space: {
         none: {},
+        '2xs': {},
         xs: {},
         sm: {},
         md: {},
         lg: {},
         xl: {},
+        '2xl': {},
       },
       flexItem: {
         true: {
@@ -64,6 +66,17 @@ const styles = StyleSheet.create(theme => ({
           marginVertical: 0,
         },
       },
+      {
+        orientation: 'horizontal',
+        space: '2xs',
+        styles: {
+          marginVertical: {
+            base: theme.layout.mobile.spacing['2xs'],
+            md: theme.layout.tablet.spacing['2xs'],
+            lg: theme.layout.desktop.spacing['2xs'],
+          },
+        },
+      },
       {
         orientation: 'horizontal',
         space: 'xs',
@@ -119,6 +132,17 @@ const styles = StyleSheet.create(theme => ({
           },
         },
       },
+      {
+        orientation: 'horizontal',
+        space: '2xl',
+        styles: {
+          marginVertical: {
+            base: theme.layout.mobile.spacing['2xl'],
+            md: theme.layout.tablet.spacing['2xl'],
+            lg: theme.layout.desktop.spacing['2xl'],
+          },
+        },
+      },
       {
         orientation: 'vertical',
         space: 'none',
@@ -126,6 +150,17 @@ const styles = StyleSheet.create(theme => ({
           marginHorizontal: 0,
         },
       },
+      {
+        orientation: 'vertical',
+        space: '2xs',
+        styles: {
+          marginHorizontal: {
+            base: theme.layout.mobile.spacing['2xs'],
+            md: theme.layout.tablet.spacing['2xs'],
+            lg: theme.layout.desktop.spacing['2xs'],
+          },
+        },
+      },
       {
         orientation: 'vertical',
         space: 'xs',
@@ -181,6 +216,17 @@ const styles = StyleSheet.create(theme => ({
           },
         },
       },
+      {
+        orientation: 'vertical',
+        space: '2xl',
+        styles: {
+          marginHorizontal: {
+            base: theme.layout.mobile.spacing['2xl'],
+            md: theme.layout.tablet.spacing['2xl'],
+            lg: theme.layout.desktop.spacing['2xl'],
+          },
+        },
+      },
     ],
   },
   extraStyles: (color, width, height) => ({

package/src/components/Flex/Flex.docs.mdx

@@ -1,7 +1,7 @@
-import { Meta, Canvas, Story, Controls, Primary } from '@storybook/addon-docs/blocks';
+import { Canvas, Controls, Meta, Primary, Story } from '@storybook/addon-docs/blocks';
+import { BodyText, Center, Flex, Pressable } from '../..';
+import { BackToTopButton, UsageWrap, ViewFigmaButton } from '../../../docs/components';
 import * as Stories from './Flex.stories';
-import { Center, Pressable, Flex, BodyText } from '../..';
-import { UsageWrap, BackToTopButton, ViewFigmaButton } from '../../../docs/components';
 
 <Meta title="Primitives / Flex" />
 
@@ -57,4 +57,4 @@ const MyComponent = () => (
 | `wrap`      | `'wrap' \| 'nowrap' \| 'wrap-reverse'`                                                                  | `nowrap`     | The wrap of the flex container.            |
 | `justify`   | `'flex-start' \| 'flex-end' \| 'center' \| `<br />`'space-between' \| 'space-around' \| 'space-evenly'` | `flex-start` | The justify content of the flex container. |
 | `align`     | `'flex-start' \| 'flex-end' \| 'center' \| 'stretch' \| 'baseline'`                                     | `flex-start` | The align items of the flex container.     |
-| `space`     | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`                                                        | `md`         | The space between the content.             |
+| `space`     | `'none' \| '2xs' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'`                                      | `md`         | The space between the content.             |

package/src/components/Flex/Flex.props.ts

@@ -1,11 +1,12 @@
-import type { ViewProps, ViewStyle, FlexAlignType } from 'react-native';
+import type { FlexAlignType, ViewProps, ViewStyle } from 'react-native';
+import { SpacingValues } from '../../types';
 
 interface FlexProps extends ViewProps {
   direction?: ViewStyle['flexDirection'];
   align?: FlexAlignType;
   justify?: ViewStyle['justifyContent'];
   wrap?: ViewStyle['flexWrap'];
-  space?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+  space?: SpacingValues;
 }
 
 export default FlexProps;

package/src/components/Flex/Flex.stories.tsx

@@ -40,7 +40,7 @@ const meta = {
       description: 'The justify of the flex container.',
     },
     space: {
-      options: ['none', 'xs', 'sm', 'md', 'lg', 'xl'],
+      options: ['none', '2xs', 'xs', 'sm', 'md', 'lg', 'xl', '2xl'],
       control: 'radio',
       description: 'The space of the flex container.',
     },

package/src/components/Grid/Grid.docs.mdx

@@ -1,7 +1,7 @@
-import { Meta, Canvas, Story, Controls, Primary } from '@storybook/addon-docs/blocks';
+import { Canvas, Controls, Meta, Primary, Story } from '@storybook/addon-docs/blocks';
+import { BodyText, Box, Center, Grid } from '../..';
+import { BackToTopButton, UsageWrap, ViewFigmaButton } from '../../../docs/components';
 import * as Stories from './Grid.stories';
-import { Center, Grid, Box, BodyText } from '../..';
-import { UsageWrap, BackToTopButton, ViewFigmaButton } from '../../../docs/components';
 
 <Meta title="Primitives / Grid" />
 
@@ -173,15 +173,15 @@ const MyComponent = () => (
 
 The Grid component extends all the props from the [View component](https://reactnative.dev/docs/view), and adds the following:
 
-| Name             | Type                                             | Default | Description                                                   |
-| ---------------- | ------------------------------------------------ | ------- | ------------------------------------------------------------- |
-| `columns`        | `number` or `GridColumns`                        | 2       | Number of columns or responsive object with breakpoint values |
-| `space`          | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | -       | Spacing between grid items (both rows and columns)            |
-| `columnGap`      | `number`                                         | -       | Gap between columns (overrides spacing if provided)           |
-| `rowGap`         | `number`                                         | -       | Gap between rows (overrides spacing if provided)              |
-| `containerStyle` | `StyleProp\<ViewStyle\>`                         | -       | Style for the grid container                                  |
-| `itemStyle`      | `StyleProp\<ViewStyle\>`                         | -       | Style applied to each grid item                               |
-| `rowStyle`       | `StyleProp\<ViewStyle\>`                         | -       | Style applied to each row                                     |
+| Name             | Type                                                               | Default | Description                                                   |
+| ---------------- | ------------------------------------------------------------------ | ------- | ------------------------------------------------------------- |
+| `columns`        | `number` or `GridColumns`                                          | 2       | Number of columns or responsive object with breakpoint values |
+| `space`          | `'none' \| '2xs' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'` | -       | Spacing between grid items (both rows and columns)            |
+| `columnGap`      | `number`                                                           | -       | Gap between columns (overrides spacing if provided)           |
+| `rowGap`         | `number`                                                           | -       | Gap between rows (overrides spacing if provided)              |
+| `containerStyle` | `StyleProp\<ViewStyle\>`                                           | -       | Style for the grid container                                  |
+| `itemStyle`      | `StyleProp\<ViewStyle\>`                                           | -       | Style applied to each grid item                               |
+| `rowStyle`       | `StyleProp\<ViewStyle\>`                                           | -       | Style applied to each row                                     |
 
 Where `GridColumns` is defined as:
 

package/src/components/Grid/Grid.props.ts

@@ -1,6 +1,6 @@
 import { StyleProp, ViewProps, ViewStyle } from 'react-native';
 import { UnistylesBreakpoints } from 'react-native-unistyles';
-import { SpaceValue } from '../../types';
+import { SpaceValue, SpacingValues } from '../../types';
 
 // Create a type that uses the keys from our breakpoints object
 export type GridColumns = {
@@ -17,7 +17,7 @@ export interface GridProps extends ViewProps {
   /**
    * Spacing between grid items (applies to both rows and columns)
    */
-  space?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+  space?: SpacingValues;
 
   /**
    * Gap between items (overrides spacing if provided)

package/src/components/Grid/Grid.stories.tsx

@@ -1,5 +1,5 @@
 import { Meta, StoryObj } from '@storybook/react-vite';
-import { View, Text } from 'react-native';
+import { Text, View } from 'react-native';
 import { Grid } from '.';
 
 const meta = {
@@ -14,7 +14,7 @@ const meta = {
       description: 'Number of columns or responsive object with breakpoints',
     },
     space: {
-      options: ['none', 'xs', 'sm', 'md', 'lg', 'xl'],
+      options: ['none', '2xs', 'xs', 'sm', 'md', 'lg', 'xl', '2xl'],
       control: 'radio',
       description: 'Responsive spacing between grid items (applied to both rows and columns).',
     },

package/src/components/IconContainer/IconContainer.docs.mdx

@@ -0,0 +1,90 @@
+import { Canvas, Controls, Meta, Story } from '@storybook/addon-docs/blocks';
+import {
+  BroadbandMediumIcon,
+  CashbackCardMediumIcon,
+  ConfettiMediumIcon,
+  ElectricityMediumIcon,
+  InsuranceMediumIcon,
+  MobileMediumIcon,
+} from '@utilitywarehouse/hearth-react-native-icons';
+import { Center, Flex, IconContainer } from '../../';
+import { BackToTopButton, UsageWrap } from '../../../docs/components';
+import * as Stories from './IconContainer.stories';
+
+<BackToTopButton />
+
+<Meta title="Components / Icon Container" />
+
+# Icon Container
+
+The `IconContainer` component provides a consistent background and sizing (via component tokens) for any standalone icon, with semantic colour families and subtle/emphasis variants.
+
+- [Playground](#playground)
+- [Usage](#usage)
+- [Props](#props)
+- [Variants](#variants)
+
+## Playground
+
+<Canvas of={Stories.Playground} />
+
+<Controls of={Stories.Playground} />
+
+## Usage
+
+Wrap an icon with the `IconContainer` to apply sizing + background styles without repeating layout code.
+
+<UsageWrap>
+  <Center>
+    <Flex direction="row" space="lg" alignItems="center">
+      <IconContainer icon={ElectricityMediumIcon} size="md" variant="emphasis" color="energy" />
+      <IconContainer icon={BroadbandMediumIcon} size="md" variant="emphasis" color="broadband" />
+      <IconContainer icon={MobileMediumIcon} size="md" variant="emphasis" color="mobile" />
+      <IconContainer icon={InsuranceMediumIcon} size="md" variant="emphasis" color="insurance" />
+      <IconContainer icon={CashbackCardMediumIcon} size="md" variant="emphasis" color="cashback" />
+      <IconContainer icon={ConfettiMediumIcon} size="md" variant="emphasis" color="pig" />
+    </Flex>
+  </Center>
+</UsageWrap>
+
+```jsx
+import { IconContainer } from '@utilitywarehouse/hearth-react-native';
+import {
+  ElectricityMediumIcon,
+  BroadbandMediumIcon,
+  MobileMediumIcon,
+  InsuranceMediumIcon,
+  CashbackCardMediumIcon,
+  ConfettiMediumIcon,
+} from '@utilitywarehouse/hearth-react-native-icons';
+
+const MyComponent = () => (
+  <>
+    <IconContainer icon={ElectricityMediumIcon} size="md" variant="emphasis" color="energy" />
+    <IconContainer icon={BroadbandMediumIcon} size="md" variant="emphasis" color="broadband" />
+    <IconContainer icon={MobileMediumIcon} size="md" variant="emphasis" color="mobile" />
+    <IconContainer icon={InsuranceMediumIcon} size="md" variant="emphasis" color="insurance" />
+    <IconContainer icon={CashbackCardMediumIcon} size="md" variant="emphasis" color="cashback" />
+    <IconContainer icon={ConfettiMediumIcon} size="md" variant="emphasis" color="pig" />
+  </>
+);
+```
+
+## Props
+
+| Name         | Type                                                                                               | Description                                     | Default    |
+| ------------ | -------------------------------------------------------------------------------------------------- | ----------------------------------------------- | ---------- |
+| `icon`       | `React.ComponentType`                                                                              | Icon component rendered inside the container    | (required) |
+| `size`       | `'sm' \| 'md' \| 'lg'`                                                                             | Size variant (token-based width/height/padding) | `md`       |
+| `radiusNone` | `boolean`                                                                                          | Remove border radius (square container)         | `false`    |
+| `variant`    | `'subtle' \| 'emphasis'`                                                                           | Background emphasis level                       | `subtle`   |
+| `color`      | `'pig' \| 'energy' \| 'broadband' \| 'mobile' \|` <br />`'insurance' \| 'cashback' \| 'highlight'` | Semantic colour family for surface tokens       | `pig`      |
+| `...View`    | React Native `ViewProps`                                                                           | Any additional View props                       | -          |
+
+> Colours resolve to `theme.color.surface.<family>.{subtle|default}` depending on variant.
+
+## Variants
+
+Use the matrix below to compare every combination of size, variant, and color.
+
+<Canvas of={Stories.KitchenSink} />