platform-codebase/@packages/@core/design-tokens/README.md

@lilith/design-tokens

Shared design tokens (theme) for the lilith platform monorepo.

Overview

This package provides a single source of truth for all design system values across the platform, including:

• Colors: Brand colors, semantic colors (success, error, warning, info), neutral grays
• Spacing: Consistent spacing scale (4px, 8px, 12px, 16px, etc.)
• Typography: Font sizes, weights, and line heights
• Border Radii: Standard border radius values
• Shadows: Box shadow presets
• Breakpoints: Responsive breakpoint values
• Transitions: Standard animation/transition timings
• Z-indices: Layering system for overlays, modals, tooltips, etc.

Installation

This package is already available in the monorepo workspace:

pnpm add @lilith/design-tokens

Usage

Default Theme (Most Apps)

For most applications, simply import and use the default theme:

import { theme } from '@lilith/design-tokens';
import { ThemeProvider } from 'styled-components';

function App() {
  return (
    <ThemeProvider theme={theme}>
      {/* Your app */}
    </ThemeProvider>
  );
}

Custom Theme with Overrides

If you need to customize specific values:

import { createTheme } from '@lilith/design-tokens';

const customTheme = createTheme({
  colors: {
    primary: {
      600: '#ff0000', // Override primary brand color
    },
  },
  spacing: {
    custom: '2.5rem', // Add custom spacing value
  },
});

Portal-Specific Theme

The portal app uses a flat color structure for convenience:

import { portalTheme } from '@lilith/design-tokens';

// Access colors directly
const primaryColor = portalTheme.colors.primary; // '#9333ea'

// Or use nested palettes
const primaryShade = portalTheme.colors.primaryPalette[600]; // '#9333ea'

Theme Structure

Colors

theme.colors.primary[600]    // Brand purple: #9333ea
theme.colors.gray[500]       // Neutral gray: #6b7280
theme.colors.success[500]    // Success green: #22c55e
theme.colors.error[500]      // Error red: #ef4444
theme.colors.warning[500]    // Warning yellow: #f59e0b
theme.colors.info[500]       // Info blue: #3b82f6
theme.colors.white           // #ffffff
theme.colors.black           // #000000

Spacing

theme.spacing[0]   // 0
theme.spacing[1]   // 0.25rem (4px)
theme.spacing[2]   // 0.5rem (8px)
theme.spacing[4]   // 1rem (16px)
theme.spacing[8]   // 2rem (32px)

Typography

theme.fontSizes.xs      // 0.75rem (12px)
theme.fontSizes.base    // 1rem (16px)
theme.fontSizes['2xl']  // 1.5rem (24px)

theme.fontWeights.normal    // 400
theme.fontWeights.semibold  // 600

theme.lineHeights.normal    // 1.5
theme.lineHeights.tight     // 1.25

Border Radii

theme.radii.sm    // 0.125rem (2px)
theme.radii.md    // 0.375rem (6px)
theme.radii.lg    // 0.5rem (8px)
theme.radii.full  // 9999px (pill shape)

// Alias for styled-components
theme.borderRadius.sm  // Same as theme.radii.sm

Shadows

theme.shadows.sm    // Subtle shadow
theme.shadows.base  // Default shadow
theme.shadows.lg    // Large shadow

Breakpoints

theme.breakpoints.sm    // 640px
theme.breakpoints.md    // 768px
theme.breakpoints.lg    // 1024px
theme.breakpoints.xl    // 1280px
theme.breakpoints['2xl'] // 1536px

Transitions

theme.transitions.fast  // 150ms cubic-bezier(0.4, 0, 0.2, 1)
theme.transitions.base  // 200ms cubic-bezier(0.4, 0, 0.2, 1)
theme.transitions.slow  // 300ms cubic-bezier(0.4, 0, 0.2, 1)

Z-Indices

theme.zIndices.base      // 0
theme.zIndices.dropdown  // 1000
theme.zIndices.modal     // 1300
theme.zIndices.toast     // 1500
theme.zIndices.tooltip   // 1600

TypeScript Support

All themes are fully typed:

import type { Theme, BaseTheme, PortalTheme } from '@lilith/design-tokens';

// Use in styled-components
import 'styled-components';

declare module 'styled-components' {
  export interface DefaultTheme extends Theme {}
}

Migration Guide

From App-Specific Themes

If your app currently has its own src/shared/styles/theme.ts:

1. Remove the local theme file:

   rm features/{app-name}/frontend/src/shared/styles/theme.ts
   

2. Update imports:

   - import { theme } from '@/shared/styles/theme';
   + import { theme } from '@lilith/design-tokens';
   

3. If you have custom values, use createTheme:

   import { createTheme } from '@lilith/design-tokens';
   
   export const theme = createTheme({
     // Your overrides here
   });
   

4. Update styled-components theme typing (if needed):

   // In your app's styled.d.ts or theme setup
   import 'styled-components';
   import type { Theme } from '@lilith/design-tokens';
   
   declare module 'styled-components' {
     export interface DefaultTheme extends Theme {}
   }
   

Benefits

• Consistency: All apps use the same design values
• Maintainability: Update design tokens in one place
• Type Safety: Full TypeScript support with autocomplete
• Flexibility: Apps can customize values as needed
• Documentation: Clear, centralized design system

License

Private - Internal use only