# Oxios Design System
> shadcn/ui + Tailwind CSS v4, Zinc base, OKLCH color space, New York style.
> Auto-generated by Design Farmer. Phase 8 reviewers reference this file for calibration.
## Config
```yaml
packageManager: bun
framework: vite-react
isMonorepo: false
systemPath: "/Volumes/MERCURY/PROJECTS/oxios/web"
designSystemPackage: "oxios-web"
componentScope: full
headlessLibrary: ark
themeStrategy: light-dark
themeLibrary: custom
accessibilityLevel: apca
radiusTone: rounded
targetPlatforms: web
designMaturity: emerging
maturityScore: 5
```
---
## 1. Visual Theme & Atmosphere
Oxios is an **Agent Operating System** — a technical, professional dashboard for managing AI agent lifecycles. The visual language reflects this: quiet confidence, information density, and calm authority. Zinc-neutral surfaces let agent status colors (emerald running, amber pending, red failed) speak without competition.
The design avoids decorative elements. Depth comes from shadow and surface elevation, not gradients or illustration. Typography uses weight and size for hierarchy, never color variety. The result is a system that feels like a well-organized control room — every pixel has a purpose.
Dark mode is a first-class citizen. OKLCH lightness inversion preserves the same perceptual contrast relationship between surface levels, so the spatial hierarchy reads identically in both modes. Agent status colors shift to their lighter variants (emerald-400, amber-400, red-400) to maintain visibility against dark backgrounds.
**Key Characteristics:**
- Background base: `oklch(1 0 0)` (light) / `oklch(0.141 0.005 285.823)` (dark)
- Primary font: Inter with system fallback
- Brand accent: Zinc 900 (light) / White (dark) — intentionally neutral
- Border style: `oklch(0.92 0.004 286.32)` — subtle, structural
---
## 2. Color Palette & Roles
### Background Surfaces
- **Background** (`oklch(1 0 0)` → `oklch(0.141 0.005 285.823)`): Main page surface
- **Card** (`oklch(1 0 0)` → `oklch(0.178 0.008 285.89)`): Elevated cards, dialogs
- **Muted** (`oklch(0.967 0.001 286.375)` → `oklch(0.274 0.006 286.033)`): Subtle fills, hover states
- **Popover** (`oklch(1 0 0)` → `oklch(0.178 0.008 285.89)`): Dropdowns, tooltips
### Text & Content
- **Foreground** (`oklch(0.141 0.005 285.823)` → `oklch(0.985 0 0)`): Primary text, headings
- **Muted Foreground** (`oklch(0.552 0.016 285.938)` → `oklch(0.705 0.015 286.067)`): Captions, metadata
### Interactive
- **Primary** (`oklch(0.21 0.006 285.885)` → `oklch(0.985 0 0)`): CTAs, selected states
- **Secondary** (`oklch(0.967 0.001 286.375)` → `oklch(0.274 0.006 286.033)`): Supporting fills
- **Accent** (`oklch(0.967 0.001 286.375)` → `oklch(0.274 0.006 286.033)`): Hover backgrounds
- **Destructive** (`oklch(0.577 0.245 27.325)` → `oklch(0.704 0.191 22.216)`): Delete, kill, error
### Status
- **Success** (`oklch(0.596 0.145 163)` → `oklch(0.723 0.219 149.579)`): Running, Active, Approved
- **Warning** (`oklch(0.669 0.162 70)` → `oklch(0.769 0.188 70.08)`): Idle, Pending
- **Error** (`oklch(0.577 0.245 27.325)` → `oklch(0.704 0.191 22.216)`): Stopped, Failed, Rejected
- **Info** (`oklch(0.623 0.214 259.815)` → `oklch(0.685 0.196 259)`): Informational
### Status Backgrounds
- **Success Subtle** (`oklch(0.97 0.014 163)` → `oklch(0.18 0.03 163)`): Panel backgrounds
- **Warning Subtle** (`oklch(0.97 0.014 70)` → `oklch(0.18 0.03 70)`): Panel backgrounds
- **Error Subtle** (`oklch(0.97 0.014 27)` → `oklch(0.18 0.03 27)`): Panel backgrounds
- **Info Subtle** (`oklch(0.97 0.014 259)` → `oklch(0.18 0.03 259)`): Panel backgrounds
### Borders & Dividers
- **Border** (`oklch(0.92 0.004 286.32)` → `oklch(1 0 0 / 10%)`): Standard separators
- **Input** (`oklch(0.92 0.004 286.32)` → `oklch(1 0 0 / 15%)`): Input borders
- **Ring** (`oklch(0.708 0 0)` → `oklch(0.552 0.016 285.938)`): Focus rings
### 11-Step Primitive Palettes
Available in `src/design-system/tokens/index.ts` as `primitiveColors`:
| Zinc | 286° | Neutral base, all surfaces and text |
| Red | 27° | Error, destructive actions |
| Emerald | 163° | Success, positive states |
| Amber | 70° | Warning, caution states |
| Blue | 259° | Info, accent highlights |
| Violet | 303° | Special highlights (dream, memory) |
---
## 3. Typography Rules
### Font Family
- **Primary**: `'Geist', system-ui, -apple-system, sans-serif`
- **Monospace**: `'Geist Mono', ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, monospace`
### Hierarchy
| Display | 36px | text-4xl | 700 | — |
| Heading 1 | 30px | text-3xl | 600 | — |
| Heading 2 | 24px | text-2xl | 600 | Page titles (8 uses) |
| Heading 3 | 20px | text-xl | 600 | Section headings (1 use) |
| Heading 4 | 18px | text-lg | 600 | Card titles (14 uses) |
| Body | 16px | text-base | 400 | Primary body (14 uses) |
| Small | 14px | text-sm | 400 | Secondary text (213 uses) |
| Extra Small | 12px | text-xs | 400 | Labels, hints (265 uses) |
| Micro | 10px | text-2xs | 500 | Badges, metadata only |
### Typography Principles
Weight creates hierarchy, not color. `font-medium` (500) is the workhorse — used 130 times for labels, badges, and inline emphasis. `font-semibold` (600) marks headings and section titles. `font-bold` (700) is reserved for maximum emphasis. Letter-spacing (`tracking-wider`, 19 uses) is used exclusively for uppercase micro labels and status badges.
---
## 4. Component Stylings
### Buttons
**Primary Button** — `variant="default"`
- Background: `var(--primary)` (Zinc 900 light / White dark)
- Text: `var(--primary-foreground)`
- Border-radius: `var(--radius-md)` (8px)
- Hover: `opacity: 0.9`
- Disabled: `opacity: 50%`
**Secondary Button** — `variant="secondary"`
- Background: `var(--secondary)`
- Text: `var(--secondary-foreground)`
- Hover: `background: var(--accent)`
**Ghost Button** — `variant="ghost"`
- Background: transparent
- Text: `var(--foreground)`
- Hover background: `var(--accent)`
**Outline Button** — `variant="outline"`
- Background: transparent
- Border: `1px solid var(--border)`
- Text: `var(--foreground)`
**Destructive Button** — `variant="destructive"`
- Background: `var(--destructive)`
- Text: `var(--destructive-foreground)`
**Size Scale:**
| Default | `h-9 px-4 py-2` | Standard actions |
| SM | `h-8 px-3 text-xs` | Inline, toolbar |
| LG | `h-10 px-6` | Primary CTAs |
| Icon | `h-9 w-9` | Icon-only buttons |
### Inputs & Forms
**Text Input** (normal state)
- Background: `var(--background)`
- Border: `1px solid var(--input)`
- Border-radius: `var(--radius-md)` (8px)
- Padding: `px-3 py-1` (sm) or `px-3 py-2` (default)
- Focus: ring-1 ring-ring
- Error: `var(--error)`
- Placeholder: `var(--muted-foreground)`
### Cards & Containers
**Outlined Card**
- Background: `var(--card)`
- Text: `var(--card-foreground)`
- Border: `1px solid var(--border)`
- Border-radius: `var(--radius-lg)` (10px)
Card sub-components: CardHeader, CardTitle (semibold), CardDescription (muted), CardContent, CardFooter.
### Badges
| default | `var(--primary)` | `var(--primary-foreground)` |
| secondary | `var(--secondary)` | `var(--secondary-foreground)` |
| outline | transparent | `var(--foreground)` |
| destructive | `var(--destructive)` | `var(--destructive-foreground)` |
| success | `var(--success-subtle)` | `var(--success)` |
| warning | `var(--warning-subtle)` | `var(--warning)` |
| error | `var(--error-subtle)` | `var(--error)` |
Shape: `rounded-full` (pill)
### Radius Mapping
| Button, Input, Select | 8px | `--radius-md` |
| Card, Dialog | 10px | `--radius-lg` |
| Popover, Tooltip | 14px | `--radius-xl` |
| Badge | 9999px | full |
---
## 5. Layout Principles
### Spacing System
- Base unit: `4px` (Tailwind default)
- Most used: `gap-2` (8px, 159 uses), `p-2` (8px, 184 uses)
- Scale: 2, 4, 6, 8, 10, 12, 16, 20, 24, 32, 40, 48, 64 px
### Sidebar Primitives (Shared Design System)
All three sidebar modes (Console, Knowledge, Chat) use shared style primitives:
```
itemBase = "flex items-center w-full text-sm py-2 px-2 gap-3 rounded-md transition-colors"
itemDense = "flex items-center w-full text-xs py-1.5 px-2 gap-2 rounded-sm transition-colors"
itemActive = "bg-accent text-accent-foreground font-medium"
itemInactive = "text-muted-foreground hover:text-foreground hover:bg-accent/50"
itemCollapsed = "flex items-center justify-center w-9 h-9 rounded-md"
sectionHeader = "px-2 py-1.5 text-[10px] font-medium tracking-wider text-muted-foreground/60 uppercase"
sectionGap = "mt-2"
sectionSep = "my-2 border-t border-border/50"
```
### Breakpoints
| sm | 640px | 34 uses — tablet adjustments |
| md | 768px | 14 uses — layout shifts |
| lg | 1024px | 23 uses — sidebar collapse |
### Whitespace Philosophy
Density is valued — this is an agent OS dashboard, not a marketing site. `gap-2` (8px) is the default rhythm. Negative space creates hierarchy at section level (`gap-4` = 16px between sections) rather than within components.
---
## 6. Depth & Elevation
| Flat | No shadow | Page background, table rows |
| SM | `shadow-sm` | Cards, inputs |
| MD | `shadow-md` | Dropdowns, popovers |
| LG | `shadow-lg` | Modals, drawers |
| XL | `shadow-xl` | Spotlight dialogs |
| Focus | `ring-1 ring-ring` | Keyboard focus ring |
Shadow values use `oklch(0 0 0 / alpha)` for dark-mode consistency.
---
## 7. Do's and Don'ts
### Do
- Use semantic tokens (`text-muted-foreground`, not `text-zinc-500`) in components
- Use `bg-success` / `text-warning` for status — not `bg-emerald-500` / `text-amber-700`
- Use CSS `:hover` and `:active` for interactive states — not JS event handlers
- Use the shared sidebar primitives (`itemBase`, `itemActive`, etc.) for all sidebar modes
- Use `oklch()` for all color values in token definitions
- Verify APCA contrast Lc ≥ 60 for text/surface pairs
### Don't
- Don't hardcode color values (`#10b981`, `rgb(16 185 129)`) in components — use semantic tokens
- Don't use direct Tailwind color classes (`bg-emerald-500`, `text-blue-800`) — use status tokens
- Don't use CSS `border` on interactive elements that change state — prefer `box-shadow`
- Don't use inline `style={{}}` for colors — use Tailwind classes with semantic tokens
- Don't use JS state (onMouseEnter/onMouseLeave) for hover/active — use CSS :hover/:active
---
## 8. Responsive Behavior
### Breakpoints
| Mobile | < 768px | Sidebar becomes overlay, hamburger toggle, stacked cards |
| Tablet | 768–1024px | Sidebar collapsible, two-column layout |
| Desktop | > 1024px | Full sidebar, three zones (sidebar + main + panel) |
### Touch Targets
- Minimum tap target: 44×44px
- Sidebar items: `py-2` (8px vertical padding) with `gap-3` (12px)
---
## 9. Decisions Log
- `2026-06-07` — Initial DESIGN.md written with shadcn/ui + Tailwind v4 + OKLCH foundation
- `2026-06-07` — Sidebar design primitives unified across Console/Knowledge/Chat modes
- `2026-06-07` — Mode tabs (Console/Knowledge/Chat) promoted to header, sidebar stays mode-adaptive
- `2026-06-07` — Design Farmer Phase 4.5: full DESIGN.md expansion with token hierarchy, component stylings, status color system, shared sidebar primitives
- `2026-06-07` — Config: headless=ark, scope=full, theme=light-dark/custom, a11y=apca, radius=rounded
---
## 10. Agent Prompt Guide
### Quick Token Reference
- Primary action: `bg-primary text-primary-foreground`
- Page background: `bg-background text-foreground`
- Card: `bg-card text-card-foreground border border-border`
- Muted text: `text-muted-foreground`
- Status success: `text-success bg-success-subtle border-success-subtle-border`
- Status warning: `text-warning bg-warning-subtle border-warning-subtle-border`
- Status error: `text-error bg-error-subtle border-error-subtle-border`
- Focus ring: `ring-1 ring-ring`
- Sidebar item: Use shared primitives (`itemBase`, `itemActive`, `itemInactive`)
### File Locations
| `src/index.css` | Theme tokens, OKLCH variables, `@theme inline` |
| `src/design-system/tokens/index.ts` | TypeScript token definitions |
| `src/design-system/index.ts` | Public API barrel export |
| `src/components/ui/` | shadcn/ui base components |
| `src/components/layout/` | Layout components (sidebar, header, mode tabs) |
| `src/lib/utils.ts` | `cn()` helper |
| `components.json` | shadcn/ui configuration |
### Adding Components
```bash
bunx shadcn@latest add [component-name]
```
### Iteration Guide
1. Always reference semantic tokens, never raw color values
2. When adding status-colored UI, use `text-success`/`bg-success-subtle` — not `text-emerald-500`
3. Match border approach: `border-border` for structural, `ring` for interactive focus
4. Test hover/focus/active/disabled states in both light and dark themes
5. Use shared sidebar primitives for any new sidebar content