tutti/docs/conventions/desktop-visual-language.md

# Desktop Visual Language

This document defines the intended visual language for `tutti` desktop renderer surfaces.

It captures durable design rules for a disciplined desktop workbench language,
adapted to `tutti`'s lighter current product shell.

## Purpose

`tutti` should not feel like a marketing site stitched together from pretty cards.

It should feel like:

- a welcoming desktop launcher at entry
- a disciplined workbench once the user is inside a workspace
- one coherent product shell across both states

This document exists to guide design and component decisions that scripts cannot judge.

## Source And Translation

The goal is not to mirror a different product's brand palette or asset style.

What should be carried over is the design discipline:

- token-first visual systems
- restrained depth and structural layering
- workbench-grade information hierarchy
- components that read as tools, not marketing tiles

What should not be copied directly:

- a brand-specific dark palette
- another product's naming or token vocabulary
- heavy adaptation of a deep-dark shell into places where `tutti` should stay lighter and calmer

## Core Posture

The desired `tutti` posture is:

- `launcher`: light, breathable, welcoming, slightly editorial
- `workspace`: sober, structured, workbench-like
- shared primitives: neutral, disciplined, reusable, not brand-performative

In short:

- the launcher may invite
- the workspace must support work

## Visual Hierarchy

Prefer hierarchy built from structure, not decoration.

Use these levers first:

- spacing rhythm
- container boundaries
- typography contrast
- subtle surface shifts
- restrained border and ring changes

Use these levers sparingly:

- large shadows
- saturated fills
- oversized icons
- decorative gradients
- high-motion emphasis

If multiple elements on a screen are all trying to feel "featured", the hierarchy is wrong.

## Color Strategy

`tutti` should remain light-first for now, but it should keep strong
discipline around color roles.

Guidelines:

- keep large surfaces quiet and low-noise
- reserve high-chroma color for focus, state, and a small number of primary actions
- keep semantic states stronger than decorative accents
- make status color useful before making it expressive

The UI system should optimize for semantic colors such as:

- background and elevated surfaces
- foreground and muted text
- border and input
- primary action
- accent
- success, warning, destructive

Brand color should not become a substitute for hierarchy.

## Typography Strategy

Typography should feel closer to a tool than a campaign page.

Guidelines:

- use one clear UI workhorse family for most interface text
- reserve display treatment for a small number of page titles or empty-state moments
- favor medium weight and clean rhythm over dramatic size jumps
- keep body copy easy to scan under medium information density

The overall hierarchy should compress gracefully:

- launcher can afford a more expressive page title
- workspace should favor clarity, compactness, and stable scanning patterns

## Radius And Depth

Prefer restrained workbench geometry.

Guidelines:

- default toward tool-like radii, not oversized marketing pills
- let radius scale communicate component class rather than visual novelty
- prefer fine borders and soft elevation over heavy drop shadows
- use glow or blur only when it clarifies layering, not just to add polish

In practice this means:

- buttons and controls should feel precise
- panels and cards should feel calm and substantial
- badges and chips may be rounder, but should not define the whole product language

## Component Language

Shared primitives should read as product infrastructure.

### Buttons

- primary buttons should mark true forward actions, not every clickable item
- secondary and ghost actions should carry most of the routine UI
- button styling should emphasize state clarity over visual loudness

### Cards And Panels

- cards should behave as information containers, not visual showcases
- major containers should define structure, grouping, and action placement
- inset sections should provide one level of nesting without creating a second visual theme

### Badges And Status

- badges should separate identity, state, and metadata roles
- status treatments should feel systematic and repeatable
- avoid decorative badge proliferation
- visible error and failure banners, plus context-handoff notices, use the
  light-red danger surface: `--on-danger` background, `--on-danger-hover`
  border, and `--state-danger` accents
- routine conversation system notices use the neutral system surface:
  `--transparency-block` background, `--line-2` border, and `--text-secondary`
  text
- never use yellow/warning surfaces (`--state-warning`-tinted fills or
  borders) for banner or notice boxes; reserve `--state-warning` for small
  inline accents such as status dots, usage meters, and icon or text tints

### Icons

- icons should be semantic helpers first
- default icon usage should stay small and integrated with text or state
- oversized or high-contrast icons should be reserved for empty states, brand anchors, or rare hero moments

### Workbench Window Chrome

Workbench window headers should share one compact chrome language across Agent
GUI, task center, file manager, and future workspace tools.

Use these rules:

- use `--background-panel` for the header surface unless a host shell owns a
  more specific chrome token
- keep window titles at `15px`, semibold, `20px` line height, and
  `--text-primary`
- keep routine chrome icons at `14px`; reserve larger icons for content
  regions, empty states, or app identity
- keep macOS workspace traffic lights at the native `12px` diameter, `16px`
  leading inset, and vertically centered in the `52px` workspace header; custom
  Agent GUI workbench traffic lights should use the same `12px` size and `16px`
  leading inset, with `12px` between the traffic-light group and agent identity;
  custom workbench traffic lights should keep a `12px` visual dot inside a
  `20px` pointer hit area, and browser, file, task-center, Agent GUI, and future
  workbench node headers should place close/minimize/maximize controls on the
  leading side before titles or tool controls; update Electron
  `trafficLightPosition`, renderer header clearance, and custom workbench header
  spacing together
- keep Agent GUI workbench identity icons at `20px` square without shadows
- pin the Agent GUI conversation rail toggle to the trailing edge of the rail
  header area, without drawing a right border on the rail
- keep Agent GUI rail toolbar controls flush with the rail header; do not add
  extra top padding above the search field and new-session button
- use `--text-secondary` for inactive icon actions and `--text-primary` for
  hover/focus states
- place routine header actions with `4px` gaps and prevent pointer or double
  click events on those actions from starting window drags
- keep drag handles structural and invisible; do not create a second visible
  titlebar treatment inside individual tools

Window chrome should feel like a shared product shell, not like each workspace
module designed its own toolbar.

### Shared Control Defaults

Default workbench controls should be precise and quiet.

Use these rules:

- routine buttons and text inputs default to `32px` height and `6px` radius
- small icon buttons may use tighter radii, but should still inherit the shared
  radius scale instead of one-off values
- transparent field surfaces use `--transparency-block`, with
  `--transparency-hover` for hover and focus surfaces
- destructive buttons use `--state-danger`, `--state-danger-hover`, and
  `--white-stationary` instead of raw red fills
- underline tabs use `13px` labels and medium weight; in English contexts this
  means `font-weight: 500`, while CJK contexts keep the same 500 emphasis
  through the shared language rules

## Page Composition

Screens should follow a stable composition order:

1. establish the shell
2. place the working content
3. add emphasis only where needed

### Launcher

The launcher may use:

- more generous spacing
- stronger welcome copy
- slightly warmer or softer presentation
- clearer onboarding-style calls to action

### Workspace

The workspace should use:

- tighter but still readable spacing
- clearer module boundaries
- lower decoration density
- stronger alignment discipline across headers, metadata, controls, and status areas

Workspace surfaces should be ready to grow in complexity without changing visual dialect every time a new module appears.

### Nested Menus in Constrained Surfaces

Nested menus and menu-like popovers must remain usable in narrow workspace
windows instead of assuming that the preferred side is always available.

- use the shared viewport menu surface and standard viewport padding
- prefer the logical forward side, flip to the opposite side when needed, and
  overlay the parent menu when neither side can fit
- when a submenu overlays its parent, add a first-row back action so the
  hierarchy and return path remain explicit
- cap tall menus to the available viewport height and allow their contents to
  scroll
- recompute placement when the viewport or scroll position changes
- preserve keyboard hierarchy: forward arrow enters the submenu, while back
  arrow and Escape return focus to its trigger
- when a menu is portaled out of a side panel, stack it on the shared
  `--z-panel-popover` layer; a raw numeric fallback below `--z-panel` leaves the
  menu rendered but hidden behind the panel

### Settings Dialogs

Workspace settings dialogs are compact workbench overlays, not full pages.

Use these rules:

- center the dialog over a light blurred overlay
- use `--background-panel` for the settings dialog shell and sidebar; reserve `--background-fronted` for frontmost menus and select popovers
- use the shared `--backdrop` token for the settings overlay instead of raw overlay colors
- use `--shadow-elevated` for settings panel elevation and keep the shadow balanced around the panel; avoid large positive y-axis offsets that make the bottom edge look heavier than the shell
- use a `960px` width cap and `640px` height cap on wide windows (`>=1280px`), a compact `760px` width cap and `500px` height cap from `960px` to `1279px`, and a `640px` width cap and `480px` height cap below `960px`; use a `16px` outer radius and a `54px` title bar
- use a fixed two-column structure at all supported window widths: `160px` section navigation on the left, settings content on the right
- keep navigation items compact and scannable, with selected state from the shared accent surface
- align compact setting rows as label/content pairs; labels use semibold `13px`, values use `11px`
- keep routine select/input controls around `200px` wide on desktop and full-width only on narrow responsive layouts
- keep routine controls at `32px` height with `6px` radius
- use token-backed danger surfaces for destructive zones: `--state-danger`, `--on-danger`, and `--on-danger-hover`
- portal popovers from inside the settings dialog above the panel with `--z-panel-popover`

The settings surface should look like a focused tool sheet. Avoid card stacks,
large decorative shadows, or one-off control styles inside individual sections.

## Anti-Patterns

Avoid these decisions even if they look attractive in isolation:

- turning every card into a featured tile
- using brand color as the main source of structure
- relying on oversized shadows to separate layout regions
- giving workbench surfaces marketing-style pill CTAs by default
- mixing airy launcher spacing into dense workspace surfaces without reason
- introducing one-off visual moods for individual modules inside the same workspace shell

## Design Review Questions

When reviewing renderer or `ui-system` work, ask:

1. Does this feel more like a tool shell or like a marketing fragment?
2. Is hierarchy coming from structure first, not color and effects first?
3. Is this component calm enough to survive repeated use across the product?
4. Does the launcher stay welcoming while the workspace stays work-oriented?
5. If this module grew denser, would the visual system still hold together?