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

tsx
1import { cva, VariantProps } from 'class-variance-authority';
2import { ComponentProps, FC } from 'react';
3import { cn } from '../../utils';
4
5const variants = cva('base-classes', {
6  variants: { /* ... */ },
7  defaultVariants: { /* ... */ },
8});
9
10type MyComponentProps = ComponentProps<'div'> & VariantProps<typeof variants>;
11
12export const MyComponent: FC<MyComponentProps> = ({
13  className,
14  variant,
15  ...props
16}) => (
17  <div className={cn(variants({ variant, className }))} {...props} />
18);

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:

tsx
1import { Meta, StoryObj } from '@storybook/react-vite';
2import { useState } from 'react';
3import { MyComponent } from '@nuclearplayer/ui';
4
5const meta = {
6  title: 'Components/MyComponent',
7  component: MyComponent,
8  tags: ['autodocs'],
9} satisfies Meta<typeof MyComponent>;
10
11export default meta;
12type Story = StoryObj<typeof MyComponent>;
13
14export const AllVariants: Story = {
15  render: () => {
16    const [state, setState] = useState(initialState);
17    return (
18      <div className="flex flex-col gap-4">
19        {/* Show all variants, states, interactions */}
20      </div>
21    );
22  },
23};

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:

tsx
1type Props = 
2  | { multiple?: false; selected: string; onChange: (id: string) => void }
3  | { 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

We don't care about that. If there's an opportunity to handle that easily, do it, but don't go out of your way.

Checklist

• Component in packages/ui/src/components/MyComponent/
• Exported from packages/ui/src/components/index.ts
• Tests cover behavior, not implementation
• Tests consolidated (not one per variant)
• One story showing all variants
• No CSS class assertions in tests
• No duplicate component when extending existing one works