Aurora Design System - Components Library

⚠️ Personal Project Notice

This library is designed for my personal projects and is not intended for public use. Feel free to use it as inspiration or reference, but no support or maintenance is guaranteed.

A React component library with default theme included. Ready to use in 3 lines of code.

Key Features:

• ✅ Default theme included - No configuration needed
• ✅ TypeScript autocomplete - Full IntelliSense support
• ✅ Easy to customize - Spread operator to override
• ✅ Built with @aurora-ds/theme v3 - Powerful theming system

Installation

yarn add @aurora-ds/components @aurora-ds/theme react react-dom

Quick Start

import { ThemeProvider } from '@aurora-ds/theme'
import { defaultTheme, Button } from '@aurora-ds/components'

function App() {
  return (
    <ThemeProvider theme={defaultTheme}>
      <Button label="Click me" variant="contained" />
    </ThemeProvider>
  )
}

That's it! 🎉

🎨 Customization

Use Case 1: Change Token Values

You have two options to customize the theme:

Option A: Using spread operator (simple)

import { defaultTheme } from '@aurora-ds/components'
import { colors } from '@aurora-ds/theme'

const myTheme = {
  ...defaultTheme,
  colors: {
    ...defaultTheme.colors,
    primary: colors.purple[600],     // Change primary color
    success: colors.teal[600],       // Change success color
  },
  spacing: {
    ...defaultTheme.spacing,
    lg: '2rem',                       // Change large spacing
  },
  radius: {
    ...defaultTheme.radius,
    md: '1rem',                       // Change medium radius
  }
}

<ThemeProvider theme={myTheme}>
  <App />
</ThemeProvider>

Option B: Using createTheme (type-safe)

import { createTheme, colors } from '@aurora-ds/theme'
import { defaultTheme } from '@aurora-ds/components'

const myTheme = createTheme({
  ...defaultTheme,
  colors: {
    ...defaultTheme.colors,
    primary: colors.purple[600],
    success: colors.teal[600],
  }
})

<ThemeProvider theme={myTheme}>
  <App />
</ThemeProvider>

Both approaches work! createTheme provides additional type validation.

Use Case 2: Add Custom Tokens

If you need tokens that don't exist in defaultTheme (for very specific use cases):

Step 1: Create your theme types

// src/theme/theme.types.ts
import type { Theme as BaseTheme } from '@aurora-ds/components'

export interface Theme extends BaseTheme {
  colors: BaseTheme['colors'] & {
    brand: string           // New custom token
    custom: string          // New custom token
  }
  customSpacing: {          // Entirely new category
    hero: string
    section: string
  }
}

Step 2: Create module augmentation

// src/theme/theme.module.ts
import type { Theme } from './theme.types'

declare module '@aurora-ds/theme' {
  interface ThemeRegistry {
    theme: Theme
  }
}

Step 3: Create your theme with createTheme

// src/theme/theme.ts
import './theme.module'
import { createTheme, colors } from '@aurora-ds/theme'
import { defaultTheme } from '@aurora-ds/components'

export const myTheme = createTheme({
  ...defaultTheme,
  colors: {
    ...defaultTheme.colors,
    brand: colors.purple[600],      // Your custom token
    custom: colors.pink[500],       // Your custom token
  },
  customSpacing: {                  // Your custom category
    hero: '10rem',
    section: '5rem',
  }
} as Theme)

Step 4: Use it

// src/App.tsx
import { myTheme } from './theme/theme'

<ThemeProvider theme={myTheme}>
  <App />
</ThemeProvider>

Now you get autocomplete on your custom tokens! ✅

Note: Most projects won't need this. The default theme already includes common tokens like highlight, accent, and link.

Use Case 3: Multiple Themes (Light/Dark)

Create multiple theme variants:

import { createTheme, colors } from '@aurora-ds/theme'
import { defaultTheme } from '@aurora-ds/components'

// Light theme (use default)
export const lightTheme = defaultTheme

// Dark theme with createTheme
export const darkTheme = createTheme({
  ...defaultTheme,
  colors: {
    ...defaultTheme.colors,
    background: colors.slate[950],
    surface: colors.slate[900],
    text: colors.slate[50],
    primary: colors.indigo[400],
    secondary: colors.slate[800],
    border: colors.slate[800],
    // ... other dark mode colors
  }
})

// In your app
const [isDark, setIsDark] = useState(false)

<ThemeProvider theme={isDark ? darkTheme : lightTheme}>
  <App />
</ThemeProvider>

📦 Available Tokens

The defaultTheme includes these token categories:

• colors: primary, secondary, error, success, warning, info, highlight, accent, link, text, background, etc.
• spacing: none, 2xs (2px), xs (4px), sm (8px), md (16px), lg (24px), xl (32px), etc.
• radius: none, xs (2px), sm (4px), md (6px), lg (8px), xl (12px), 2xl (16px), full
• fontSize: 2xs (10px), xs (12px), sm (14px), md (16px), lg (20px), xl (24px), etc.
• fontWeight: light (300), regular (400), medium (500), semibold (600), bold (700)
• shadows, transition, breakpoints, zIndex, etc.

💡 See all values in src/theme/values/

🧩 Available Components

Buttons: Button, IconButton
Layout: Box, Card, Stack, Grid, Page, PageSection, Separator
Typography: Text
Forms: Input, TextArea, Select, DatePicker, Form, FilePicker, ImagePicker
Data Display: Status, Avatar, AvatarGroup, Icon
Navigation: Breadcrumb, Tabs, DrawerItem, Menu, Pagination
Feedback: Alert, Accordion

License

MIT