---
name: design-system-foundations
description: Use when writing UI code, CSS, components, or any visual element. Triggers on colors, typography, text, fonts, sizes, spacing, padding, margin, shadows, border radius, grid, or building any screen or component.
---

# Design System Foundations

## Overview

Source of truth for all visual tokens. Check before writing any color, typography, spacing, radius, shadow, or grid value.

## When to Use

- Writing any CSS or styled component
- Choosing colors, font sizes, spacing, shadows, or border radius
- Building a new screen, layout, or component
- Reviewing UI code for design consistency

## When NOT to Use

- Non-visual backend logic
- Third-party component libraries with their own design systems
- Print or PDF generation

## References

| Category | File | Contents |
|----------|------|----------|
| Colors | `references/colors.md` | 15 color families + semantic UI tokens |
| Typography | `references/typography.md` | Roboto scale, CSS for all 8 size tokens |
| Spacing | `references/spacing.md` | 8px base system with semantic guide |
| Border Radius | `references/border-radius.md` | Height-based token selection (S/M/L) |
| Grid | `references/grid.md` | Responsive grid tokens (S-Fluid to XL-Fixed) |
| Elevation | `references/elevation.md` | 3 shadow tokens (4dp, 8dp, Inverted) |

---

## Typography

**Single font:** Roboto — weights 400 (Regular) and 600 (SemiBold) only.
**Constants:** `letter-spacing: 0.2px` · `line-height: 1.4` (exception: Global-XL → 1.3)

| Token       | font-size |
|-------------|-----------|
| Global-XXXS | 10px      |
| Global-XXS  | 12px      |
| Global-XS   | 14px      |
| Global-S    | 16px      |
| Global-M    | 18px      |
| Global-L    | 24px      |
| Global-XL   | 32px      |
| Global-XXL  | 36px      |

SemiBold (600) is applied on top of any token to establish hierarchy.

---

## Key Semantic Colors

```css
--text/neutral/default:      #303036   /* primary text */
--text/neutral/lighter:      #636271   /* secondary text */
--brand/400:                 #6f93eb   /* brand accent */
--blueprimary/100:           #eff2ff   /* table header background */
--blueprimary/800:           #213478   /* text on blueprimary/100 */
--background/layout/default: #f5f6f8   /* page background */
```

Full palette → `references/colors.md`

---

## Spacing (8px base)

```
2px / 4px / 12px  →  intimately related elements
8px / 16px        →  internal component padding
24px              →  grouping within a section
32px / 40px       →  separation between sections
64px / 72px       →  large blocks
128px             →  maximum page separation
```

Full semantic guide → `references/spacing.md`

---

## Border Radius (by element height)

| Token | Value | Element height |
|-------|-------|----------------|
| S     | 4px   | up to 39px     |
| M     | 8px   | 40–71px        |
| L     | 16px  | 72px+          |

Exception: badges/chips → `border-radius: 999px`

---

## Elevation

| Token    | Usage                                       |
|----------|---------------------------------------------|
| 4dp      | Actionable cards (with a button)            |
| 8dp      | Dropdowns, card hover state                 |
| Inverted | Mobile bottom sheets (emerge from below)    |

Full CSS → `references/elevation.md`

---

## Grid

| Token    | Screen      | Margin | Gutter | Columns |
|----------|-------------|--------|--------|---------|
| S-Fluid  | 0–599px     | 16px   | 16px   | 4       |
| M-Fluid  | 600–839px   | 32px   | 16px   | 8       |
| L-Fluid  | 840–1199px  | 32px   | 16px   | 12      |
| XL-Fluid | 1200+       | 16px   | 24px   | 12      |
| XL-Fixed | 1200+       | Fluid  | 16px   | 12      |

Up to 3 grids can coexist in the same interface. Full CSS → `references/grid.md`

---

## Rules

1. Never hardcode hex or px values when a token exists
2. Roboto only, weights 400 or 600 — no other weights
3. `letter-spacing` is always 0.2px; `line-height` is 1.4 (Global-XL → 1.3)
4. Border radius by element **height** (S / M / L)
5. Only the 3 system shadows (4dp, 8dp, Inverted) — never invent box-shadows
6. When in doubt about a color → load `references/colors.md`

---

## Common Mistakes

| Mistake                            | Fix                                             |
|------------------------------------|-------------------------------------------------|
| `font-weight: 700` or `300`       | Only 400 and 600 exist in the system            |
| `border-radius` chosen visually    | Choose by element height (S/M/L)                |
| Invented `box-shadow`             | Only the 3 elevation tokens (4dp, 8dp, Inv.)    |
| Hardcoded hex without token       | Find the semantic token in references/colors     |
| `line-height` other than 1.4      | Only Global-XL uses 1.3 — everything else is 1.4 |
| `letter-spacing` omitted          | Always 0.2px on all tokens                       |
