DESIGN.md

DESIGN.md

Purpose

This file is the reusable visual and interaction source of truth for Yggdrasil applications.

Use it in two layers:

1. Core System: reusable design rules that should transfer cleanly across projects.
2. Project Overlay: product-specific vocabulary, workflows, and UI emphasis.

When this file is copied into another repo, the default move is:

• keep Core System
• replace or trim Project Overlay

Do not bury project-only nouns in the reusable sections.

Core System

Brand intent

Yggdrasil apps should feel:

• calm
• modern
• lightly premium
• youthful without being toy-like
• crisp rather than ornamental
• soft around the edges, but not soft-headed

They should not feel like:

• a Linux utility panel
• a web admin dashboard
• a noisy IDE clone
• a skeuomorphic toy
• a stack of nested cards inside more cards

The target impression is:

• one clear main workspace
• supportive chrome around it
• low-friction controls
• light, breathable, polished surfaces

Visual structure

Main workspace

The main workspace is the focus.

• It should read like a calm sheet, canvas, or stage.
• In light mode it should generally be white or near-white.
• It may have a soft shadow and mild radius.
• It should feel like it is floating slightly above the surrounding chrome rather than being boxed into it.
• It should not be crowded by decorative headers, nested boxes, or redundant toolbars.
• Whatever the app’s core artifact is, it should feel native to the main canvas rather than pasted inside a widget frame.

Supporting chrome

The surrounding chrome should feel supportive, not dominant.

• Side rails should be lighter and quieter than the main canvas.
• A faint blue-to-green fresh tint over a muted neutral base is desirable.
• A light gradient plus blur system is preferred when the platform supports it.
• Rails should avoid heavy borders.
• The shell should feel visually unified rather than partitioned into harsh boxes.
• Titlebar, side rails, and utility surfaces should feel like one seamless scaffold around the floating main canvas.

Shape language

• Rounded corners are welcome, but should stay restrained and OS-friendly.
• Outer shell rounding should feel closer to modern KDE/Windows than to exaggerated mobile UI.
• In maximized state, outer window corner radius should collapse to zero.
• Inner radii should be smaller than outer shell radii.

Color direction

Light mode is the primary reference unless a project explicitly says otherwise.

• Prefer white and pale blue-grey foundations.
• Accent color can lean clean blue.
• Background tint may gently lean sky-blue to green.
• Use contrast carefully; avoid washed-out unreadable controls.
• Keep the main canvas and supporting chrome visually coherent.

Avoid:

• muddy greys
• purple-heavy defaults
• overly opaque frosted layers that bury hierarchy
• gratuitous gradients inside the main content region

Theming system

Yggdrasil shells should support a reusable visual theme editor.

• Theme editing should be centered on a small floating modal, not a full settings page takeover.
• The editor should feel Arc-like or Zen-like: compact, visual, tactile.
• The core interaction model is:
  • a preview pad
  • draggable color stops
  • a lightweight color library
  • a brightness control
  • a single grain dial control
• Double-clicking the preview pad should be able to add a color stop.
• The preview pad should use a visible grid, not a blank field, so stop placement feels intentional.
• Dragging color stops should live-preview the shell background.
• Light and dark shell modes should remain selectable independently of the custom gradient.
• Saving should persist the theme; cancel should revert live preview.
• Reset should always return to the project’s base shell theme, not an empty placeholder state.
• The active portable theme should be stored in ~/.yggterm/settings.json under the theme object.
• If no custom colors exist, the shell should fall back to the system gradient cleanly.

Theme surfaces

• The outer shell background should be theme-driven.
• Supporting chrome should inherit the shell gradient subtly through transparency and blur.
• The main workspace should remain calmer and more neutral than the shell chrome.
• Theme accent can be derived from the dominant gradient stop for lightweight emphasis.
• The theme modal itself should not blur the background. The surrounding UI should remain clearly visible, with a calm blue active-state halo around the modal to signal focused editing.

Typography

Interface font

• Linux: Inter Variable
• macOS/Windows: default platform system UI font

General text guidance

• small text must still feel antialiased and intentional
• avoid overly thin utility-rail typography
• headings should feel clean and editorial, not shouty
• labels should be concise and legible

Project overlays can define additional content fonts, such as terminal, code, map, or data fonts.

Preferred monospace font

• JetBrains Mono is the preferred monospace across all platforms unless a project explicitly overrides it.

Control language

Segmented controls

Segmented pills are preferred for compact mode switches.

They should:

• clearly show the active segment
• have a clean outer shell
• avoid muddy selected states
• feel stable and precise

Primary buttons

Primary actions should look unmistakably clickable.

• blue background is acceptable for the main affirmative action
• white text
• clear contrast
• enough padding to feel intentional

If a user says “this does not look like a button”, that is a design failure.

Inputs

• Prefer clean rectangular or softly rounded input boxes.
• Avoid pill-shaped text fields unless there is a strong reason.
• Inputs must remain visible against the supporting chrome.

Search in chrome

• If the product has a global or sidebar search, the default preference is a centered search field in the titlebar.
• The search field should feel like part of the shell, not a floating badge.
• Search should generally be the visual anchor of the center titlebar slot.
• When an app has an active primary artifact such as a session, terminal, paper, or preview, its title should live in the titlebar to the left of the search field rather than consuming a duplicate header inside the main canvas.
• Hovering the title control should expose the summary via tooltip, and clicking it may open a compact dropdown with the fuller summary and related actions.
• Avoid showing both a titlebar title and a second in-canvas title card for the same artifact unless the inner canvas is itself an editor that must edit the title as content.

Context menus

Context menus should feel closer to modern Microsoft app menus than generic web popovers.

That means:

• open at the cursor
• modest radius
• clean light surface
• subtle shadow
• compact but breathable row sizing
• strong label clarity

Avoid:

• giant floating glass blobs
• top-left fallback placement
• labels that invent confusing product language

Motion and interaction

Motion should be functional, not decorative.

• side panels can ease in and out
• notifications should stack and reflow smoothly
• drag-and-drop should show clear make-way affordances
• state changes should feel crisp, not rubbery

Notifications

Notifications are reusable shell components, not one-off project afterthoughts.

• In-app toast notifications should be supported by default.
• Toasts should have clear tone coloring.
• Toast stacks should animate upward when items leave.
• Notification history panels are acceptable when the product benefits from persistent event history.
• Clear-one and clear-all actions should be supported when a notification panel exists.
• In-app toasts should usually sit horizontally centered near the top of the app, not pinned to a screen edge.
• Long-running work such as generation, caching, indexing, sync, or remote bootstrap should use reusable job notifications with a visible progress bar.
• Background jobs should not be silent; if the work may take more than a moment, the shell should make that work legible.
• Job notifications should coalesce by task identity instead of stacking duplicate progress cards.

Audio alerts

Audio alerts are a shell-level contract, not app-specific improvisation.

• Audio should be optional, user-toggleable, and easy to silence.
• The preferred control is a simple Sound toggle inside the shell’s appearance or notification surface.
• Audio is for state changes that matter, not for ordinary navigation.

Use this tone language:

• Info: one short soft rise
  • use for job start or gentle attention
• Success: two quick rising tones
  • use for build ready, update ready, or completed work
• Warning: two even attention tones
  • use for recoverable issues or states that need a look soon
• Error: one short descending urgent tone
  • use for build failure, sync failure, or action blocked

Avoid:

• sounds on hover
• sounds on every click
• novelty effects
• multiple different sound languages across Ygg apps

Update system

Update UX is a reusable shell concern, not project-specific glue.

• Direct-install update flows should reuse the notification and chrome systems.
• Installing an update must not immediately tear down a running productive workspace.
• Preferred behavior is:
  • install in the background
  • notify that the update is ready
  • expose an explicit restart affordance
• Update state should be readable from shell chrome without feeling alarmist.
• If a restart is required, the app should say so plainly instead of silently relaunching itself.

Debug telemetry

Debug-only telemetry is a design-support component, not just an engineering detail.

• Instrumentation should help explain interaction failures such as drag, selection, layout, or context-menu issues.
• Debug telemetry should be local-first and easy to inspect.
• It should be safe to remove or gate behind debug builds without affecting the product UI.
• If a complex interaction is likely to be reused, the telemetry strategy should be reusable too.

Drag and drop

If a project has drag-and-drop tree or list reordering:

• explicit before / inside / after snap zones are preferred
• a floating drag card is preferred over invisible drags
• hover affordances should show where the item will land
• adjacent snap boundaries must behave predictably
• multi-select drag can use stacked-card visuals
• the final placement must match the visible snap indicator exactly

Preview surfaces

If a project has a conversation preview surface:

• preview reading mode and runtime/live mode should share one header system
• generated title and summary should be treated as refreshable navigational aids
• preview content should render like content, not raw log lines
• headings, bullets, task items, quotes, and code fences should each have distinct treatment
• overview/graph mode should feel structural, not like the same chat list in a second skin
• overview mode should highlight summary, counts, and message progression before full transcript detail

Reusable shell guidance

If a project has:

• a main canvas
• left or right rails
• titlebar actions
• reorderable tree/list structures

then the shell should be designed as reusable primitives rather than one-off page markup.

Preferred reusable boundaries:

• drag/reorder engine
• drag ghost / drop-zone visuals
• titlebar primitives
• window control primitives
• rail/panel primitives
• menu and toast primitives
• update-state primitives
• telemetry hooks for interaction-heavy components

Window chrome specifics

If a project owns its own titlebar/chrome:

• the main viewport should sit visually above a seamless titlebar + rail scaffold
• the preferred top-right control order is:
  • always-on-top
  • minimize
  • maximize / restore
  • close
• these controls should use crisp simple line icons
• minimize/maximize/always-on-top should stay neutral by default
• close should gain a red background with a white X on hover
• outer radii should disappear in maximized state

Project Overlay Interface

Each project should define the following explicitly.

1. Main artifact

What is the main canvas actually for?

Examples:

• terminal
• map
• graph
• document
• dashboard

2. Navigation model

What lives in the left rail?

Examples:

• sessions
• folders
• machines
• topology nodes
• boards

3. Right rail modes

What modes can the right rail switch between?

Examples:

• metadata
• settings
• notifications
• inspector
• filters

4. Vocabulary

Define the user-facing nouns here, not in the reusable sections.

Examples:

• session
• terminal
• paper
• folder
• separator

5. Domain-specific control rules

Document:

• quick action labels
• context menu labels
• titlebar actions
• view toggles

6. Domain content typography

If the main artifact needs a special font, define it here.

Examples:

• terminal font
• map label font
• monospace editor font

Project Overlay: Yggdrasil Maker

This section is intentionally project-specific.

yggdrasil-maker is a libyggterm app. It does not own a window, a titlebar, a theme editor or a window-manager story: it declares a web surface on its own PTY and yggterm renders it. Everything the previous desktop app specified about shell chrome, custom titlebars, meta-key layers and app-control probes now belongs to yggterm, and this overlay is deliberately much smaller as a result.

Main artifact

The build itself — what this checkout would produce, what it would run to get there, and what happened when it ran.

Navigation model

One viewport surface with a segmented Home / Plan / Run switch.

• Not three surfaces: the flows are one task at three depths.
• Not a sidebar: the surface is the whole viewport, and yggterm already owns the one control that must not be duplicated — the ⌨ Terminal toggle that brings the PTY back to the front.
• The segmented pill follows Core System → Control language.

Preferred user-facing terms

Prefer	Over
checkout	workspace, project
config	setup, preset
profile	variant, flavour, edition
knob	option, setting, field
plan	preview, simulate
stage	step, phase, task

Honesty rules

These are visual rules because they are mostly about what may be drawn.

• No simulated progress. A stage that has not started has no percentage, so no bar is drawn for it. Progress is only ever shown for something really running that really reports it.
• A cost is always visible. Every stage carries what it really costs — seconds and rootless, needs root, or root and tens of minutes — so nothing looks one click away when it is forty minutes and a password away.
• An unavailable fact says so. When something cannot be read from the checkout, the UI shows that it could not be read, with the error. It never falls back to a plausible remembered value.
• A command line is never hidden. Any flow that would run something shows the argv it would run.

Log surface

The run log is the one place monospace dominates.

• JetBrains Mono, per Core System.
• stderr is tinted with the warning colour; stdout stays default ink.
• The exit line is quiet, not celebratory. A build finishing is information.
• It follows the tail only when the reader is already at the tail.

Domain content typography

• Config keys, values, paths and command lines are monospace.
• Prose, labels and section headers are the interface font.
• A knob's # hint from the TOML is prose, not code, even though its source is a comment in a config file.