UI Design System & Styling
Relevant source files
The following files were used as context for generating this wiki page:
The Termul UI Design System is a dark-first desktop workspace environment. It utilizes semantic styling powered by Tailwind CSS, OKLCH color tokens, and a theme application engine that ensures accessibility and visual consistency across desktop, web, and mobile surfaces.
The system enforces a strict layering rule where components must use semantic tokens (e.g., bg-background, text-destructive) rather than raw hex codes or Tailwind palette primitives (e.g., bg-red-500). This architecture allows for real-time theme swapping while maintaining WCAG AA contrast standards.
Sources: DESIGN.md:3-12, AGENTS.md:120-125
Color Architecture & OKLCH Tokens
Termul defines colors using OKLCH "L C H" components. These components are stored as CSS variables and read via oklch(var(--token)). The system uses semantic tokens to describe the role of a color rather than its literal hue.
Semantic Token Categories
| Category | Tokens | Description |
|---|---|---|
| Neutral Surfaces | --background, --card, --popover, --secondary | Core layout surfaces based on the "Linear void" scale. |
| Typography | --foreground, --muted-foreground, --disabled-foreground | Text tokens adjusted for readability on various surfaces. |
| Brand/Action | --primary, --primary-fill, --accent, --accent-fill | Visual identity colors used for buttons and highlights. |
| Status | --success, --warning, --destructive, --connection | Semantic feedback for operations and system states. |
| Feedback Elements | --diff-added, --glow-green, --glow-blue | Specific colors for code diffs and agent thinking animations. |
Sources: src/renderer/index.css:41-94, src/renderer/lib/themes/apply-color-theme.ts:60-66
Theme Application Flow
The applyColorTheme function serves as the central engine for updating the UI appearance. It resolves a theme definition into specific OKLCH components and updates the document root.
The system suppresses transitions during a theme swap to prevent visual artifacts while all primary buttons and shadows restyle simultaneously.
Sources: src/renderer/lib/themes/apply-color-theme.ts:219-231, src/renderer/lib/themes/apply-color-theme.test.ts:22-27
Accessibility & Contrast Scaling
Termul automatically enforces WCAG AA contrast (minimum 4.5:1) for text tokens. The solveEmittedContrast function shifts the lightness of color tokens while preserving their hue until they meet contrast requirements against their background surfaces (typically --card or --secondary).
Contrast Constraints
- Text Tokens: Must pass 4.5:1 (AA) on standard surfaces.
- Solid Fills: Tokens like
--primary-filland--success-fillcarry near-white ink that must meet AA standards. - Disabled State: Disabled foregrounds must meet at least 3:1 contrast to remain legible but de-emphasized.
- Mobile Exceptions: On mobile, certain labels (like "Amend last commit") use a
muted-foreground/75ratio to maintain contrast where the desktop version uses a lighter/40opacity.
Sources: src/renderer/lib/themes/apply-color-theme.ts:69-75, src/renderer/lib/themes/apply-color-theme.test.ts:134-168, src/renderer/components/git/GitPanel.mobile.test.tsx:160-168
Component Styling Rules
The design system provides specific rules for core UI components to maintain a unified desktop feel.
Buttons and Fills
- Primary Buttons: The
Buttoncomponent usesdefaultas the primary fill. It does not have a separateprimaryvariant. - Semantic Fills: Components use solid fill tokens (e.g.,
--destructive-fill) for high-intent actions. - Press Feedback: All pressable elements (buttons, summaries,
role="button") use a subtle scale transform (scale(0.96)) and a customease-outtransition to provide tactile feedback.
Sources: AGENTS.md:124-125, src/renderer/index.css:151-164
Typography
Typography is organized into semantic roles rather than raw sizes:
- .label-section: 12px, normal weight, uppercase, tracking-wider. Used for panel and section headers.
- .label-group: 12px, semibold weight, uppercase. Used for menu and field micro-labels.
- Font Stacks: The UI uses
Inter Variablefor general interface text andIoskeley MonoorJetBrains Monofor code and terminal surfaces.
Sources: src/renderer/index.css:471-496, src/renderer/index.css:12-32
Motion and Animations
Termul uses a custom motion scale to make the UI feel intentional and responsive.
Transitions for anchored menus (popovers, dropdowns) use origin-aware scaling, where the transform-origin is derived from the Radix trigger position.
Sources: src/renderer/index.css:98-124, src/renderer/index.css:359-385
Specialized Surface Styling
Terminal Emulation (xterm.js)
The terminal grid surface background must match the application --background and --terminal-bg tokens. Scrollbars within the terminal are styled with transparency (e.g., --terminal-scrollbar-alpha) to prevent text overlap while remaining reachable (8px width).
Sources: src/renderer/lib/themes/apply-color-theme.test.ts:74-85, src/renderer/index.css:337-348
Agent Thinking & Shimmer
The AI agent interface uses specialized animation tokens for "thinking" states:
- Shimmer: A highlight band sweeps across muted labels using
--shimmer-dur(2000ms). - Thinking Swap: Text transitions between states using a blur and vertical shift (
--think-distance: 8px). - Comet Spinner: A 700ms linear rotation used for loading states.
Sources: src/renderer/index.css:622-670, src/renderer/index.css:738-752
The Termul UI Design System ensures that the application remains a cohesive, project-aware workspace by strictly enforcing semantic token usage and automated accessibility checks during theme resolution.