This is the Foundations and tokens part of the Atomus documentation: colour, type, spacing, radius, icons, theming and the code token formats.
---
# Colour
URL: https://docs.atomus.io/foundations/color/
Use **semantic tokens** only. Each has a Light and Dark value and follows the Brand collection. Names below are the CSS variables (Figma names in brackets).
## Text
Text colour. `primary` for headings and body, `secondary` for supporting copy, `tertiary` for hints and meta, `placeholder` in inputs, `brand` for links/highlights, `on-brand` on brand fills.
| Token | Light | Dark |
| ------------------------------------------------------- | --------------- | --------------- |
| `--color-text-primary` Figma: Text/text-primary | `#18181b` | `#fafafa` |
| `--color-text-secondary` Figma: Text/text-secondary | `#3f3f46` | `#d4d4d8` |
| `--color-text-white` Figma: Text/text-white | `#ffffff` | `#ffffff` |
| `--color-text-opacity` Figma: Text/text-opacity | `#00000099` 60% | `#ffffff99` 60% |
| `--color-text-link` Figma: Text/text-link | `#4057ff` | `#6e96ff` |
| `--color-text-tertiary` Figma: Text/text-tertiary | `#71717a` | `#a1a1aa` |
| `--color-text-placeholder` Figma: Text/text-placeholder | `#71717a` | `#a1a1aa` |
| `--color-text-disabled` Figma: Text/text-disabled | `#d4d4d8` | `#52525b` |
| `--color-text-brand` Figma: Text/text-brand | `#4057ff` | `#6e96ff` |
| `--color-text-on-brand` Figma: Text/text-on-brand | `#ffffff` | `#ffffff` |
| `--color-text-error` Figma: Text/text-error | `#be123c` | `#fda4af` |
| `--color-text-warning` Figma: Text/text-warning | `#b45309` | `#fbbf24` |
| `--color-text-success` Figma: Text/text-success | `#15803d` | `#49de80` |
| `--color-text-brand-hover` Figma: Text/text-brand_hover | `#2335d6` | `#97bdff` |
| `--color-text-inverse` Figma: Text/text-inverse | `#ffffff` | `#18181b` |
| `--color-text-on-warning` Figma: Text/text-on-warning | `#18181b` | `#18181b` |
## Background
Surface fills. `primary` page and cards, `secondary` sections and table headers, `tertiary` subtle fills and image placeholders, `brand-solid` primary buttons, `brand-subtle` selected/tinted areas, `overlay` behind modals.
| Token | Light | Dark |
| --------------------------------------------------------------------- | --------------- | --------------- |
| `--color-bg-primary` Figma: Background/bg-primary | `#ffffff` | `#18181b` |
| `--color-bg-primary-hover` Figma: Background/bg-primary_hover | `#fafafa` | `#27272a` |
| `--color-bg-secondary` Figma: Background/bg-secondary | `#fafafa` | `#27272a` |
| `--color-bg-tertiary` Figma: Background/bg-tertiary | `#f4f4f5` | `#3f3f46` |
| `--color-bg-inverse` Figma: Background/bg-inverse | `#18181b` | `#ffffff` |
| `--color-bg-disabled` Figma: Background/bg-disabled | `#f4f4f5` | `#27272a` |
| `--color-bg-brand-solid` Figma: Background/bg-brand-solid | `#4057ff` | `#4057ff` |
| `--color-bg-brand-solid-hover` Figma: Background/bg-brand-solid_hover | `#2335d6` | `#2335d6` |
| `--color-bg-brand-subtle` Figma: Background/bg-brand-subtle | `#ebf5ff` | `#121f8c` |
| `--color-bg-error-solid` Figma: Background/bg-error-solid | `#e11d48` | `#e11d48` |
| `--color-bg-error-subtle` Figma: Background/bg-error-subtle | `#fff1f2` | `#881337` |
| `--color-bg-warning-subtle` Figma: Background/bg-warning-subtle | `#fffbeb` | `#78350f` |
| `--color-bg-success-subtle` Figma: Background/bg-success-subtle | `#f0fdf4` | `#14532d` |
| `--color-bg-tertiary-hover` Figma: Background/bg-tertiary_hover | `#e4e4e7` | `#52525b` |
| `--color-bg-warning-solid` Figma: Background/bg-warning-solid | `#f59e0b` | `#f59e0b` |
| `--color-bg-success-solid` Figma: Background/bg-success-solid | `#15803d` | `#15803d` |
| `--color-bg-overlay` Figma: Background/bg-overlay | `#18181bb2` 70% | `#000000b2` 70% |
| `--color-bg-quaternary` Figma: Background/bg-quaternary | `#e4e4e7` | `#3f3f46` |
| `--color-bg-quaternary-hover` Figma: Background/bg-quaternary_hover | `#d4d4d8` | `#52525b` |
## Border
Strokes. `secondary` for cards and dividers, `primary` for inputs and outlined controls, `brand` / `focus` for selected and focused states.
| Token | Light | Dark |
| --------------------------------------------------------- | --------- | --------- |
| `--color-border-primary` Figma: Border/border-primary | `#d4d4d8` | `#3f3f46` |
| `--color-border-secondary` Figma: Border/border-secondary | `#e4e4e7` | `#27272a` |
| `--color-border-disabled` Figma: Border/border-disabled | `#e4e4e7` | `#3f3f46` |
| `--color-border-brand` Figma: Border/border-brand | `#4057ff` | `#6e96ff` |
| `--color-border-focus` Figma: Border/border-focus | `#4c70ff` | `#6e96ff` |
| `--color-border-error` Figma: Border/border-error | `#e11d48` | `#fb7185` |
| `--color-border-warning` Figma: Border/border-warning | `#f59e0b` | `#fbbf24` |
| `--color-border-success` Figma: Border/border-success | `#16a34a` | `#49de80` |
## Foreground
Icons and graphics. Same roles as Text.
| Token | Light | Dark |
| ------------------------------------------------------------------- | --------- | --------- |
| `--color-fg-primary` Figma: Foreground/fg-primary | `#18181b` | `#ffffff` |
| `--color-fg-secondary` Figma: Foreground/fg-secondary | `#52525b` | `#d4d4d8` |
| `--color-fg-tertiary` Figma: Foreground/fg-tertiary | `#71717a` | `#a1a1aa` |
| `--color-fg-disabled` Figma: Foreground/fg-disabled | `#d4d4d8` | `#52525b` |
| `--color-fg-brand` Figma: Foreground/fg-brand | `#4057ff` | `#6e96ff` |
| `--color-fg-on-brand` Figma: Foreground/fg-on-brand | `#ffffff` | `#ffffff` |
| `--color-fg-error` Figma: Foreground/fg-error | `#e11d48` | `#fb7185` |
| `--color-fg-warning` Figma: Foreground/fg-warning | `#d97706` | `#fbbf24` |
| `--color-fg-success` Figma: Foreground/fg-success | `#16a34a` | `#49de80` |
| `--color-fg-inverse` Figma: Foreground/fg-inverse | `#ffffff` | `#18181b` |
| `--color-fg-on-warning` Figma: Foreground/fg-on-warning | `#18181b` | `#18181b` |
| `--color-fg-contrast` Figma: Foreground/fg-contrast | `#000000` | `#ffffff` |
| `--color-fg-contrast-inverse` Figma: Foreground/fg-contrast-inverse | `#ffffff` | `#000000` |
`fg-contrast` is the maximum-contrast foreground (pure black in Light, pure white in Dark) for marks that must read on any surface, such as the Stop button of the Prompt input; put `fg-contrast-inverse` on top of it.
## AI
The Agent kit’s layer for AI content (see `components/ai-label.md`). Each value is the brand ramp blended with purple, so AI reads as related to the brand but distinct from it, and follows the Brand mode. Hex values below are for the Atomus brand. `bg-ai-subtle` tints AI surfaces (AI label, assistant avatar, reasoning, active citations), `border-ai` is their hairline, `text-ai` their label and accent text. `--gradient-ai` (brand-500 → purple → pink-400 at 135°; 400/300 stops in Dark) fills the AI mark, the streaming caret and the focused Prompt input border.
| Token | Light | Dark |
| ----------------------------------------------------- | --------- | --------------- |
| `--color-bg-ai-subtle` Figma: Background/bg-ai-subtle | `#f2f5ff` | `#938efe1f` 12% |
| `--color-border-ai` Figma: Border/border-ai | `#b4b9ff` | `#938efe66` 40% |
| `--color-text-ai` Figma: Text/text-ai | `#4c2cd2` | `#b4b9ff` |
Use the AI layer only to identify AI content. Never decorate other UI with it, and never let it be the only signal: pair it with the AI label.
## Primitives
Raw ramps (`--color-gray-25 … 950`, `--color-red-*`, … `--color-alpha-black-5 … 90`) exist only to be aliased. The brand ramp is `--color-brand-25 … 950` and changes with the Brand mode.
### Brand
Atomus Violet
`brand`
1. 25 `#f5faff`
2. 50 `#ebf5ff`
3. 100 `#dbeaff`
4. 200 `#bed9ff`
5. 300 `#97bdff`
6. 400 `#6e96ff`
7. 500 `#4c70ff`
8. 600 `#4057ff`
9. 700 `#2335d6`
10. 800 `#1d2fb6`
11. 900 `#121f8c`
12. 950 `#0b1354`
`--color-brand-25 … 950` point at `atomus-blue` by default and at `violet` under `data-brand="violet"`.
### Neutrals
`gray`
1. 25 `#fdfdfd`
2. 50 `#fafafa`
3. 100 `#f4f4f5`
4. 200 `#e4e4e7`
5. 300 `#d4d4d8`
6. 400 `#a1a1aa`
7. 500 `#71717a`
8. 600 `#52525b`
9. 700 `#3f3f46`
10. 800 `#27272a`
11. 900 `#18181b`
12. 950 `#0e0e10`
`blue-gray`
1. 25 `#fbfdfd`
2. 50 `#f8fafc`
3. 100 `#f1f5f9`
4. 200 `#e2e8f0`
5. 300 `#cbd5e1`
6. 400 `#94a3b8`
7. 500 `#64748b`
8. 600 `#475569`
9. 700 `#334155`
10. 800 `#1e293c`
11. 900 `#0f172a`
12. 950 `#090e19`
`cool-gray`
1. 25 `#fcfdfd`
2. 50 `#f9fafb`
3. 100 `#f3f4f6`
4. 200 `#e5e7eb`
5. 300 `#d1d5db`
6. 400 `#9ca3af`
7. 500 `#6b7280`
8. 600 `#4b5563`
9. 700 `#374151`
10. 800 `#1f2937`
11. 900 `#111827`
12. 950 `#0a0e17`
`true-gray`
1. 25 `#fdfdfd`
2. 50 `#fafafa`
3. 100 `#f5f5f5`
4. 200 `#e5e5e5`
5. 300 `#d4d4d4`
6. 400 `#a3a3a3`
7. 500 `#737373`
8. 600 `#525252`
9. 700 `#404040`
10. 800 `#262626`
11. 900 `#171717`
12. 950 `#0e0e0e`
`warm-gray`
1. 25 `#fdfdfc`
2. 50 `#fafaf9`
3. 100 `#f5f5f4`
4. 200 `#e7e5e4`
5. 300 `#d6d3d1`
6. 400 `#a8a29e`
7. 500 `#78716c`
8. 600 `#57534e`
9. 700 `#44403c`
10. 800 `#292524`
11. 900 `#1c1917`
12. 950 `#110f0e`
### Hues
`red`
1. 25 `#fff9f9`
2. 50 `#fef2f2`
3. 100 `#fee2e2`
4. 200 `#fecaca`
5. 300 `#fca5a5`
6. 400 `#f87171`
7. 500 `#ef4444`
8. 600 `#dc2626`
9. 700 `#b91c1c`
10. 800 `#991b1b`
11. 900 `#7f1d1d`
12. 950 `#4c1111`
`rose`
1. 25 `#fff8f9`
2. 50 `#fff1f2`
3. 100 `#ffe4e6`
4. 200 `#fecdd3`
5. 300 `#fda4af`
6. 400 `#fb7185`
7. 500 `#f43f5e`
8. 600 `#e11d48`
9. 700 `#be123c`
10. 800 `#9f1239`
11. 900 `#881337`
12. 950 `#520b21`
`pink`
1. 25 `#fef9fb`
2. 50 `#fdf2f8`
3. 100 `#fce7f3`
4. 200 `#fbcfe8`
5. 300 `#f9a8d4`
6. 400 `#f472b6`
7. 500 `#ec4899`
8. 600 `#db2777`
9. 700 `#be185d`
10. 800 `#9d174d`
11. 900 `#831843`
12. 950 `#4f0e28`
`fuschia`
1. 25 `#fef9ff`
2. 50 `#fdf4ff`
3. 100 `#fae8ff`
4. 200 `#f5d0fe`
5. 300 `#f0abfc`
6. 400 `#e879f9`
7. 500 `#d946ef`
8. 600 `#c026d3`
9. 700 `#a21caf`
10. 800 `#86198f`
11. 900 `#701a75`
12. 950 `#431046`
`purple`
1. 25 `#fdfaff`
2. 50 `#faf5ff`
3. 100 `#f3e8ff`
4. 200 `#e9d5ff`
5. 300 `#d8b4fe`
6. 400 `#c084fc`
7. 500 `#a855f7`
8. 600 `#9333ea`
9. 700 `#7e22ce`
10. 800 `#6b21a8`
11. 900 `#581c87`
12. 950 `#351151`
`violet`
1. 25 `#faf9ff`
2. 50 `#f5f3ff`
3. 100 `#ede9fe`
4. 200 `#ddd6fe`
5. 300 `#c4b5fd`
6. 400 `#a78bfa`
7. 500 `#8b5cf6`
8. 600 `#7c3aed`
9. 700 `#6d28d9`
10. 800 `#5b21b6`
11. 900 `#4c1d95`
12. 950 `#2e1159`
`indigo`
1. 25 `#f7f9ff`
2. 50 `#eef2ff`
3. 100 `#e0e7ff`
4. 200 `#c7d2fe`
5. 300 `#a5b4fc`
6. 400 `#818cf8`
7. 500 `#6366f1`
8. 600 `#4f46e5`
9. 700 `#4338ca`
10. 800 `#3730a3`
11. 900 `#312e81`
12. 950 `#1d1c4d`
`blue`
1. 25 `#f7fbff`
2. 50 `#eff6ff`
3. 100 `#dbeafe`
4. 200 `#bfdbfe`
5. 300 `#93c5fd`
6. 400 `#60a5fa`
7. 500 `#3b82f6`
8. 600 `#2563eb`
9. 700 `#1d4ed8`
10. 800 `#1e40af`
11. 900 `#1e3a8a`
12. 950 `#122353`
`light-blue`
1. 25 `#f7fcff`
2. 50 `#f0f9ff`
3. 100 `#e0f2fe`
4. 200 `#bae6fd`
5. 300 `#7dd3fc`
6. 400 `#38bdf8`
7. 500 `#0ea5e9`
8. 600 `#0284c7`
9. 700 `#0369a1`
10. 800 `#075985`
11. 900 `#0c4a6e`
12. 950 `#072c42`
`cyan`
1. 25 `#f5ffff`
2. 50 `#ecfeff`
3. 100 `#cffafe`
4. 200 `#a5f3fc`
5. 300 `#67e8f9`
6. 400 `#22d3ee`
7. 500 `#06b6d4`
8. 600 `#0891b2`
9. 700 `#0e7490`
10. 800 `#155e75`
11. 900 `#164e63`
12. 950 `#0d2f3b`
`teal`
1. 25 `#f7fefd`
2. 50 `#f0fdfa`
3. 100 `#ccfbf1`
4. 200 `#99f6e4`
5. 300 `#5eead4`
6. 400 `#2dd4bf`
7. 500 `#14b8a6`
8. 600 `#0d9488`
9. 700 `#0f766e`
10. 800 `#115e59`
11. 900 `#134e4a`
12. 950 `#0b2f2c`
`emerald`
1. 25 `#f5fefa`
2. 50 `#ecfdf5`
3. 100 `#d1fae5`
4. 200 `#a7f3d0`
5. 300 `#6ee7b7`
6. 400 `#34d399`
7. 500 `#10b981`
8. 600 `#059669`
9. 700 `#047857`
10. 800 `#065f46`
11. 900 `#064e3b`
12. 950 `#042f23`
`green`
1. 25 `#f7fef9`
2. 50 `#f0fdf4`
3. 100 `#dcfce7`
4. 200 `#baf7d0`
5. 300 `#85efab`
6. 400 `#49de80`
7. 500 `#22c55d`
8. 600 `#16a34a`
9. 700 `#15803d`
10. 800 `#166534`
11. 900 `#14532d`
12. 950 `#0c321b`
`lime`
1. 25 `#fbfff3`
2. 50 `#f7fee7`
3. 100 `#ecfccb`
4. 200 `#d9f99d`
5. 300 `#bef264`
6. 400 `#a3e635`
7. 500 `#84cc16`
8. 600 `#65a30d`
9. 700 `#4d7c0f`
10. 800 `#3f6212`
11. 900 `#365314`
12. 950 `#20320c`
`yellow`
1. 25 `#fffdf3`
2. 50 `#fefce8`
3. 100 `#fef9c3`
4. 200 `#fef08a`
5. 300 `#fde047`
6. 400 `#facc15`
7. 500 `#eab308`
8. 600 `#ca8a04`
9. 700 `#a16207`
10. 800 `#854d0e`
11. 900 `#713f12`
12. 950 `#44260b`
`amber`
1. 25 `#fffdf5`
2. 50 `#fffbeb`
3. 100 `#fef3c7`
4. 200 `#fde68a`
5. 300 `#fcd34d`
6. 400 `#fbbf24`
7. 500 `#f59e0b`
8. 600 `#d97706`
9. 700 `#b45309`
10. 800 `#92400e`
11. 900 `#78350f`
12. 950 `#482009`
`orange`
1. 25 `#fffbf6`
2. 50 `#fff7ed`
3. 100 `#ffedd5`
4. 200 `#fed7aa`
5. 300 `#fdba74`
6. 400 `#fb923c`
7. 500 `#f97316`
8. 600 `#ea580c`
9. 700 `#c2410c`
10. 800 `#9a3412`
11. 900 `#7c2d12`
12. 950 `#4a1b0b`
### Alpha
`alpha-black`
1. 5 `#0000000d`
2. 10 `#0000001a`
3. 20 `#00000033`
4. 30 `#0000004d`
5. 40 `#00000066`
6. 50 `#00000080`
7. 60 `#00000099`
8. 70 `#000000b2`
9. 80 `#000000cc`
10. 90 `#000000e5`
`alpha-white`
1. 5 `#ffffff0d`
2. 10 `#ffffff1a`
3. 20 `#ffffff33`
4. 30 `#ffffff4d`
5. 40 `#ffffff66`
6. 50 `#ffffff80`
7. 60 `#ffffff99`
8. 70 `#ffffffb2`
9. 80 `#ffffffcc`
10. 90 `#ffffffe5`
---
# Typography
URL: https://docs.atomus.io/foundations/typography/
Families: **Inter Display** (headlines), **Inter** (body and UI), **Roboto Mono** (code). Sizes and line heights are variables with Desktop / Tablet / Mobile values; the text styles below use them.
## Font families
### Inter Display
Headlines · `--font-family-title`
ABCDEFGHIJKLMNOPQRSTUVWXYZ\
abcdefghijklmnopqrstuvwxyz\
0123456789 &@$%?!
- Medium `500`
- Semi Bold `600`
- Bold `700`
### Inter
Body and UI · `--font-family-body`
ABCDEFGHIJKLMNOPQRSTUVWXYZ\
abcdefghijklmnopqrstuvwxyz\
0123456789 &@$%?!
- Light `300`
- Regular `400`
- Medium `500`
- Semi Bold `600`
- Bold `700`
### Roboto Mono
Code and tokens · `.text-components-code`
ABCDEFGHIJKLMNOPQRSTUVWXYZ\
abcdefghijklmnopqrstuvwxyz\
0123456789 &@$%?!
- Regular `400`
- Medium `500`
## Type scale
Every style below is rendered with its CSS class, so sizes switch at the tablet and mobile breakpoints like they do in product.
### Headline
**Headline/Huge** `.text-headline-huge`
- Desktop
120/140
- Tablet
88/100
- Mobile
56/64
- Weight
SemiBold
Build faster
**Headline/H1** `.text-headline-h1`
- Desktop
64/72
- Tablet
52/60
- Mobile
40/52
- Weight
SemiBold
Build faster
**Headline/H2** `.text-headline-h2`
- Desktop
56/64
- Tablet
44/52
- Mobile
36/48
- Weight
Medium
One system
**Headline/H3** `.text-headline-h3`
- Desktop
40/44
- Tablet
36/44
- Mobile
32/40
- Weight
Medium
Design that scales
**Headline/H4** `.text-headline-h4`
- Desktop
32/40
- Tablet
30/40
- Mobile
28/36
- Weight
Medium
Design that scales
**Headline/H5** `.text-headline-h5`
- Desktop
24/32
- Weight
Medium
The quick brown fox jumps over the lazy dog
**Headline/H6** `.text-headline-h6`
- Desktop
20/28
- Weight
Medium
The quick brown fox jumps over the lazy dog
**Headline/Subtitle** `.text-headline-subtitle`
- Desktop
12/20
- Weight
Medium
Design system
**Headline/Overline** `.text-headline-overline`
- Desktop
14/20
- Weight
Bold
Design system
### Content
**Content/Body leading** `.text-content-body-leading`
- Desktop
18/28
- Weight
Medium
Atomus keeps product UI and marketing websites in one design language.
**Content/Body leading bold** `.text-content-body-leading-bold`
- Desktop
18/28
- Weight
Bold
Atomus keeps product UI and marketing websites in one design language.
**Content/Body** `.text-content-body`
- Desktop
16/24
- Weight
Regular
App body copy
Atomus keeps product UI and marketing websites in one design language.
**Content/Body bold** `.text-content-body-bold`
- Desktop
16/24
- Weight
Semi Bold
Atomus keeps product UI and marketing websites in one design language.
**Content/Small** `.text-content-small`
- Desktop
14/20
- Weight
Regular
Most UI text, table cells
Atomus keeps product UI and marketing websites in one design language.
**Content/Small Bold** `.text-content-small-bold`
- Desktop
14/20
- Weight
Semi Bold
Atomus keeps product UI and marketing websites in one design language.
**Content/Tiny** `.text-content-tiny`
- Desktop
12/16
- Weight
Regular
Meta, captions
Atomus keeps product UI and marketing websites in one design language.
**Content/Tiny bold** `.text-content-tiny-bold`
- Desktop
12/16
- Weight
Medium
Atomus keeps product UI and marketing websites in one design language.
**Content/Micro** `.text-content-micro`
- Desktop
10/12
- Weight
Regular
Atomus keeps product UI and marketing websites in one design language.
**Content/Micro Bold** `.text-content-micro-bold`
- Desktop
10/12
- Weight
Semi Bold
Atomus keeps product UI and marketing websites in one design language.
### Components
**Components/Button xSmall** `.text-components-button-xsmall`
- Desktop
10/12
- Weight
Semi Bold
Save changes
**Components/Button Small** `.text-components-button-small`
- Desktop
12/16
- Weight
Semi Bold
Save changes
**Components/Button Medium** `.text-components-button-medium`
- Desktop
14/16
- Weight
Semi Bold
Save changes
**Components/Button Large** `.text-components-button-large`
- Desktop
16/20
- Weight
Semi Bold
Save changes
**Components/Button xLarge** `.text-components-button-xlarge`
- Desktop
18/20
- Weight
Semi Bold
Save changes
**Components/Input xSmall** `.text-components-input-xsmall`
- Desktop
12/12
- Weight
Regular
you\@company.com
**Components/Input Small** `.text-components-input-small`
- Desktop
14/16
- Weight
Regular
you\@company.com
**Components/Input Medium** `.text-components-input-medium`
- Desktop
15/16
- Weight
Regular
you\@company.com
**Components/Input Large** `.text-components-input-large`
- Desktop
18/20
- Weight
Regular
you\@company.com
**Components/Caption xSmall** `.text-components-caption-xsmall`
- Desktop
10/12
- Weight
Semi Bold
Caption text
**Components/Caption Small** `.text-components-caption-small`
- Desktop
12/12
- Weight
Medium
Caption text
**Components/Caption Medium** `.text-components-caption-medium`
- Desktop
14/16
- Weight
Semi Bold
Caption text
**Components/Caption Large** `.text-components-caption-large`
- Desktop
16/16
- Weight
Semi Bold
Caption text
**Components/Metric value** `.text-components-metric-value`
- Desktop
36/44
- Weight
Semi Bold
$48.2k
**Components/Code** `.text-components-code`
- Desktop
14/20
- Weight
Regular
const theme = "dark";
### Template
**Template/Title** `.text-template-title`
- Desktop
48/56
- Weight
Semi Bold
One system
**Template/Heading** `.text-template-heading`
- Desktop
24/32
- Weight
Semi Bold
Page/drawer titles in app
The quick brown fox jumps over the lazy dog
**Template/Eyebrow** `.text-template-eyebrow`
- Desktop
14/20
- Weight
Semi Bold
Design system
### Web
**Web/Display** `.text-web-display`
- Desktop
64/72
- Tablet
52/60
- Mobile
40/52
- Weight
Semi Bold
Hero headlines
Build faster
**Web/Heading xl** `.text-web-heading-xl`
- Desktop
56/64
- Tablet
44/52
- Mobile
36/48
- Weight
Semi Bold
Section titles
One system
**Web/Heading lg** `.text-web-heading-lg`
- Desktop
40/44
- Tablet
36/44
- Mobile
32/40
- Weight
Semi Bold
Large card / split headings
Design that scales
**Web/Heading md** `.text-web-heading-md`
- Desktop
32/40
- Tablet
30/40
- Mobile
28/36
- Weight
Semi Bold
Sub-section titles
Design that scales
**Web/Heading sm** `.text-web-heading-sm`
- Desktop
24/32
- Weight
Semi Bold
Card titles, article H2
The quick brown fox jumps over the lazy dog
**Web/Heading xs** `.text-web-heading-xs`
- Desktop
20/28
- Weight
Semi Bold
Small titles, quotes
The quick brown fox jumps over the lazy dog
**Web/Body lg** `.text-web-body-lg`
- Desktop
18/28
- Weight
Regular
Lead paragraphs
Atomus keeps product UI and marketing websites in one design language.
**Web/Body** `.text-web-body`
- Desktop
16/24
- Weight
Regular
Website body copy
Atomus keeps product UI and marketing websites in one design language.
**Web/Eyebrow** `.text-web-eyebrow`
- Desktop
14/20
- Weight
Semi Bold
Labels above headings
Design system
**Web/Quote** `.text-web-quote`
- Desktop
20/28
- Weight
Italic
Atomus keeps product UI and marketing websites in one design language.
---
# Spacing, layout and breakpoints
URL: https://docs.atomus.io/foundations/spacing-layout/
Breakpoints: **Desktop ≥ 1024px**, **Tablet 768–1023px**, **Mobile < 768px** (Figma frames 1440 / 768 / 375).
### Inside components (padding, gaps)
| Token | Desktop | Tablet | Mobile | Preview |
| ---------------- | ------- | ------ | ------ | ------- |
| `--spacing-none` | 0 | 0 | 0 | |
| `--spacing-xxs` | 2 | 2 | 2 | |
| `--spacing-xs` | 4 | 4 | 4 | |
| `--spacing-sm` | 6 | 6 | 6 | |
| `--spacing-md` | 8 | 8 | 8 | |
| `--spacing-lg` | 12 | 12 | 12 | |
| `--spacing-xl` | 16 | 16 | 16 | |
| `--spacing-2xl` | 20 | 20 | 20 | |
| `--spacing-3xl` | 24 | 24 | 24 | |
### Between blocks and sections
| Token | Desktop | Tablet | Mobile | Preview |
| -------------- | ------- | ------ | ------ | ------- |
| `--layout-xs` | 32 | 32 | 24 | |
| `--layout-sm` | 40 | 32 | 24 | |
| `--layout-md` | 48 | 40 | 32 | |
| `--layout-lg` | 56 | 48 | 32 | |
| `--layout-xl` | 64 | 48 | 40 | |
| `--layout-2xl` | 72 | 56 | 40 | |
| `--layout-3xl` | 80 | 64 | 40 | |
| `--layout-4xl` | 96 | 72 | 56 | |
| `--layout-5xl` | 120 | 80 | 56 | |
| `--layout-6xl` | 160 | 120 | 80 | |
| `--layout-7xl` | 200 | 160 | 80 | |
| `--layout-8xl` | 240 | 160 | 80 | |
### Icon size
| Token | Desktop | Tablet | Mobile | Preview |
| ----------- | ------- | ------ | ------ | ------- |
| `--icon-xs` | 12 | 12 | 12 | |
| `--icon-sm` | 16 | 16 | 16 | |
| `--icon-md` | 20 | 20 | 20 | |
| `--icon-lg` | 24 | 24 | 24 | |
| `--icon-xl` | 32 | 32 | 32 | |
### Control height (sm 32, md 40, lg 48)
| Token | Desktop | Tablet | Mobile | Preview |
| ------------ | ------- | ------ | ------ | ------- |
| `--size-xs` | 24 | 24 | 24 | |
| `--size-sm` | 32 | 32 | 32 | |
| `--size-md` | 40 | 40 | 40 | |
| `--size-lg` | 48 | 48 | 48 | |
| `--size-xl` | 56 | 56 | 56 | |
| `--size-2xl` | 64 | 64 | 64 | |
### Page container
| Token | Desktop | Tablet | Mobile | Preview |
| ----------------------- | ------- | ------ | ------ | ------- |
| `--container-padding` | 80 | 32 | 16 | |
| `--container-max-width` | 1280 | 704 | 343 | |
| `--section-padding` | 96 | 72 | 56 | |
Grid styles in Figma: Desktop 12 col (gutter 32, margin 80), Tablet 8 col (24 / 32), Mobile 4 col (16 / 16), plus 8px and 4px baseline grids.
---
# Radius and effects
URL: https://docs.atomus.io/foundations/radius-effects/
## Radius (modes: Default · Sharp · Round)
Default **0**
Sharp **0**
Round **0**
`--radius-none`
Default **2**
Sharp **0**
Round **4**
`--radius-xxs`
Default **4**
Sharp **2**
Round **6**
`--radius-xs`
Default **6**
Sharp **2**
Round **8**
`--radius-sm`
Default **8**
Sharp **4**
Round **12**
`--radius-md`
Default **10**
Sharp **4**
Round **16**
`--radius-lg`
Default **12**
Sharp **6**
Round **20**
`--radius-xl`
Default **16**
Sharp **8**
Round **24**
`--radius-2xl`
Default **20**
Sharp **10**
Round **32**
`--radius-3xl`
Default **24**
Sharp **12**
Round **40**
`--radius-4xl`
Default **full**
Sharp **full**
Round **full**
`--radius-full`
Default **32**
Sharp **16**
Round **48**
`--radius-5xl`
Default **40**
Sharp **20**
Round **64**
`--radius-6xl`
Controls (buttons, inputs) use `radius-md`; cards `radius-xl`/`2xl`; badges and avatars `radius-full`.
## Shadows (Effects: Light · Dark)
`--shadow-elevation-1 … 24`. Use 1–2 for cards, 3–4 for dropdowns and popovers, 6–8 for drawers and modals, 9+ for marketing visuals. Dark mode uses stronger, neutral shadows.
1 Cards
`--shadow-elevation-1`
Values
**Light** `0px 1px 2px 0px #1111140f`
**Dark** `0px 1px 2px 0px #00000026`
2 Cards
`--shadow-elevation-2`
Values
**Light** `0px 1px 3px 0px #11111414, 0px 1px 2px 0px #1111140f`
**Dark** `0px 1px 3px 0px #00000033, 0px 1px 2px 0px #00000026`
3 Dropdowns, popovers
`--shadow-elevation-3`
Values
**Light** `0px 4px 8px -2px #1111141a, 0px 1px 2px 0px #1111140a`
**Dark** `0px 4px 8px -2px #00000040, 0px 1px 2px 0px #00000019`
4 Dropdowns, popovers
`--shadow-elevation-4`
Values
**Light** `0px 12px 16px -4px #11111414, 0px 4px 6px -2px #1111140a`
**Dark** `0px 12px 16px -4px #00000033, 0px 4px 6px -2px #00000019`
6 Drawers, modals
`--shadow-elevation-6`
Values
**Light** `0px 20px 24px -4px #11111414, 0px 8px 8px -4px #11111408`
**Dark** `0px 20px 24px -4px #00000033, 0px 8px 8px -4px #00000013`
8 Drawers, modals
`--shadow-elevation-8`
Values
**Light** `0px 24px 48px -12px #1111142e`
**Dark** `0px 24px 48px -12px #00000073`
9 Marketing visuals
`--shadow-elevation-9`
Values
**Light** `0px 32px 64px -12px #1111143d`
**Dark** `0px 32px 64px -12px #00000099`
12 Marketing visuals
`--shadow-elevation-12`
Values
**Light** `0px 40px 80px -12px #11111452`
**Dark** `0px 40px 80px -12px #00000099`
16 Marketing visuals
`--shadow-elevation-16`
Values
**Light** `0px 48px 96px -12px #11111466`
**Dark** `0px 48px 96px -12px #00000099`
24 Marketing visuals
`--shadow-elevation-24`
Values
**Light** `0px 56px 112px -12px #1111147a`
**Dark** `0px 56px 112px -12px #00000099`
## Focus
Focused controls get a 4px ring in `bg-brand-subtle` (`--shadow-focus-ring`) and a `border-brand` stroke; errors use `bg-error-subtle` / `border-error`.
Focused input
`--shadow-focus-ring` + `--color-border-brand`
Invalid input
`--shadow-focus-ring-error` + `--color-border-error`
## Blur
Effect styles `Blur/Backdrop sm 8 · md 16 · lg 24 · xl 40` for glass overlays.
8px
Effect style `Blur/Backdrop sm` `backdrop-filter: blur(8px)`
16px
Effect style `Blur/Backdrop md` `backdrop-filter: blur(16px)`
24px
Effect style `Blur/Backdrop lg` `backdrop-filter: blur(24px)`
40px
Effect style `Blur/Backdrop xl` `backdrop-filter: blur(40px)`
## Motion
Streaming motion for the Agent kit: `--motion-stream-caret-blink` (1s) is the blink period of the Streaming text caret, and `--motion-stream-shimmer-duration` (1.8s) is one sweep of the Shimmer on status text. Under `prefers-reduced-motion: reduce` both become `0s` and the components switch the animation off: the caret stays solid and the shimmer shows static text.
---
# Icons
URL: https://docs.atomus.io/foundations/icons/
- **UI icons**: 88 components named `icon/` (e.g. `icon/arrow-right`, `icon/magnifying-glass`). 24px frame; colour from Foreground tokens. Swap via the icon property of Button, Input, Badge, Menu item…
- Because names match Font Awesome, a file can switch to Font Awesome Pro with **Swap library**.
- Sizes: `icon-xs 12 · sm 16 · md 20 · lg 24 · xl 32`.
- Other sets: Icon brand (44 logos), Icon payment (24), Icon flag (18), Icon file type (12 types × 2 sizes), Icon folder, Icon integration (16 app tiles), Star rating, Featured icon.
- Never mix icon families; never use an icon without a label or tooltip for actions.
## Sizes
`--icon-xs` 12px
`--icon-sm` 16px
`--icon-md` 20px
`--icon-lg` 24px
`--icon-xl` 32px
## Glyphs in the React package
The React components ship a small set of internal glyphs (``) for checks, close buttons, status and navigation. Product icons come from the 88 `icon/*` components in Figma or Font Awesome.
- `check`
- `minus`
- `x`
- `plus`
- `info`
- `alert`
- `success`
- `search`
- `folder`
- `user`
- `home`
- `settings`
- `bell`
- `menu`
- `more`
- `calendar`
- `sort`
- `arrowUp`
- `arrowDown`
- `chevronDown`
- `chevronUp`
- `chevronLeft`
- `chevronRight`
---
# Theming
URL: https://docs.atomus.io/foundations/theming/
Three collections re-theme everything without touching components. Set the mode on the top frame (Figma) or an attribute on an element (code):
| Collection | Modes | Code |
| ---------------------------- | ----------------------------------------- | ------------------------- |
| Brand | Atomus · Example — Violet · (your brands) | `data-brand="violet"` |
| Color | Light · Dark | `data-theme="dark"` |
| Radius | Default · Sharp · Round | `data-radius="sharp"` |
| Spacing & Layout, Typography | Desktop · Tablet · Mobile | media queries (automatic) |
**Add a client brand:** add a mode to Brand, point `brand-25 … brand-950` at the client ramp (add the ramp to \_Primitives first). In CSS, copy the `[data-brand="violet"]` block.
---
# Design tokens
> W3C DTCG token files generated from the Figma variables.
URL: https://docs.atomus.io/code/tokens/
The [`tokens/`](https://github.com/StanVisionAgency/atomus/tree/main/tokens) folder holds one **DTCG 2025.10** JSON file per collection and mode, plus `$themes.json` (which files make each theme) and `text-styles.tokens.json`.
| File | Contents |
| ------------------------------------------------------ | ------------------------------------------------ |
| `primitives.tokens.json` | Colour ramps, alpha ramps, size scale |
| `brand.atomus.tokens.json`, `brand.violet.tokens.json` | Brand ramp per brand mode |
| `color.light.tokens.json`, `color.dark.tokens.json` | Semantic colours |
| `radius.default/sharp/round.tokens.json` | Corner scale per shape mode |
| `spacing-layout.desktop/tablet/mobile.tokens.json` | Spacing, layout, sizes, containers |
| `typography.desktop/tablet/mobile.tokens.json` | Families, weights, sizes, line heights |
| `effects.light/dark.tokens.json` | Shadow layers per elevation |
| `text-styles.tokens.json` | Composite typography tokens for every text style |
They import into Tokens Studio, Style Dictionary and Terrazzo. Token names map to the CSS names shown in Figma Dev Mode, for example `Text/text-primary` → `--color-text-primary`.
---
# CSS
> atomus.css — every token as a CSS custom property, with theme, brand, radius and breakpoint switches.
URL: https://docs.atomus.io/code/css/
[`css/atomus.css`](https://github.com/StanVisionAgency/atomus/blob/main/css/atomus.css) works with any stack.
```html
```
- Switches nest: a `data-theme` or `data-brand` on any element re-themes everything inside it.
- Breakpoints follow the Figma modes: Desktop ≥ 1024px, Tablet 768–1023px, Mobile < 768px. Layout spacing, container padding and headline sizes change automatically.
- `.text-*` classes match every Figma text style (`.text-headline-h1`, `.text-content-body`, `.text-web-display` …).
- Shadows: `--shadow-elevation-1 … 24` and `--shadow-focus-ring`.
## Add a client brand
1. In Figma, add a mode to the **Brand** collection and point `brand-25 … brand-950` at the client ramp.
2. In CSS, copy the `[data-brand="violet"]` block, rename it and paste the client hex values.
---
# Tailwind CSS v4
> The Atomus theme for Tailwind v4 with semantic utilities.
URL: https://docs.atomus.io/code/tailwind/
```css
@import "tailwindcss";
@import "./atomus.tailwind.css";
```
```html
…
```
- `@theme` holds the palette (`bg-brand-600`, `text-gray-900` …), radius, spacing (`p-md`, `gap-layout-sm`), type scale (`text-h1`) and shadows (`shadow-e1 … e24`).
- 54 semantic utilities: `text-primary`, `bg-secondary`, `border-primary`, `fg-brand`, `text-on-warning` …
- `dark:` works with `data-theme="dark"` or `.dark`. Brand, radius and breakpoint switches come from `atomus.css`, which the theme imports.
Use **either** this theme **or** the shadcn/ui theme in one app — both define `bg-primary` with different meanings.
---
# shadcn/ui
> Map shadcn/ui's theme variables onto Atomus tokens.
URL: https://docs.atomus.io/code/shadcn/
Replace the `:root` / `.dark` blocks in your `globals.css` with [`shadcn/globals.css`](https://github.com/StanVisionAgency/atomus/blob/main/shadcn/globals.css), after `@import "tailwindcss"`.
| shadcn variable | Atomus token |
| ------------------------------------- | ------------------------------------------------------ |
| `--background`, `--card`, `--popover` | `bg-primary` |
| `--foreground` | `text-primary` |
| `--primary` / `--primary-foreground` | `bg-brand-solid` / `text-on-brand` |
| `--secondary` | `bg-secondary` |
| `--muted` / `--muted-foreground` | `bg-tertiary` / `text-tertiary` |
| `--accent` / `--accent-foreground` | `bg-brand-subtle` / `text-brand` |
| `--destructive` | `bg-error-solid` |
| `--border` / `--input` / `--ring` | `border-secondary` / `border-primary` / `border-focus` |
| `--chart-1 … 5` | brand 600, 400, 200, gray 400, 200 |
| `--sidebar-*` | sidebar surfaces and accents |
| `--radius` | `radius-lg` |
Brand, theme and radius modes keep working: shadcn components follow `data-brand`, `data-theme` and `data-radius`.
## Install with the shadcn CLI
The same mapping ships as the `atomus-theme` item of the [Atomus shadcn registry](https://docs.atomus.io/ai/registry/). It writes the tokens and the variables above into your CSS file:
```bash
npx shadcn@latest add https://docs.atomus.io/r/atomus-theme.json
```