@lunit/oui/docs/TOKENS.md

Lunit Oncology UI components

# @lunit/oui — Design Tokens

Always use tokens for color, spacing, and typography. Never hardcode magic values (`#3BC9DB`, `16px`).
The source of truth is `src/foundations/` (palette.ts / spacing.ts / typography.ts).

```ts
import { palette, spacing, typography, theme } from '@lunit/oui';
// Inside a component's styled, access via the theme arg: (theme) => ({ color: theme.palette.lunitTeal[40] })
```

## Usage rules

| Kind | ❌ Don't | ✅ Do |
|---|---|---|
| Color | `color: '#3BC9DB'` | `color: theme.palette.lunitTeal[30]` |
| Spacing | `padding: '16px'` | `padding: theme.spacing(4)` |
| Typography | `fontSize: 14, fontWeight: 600` | `<Typography variant="body_sb1">` |

## Color (palette)

Form: `theme.palette.<group>[<key>]`. The key is a brightness scale (lower = brighter).

| Group | Key scale | Purpose |
|---|---|---|
| `brand` | `primary`, `secondary` | Brand colors (`#3BC9DB`, `#96EDFF`) |
| `lunitTeal` | 5–90 | Main teal palette (primary actions) |
| `neutralGrey` | 0–100 | Grayscale (0 = white, 100 = black). Backgrounds, text, borders |
| `red` | 5–50 | Error/danger |
| `blue` | 5–75 | Info |
| `green` | 10–50 | Success |
| `yellow` / `orange` | 5–20 | Caution/warning |
| `magenta` / `purple` | — | Secondary accents |
| `text` | `primary`, `secondary`, `disabled` | Text colors |
| `alert` | `InfoBG`, `SuccessBG`, `ErrorBG`, `WarningBG` | Alert backgrounds |

### Domain (histology) colors

Color groups exclusive to tumor analysis — do not use them for general UI.
`pdl1Tps`, `pdl1Cps`, `io`, `tumorPurity`, `her2`, `erpr`, `analysisStatus`

## Spacing

base unit = **4px**. `theme.spacing(n)` = `n * 4px`.

```
spacing(1)=4px  spacing(2)=8px  spacing(3)=12px  spacing(4)=16px  spacing(6)=24px
```

## Typography (variants)

Use via `<Typography variant="...">`, or `theme.typography.<variant>` in styled. Custom variants:

- **Heading**: `h7`, `h8`, `h9`, `h10`, `subtitle3`
- **Body (weight suffix)**: `b`=bold, `sb`=semibold, `m`=medium, none=regular, `l`=light
  - `body_b1~2`, `body_sb1~5`, `body_m1~2`, `body1~8`
  - `small_body_b1~5`, `small_body_sb1`, `small_body_m1~7`, `small_body1~5`, `small_body_l1~2`
- **Other**: `button1`, `button2`, `overline`, `caption`

> If you need a new token, define it in `src/foundations/` first. When you extend palette/typography,
> also update the `declare module '@mui/material/styles'` type augmentation in `theme.ts`.