Feat: Document tokens in Storybook (#1008)

* feat: elevations, space scale, colour palette and themed colour stories

* feat: prototype new Box and Stack with sprinkles and intrinsic attributes

.prettierignore

@@ -3,6 +3,7 @@
 !/jest/
 !/lib/
 !/scripts/
+!/stories/
 !/.github/
 !/.storybook/
 !/.changeset

.storybook/main.js

@@ -1,7 +1,7 @@
 /** @type { import('@storybook/react-vite').StorybookConfig } */
 const config = {
 	stories: [
-		'../stories/**/*.mdx',
+		'../lib/stories/*.@(mdx|jsx|tsx)',
 		'../lib/**/*.stories.@(js|jsx|mjs|ts|tsx)',
 	],
 	addons: [

.storybook/preview.jsx

@@ -179,7 +179,7 @@ const preview = {
 		},
 		options: {
 			storySort: {
-				order: ['Overdrive'],
+				order: ['Overdrive', 'Foundation'],
 			},
 		},
 	},

lib/stories/borders.stories.tsx

@@ -0,0 +1,105 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import React from 'react';
+
+import { Heading } from '../components/Heading';
+import { tokens } from '../themes/base/tokens';
+
+import { Box, Stack, type Sprinkles } from './helpers';
+import { labels, titles } from './helpers/styles.css';
+
+const { border, elevation } = tokens;
+const elevationItems = Object.keys(elevation);
+const widthItems = Object.keys(border.width);
+const radiusItems = Object.keys(border.radius);
+
+const Elevation = () => (
+	<Stack>
+		<Heading is="h2" className={titles}>
+			Elevation
+		</Heading>
+
+		{elevationItems.map((elevation) => (
+			<Stack space="sm" alignItems="center" horizontal key={elevation}>
+				<Box
+					background="gray100"
+					borderRadius="1"
+					boxShadow={elevation as Sprinkles['boxShadow']}
+					size="9"
+				/>
+				<p className={labels}>{elevation}</p>
+			</Stack>
+		))}
+	</Stack>
+);
+
+const Widths = () => {
+	return (
+		<Stack>
+			<Heading is="h2" className={titles}>
+				Width
+			</Heading>
+
+			{widthItems.map((width) => (
+				<Stack space="sm" alignItems="center" horizontal key={width}>
+					<Box
+						background="black100"
+						borderColor="dark"
+						borderRadius="1"
+						borderStyle="solid"
+						borderWidth={width as Sprinkles['borderWidth']}
+						size="9"
+					/>
+					<p className={labels}>{width}</p>
+				</Stack>
+			))}
+		</Stack>
+	);
+};
+
+const Radius = () => {
+	return (
+		<Stack>
+			<Heading is="h2" className={titles}>
+				Radius
+			</Heading>
+
+			{radiusItems.sort().map((radius) => (
+				<Stack space="sm" alignItems="center" horizontal key={radius}>
+					<Box
+						background="black500"
+						borderColor="gray"
+						borderRadius={radius as Sprinkles['borderRadius']}
+						size="9"
+						style={
+							radius === 'pill' ? { height: '74px' } : undefined
+						}
+					/>
+					<p className={labels}>{radius}</p>
+				</Stack>
+			))}
+		</Stack>
+	);
+};
+
+const meta: Meta = {
+	title: 'Foundation/Borders',
+	tags: ['!autodocs'],
+};
+export default meta;
+
+type Story = StoryObj;
+
+export const Borders: Story = {
+	render: () => (
+		<Stack gap="8" horizontal>
+			<Heading is="h1">
+				Borders &amp;
+				<br />
+				Elevation
+			</Heading>
+			<Elevation />
+			<Radius />
+			<Widths />
+		</Stack>
+	),
+};

lib/stories/helpers/index.tsx

@@ -0,0 +1,70 @@
+import clsx from 'clsx';
+import React from 'react';
+
+import { sprinkles, type Sprinkles } from '../../styles/sprinkles.css';
+import { stack, type RecipeStackProps } from '../../styles/stack.css';
+
+import {
+	variantColourSwatch,
+	type VariantColourSwatchProps,
+} from './styles.css';
+
+type ElementAttributes = React.ComponentPropsWithoutRef<'div'>;
+type FilteredAttributes = Pick<ElementAttributes, 'className' | 'style'>;
+type ComponentProps<P> = React.PropsWithChildren<P & FilteredAttributes>;
+
+export const Box = ({
+	children,
+	className,
+	style,
+	...props
+}: ComponentProps<Sprinkles>) => (
+	<div className={clsx([sprinkles(props), className])} style={style}>
+		{children}
+	</div>
+);
+
+type StackSprinkles = Pick<
+	Sprinkles,
+	'alignItems' | 'flexDirection' | 'flexWrap' | 'gap' | 'justifyContent'
+>;
+export const Stack = ({
+	alignItems,
+	children,
+	className,
+	flexDirection,
+	flexWrap,
+	gap,
+	horizontal,
+	justifyContent,
+	space,
+	style,
+	...props
+}: ComponentProps<StackSprinkles & RecipeStackProps>) => (
+	<div
+		{...props}
+		className={clsx([
+			sprinkles({
+				alignItems,
+				flexDirection,
+				flexWrap,
+				gap,
+				justifyContent,
+			}),
+			stack({ space, horizontal }),
+			className,
+		])}
+		style={style}
+	>
+		{children}
+	</div>
+);
+
+type ColourSwatchProps = ComponentProps<
+	Omit<Sprinkles, 'size'> & VariantColourSwatchProps
+>;
+export const ColourSwatch = ({ shape, size, ...props }: ColourSwatchProps) => (
+	<Box {...props} className={variantColourSwatch({ shape, size })}></Box>
+);
+
+export { type Sprinkles } from '../../styles/sprinkles.css';

lib/stories/helpers/styles.css.ts

@@ -0,0 +1,54 @@
+import { style } from '@vanilla-extract/css';
+import { recipe, type RecipeVariants } from '@vanilla-extract/recipes';
+
+import { themeContractVars as vars } from '../../themes/theme.css';
+
+export const titles = style({
+	marginTop: '11px',
+});
+
+export const labels = style({
+	textTransform: 'capitalize',
+});
+
+export const small = style({
+	fontSize: 'small',
+});
+
+export const hexPill = style({
+	backgroundColor: 'hsl(0 0 100 / 75%)',
+	borderRadius: '100px',
+	display: 'inline-block',
+	fontSize: '11px',
+	padding: '1px 8px',
+	position: 'absolute',
+	textTransform: 'uppercase',
+	top: '5px',
+});
+
+export const variantColourSwatch = recipe({
+	base: {
+		position: 'relative',
+		borderColor: vars.border.colours.light,
+		borderStyle: 'solid',
+		borderWidth: vars.border.width[1],
+	},
+	variants: {
+		size: {
+			sm: { height: vars.space[7], width: vars.space[7] },
+			md: { height: vars.space[8], width: vars.space[8] },
+			lg: { height: vars.space[9], width: vars.space[9] },
+		},
+		shape: {
+			circle: { borderRadius: '100%' },
+		},
+	},
+	defaultVariants: {
+		size: 'md',
+		shape: 'circle',
+	},
+});
+
+export type VariantColourSwatchProps = NonNullable<
+	RecipeVariants<typeof variantColourSwatch>
+>;

lib/stories/palette.stories.tsx

@@ -0,0 +1,87 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import clsx from 'clsx';
+import React from 'react';
+
+import { Heading } from '../components/Heading';
+import { sprinkles } from '../styles/sprinkles.css';
+import { baseThemeColours } from '../themes/base/tokens';
+import type { ColourGamut, ColourValue } from '../themes/tokens';
+
+import { ColourSwatch, Stack } from './helpers';
+import { labels, hexPill } from './helpers/styles.css';
+
+interface SwatchProps {
+	colour: ColourGamut;
+	hex?: string;
+	hue?: string;
+}
+const Swatch = ({ colour, hex, hue }: SwatchProps) => (
+	<Stack
+		horizontal
+		alignItems="center"
+		style={{
+			gap: '10px',
+			position: 'relative',
+		}}
+	>
+		<ColourSwatch background={colour} size="lg">
+			<div className={hexPill}>{hex}</div>
+		</ColourSwatch>
+		{hue && colour.replace(hue, '')}
+	</Stack>
+);
+
+interface PaletteSwatchesProps {
+	hue: string;
+	shades: ColourValue;
+}
+const PaletteSwatches = ({ hue, shades }: PaletteSwatchesProps) => (
+	<Stack space="sm">
+		{Object.entries(shades)
+			.reverse()
+			.map(([colour, hex]) => (
+				<Swatch
+					colour={`${hue}${colour}` as ColourGamut}
+					hex={hex}
+					hue={hue}
+					key={colour}
+				/>
+			))}
+	</Stack>
+);
+
+const Palettes = () => (
+	<Stack horizontal space="md">
+		{['green', 'blue', 'yellow', 'red', 'gray', 'black'].map((hue) => (
+			<div key={hue}>
+				<Heading
+					is="h3"
+					className={clsx([labels, sprinkles({ marginBottom: '5' })])}
+				>
+					{hue}
+				</Heading>
+				<PaletteSwatches hue={hue} shades={baseThemeColours[hue]} />
+			</div>
+		))}
+	</Stack>
+);
+
+const meta: Meta = {
+	title: 'Foundation/Palette',
+	tags: ['!autodocs'],
+};
+export default meta;
+
+type Story = StoryObj;
+
+export const Palette: Story = {
+	render: () => {
+		return (
+			<Stack space="md">
+				<Heading is="h1">Palette</Heading>
+				<Heading is="h2">Colours</Heading>
+				<Palettes />
+			</Stack>
+		);
+	},
+};