Design System & CSS Tokens
Relevant source files
The following files were used as context for generating this wiki page:
The J.A.R.V.I.S. Design System is a token-driven architectural framework designed for the Electron desktop environment. It prioritizes a "flat over boxed" aesthetic, utilizing semi-transparent glassmorphism, technical typography, and a strict contract of CSS variables to maintain visual consistency across components and themes. The system ensures that all UI elements—from the primary 3D Orb to floating overlays—adhere to a unified visual language of elevation, intent, and motion.
The system is built on the principle of "one source per concern," where primitives like Button, SearchField, and SegmentedControl own their internal styles, and call sites interact with them through semantic variants and sizes rather than ad-hoc CSS overrides.
Sources: instructions/DESIGN.md:4-12, src/renderer.css:1-15
Core Design Principles
The architecture is governed by several durable principles that define how components are structured and how they interact:
- Flatness over Nesting: The system discourages card-in-card layouts. Grouping is achieved through whitespace and single hairlines (
--ui-stroke-tertiary) rather than nested rounded boxes. - Borderless Elevation: Floating panels use a specific combination of
shadow-nousand the--stroke-noushairline instead of thick frames or borders. - Tokenization over Literals: Hardcoded hex values or RGBA strings are forbidden. All styles must reference CSS variables prefixed with
--ui-*,--theme-*, or--dt-*. - Intent-Driven UI: The interface provides immediate feedback for direct manipulation, with network reconciliation happening asynchronously.
Sources: instructions/DESIGN.md:16-30, apps/bootstrap-installer/src/styles-desktop.css:122-132
Visual Hierarchy Flow
The following diagram illustrates the relationship between design tokens and the rendered UI components.
The diagram shows how abstract tokens flow through standard primitives and design rules to generate the final interface.
Sources: instructions/DESIGN.md:4-15, src/renderer.css:32-60
CSS Token Architecture
The design system utilizes a tiered token structure defined in :root and :root.dark scopes. These tokens handle colors, strokes, shadows, and z-index layers.
Stroke and Text Tokens
| Token | Category | Usage |
|---|---|---|
--ui-stroke-primary | Stroke | Hairlines with high strength |
--ui-stroke-tertiary | Stroke | Default in-panel divider and list hairline |
--stroke-nous | Elevation | The specific hairline used for floating overlays |
--ui-text-primary | Typography | Primary text hierarchy |
--ui-text-tertiary | Typography | Muted metadata and captions |
--chrome-action-hover | Interaction | Hover fill for quiet UI controls |
Sources: instructions/DESIGN.md:58-69, src/renderer.css:18-30
Elevation and Shadows
Floating panels and overlays follow a specific elevation contract to prevent z-index competition.
--shadow-nous: A downward-weighted, layered contact-to-ambient falloff shadow.--z-modal(130): Base rung for modal dialogs.--z-over-modal(200): Used for toasts, tooltips, and command surfaces.--z-crash(1500): The highest rung, reserved for critical system failure states.
Sources: instructions/DESIGN.md:43-52, apps/bootstrap-installer/src/styles-desktop.css:122-140
UI Components & Primitives
The system provides standardized primitives that encapsulate layout and styling logic. Call sites must use these rather than defining custom styles.
Buttons and Controls
The Button primitive supports specific semantic variants:
- Variants:
default,secondary(soft fill),ghost,outline,text, andtextStrong. - Sizes:
xs,sm,lg,icon, andicon-titlebar. - Styling Rule: Icon buttons carry a shared 4px radius, while text buttons are square and sized by padding.
Sources: instructions/DESIGN.md:73-86, src/renderer.css:262-290
Specialized HUD Primitives
Standardized HUD elements are defined in src/renderer.css for the "Control Room" aesthetic:
.segmented-control: A container for small, mutually-exclusive sets (e.g., switching between Local and Cloud modes)..search-field: A borderless input with an underline-on-focus effect, used as the only search input in the app..list-row: A flat, flush-left row for settings and data lists, avoiding per-row indentation.
Sources: instructions/DESIGN.md:105-115, src/renderer.css:327-355
The 3D Orb System
The "Orb" is a composite semantic system indicator, not just decoration. Its visual state is tied directly to the backend service's lifecycle.
State Mapping
| State | Visual Language | Meaning |
|---|---|---|
idle | Muted cyan, slow orbit | Core initialized, no active work |
ready | Luminous blue, steady pulse | Local service is healthy |
listening | Green receptive pulse | Active voice intake |
thinking | Violet fast orbit | Model inference in progress |
error | Red high-contrast warning | Runtime fault detected |
disconnected | Dim desaturated core | Service unreachable |
Sources: src/renderer.css:577-586, src/index.html:1-5
Orb Interaction Sequence
The Orb state changes based on asynchronous events from the backend and voice systems.
The diagram outlines how the Orb acts as the primary feedback mechanism for system activity.
Sources: instructions/DESIGN.md:139-150, src/renderer.css:545-575
Theme Support
The design system supports both Light and Dark themes through a "Seed" based color injection. In the installer, where a runtime theme switcher is absent, the system mirrors the "Nous" dark seeds manually to ensure consistency during the setup process.
- Dark Mode Mix Knobs: In
darkmode, the system adjusts--theme-mix-chromeand--theme-mix-cardvalues to shift the base colors towards neutral darks while maintaining legibility. - Inversion Logic: The
--backdrop-invert-multoken is used to handle transparency and blur effects differently across themes.
Sources: apps/bootstrap-installer/src/styles-desktop.css:251-285, apps/bootstrap-installer/src/styles.css:48-65
Motion and Performance
Motion in the design system is functional rather than decorative.
- Timing: Quick transitions (~100ms) for controls.
- Reduced Motion: The system includes a blanket override that kills all CSS animations and transitions when
prefers-reduced-motionis detected. - Direct Manipulation: The UI paints the interaction feedback immediately in the current frame, with network persistence reconciling later.
Sources: instructions/DESIGN.md:156-168, apps/bootstrap-installer/src/styles-desktop.css:12-23