Design System Beacon

How to Use

Guidelines for designers and developers working with Beacon Design System.

For Designers

Use the Beacon Figma library as the primary design tool for all components, tokens, and patterns.

Use the Figma library as the single source of truth for colors, typography, spacing, and components
Use predefined components from the Figma library. Browse component documentation to understand variants and usage
Use design tokens for spacing, colors, and typography instead of arbitrary values
Reference themes documentation for light and dark mode implementations
Use CSS-based background patterns from the Background Patterns utility page. Patterns automatically adapt to light and dark themes
Extend existing patterns rather than creating one-off solutions. Check existing components first

For Developers

Reference component documentation and use design tokens for all styling. Each component page includes interactive playgrounds and code examples.

Reference documented components and design tokens. Use interactive playgrounds to customize and copy code
Use design tokens as CSS variables (e.g., var(--bg-primary), var(--spacing-400)) instead of hardcoded values
Apply CSS background patterns using pattern classes (e.g., dot-node, grid-nested) from the Background Patterns utility page. Patterns use token variables and adapt to themes automatically
Match component behavior and states exactly as defined in documentation
Follow accessibility guidelines. All components meet WCAG 2.1 AA standards
Use TypeScript types from component documentation for type safety
Explore the Motion animations system for adding animations to components

Installation

Install both packages to get started with Beacon Design System components and icons.

Install Packages

npm install beacon-ui

npm install beacon-icons

Setup

Import design tokens and wrap your app with ThemeProvider:

// Import tokens CSS
import 'beacon-ui/tokens';

// Wrap your app with ThemeProvider
import { ThemeProvider } from 'beacon-ui';

function App() {
  return (
    <ThemeProvider defaultTheme="dark" defaultHue="hue-sky">
      {/* Your app content */}
    </ThemeProvider>
  );
}

Usage

Import and use components and icons:

import { Button, Card, Tabs, Tab, TabItem } from 'beacon-ui';
import { SearchIcon, CheckIcon } from 'beacon-icons';

function MyComponent() {
  return (
    <>
      <Button startIcon={<SearchIcon size="xs" />}>
        Search
      </Button>
      <Card padding={400} showBgPattern patternType="dot-node">
        <p>Card with background pattern</p>
      </Card>
      <Tabs>
        <TabItem label="Tab 1" value="tab1">Content 1</TabItem>
        <TabItem label="Tab 2" value="tab2">Content 2</TabItem>
      </Tabs>
    </>
  );
}

General Guidelines

Principles that apply to both designers and developers:

Use Beacon as the default UI layer. Check existing components before creating new solutions
Avoid local component modifications. Propose changes for inclusion in the design system
Follow accessibility and responsiveness guidelines as non-optional requirements
Check documentation before designing or building to prevent duplication
Use design tokens consistently. Never hardcode colors, spacing, or typography values
Use CSS-based background patterns instead of image assets for better performance and theme compatibility
Reference the Background Patterns utility page for available pattern options