Skip to main content

ADR-003: Use Chakra UI for Component Library

Date: 2025-10-06 Status: Accepted Deciders: Development Team Tags: ui, components, styling

Context​

Need a component library that provides:

  • Professional, accessible components
  • Dark/light theme support
  • VS Code-like aesthetics
  • TypeScript support
  • Customizable styling

Decision​

Use Chakra UI 2.8 as the primary component library.

Rationale​

Why Chakra UI​

  1. Accessibility: WCAG compliant out of the box
  2. Theme System: Built-in dark/light mode
  3. TypeScript: Full TypeScript support
  4. Composition: Component composition pattern
  5. Customization: Easy to override styles
  6. No CSS: Style props, no separate CSS files
  7. Performance: Only loads used components

Key Features​

  • Color mode management (dark/light)
  • Responsive design system
  • Semantic HTML components
  • Focus management
  • Keyboard navigation

Alternatives Considered​

Material-UI (MUI)​

  • Pros: Most popular, comprehensive
  • Cons: Larger bundle, Material Design aesthetic
  • Rejected: Too opinionated, heavier

Ant Design​

  • Pros: Enterprise-ready, many components
  • Cons: Chinese-centric, large bundle
  • Rejected: Not suitable for VS Code aesthetic

Tailwind CSS + Headless UI​

  • Pros: Full control, small bundle
  • Cons: More manual work, utility class verbosity
  • Rejected: Need ready components, not utilities

Radix UI​

  • Pros: Unstyled, accessible, composable
  • Cons: Need to style everything manually
  • Rejected: Too much styling work needed

Consequences​

Positive​

  • Fast UI development with ready components
  • Consistent dark/light themes
  • Built-in accessibility
  • Good documentation
  • Active community

Negative​

  • Learning curve for Chakra's API
  • Bundle size larger than CSS-only solutions
  • Some custom styling still needed for VS Code look

Implementation​

Theme Configuration​

// chakra-theme.ts
import { extendTheme } from '@chakra-ui/react';

const theme = extendTheme({
  config: {
    initialColorMode: 'dark',
    useSystemColorMode: false,
  },
  colors: {
    brand: {
      500: '#2196f3',
      // ...
    },
  },
  semanticTokens: {
    colors: {
      'editor.bg': {
        default: '#1e1e1e',
        _light: '#ffffff',
      },
      'editor.sidebar': {
        default: '#252526',
        _light: '#f5f5f5',
      },
    },
  },
});

Component Usage​

<Flex h="100vh" bg="editor.bg">
  <Box bg="editor.sidebar" w="250px">
    <Heading size="sm">FILES</Heading>
    <VStack>
      <Button variant="ghost">file.ts</Button>
    </VStack>
  </Box>
</Flex>

VS Code-like Styling​

Custom semantic tokens for VS Code theme:

  • editor.bg: Main background
  • editor.sidebar: Sidebar background
  • editor.border: Border colors
  • editor.text: Text colors

References​