Component Library Design Guide

// Bad: Monolithic component
<ComplexCard
  showImage={true}
  showTitle={true}
  showDescription={true}
  showActions={true}
  imagePosition="left"
/>

// Good: Composable components
<Card>
  <CardImage src="..." />
  <CardBody>
    <CardTitle>Title</CardTitle>
    <CardDescription>Description</CardDescription>
    <CardActions>
      <Button>Action</Button>
    </CardActions>
  </CardBody>
</Card>

// Consistent prop naming
<Button variant="primary" size="lg" disabled={false} />
<Input variant="outlined" size="lg" disabled={false} />
<Select variant="outlined" size="lg" disabled={false} />

// Accessible by default
function Button({ children, ...props }) {
  return (
    <button
      type="button"
      {...props}
      className={cn(
        'base-styles',
        props.disabled && 'disabled-styles'
      )}
    >
      {children}
    </button>
  );
}

// Good: Clear, minimal props
interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'ghost';
  size?: 'sm' | 'md' | 'lg';
  disabled?: boolean;
  loading?: boolean;
  leftIcon?: React.ReactNode;
  rightIcon?: React.ReactNode;
  children: React.ReactNode;
  onClick?: () => void;
}

// Usage
<Dialog>
  <DialogTrigger>Open Dialog</DialogTrigger>
  <DialogContent>
    <DialogTitle>Confirm Action</DialogTitle>
    <DialogDescription>
      Are you sure you want to proceed?
    </DialogDescription>
    <DialogFooter>
      <DialogClose>Cancel</DialogClose>
      <DialogAction>Confirm</DialogAction>
    </DialogFooter>
  </DialogContent>
</Dialog>

// Implementation
const DialogContext = createContext({});

function Dialog({ children, ...props }) {
  const [open, setOpen] = useState(false);
  return (
    <DialogContext.Provider value={{ open, setOpen }}>
      {/* ... */}
    </DialogContext.Provider>
  );
}

function DialogTrigger({ children }) {
  const { setOpen } = useContext(DialogContext);
  return <button onClick={() => setOpen(true)}>{children}</button>;
}

function DataFetcher({ url, render, renderLoading, renderError }) {
  const { data, loading, error } = useFetch(url);

  if (loading) return renderLoading?.();
  if (error) return renderError?.(error);
  return render(data);
}

// Usage
<DataFetcher
  url="/api/users"
  renderLoading={() => <Spinner />}
  renderError={(error) => <Error message={error.message} />}
  render={(users) => <UserList users={users} />}
/>

// Theme configuration
const theme = {
  colors: {
    primary: {
      50: '#f0f9ff',
      100: '#e0f2fe',
      500: '#0ea5e9',
      900: '#0c4a6e',
    },
  },
  spacing: {
    xs: '0.25rem',
    sm: '0.5rem',
    md: '1rem',
    lg: '1.5rem',
    xl: '2rem',
  },
};

// Component usage
function Button() {
  return (
    <button
      style={{
        padding: theme.spacing.md,
        background: theme.colors.primary[500],
      }}
    >
      Click me
    </button>
  );
}

function Button({ className, style, ...props }) {
  return (
    <button
      className={cn('btn-base', className)}
      style={style}
      {...props}
    />
  );
}

// Usage with Tailwind
<Button className="bg-blue-500 hover:bg-blue-600" />
// Usage with custom styles
<Button style={{ background: 'custom-color' }} />

// Button.stories.tsx
export default {
  title: 'Components/Button',
  component: Button,
};

export const Primary = {
  args: {
    variant: 'primary',
    children: 'Primary Button',
  },
};

export const Secondary = {
  args: {
    variant: 'secondary',
    children: 'Secondary Button',
  },
};

export const WithIcon = {
  args: {
    variant: 'primary',
    leftIcon: <Icon name="star" />,
    children: 'With Icon',
  },
};

## Button

Primary action button for the application.

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| variant | 'primary' | 'secondary' | 'ghost' | 'primary' | Visual style |
| size | 'sm' | 'md' | 'lg' | 'md' | Button size |
| disabled | boolean | false | Disable interaction |
| loading | boolean | false | Show loading state |
| children | ReactNode | - | Button content |

### Examples

// Chromatic with Storybook
test('Button visual variants', async () => {
  await expect(page).toHaveScreenshot('button-primary.png');
  await expect(page).toHaveScreenshot('button-secondary.png');
});

import { axe, toHaveNoViolations } from 'jest-axe';

expect.extend(toHaveNoViolations);

test('Button should not have accessibility violations', async () => {
  const { container } = render(<Button>Click me</Button>);
  const results = await axe(container);
  expect(results).toHaveNoViolations();
});

## Distribution

### Package Configuration

### Build Process

Multiple output formats.

## Best Practices

### DOs

- Start with accessibility
- Provide sensible defaults
- Make APIs intuitive
- Document everything
- Test thoroughly
- Version carefully

### DON'Ts

- Over-abstract early
- Create rigid components
- Ignore performance
- Skip documentation
- Break changes without major version bump
- Assume one use case

## Performance

### Tree Shaking

Enable tree shaking for small bundles.

### Memoization

Optimize expensive renders.

## Conclusion

Great component libraries are built on strong foundations: composability, consistency, accessibility, and excellent documentation. Start small, iterate based on feedback, and maintain backward compatibility. Your library should make developers more productive, not frustrated.