Olive Design System

Olive is a Svelte component library and design system. It provides the visual language, design tokens, and component primitives for building professional, human-scale software tools.

The Character of Olive

Olive has a specific character — a way of feeling when you use it. It is not neutral. It is not generic. Every decision in this system is in service of that character.

Calm precision. The interface should feel like a well-organized workbench: everything in its place, nothing extraneous, the right tool within reach. There is no decoration for decoration's sake. Whitespace is not empty — it is the breathing room that lets content speak clearly. When the screen is calm, the user can focus on the work, not the interface.

Warmth without whimsy. Professional tools can have a soul. The color is a soft yellow-green — the color of a garden, of something grown. It does not scream. It does not demand attention. But it is unmistakably alive, and it makes the interface feel like something made by people who care. Empty states are friendly. Confirmations are human. Nothing is cold or corporate.

Trust through honesty. Olive is used to build tools that handle important things. The UI must communicate reliability. That means no layout shifts. No misleading affordances. No animation that obscures rather than clarifies. Numbers are formatted precisely. Errors say exactly what happened. Timestamps are readable. The system respects the user's intelligence and treats them as a professional.

Invisible infrastructure. The best UI moment is when the user stops thinking about the interface and thinks only about their work. Chrome — navbars, cards, borders, toolbars — is scaffolding. It should be there when needed and recede when not. Content is the primary element. Structure serves it.

Motion

Motion in Olive is purposeful. Every transition answers the question: "what changed, and where did it go?"

Animations communicate state, not personality. They orient the user — a panel slides in from the side so you know where it came from. A dialog fades up from center so you know it's floating above the page. A row highlights for 150ms so you know it was just updated.

Motion is never decorative. Nothing spins for the sake of spinning. Nothing bounces. Nothing draws attention to itself.

Timing

Duration	Usage
`100ms`	Micro-feedback: button press, checkbox tick
`150ms`	Hover states, focus rings, badge color changes
`200ms`	Component appear/disappear (toast, tooltip, dropdown)
`250ms`	Panel slides, sheet entrances, modal fade-up
`350ms`	Page-level transitions, large layout changes

Easing:

Entering elements: cubic-bezier(0.16, 1, 0.3, 1) — fast start, smooth landing
Exiting elements: cubic-bezier(0.4, 0, 1, 1) — quick, clean exit
Position changes: cubic-bezier(0.25, 0.46, 0.45, 0.94) — natural arc

Only ever animate opacity and transform. Never animate height, width, top, left, or any property that triggers layout. Layout animation causes jank. opacity + transform are GPU-composited and always smooth.

Do not show a loading indicator for operations under 200ms. Add a deliberate short delay before revealing any loading state — a spinner that flashes for 80ms is worse than no spinner at all.

Respect prefers-reduced-motion. Wrap all non-essential transitions in a media query check and disable or reduce them.

Typography

Text is the primary material of Olive interfaces. It should be legible at every size, on every screen, in both light and dark modes.

Primary font: Plus Jakarta Sans, weights 400/500/600/700. Its geometry is soft, slightly rounded — professional without being cold. It pairs naturally with the olive-green palette because both have warmth without loudness. Never substitute it. Never add additional font families.

Monospace font: ui-monospace, 'Cascadia Code', 'Source Code Pro', monospace. Used for any content the user would copy-paste: identifiers, connection strings, keys, queries, payloads, schema names. If it came from a system or will go back into one, it is monospaced. This distinction is important — it immediately communicates "this is data" vs "this is UI".

Font smoothing is always on: -webkit-font-smoothing: antialiased. Sub-pixel rendering makes text look heavy on modern displays.

Type Scale

Step	Size	Weight	Usage
`display`	`2xl` (1.5rem)	`semibold`	Page titles. One per page.
`title`	`lg` (1.125rem)	`semibold`	Card titles, section headers
`label`	`sm` (0.875rem)	`medium`	Nav items, form labels, column headers
`body`	`sm` (0.875rem)	`normal`	All body text
`caption`	`xs` (0.75rem)	`normal`	Metadata, timestamps, secondary info
`micro`	`xs` (0.75rem) + uppercase + tracking-wide	`medium`	Section labels, tiny category tags
`code`	`sm` (0.875rem)	`normal`	Inline code, monospaced content

Typography Rules

Use 2–3 weights per page maximum (400, 500, 600). More than three weights creates visual noise.
Secondary information lives at muted-foreground. It should be clearly subordinate, readable, but not competing.
Never use colored text for emphasis in body copy. Use weight (font-medium, font-semibold) instead. Reserve colored text for interactive elements and status indicators.
ALL CAPS only for micro labels. Never for headings or action labels.
Keep descriptions under 15 words.
Line length: max-w-prose (65ch) for reading text. Never let a line of prose stretch edge-to-edge.

Color

The palette is built around a yellow-green primary at hue ~75 — the color of fresh basil, of olives on the branch. It is warm, slightly muted, alive. Every neutral in the system carries a faint echo of this hue (hue 60–70) so the palette feels cohesive and nothing reads as cold or disconnected.

Backgrounds are never pure white or pure black. In light mode the background is a warm off-white. In dark mode it is a deep charcoal with a hint of green. This softness is deliberate — it reduces eye fatigue over long sessions and keeps the primary color from feeling harsh against it.

Semantic Tokens

Token	Light	Dark	Usage
`--background`	`hsl(60 8% 95%)`	`hsl(70 4% 9%)`	Page background
`--foreground`	`hsl(70 8% 15%)`	`hsl(60 8% 85%)`	Primary text
`--card`	`hsl(60 6% 97%)`	`hsl(70 4% 11%)`	Card and panel surfaces
`--card-foreground`	`hsl(70 8% 15%)`	`hsl(60 8% 85%)`	Text on card surfaces
`--muted`	`hsl(65 8% 91%)`	`hsl(70 4% 15%)`	Subtle fills, toggles, pill containers
`--muted-foreground`	`hsl(70 4% 45%)`	`hsl(65 4% 50%)`	Secondary text, metadata, placeholders
`--border`	`hsl(65 6% 86%)`	`hsl(70 4% 18%)`	Borders, dividers
`--primary`	`hsl(75 60% 44%)`	`hsl(75 55% 52%)`	Brand accent — buttons, focus rings, active states
`--primary-foreground`	`hsl(70 8% 15%)`	`hsl(70 4% 9%)`	Text on primary-colored surfaces
`--destructive`	`hsl(0 55% 52%)`	`hsl(0 45% 42%)`	Error, delete actions
`--destructive-foreground`	`hsl(0 0% 98%)`	`hsl(0 0% 98%)`	Text on destructive surfaces
`--ring`	`hsl(75 60% 44%)`	`hsl(75 55% 52%)`	Focus rings (equals `--primary`)
`--radius`	`0.75rem`	—	Global border radius (12px) — cards, panels, inputs
`--radius-button`	`0.4375rem`	—	Button border radius (7px) — tighter than cards for a more grounded feel

Primitive Palette

Not used directly in components. These inform the semantic tokens.

olive-50   hsl(75 60% 96%)
olive-100  hsl(75 60% 90%)
olive-200  hsl(75 58% 78%)
olive-300  hsl(75 56% 66%)
olive-400  hsl(75 58% 54%)
olive-500  hsl(75 60% 44%)   ← primary (light mode)
olive-600  hsl(75 55% 38%)
olive-700  hsl(75 50% 32%)
olive-800  hsl(75 45% 24%)
olive-900  hsl(75 40% 16%)

Semantic Status Colors

Status colors communicate state meaning. They are always used in icon backgrounds and small tints — never as large solid fills, which read as heavy.

Status	Background	Text	Dark text	Usage
Success / Active	`emerald-500/10`	`emerald-600`	`emerald-400`	Active, running, OK
Warning / Paused	`amber-500/10`	`amber-600`	`amber-400`	Paused, pending, attention
Error	`red-500/10`	`red-600`	`red-400`	Errors, failures, deletes
Info	`sky-500/10`	`sky-600`	`sky-400`	Informational
Debug	`purple-500/10`	`purple-600`	`purple-400`	Debug, verbose
Trace	`muted/50`	`muted-foreground`	`muted-foreground`	Trace, lowest priority

In dark mode: increase alpha to /15, shift text to the *-400 step.

Badge Classes

For standalone status pills and type labels, use named CSS classes rather than composed Tailwind utilities. This is required for Tailwind v4 compatibility — composed utilities may not be generated if they don't appear in source.

Class	Meaning
`.badge-active`	Active / running
`.badge-paused`	Paused / pending
`.badge-error`	Error / failed
`.badge-warning`	Warning / degraded
`.badge-info`	Informational
`.badge-debug`	Debug level
`.badge-trace`	Trace level
`.badge-write`	Write operation
`.badge-delete`	Delete operation

Color Rules

Use CSS variable classes (text-primary, bg-muted, bg-primary/10) over hardcoded Tailwind colors for all brand and neutral elements.
The only hardcoded Tailwind color classes acceptable are the semantic status colors above (emerald, amber, red, sky, purple), and only because they are explicitly listed in source.
No gradients. Flat, solid colors only. The primary color is strong enough without them.
No pure black (#000) or pure white (#fff). No cold gray Tailwind classes (gray-*, slate-*, zinc-*). Use the token system.
Icon container backgrounds use a /10 tint. Never a solid fill.

Responsive Design

Olive interfaces must work on any screen — a phone held in one hand, a tablet at a café, a large monitor at a desk, and a display on a wall. This is not an afterthought. The layout system must flow gracefully across all of these.

Breakpoints

Name	Min-width	Typical device
(base)	0px	Small phones
`sm`	640px	Large phones, small tablets
`md`	768px	Tablets
`lg`	1024px	Laptops
`xl`	1280px	Desktops
`2xl`	1536px	Wide monitors, TVs

Layout Strategy

Mobile first. Write base styles for the smallest screen, then add overrides at larger breakpoints. Never start from desktop and work down.
Fluid containers. Page content uses px-4 sm:px-6 lg:px-8 with max-w-7xl. Content breathes at every width.
Responsive grids. Cards and metrics use grids that reflow: grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4. Never hardcode column counts for all screens.
Touch targets. Interactive elements must be at minimum 44×44px on touch screens. Use size="lg" for primary page-level CTAs on mobile. Never rely on hover for important affordances — touch devices have no hover state.
Scrollable on small screens. Horizontal-scrolling containers (overflow-x-auto) for tables and data views. Never clip or crop content — always provide a scroll path.
Large screens. At 2xl, content should not stretch uncomfortably wide. The max-w-7xl constraint applies everywhere. Very wide displays see more breathing room around the content, not wider content.

Component-Level Responsiveness

Navigation collapses to a hamburger/sheet at sm and below.
Dialogs are max-w-[calc(100vw-2rem)] on mobile — always inset from the screen edge.
Sidebars and panels collapse to overlays on small screens.
Stat grids drop to 2 columns on mobile, 4 on desktop.
Tables get horizontal scroll containers on mobile rather than reflowing into cards (data tables need their columns).

Spacing

All spacing comes from the 4px/8px base scale. No arbitrary pixel values.

Step	px	rem	Common use
1	4px	0.25rem	Tight internal gaps, icon margins
2	8px	0.5rem	Icon-to-label gaps, input padding
3	12px	0.75rem	Component internal padding
4	16px	1rem	Standard gap, card padding
6	24px	1.5rem	Section gaps, between form fields
8	32px	2rem	Between distinct content groups
12	48px	3rem	Between page sections
16	64px	4rem	Empty state padding, hero spacing

Generous whitespace is not wasteful. It is what lets the eye move without effort. When in doubt, add more space, not less.

Shadows

Shadows follow the foreground color at low opacity so they respect both light and dark themes.

--shadow-sm:  0 1px 2px hsl(var(--foreground) / 0.06);
--shadow-md:  0 4px 12px hsl(var(--foreground) / 0.08);
--shadow-lg:  0 8px 24px hsl(var(--foreground) / 0.10);

In dark mode: reduce alpha by ~30%. Never use box-shadow with hardcoded colors.

Border Radius

Two radius tokens. Use the right one for the right surface — they serve different visual roles.

Token	Value	Use
`--radius`	`0.75rem` (12px)	Cards, panels, inputs, dropdowns, dialogs — surfaces that contain content
`--radius-button`	`0.4375rem` (7px)	Buttons only — tighter rounding grounds them visually and distinguishes them from containers

Buttons use a smaller radius deliberately. Pill-shaped buttons (high radius) feel consumer and casual. A 7px radius reads as intentional and precise without feeling sharp.

Never use rounded-full on buttons. Avatars and purely decorative circular elements are the only exception.

Light and Dark Mode

Both modes are first-class. Every component must work in light mode, dark mode, and with system preference. This is not optional. Test both before considering a component done.

The CSS custom property system handles the majority of theming automatically. The soft, warm-tinted backgrounds mean dark mode looks like a candlelit room, not a cave. It is easy on the eyes for long sessions.

Implementation:

.dark class on the root element (<html> or <body>)
Store explicit preference in localStorage as "light", "dark", or "system"
Default to "system" — respect prefers-color-scheme unless overridden
The ThemeToggle component cycles through all three states

Watch for these dark mode edge cases:

Semi-transparent backgrounds: bg-card/80 — test that the blurred content behind reads well in both modes
Semantic color tints: bump alpha from /10 to /15 in dark mode (dark:bg-emerald-500/15)
Hardcoded semantic text classes: add dark: variants (text-emerald-600 dark:text-emerald-400)
Glass morphism (backdrop-blur): test that the overlay is legible over both light and dark content behind it

Accessibility

Accessibility is not an enhancement — it is a baseline requirement.

Focus rings: All interactive elements show a visible focus ring using --ring. Never suppress :focus-visible. Keyboard users navigate these interfaces too.
Touch targets: Minimum 44×44px for all interactive elements on touch screens.
Color contrast: All text must meet WCAG AA (4.5:1 for body text, 3:1 for large text). The token system is calibrated to meet this in both modes.
Labels: All form inputs have associated labels. Icon-only buttons always have a aria-label and a visible Tooltip.
Keyboard navigation: Dropdowns, dialogs, and menus are keyboard navigable (arrow keys, Escape, Enter/Space). Never build custom interactive elements without keyboard handling.
Announcements: Toasts and dynamic status changes use aria-live regions so screen readers catch them.
Motion: Respect prefers-reduced-motion. Wrap all transitions in the appropriate media query.

Components

The full Olive component inventory. All components are Svelte primitives exported from the library.

Primitives

The atoms. Everything else composes from these.

Component	Description
`Button`	Primary action surface. Variants: `default`, `outline`, `ghost`, `destructive`, `link`. Sizes: `sm` (28px), `md` (32px), `lg` (40px), `icon` (32px square). Uses `--radius-button` (7px). Default and destructive variants carry a subtle box-shadow for depth — inner top highlight and outer bottom shadow. Active state collapses the shadow inward.
`Input`	Text input. Focus ring, placeholder, disabled, error state.
`Textarea`	Multiline input. Vertical resize.
`Label`	Form field label, associated via `for`.
`Checkbox`	Binary toggle. Supports indeterminate state.
`RadioGroup` + `RadioItem`	Mutually exclusive option group.
`Select` + `SelectItem`	Dropdown selector. Keyboard navigable.
`Switch`	Toggle for boolean settings.
`Slider`	Range input. Single value and range variants.
`Badge`	Status and label pill. Variants map to semantic status colors.
`Avatar`	Image or initials identifier circle.
`Separator`	Horizontal or vertical divider.

Layout

Structure and containment.

Component	Description
`Card` + `CardHeader` + `CardTitle` + `CardDescription` + `CardContent` + `CardFooter`	Standard content container for any distinct entity. Do not nest cards unless there is a clear parent–child relationship.
`Page`	Outermost page wrapper. Applies background, max-width, standard padding.
`PageHeader`	Page title, description, and primary action slot.
`Breadcrumbs`	Hierarchical path navigation.
`Panel`	Fixed or floating side panel. Collapsible.
`Sidebar`	Persistent lateral navigation for section-level structure.
`Resizable`	Draggable split pane, horizontal or vertical.
`ScrollArea`	Custom scrollbar container. Cross-platform consistent.
`Tabs` + `TabList` + `Tab` + `TabPanel`	Section-level tab navigation. State-driven.

Navigation

Component	Description
`Navbar`	Sticky top bar with backdrop blur. Logo, nav links, and actions slots. `h-14` height.
`NavItem`	Single nav link. Icon + label or label only. Active state.
`MobileMenu`	Collapsible navigation panel for small screens. Opens from Navbar.
`ThemeToggle`	Light / dark / system mode toggle. Icon button with smooth icon transition.
`CommandPalette`	Keyboard-driven search and navigation overlay (⌘K). Debounced search, arrow-key navigation, shortcut hints.

Overlay & Feedback

Component	Description
`Dialog` + `DialogHeader` + `DialogContent` + `DialogFooter`	Modal for creation forms and destructive confirmations. Always requires explicit dismiss.
`Sheet`	Sliding panel from screen edge. For detail views and settings drawers.
`Tooltip`	Hover-activated label. Required on all icon-only buttons.
`Popover`	Anchored floating container for inline content.
`DropdownMenu` + `DropdownItem` + `DropdownSeparator`	Contextual action menu. Keyboard navigable.
`ContextMenu`	Right-click menu. Same structure as DropdownMenu.
`Toast`	Transient notification. Fixed bottom center. Auto-dismiss. Variants: default, success, warning, error.
`Alert`	Inline status message. Not dismissible. Variants: info, success, warning, error.
`AlertDialog`	Blocking confirmation for destructive actions. Explicit confirm + cancel required.
`Progress`	Linear progress bar. Determinate and indeterminate. Color maps to semantic status.
`Skeleton`	Loading placeholder. Matches the geometry of the content it replaces.

Data Display

Component	Description
`Table` + `TableHeader` + `TableRow` + `TableCell` + `TableBody`	Tabular data. Sticky headers. Monospace cells for data values. Hover row. Truncation with tooltip.
`DataTable`	Table with sorting, filtering, and pagination built in.
`CodeBlock`	Syntax-highlighted code display. Monospace. Copy-to-clipboard. Language label.
`CodeEditor`	Monaco-based code editor. Dark/light theme sync.
`JsonViewer`	Collapsible JSON tree. Syntax highlighted. Copy individual values.
`KeyValue`	Compact key–value pair display. Monospace values. Copy action.
`MetricCard`	Single metric: icon with tinted background, label, value.
`StatGrid`	Responsive grid of MetricCards.
`EmptyState`	Centered message and CTA for zero-data views. Always includes a primary action.
`Timeline`	Interactive time-range control with play/pause/step playback.
`RelationsGraph`	SVG entity relationship diagram. Node cards, Bezier curve edges, hover labels.
`KanbanBoard` + `KanbanColumn` + `KanbanCard`	Drag-and-drop board. Columns with drop targets. Cards with hover-reveal actions.

Forms

Component	Description
`Form` + `FormField` + `FormLabel` + `FormControl` + `FormMessage`	Form structure with validation state, error messages, and accessible labeling.
`Combobox`	Searchable select with type-ahead. Keyboard navigable.
`MultiSelect`	Tag-style multi-value select.
`DatePicker`	Calendar popover for date selection.
`DateRangePicker`	Calendar popover for start and end date selection.
`FileUpload`	Drop zone and click-to-browse. Drag-over state. File type and size validation.
`SearchInput`	Input with search icon, clear button, and debounce.

Specialized

Purpose-built for technical and infrastructure contexts.

Component	Description
`LogStream`	High-performance virtualized log viewer. Level badges, timestamp formatting, jump-to-bottom, pause-on-scroll.
`SqlEditor`	Monaco editor configured for SQL. Schema-aware autocomplete, execution state.
`SchemaView`	Table schema display: columns, types, constraints, indexes, foreign keys.
`ConnectionString`	Formatted connection string with copy action and optional value masking.
`ApiKeyCard`	Key display with masked value, type badge, copy button, created date, revoke action.
`OperationBadge`	Badge for data operation types (Write, Delete, Update) with semantic color.
`DrawCanvas`	Full-screen canvas. Tool states, pan, zoom, pointer event handling.
`Toolbar`	Fixed vertical or horizontal toolbar. Tool sections with icon buttons and collapse.
`PropertyPanel`	Collapsible properties sidebar. Sections, field rows with labels and controls.

Do's

Layout & Spacing

Generous whitespace. More padding, not less. Space is structure.
max-w-7xl on all page content. Never edge-to-edge on wide screens.
4px/8px spacing scale only. No arbitrary pixel values.
Left-align labels and headings. Right-align numeric data and actions.
Navbar at h-14. Present but not dominant.

Typography

Plus Jakarta Sans everywhere. Do not add fonts.
Monospace for any content that belongs to a system.
font-semibold for titles, font-medium for labels, font-normal for body.
muted-foreground for secondary information.

Color

CSS variable classes for all brand and neutral colors.
Semantic colors only: emerald, amber, red, sky, purple — and only for their defined meanings.
Background tints at /10–/15 alpha. No solid colored areas.

Interactions

Focus rings on every interactive element. Never suppress them.
Glass morphism (bg-card/80 backdrop-blur-xl) only for navbars and overlays.
Confirm destructive actions in an AlertDialog. Never on a single click.

Data

Format numbers: 1.2K, not 1200.
Format timestamps: Mar 11, 2026 or 2 hours ago. Never raw ISO strings.
Skeleton states for loading. Empty states with a message and primary CTA.

Don'ts

No gradients on UI elements. Flat, solid colors.
No new brand colors. --primary is the only accent.
No pure black, pure white, or cold grays. Always use the token system.
No arbitrary spacing or radius values.
No !important.
No nested cards without a clear parent–child relationship.
No center-aligned body text. Center only for auth headings and empty states.
No ALL CAPS except micro-labels.
No browser alert() or confirm().
No hover-only affordances for critical actions.
No auto-close on dialog success. Show the result; let the user dismiss.
No loading spinners for operations under 200ms.
No raw system error strings. Translate them for humans.
No CSS animations on layout-triggering properties.

Tone & Copy

Direct. "Create key" not "Get started by generating your first API key".
Sentence case. "API keys" not "API Keys" (exceptions: proper nouns, acronyms like SQL, JSON, UUID).
Precise vocabulary. "Query", "schema", "index" — not watered-down alternatives.
Error messages state what happened and what to do: "Name already taken. Choose a different one."
Confirmation messages are specific: "'production' deleted" not "Item removed successfully."
Under 15 words for any description.

File Structure

olive/
  src/
    lib/
      components/
        primitives/     # Button, Input, Badge, Label, Checkbox, etc.
        layout/         # Card, Page, Panel, Sidebar, Tabs, etc.
        navigation/     # Navbar, NavItem, ThemeToggle, CommandPalette, etc.
        overlay/        # Dialog, Toast, Tooltip, Popover, Sheet, etc.
        data/           # Table, DataTable, CodeBlock, MetricCard, etc.
        forms/          # Form, Combobox, DatePicker, FileUpload, etc.
        specialized/    # LogStream, SqlEditor, DrawCanvas, Toolbar, etc.
      tokens/           # index.css — all CSS custom properties
      utils/            # cn(), formatNumber(), formatDate(), formatBytes()
    routes/
      +page.svelte      # Component showcase

design.md 25 KB História Raw