| name | creating-components |
| description | Use when creating new UI components in packages/ui. Covers component structure, tests, stories, and what to avoid. |
Creating UI Components
Component Structure
packages/ui/src/components/MyComponent/
├── MyComponent.tsx # Implementation
├── MyComponent.test.tsx # Tests
├── index.ts # Re-exports
└── __snapshots__/ # Vitest snapshots (auto-generated)
After creating, export from packages/ui/src/components/index.ts.
Implementation Pattern
import { cva, VariantProps } from 'class-variance-authority';
import { ComponentProps, FC } from 'react';
import { cn } from '../../utils';
const variants = cva('base-classes', {
variants: { },
defaultVariants: { },
});
type MyComponentProps = ComponentProps<'div'> & VariantProps<typeof variants>;
export const MyComponent: FC<MyComponentProps> = ({
className,
variant,
...props
}) => (
<div className={cn(variants({ variant, className }))} {...props} />
);
Tests
What to test:
- Snapshots (1-2 covering key variants)
- User interactions
- Behavior (callbacks called with correct args)
What NOT to test:
- CSS classes, attributes (use snapshots instead)
- Internal state
- Things TypeScript already enforces
Consolidate tests. One test can cover multiple related assertions. An exception to that is snapshot tests - one snapshot per variant/state.
Stories
Create packages/storybook/src/MyComponent.stories.tsx.
One story can show multiple related variants. For example, it's wasteful to create a story for each variant of a button. Put them all together in one place. Don't create separate stories for each variant:
import { Meta, StoryObj } from '@storybook/react-vite';
import { useState } from 'react';
import { MyComponent } from '@nuclearplayer/ui';
const meta = {
title: 'Components/MyComponent',
component: MyComponent,
tags: ['autodocs'],
} satisfies Meta<typeof MyComponent>;
export default meta;
type Story = StoryObj<typeof MyComponent>;
export const AllVariants: Story = {
render: () => {
const [state, setState] = useState(initialState);
return (
<div className="flex flex-col gap-4">
{/* Show all variants, states, interactions */}
</div>
);
},
};
This isn't an iron rule, sometimes it will make more sense to have separate stories.
Don't run storybook build checks.
Avoiding Duplication
Before creating a new component, check if an existing one can be extended.
Pattern: Discriminated unions for mode variants
Example: Instead of creating SingleSelect and MultiSelect components:
type Props =
| { multiple?: false; selected: string; onChange: (id: string) => void }
| { multiple: true; selected: string[]; onChange: (ids: string[]) => void };
TypeScript enforces correct types based on the multiple prop.
Classes for customization
Where it's likely that a component will need custom styling, expose a className prop.
If there are many parts that may need styling, consider exposing a classes prop with specific class names for each part. Define a type for the classes prop. Refer to packages/ui/src/components/TrackTable/types.ts for an example.
Strings
All user-facing strings go through i18n - no hardcoded UI text.
If a new component in the ui package needs labels and other kinds of localized text, it should accept a labels prop with the relevant strings. The prop should have its own type defined. Refer to packages/ui/src/components/QueueItem/types.ts for an example.
Accessibility
This is a videogame: it needs to be playable on a wide range of computers, and playable with keyboard + mouse, or gamepad. We need to follow accessibility best practices.
Checklist
