# Design Tokens — Cognitive Core UI

All components and patterns depend on these tokens. Load this file first before any other reference.

---

## Typography strategy

Default to **system fonts** first. Add Google Fonts only when the agent decides the stack, product context, and delivery constraints justify them.

**System font stack (default — works everywhere, no CDN needed):**
```css
--font-display: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", system-ui, sans-serif;
--font-body:    -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", system-ui, sans-serif;
--font-mono:    ui-monospace, "SFMono-Regular", Menlo, Consolas, monospace;
```

**Google Fonts (optional — use when building the Mentes Sintéticas aesthetic explicitly):**
```css
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500;600&display=swap');

--font-display: 'Inter', system-ui, sans-serif;
--font-body:    'Inter', system-ui, sans-serif;
--font-mono:    'JetBrains Mono', 'Fira Code', ui-monospace, monospace;
```

---

## Complete CSS Variables

Include this full block in every project.

```css
/* ═══════════════════════════════════════════
   SHARED TOKENS — in :root (see Token Scope Guardrails)
   ═══════════════════════════════════════════ */
:root {
  /* Typography (set defaults here; override with Google Fonts if needed) */
  --font-display: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", system-ui, sans-serif;
  --font-body:    -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", system-ui, sans-serif;
  --font-mono:    ui-monospace, "SFMono-Regular", Menlo, Consolas, monospace;

  /* Font Sizes */
  --text-xs:   0.72rem;   /* 11.5px — micro labels, mono uppercase */
  --text-sm:   0.82rem;   /* 13px */
  --text-base: 0.95rem;   /* 15px — default body */
  --text-lg:   1rem;      /* 16px */
  --text-xl:   1.25rem;   /* 20px */
  --text-2xl:  1.6rem;    /* 25.6px */
  --text-3xl:  2.2rem;    /* 35px */
  --text-4xl:  3rem;      /* 48px — stat numbers */
  --text-5xl:  4rem;      /* 64px — hero headings */

  /* Font Weights */
  --weight-light:    300;
  --weight-normal:   400;
  --weight-medium:   500;
  --weight-semibold: 600;
  --weight-bold:     700;
  --weight-black:    800;

  /* Letter Spacing */
  --tracking-tight:   -0.025em;
  --tracking-normal:  0;
  --tracking-wide:    0.04em;
  --tracking-wider:   0.08em;
  --tracking-widest:  0.12em;

  /* Line Height */
  --leading-none:    1;
  --leading-tight:   1.08;
  --leading-snug:    1.24;
  --leading-normal:  1.5;
  --leading-relaxed: 1.68;

  /* Spacing */
  --space-0:  0;
  --space-1:  0.25rem;
  --space-2:  0.5rem;
  --space-3:  0.75rem;
  --space-4:  1rem;
  --space-5:  1.25rem;
  --space-6:  1.5rem;
  --space-8:  2rem;
  --space-10: 2.5rem;
  --space-12: 3rem;
  --space-16: 4rem;
  --space-20: 5rem;
  --space-24: 6rem;

  /* Border Radius */
  --radius-sm:   0.375rem;
  --radius-md:   0.625rem;
  --radius-lg:   0.875rem;
  --radius-xl:   1.125rem;
  --radius-2xl:  1.5rem;
  --radius-full: 9999px;

  /* Interactive element heights */
  --control-xs: 1.75rem;
  --control-sm: 2rem;
  --control-md: 2.5rem;
  --control-lg: 3rem;

  /* Transitions */
  --transition-fast:  140ms ease;
  --transition-base:  200ms ease;
  --transition-slow:  300ms ease;
  --transition-theme: background 240ms ease, color 240ms ease, border-color 240ms ease, box-shadow 240ms ease;

  /* Shared interaction tokens */
  --focus-ring-width: 2px;
  --focus-ring-offset: 2px;

  /* Z-index */
  --z-base:     0;
  --z-elevated: 10;
  --z-dropdown: 20;
  --z-sticky:   30;
  --z-modal:    50;
  --z-toast:    60;
}

/* ═══════════════════════════════════════════
   DARK THEME
   ═══════════════════════════════════════════ */
[data-theme="dark"] {
  /* Backgrounds — layered navy depth */
  --bg-void:     #060910;
  --bg-base:     #0b0f15;
  --bg-surface:  #111827;
  --bg-elevated: #172133;
  --bg-overlay:  #223148;

  /* Borders */
  --border-subtle:        rgba(255, 255, 255, 0.06);
  --border-medium:        rgba(255, 255, 255, 0.10);
  --border-strong:        rgba(255, 255, 255, 0.16);
  --border-accent:        rgba(34, 211, 238, 0.26);
  --border-accent-strong: rgba(34, 211, 238, 0.50);

  /* Text */
  --text-heading:   #f7fafc;
  --text-primary:   #dbe4ee;
  --text-secondary: #95a3b8;
  --text-muted:     #6b778c;
  --text-accent:    #34d8ff;
  --text-inverse:   #081018;

  /* Accent — teal/cyan */
  --accent:        #22d3ee;
  --accent-strong: #09bfe0;
  --accent-dim:    rgba(34, 211, 238, 0.16);
  --accent-glow:   rgba(34, 211, 238, 0.12);
  --accent-subtle: rgba(34, 211, 238, 0.08);
  --accent-hover:  #06b6d4;
  --accent-contrast: #07131a;

  /* Semantic */
  --semantic-green:      #16c784;
  --semantic-green-dim:  rgba(22, 199, 132, 0.18);
  --semantic-amber:      #f4a91d;
  --semantic-amber-dim:  rgba(244, 169, 29, 0.18);
  --semantic-red:        #ff5a67;
  --semantic-red-dim:    rgba(255, 90, 103, 0.18);
  --semantic-blue:       #59a7ff;
  --semantic-blue-dim:   rgba(89, 167, 255, 0.18);
  --semantic-purple:     #a78bfa;
  --semantic-purple-dim: rgba(167, 139, 250, 0.18);

  /* Shadows */
  --shadow-sm:          0 1px 2px rgba(0, 0, 0, 0.22);
  --shadow-md:          0 8px 24px rgba(0, 0, 0, 0.32);
  --shadow-lg:          0 16px 40px rgba(0, 0, 0, 0.44);
  --shadow-glow:        0 0 0 1px rgba(34, 211, 238, 0.05), 0 10px 28px rgba(3, 12, 22, 0.42);
  --shadow-glow-strong: 0 0 30px rgba(34, 211, 238, 0.20), 0 0 10px rgba(34, 211, 238, 0.10);

  /* Scrollbar */
  --scrollbar-track: #0b0f15;
  --scrollbar-thumb: #172133;
}

/* ═══════════════════════════════════════════
   LIGHT THEME
   ═══════════════════════════════════════════ */
[data-theme="light"] {
  /* Backgrounds — layered white/gray */
  --bg-void:     #edf3f9;
  --bg-base:     #f5f8fc;
  --bg-surface:  #ffffff;
  --bg-elevated: #eaf0f6;
  --bg-overlay:  #dde8f1;

  /* Borders */
  --border-subtle:        rgba(12, 23, 40, 0.07);
  --border-medium:        rgba(12, 23, 40, 0.12);
  --border-strong:        rgba(12, 23, 40, 0.18);
  --border-accent:        rgba(14, 165, 233, 0.22);
  --border-accent-strong: rgba(14, 165, 233, 0.42);

  /* Text */
  --text-heading:   #0f172a;
  --text-primary:   #334155;
  --text-secondary: #61748a;
  --text-muted:     #8b9aae;
  --text-accent:    #0f766e;
  --text-inverse:   #f8fbff;

  /* Accent — deeper teal for AA-friendly buttons and links */
  --accent:        #0f766e;
  --accent-strong: #115e59;
  --accent-dim:    rgba(15, 118, 110, 0.10);
  --accent-glow:   rgba(15, 118, 110, 0.08);
  --accent-subtle: rgba(15, 118, 110, 0.05);
  --accent-hover:  #115e59;
  --accent-contrast: #f8fbff;

  /* Semantic */
  --semantic-green:      #059669;
  --semantic-green-dim:  rgba(5, 150, 105, 0.10);
  --semantic-amber:      #d97706;
  --semantic-amber-dim:  rgba(217, 119, 6, 0.10);
  --semantic-red:        #dc2626;
  --semantic-red-dim:    rgba(220, 38, 38, 0.10);
  --semantic-blue:       #2563eb;
  --semantic-blue-dim:   rgba(37, 99, 235, 0.10);
  --semantic-purple:     #7c3aed;
  --semantic-purple-dim: rgba(124, 58, 237, 0.10);

  /* Shadows */
  --shadow-sm:          0 1px 2px rgba(15, 23, 42, 0.04);
  --shadow-md:          0 12px 30px rgba(15, 23, 42, 0.08);
  --shadow-lg:          0 20px 48px rgba(15, 23, 42, 0.12);
  --shadow-glow:        0 0 0 1px rgba(14, 165, 233, 0.04), 0 14px 28px rgba(15, 23, 42, 0.06);
  --shadow-glow-strong: 0 4px 16px rgba(14, 165, 233, 0.12);

  /* Scrollbar */
  --scrollbar-track: #f5f8fc;
  --scrollbar-thumb: #cbd5e1;
}

/* ═══════════════════════════════════════════
   BASE STYLES
   ═══════════════════════════════════════════ */
body {
  font-family: var(--font-body);
  margin: 0;
  -webkit-font-smoothing: antialiased;
}

[data-theme] {
  color: var(--text-primary);
  background: var(--bg-base);
  transition: var(--transition-theme);
}

*, *::before, *::after { box-sizing: border-box; }

/* Custom scrollbar */
::-webkit-scrollbar { width: 6px; height: 6px; }
::-webkit-scrollbar-track { background: var(--scrollbar-track); }
::-webkit-scrollbar-thumb { background: var(--scrollbar-thumb); border-radius: var(--radius-full); }
::-webkit-scrollbar-thumb:hover { background: var(--border-medium); }
```

---

## Token Scope Guardrails

**This is the most critical implementation rule.** Font and typography bugs almost always come from scope violations.

**Rule 1:** Put typography, spacing, radius, and transition tokens in `:root` — not in `[data-theme]`.

**Rule 2:** Put theme-specific colors and surface values on the theme owner (`[data-theme]`).

**Rule 3:** If `body` consumes `var(--font-body)`, that variable must exist in `:root` or in a scope `body` inherits.

**Rule 4:** If the theme lives on a shell container instead of `body`, either keep typography in `:root`, or apply `font-family` directly on that shell.

**Safe — typography in :root:**
```css
:root { --font-body: system-ui, sans-serif; }
body { font-family: var(--font-body); }
.shell[data-theme="dark"] { --bg-base: #0b0f15; }
```

**Safe — theme on shell, font applied there:**
```css
:root { --font-body: system-ui, sans-serif; }
.shell[data-theme="dark"] { --bg-base: #0b0f15; font-family: var(--font-body); }
```

---

## Interaction Guardrails

These rules exist to stop the most common quality failures: illegible hover states, washed-out light theme buttons, and decorative overload.

1. Primary actions on accent backgrounds must use `var(--accent-contrast)`, not `var(--bg-base)`.
2. Hover states may change brightness, but must preserve or improve text contrast.
3. Focus styles must be visible on both themes. Minimum: `outline: var(--focus-ring-width) solid var(--accent)` with `outline-offset: var(--focus-ring-offset)`.
4. If a control background becomes lighter on hover, its foreground must be re-evaluated. Do not assume the base text color still works.
5. Favor one accent family and two neutral text tiers over adding extra decorative colors.

**Unsafe (font breaks silently):**
```css
/* WRONG */
.shell[data-theme="dark"] { --font-body: 'Inter', sans-serif; } /* defined on child */
body { font-family: var(--font-body); } /* body can't inherit from .shell */
```

---

## Typography Patterns

### Mono Label — the system's most distinctive element

```css
font-family: var(--font-mono);
font-size: var(--text-xs);
font-weight: var(--weight-semibold);
letter-spacing: var(--tracking-widest);
text-transform: uppercase;
color: var(--text-secondary);
```

Use for: section headers, stat labels, nav labels, badge text, timestamps, IDs.
**Do not overuse** — if everything is uppercase mono, nothing has emphasis.

### Display Heading

```css
font-family: var(--font-display);
font-weight: var(--weight-bold);
letter-spacing: var(--tracking-tight);
line-height: var(--leading-tight);
color: var(--text-heading);
```

Sizes: `--text-5xl` (hero) · `--text-3xl` (page title) · `--text-2xl` (section) · `--text-xl` (card title).

### Stat Number

```css
font-family: var(--font-display);
font-size: var(--text-4xl);
font-weight: var(--weight-bold);
line-height: var(--leading-none);
color: var(--text-heading);
font-variant-numeric: tabular-nums;
```

Pair with suffix: `font-size: var(--text-lg); color: var(--text-muted)`.

### Body Text

```css
font-family: var(--font-body);
font-size: var(--text-base);
font-weight: var(--weight-normal);
line-height: var(--leading-relaxed);
color: var(--text-primary);
```

### Primary Action

```css
background: var(--accent);
color: var(--accent-contrast);
border: none;
font-family: var(--font-body);
font-size: var(--text-sm);
font-weight: var(--weight-semibold);
letter-spacing: var(--tracking-wide);
```

Use mono only for short command-like labels. Default buttons should stay in the body family for better readability.

### Numbers in tables and lists

```css
font-variant-numeric: tabular-nums;
font-feature-settings: "tnum" 1;
```

---

## Alignment Rules

1. Keep text on a shared rhythm — headings, helpers, and numbers should align to the same left edge inside a card.
2. Avoid micro-copy smaller than `--text-xs` unless it is true metadata.
3. In dashboards: one card = one dominant metric or one dominant action. Do not stack equal-priority text blocks.
4. Above the fold: prefer 1 primary content block + 1 support block + 1 contextual rail — not a wall of equal cards.
5. Mono labels are separators, not decoration. If everything is uppercase mono, nothing is important.
6. In brownfield: fix cascade and token-scope errors before changing colors, layout, or density.
7. Interactive controls must align on shared heights (`--control-sm`, `--control-md`, `--control-lg`) and shared text baselines.

---

## Mode Guidance

### Dashboard / Admin
- Dark theme is often the best default.
- Dense, compact spacing — tighter headings, shorter line-height, less breathing room than marketing.
- Use mono labels selectively for status, timestamps, identifiers, section rails.
- Favor grouped blocks over large card matrices above the fold.

### Landing Page / Website
- Much more vertical breathing room (use `--space-16` to `--space-24` between sections).
- Prefer display + body pairings over mono-heavy layouts.
- Accent glow sparingly — trust typography and section rhythm.
- One message per section. No dashboard chrome (sidebars, status feeds, dense badges).

---

## Admin / Operational Compact Density

Use these values whenever building settings pages, admin panels, config screens, entity lists, or any dense operational UI. These replace the more generous defaults in those contexts.

### Card container scale

| Level | Use | Padding | Border Radius |
|---|---|---|---|
| L1 — page card | top-level section card | `var(--space-4)` (16px) | `22px` |
| L2 — nested card | card inside a card | `var(--space-3)` (12px) | `18px` |
| L3 — inset block | info block, disclosure body | `10px` | `14px` |

Between L1 cards: `gap: var(--space-3)` — not `--space-4` or `--space-6`.

### Card heading inside a panel

```
Eyebrow  : text-[0.68rem] uppercase tracking-[0.28em] color: var(--text-muted)
Title    : text-base (15px) font-semibold  ← never text-xl or text-2xl inside a card
Meta     : font-mono text-[0.62rem] color: var(--text-muted) truncate  ← path, ID, single-line
```

**Do not write verbose description paragraphs inside admin cards.** Replace with: mono path text, status badges, or a single collapsed `<details>` block.

### Form controls — admin context

```
Input    : px-3 py-2  text-xs  border-radius: var(--radius-md)  (height ~32px)
Select   : px-3 py-2  text-xs  border-radius: var(--radius-md)
Label    : text-[0.65rem]  mb: 2px (mb-0.5)
Button   : px-3 py-2  text-xs  border-radius: var(--radius-md)
```

These override the default `px-4 py-3 text-sm rounded-2xl` — that scale is for consumer/marketing UI, not admin density.

### List / row items

```
Row padding  : py-2 (8px top/bottom)  — not py-3 or py-4
Row gap      : gap-2.5 (10px)
Provider dot : h-2 w-2  — not h-2.5 w-2.5
Name column  : w-24 text-xs font-medium  — not w-28 text-sm
```

### Badges / chips — compact

```
Status badge : px-2 py-0.5  text-[0.6rem]  rounded-full
Tag badge    : px-2 py-0.5  text-[0.58rem]  rounded-full
```

Never use `px-3 py-1 text-xs` for inline status chips — that scale is for navigation and page-level badges.

### Entity grid (projects, providers, squads)

Never full-width stack same-type entities. Use:

```css
grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
/* or explicit: sm:grid-cols-2 lg:grid-cols-3 */
gap: var(--space-3);
```

### Modal pattern for add / edit forms

Entity add/edit forms belong in a modal, not inline expansion (accordion/RevealPanel):

```
Modal max-width : 448px (28rem)
Modal padding   : var(--space-5)
Overlay         : bg-black/50 backdrop-blur-sm
Border radius   : var(--radius-xl) — 22px
Max height      : 90vh  overflow-y: auto
```

### Disclosure / collapse pattern

Secondary tools (sync assistant, cloud connect, advanced config) go behind `<details>`:

```
Summary row : flex items-center justify-between px-3 py-2.5
              label (text-xs) + status badge (left) + action button (right)
Body        : border-t px-3 pb-3 pt-2
```

Never keep secondary tools always visible — they crowd the primary content.

### Anti-patterns in admin/operational UI

- `p-6 rounded-[28px]` on inner section cards — too large, use L1/L2/L3 scale above
- `text-xl` or `text-2xl` headings inside settings/admin cards
- Verbose description paragraphs (`text-sm leading-7`) in every card — remove them
- Full-width stacked cards for entity lists (projects, providers) — use the grid
- Inline accordion/RevealPanel for add/edit forms — use a modal
- `px-4 py-3 text-sm` for inputs and buttons in dense admin context

---

## Non-Negotiable Rules

1. Use the token system — never freestyle random hex values.
2. Keep at most **three surface levels** visible in the same viewport.
3. Teal/cyan is the **only accent** — never change it.
4. Do not default to Google Fonts when system stacks deliver the right tone.
5. Do not use mono labels as the main reading experience.
6. Keep **one obvious focal block** per viewport.
7. Fix token scope and cascade bugs before redesigning colors or layout.
8. In admin/operational UI, apply the **Compact Density** scale — never carry consumer/marketing spacing into dense panels.
9. Validate contrast and hover/focus parity before considering a screen finished.
