CSS Architecture

All styling in Lakea is centralized in the @lakea/design-system package. Other packages compose these components - they don’t define their own styles.

Package Rules

Package	Tailwind	Styling approach
design-system	Yes	Tailwind + CSS tokens
ui	No	Inline styles with DS tokens
viz (planned)	No	Inline styles with DS tokens
apps/*	No	Compose DS + ui + viz

Import Rules

Package	Can import	Cannot import
core	—	Any UI packages
design-system	core	ui, viz
ui	core, design-system	viz, Tailwind
viz (planned)	core, design-system	ui, Tailwind
apps/*	All packages	Tailwind directly

Using Design System

In Apps

import { Stack, Card, Text, Button } from '@lakea/design-system';
import '@lakea/design-system/styles.css';

function MyComponent() {
  return (
    <Stack gap="md">
      <Card>
        <Text variant="h2">Title</Text>
        <Text color="muted">Description</Text>
      </Card>
      <Button variant="primary">Action</Button>
    </Stack>
  );
}

In packages/ui or packages/viz

Use inline styles with design-system tokens for any custom styling:

import { colors, radius, shadows } from '@lakea/design-system/tokens';

const style = {
  backgroundColor: colors.slate[800],
  borderRadius: radius.lg,
  boxShadow: shadows.md,
};

Adding New Styles

Need a new visual pattern?

1. Check if @lakea/design-system already has a component for it
2. If not, add the component to design-system (atom, molecule, or layout)
3. Use the new component in your app or package

Never add Tailwind classes outside design-system.

Component Hierarchy

design-system
├── tokens (CSS variables + TS exports)
├── atoms (Button, Text, Badge, Link)
├── molecules (Card)
└── layout (Stack, Container)

ui (composes design-system)
└── charts (ScatterPlot, etc.)

viz (planned, composes design-system)
├── d3 bindings
└── three bindings

CSS Tokens

Design tokens are available as both CSS custom properties and TypeScript exports:

CSS Variables

:root {
  --ds-color-background: #0a0f1a;
  --ds-color-surface: #1e293b;
  --ds-color-text: #f1f5f9;
  --ds-color-text-muted: #94a3b8;
  --ds-space-4: 1rem;
  --ds-radius-lg: 0.5rem;
}

TypeScript

import { colors, spacing, radius } from '@lakea/design-system/tokens';

colors.cosmic[500]  // '#5a6cf4'
colors.slate[800]   // '#1e293b'
spacing[4]          // '1rem'
radius.lg           // '0.5rem'