UI Elements & Controls
Relevant source files
The following files were used as context for generating this wiki page:
The J.A.R.V.I.S. Desktop Design System is built on the philosophy of "one source per concern, tokens over literals, and flat over boxed." It defines a visual and interaction contract for the Electron-based desktop application, emphasizing immediate feedback and borderless elevation for floating panels. The system is designed to provide a futuristic, high-tech "HUD" (Heads-Up Display) experience while maintaining strict architectural boundaries between the renderer and the backend services.
Sources: instructions/DESIGN.md:3-8, instructions/design-backend-prompt.txt:12-15
Core Design Principles
The UI architecture follows seven primary principles to ensure consistency across the application:
- Flat, not boxed: Avoids card-in-card nesting and uses whitespace or single hairlines instead of divider borders.
- Borderless elevation: Overlays utilize a specific shadow token (
shadow-nous) and a hairline stroke (--stroke-nous) rather than thick frames. - One primitive per concern: The system discourages forking; there is exactly one
Button,SearchField,Loader, andErrorState. - Tokens over literals: CSS variables (e.g.,
--ui-*,--theme-*) are used exclusively instead of hardcoded hex values. - Style in the primitive: Padding, radius, and color are owned by component variants and sizes rather than call-site class overrides.
- Intent before automation: Panes or focus shifts do not occur automatically; they require user intent or useful action surfaces.
- Immediate feedback: Direct manipulation updates the view first, with persistence and potential rollbacks occurring asynchronously.
Sources: instructions/DESIGN.md:12-28
Layout & Shell Architecture
The shell layout is composed of a rigid hierarchy designed to preserve conversation context while providing quick access to tools and settings. The main body is a grid-based structure with three primary sections: a Sidebar, a Workspace Stack (Stage and Chat), and a Control Stack (Service and Diagnostics).
Sources: src/index.html:36-62, tests/shell-layout.test.ts:16-24
This diagram illustrates the primary structural layout of the JARVIS shell as defined in the HTML structure and layout tests.
Sources: src/index.html:36-120, tests/shell-layout.test.ts:11-30
Workspace Surfaces
| Surface | Product Role | Description |
|---|---|---|
| Chat | Home Surface | The transcript and composer remain primary for the conversation. |
| Pages | Durable Destinations | Destinations like Skills and Artifacts remain in the shell chrome. |
| Route Overlays | Short Tasks | Settings and Command Center render as OverlayView cards. |
| Panes | Working Context | Terminals and file previews remain attached to the current task. |
Sources: instructions/DESIGN.md:33-41
The Orb State System
The "Orb" is a composite semantic indicator at the center of the identity core. It uses a 3D shader sphere and SVG HUD rings to communicate the internal state of the system through visual mappings like color, orbit speed, and pulse rate.
Sources: instructions/design-backend-prompt.txt:64-70, src/renderer.tsx:28-40
Orb State Definitions
| State | Visual Language | Meaning |
|---|---|---|
idle | Muted cyan, slow orbit | Core initialized, no active work. |
ready | Luminous cyan, steady pulse | Local service is healthy and connected. |
listening | Green/cyan receptive pulse | Microphone active, STT intake running. |
thinking | Violet faster orbit | Model inference (Grok/Ollama) in progress. |
responding | Bright cyan expansion | TTS or streaming response output is active. |
error | Red high-contrast warning | Runtime fault requiring attention. |
disconnected | Dim desaturated core | Service unreachable or health failure. |
Sources: instructions/design-backend-prompt.txt:72-81, src/renderer.tsx:42-60
UI Primitives & Control Tokens
The system uses standardized primitives to ensure that variants (like destructive or ghost) handle their own visual states.
Stroke and Color Tokens
| Token | Application |
|---|---|
--ui-stroke-primary | Highest strength hairline for borders. |
--ui-stroke-tertiary | Default in-panel divider or transcript surface border. |
--stroke-nous | Specialized hairline for floating overlays paired with shadow-nous. |
--ui-bg-quaternary | Fill for secondary controls/buttons. |
--chrome-action-hover | Hover background fill for quiet titlebar controls. |
Sources: instructions/DESIGN.md:86-95, src/renderer.css:39-48
Buttons
Buttons are implemented via a single component (src/components/ui/button.tsx) with strict constraints on props.
- Variants:
default,destructive,secondary(soft fill),outline,ghost,link,text,textStrong. - Sizes:
default,xs,sm,lg,inline(zero box for headings),micro, and an icon family (icon,icon-xs, etc.). - Interactions: Use
cursor-pointerby default; keyboard focus rings are globally reset to custom themed styles.
Sources: instructions/DESIGN.md:100-111, src/renderer.css:262-280
Form Controls
- SearchField: Borderless input that underlines on focus. It is auto-width and hides when lists are empty.
- SegmentedControl: Used for small, mutually-exclusive choice sets like "Color Mode" or "Model Mode."
- Switch: A bare toggle without a bordered text wrapper, usually implemented at
size="xs".
Sources: instructions/DESIGN.md:139-144, src/renderer.css:334-360
Interactive Data Flow: Action Proposals
The Action Engine utilizes a specific UI pattern for human-in-the-loop approvals. When the system proposes an action (e.g., opening a URL or running a script), it renders an "Action Proposal" card.
Sources: instructions/design-backend-prompt.txt:59-62, src/renderer.tsx:774-780
This sequence shows the interaction between the Assistant, the backend Action Engine, and the UI for manual action approval.
Sources: instructions/design-backend-prompt.txt:59-62, src/renderer.tsx:774-810
Surface Elevation and Z-Index
To prevent competition between persistent layers and transient overlays, the system defines a specialized z-index ladder in src/styles.css.
| Surface Category | Z-Index Token Range | Elements |
|---|---|---|
| Boot Chain | --z-connecting to --z-crash | Setup, Onboarding, Crash Screens. |
| Modals | --z-modal-backdrop to --z-modal | Dialogs, Route Overlays. |
| Over Modal | --z-over-modal | Toasts, Tooltips, Command Palettes. |
| Feedback | z-10 / z-20 | Stacking within a single component. |
Sources: instructions/DESIGN.md:175-181
Conclusion
The UI Elements & Controls system for JARVIS Desktop Glas provides a unified framework where components are managed through semantic tokens and centralized primitives. By strictly adhering to a flat design philosophy and a controlled orb-based state machine, the system maintains a high-fidelity HUD experience that prioritizes user intent and system transparency.
Sources: instructions/DESIGN.md:275-290