@bttrlabs/ui

Composable React component library for the bttr design system. Each component is built with accessibility defaults, semantic tokens, and ergonomic APIs that scale across product surfaces.

Features

• Token-driven styling that adapts to light and dark themes automatically.
• Headless patterns with sensible defaults for buttons, forms, overlays, feedback, and layout primitives.
• TypeScript-first API design with exhaustive prop typings and meaningful autocompletion.
• Accessibility baked in (ARIA labelling, keyboard navigation, focus states, and reduced motion fallbacks).
• Tree-shakeable exports so consumers only ship the components they use.

Installation

pnpm add @bttrlabs/ui @bttrlabs/tokens

The UI package depends on the token provider to supply theme variables. Wrap your application with the ThemeProvider exported from @bttrlabs/tokens.

import { ThemeProvider } from '@bttrlabs/tokens';
import { Button } from '@bttrlabs/ui';

export function App() {
  return (
    <ThemeProvider>
      <Button variant="primary">Get started</Button>
    </ThemeProvider>
  );
}

Usage guidelines

• Import components from the root entrypoint: import { Button, Stack } from '@bttrlabs/ui';.
• Layout helpers (Stack, Flex, Grid, Container, Box) expose ergonomic props for spacing, alignment, and responsive behaviour.
• Form controls (Input, Textarea, Select, Checkbox, Radio, Switch, FileUpload) share consistent validation, helper text, and accessibility patterns.
• Overlay primitives (Modal, AlertDialog, Popover, Tooltip, Drawer) provide state-only props so you can orchestrate behaviour with your preferred state manager.
• Feedback components (Alert, Badge, Toast, Progress, Skeleton, Spinner) use semantic tokens for colour and motion.

Refer to the Storybook application (apps/storybook) for fully documented usage patterns and interactive examples.

Theming

The design system ships with light and dark semantic tokens. Consumers can either:

1. Control the active theme explicitly by passing controlledTheme="light" | "dark" to ThemeProvider.
2. Allow the provider to read system preferences and persist user overrides with useTheme from @bttrlabs/tokens.

Override component appearance by extending the exported cva variant maps, or by wrapping primitives with your own brand-specific composition.

Contributing

• Run pnpm lint and pnpm test --filter ui before opening a PR.
• New components should include stories following the shared Storybook layout helpers in apps/storybook/src/stories/shared.
• Document props and behavioural nuances in Storybook stories or the package changelog.

License

MIT © bttrlabs