18 KiB
name, description, colors, typography, rounded, spacing, components
| name | description | colors | typography | rounded | spacing | components | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ThothII | A calm, precise clinical analytics workbench for traceable and reviewable SQL workflows. |
|
|
|
|
|
Design System: ThothII
Visual review branch, September 2026
The revision on codex/ui-visual-review is approved for implementation and Docker visual review,
not yet for adoption on main. The previous look remains recoverable from the base commit and
the preserved Docker image. Historical prototypes must remain untouched.
This revision follows Impeccable's product register: one locally bundled Manrope family for the whole UI, five fixed size roles, red as the sole brand accent and additional color only for meaningful state. The primary scene remains an analyst reading data and SQL in a well-lit office.
Overview
Creative North Star: "The Clinical Workbench"
ThothII should feel like a well-kept clinical workbench: warm enough for sustained reading, exact enough for consequential review, and quiet enough that evidence, state, and decisions remain in the foreground. The visual system is calm, precise, and trustworthy. It uses familiar product patterns, restrained color, and deliberate density instead of decorative spectacle.
The primary physical scene is an analyst reviewing persisted evidence and SQL on a large monitor in a well-lit working environment. This makes the warm light theme the default. The supported dark theme serves lower-light work without becoming a separate neon aesthetic. Both themes preserve the same hierarchy and semantic roles.
The system rejects generic SaaS ornament, conspicuous ripples, bounce or elastic motion, long choreographed transitions, and effects that compete with the analytical task. Controls should feel disciplined and tactile, never playful, sluggish, or visually unstable.
Key Characteristics:
- Warm, restrained surfaces with one scarce red accent.
- One sans-serif family, with hierarchy expressed through size, weight and spacing.
- Dense information organized through hierarchy, rhythm, and progressive disclosure.
- Persisted artifacts and reviewer decisions presented as the visual source of truth.
- Fast state feedback with reduced-motion parity.
The Workbench Rule. Every visual element must support inspection, action, state, or provenance. Decoration without an operational purpose is forbidden.
The Persisted Truth Rule. Persisted artifacts and reviewer decisions receive stronger hierarchy than transient model narration.
The Density with Rhythm Rule. Preserve information density, but vary spacing between groups so users can scan structure without adding nested containers.
Colors
The palette combines warm porcelain surfaces, warm graphite text, and an instrument red used only for action, focus, and important state. OKLCH values in the frontmatter are normative because the frontend uses OKLCH tokens directly.
Primary
- Instrument Red (
instrument-red): primary actions, focus identity, and destructive meaning where the context already makes the action explicit. - Instrument Red Pressed (
instrument-red-hover): hover and active emphasis for the primary action family.
Neutral
- Porcelain Background (
porcelain-background): the main canvas. - Porcelain Card (
porcelain-card): lifted panels, cards, and popovers. - Warm Surface (
warm-surface): sidebars, secondary controls, and muted regions. - Sunken Surface (
sunken-surface): selected rows, quiet emphasis, and inset regions. - Warm Graphite (
warm-graphite): primary text and high-confidence labels. - Muted Graphite (
muted-graphite): descriptions, timestamps, and secondary metadata. - Quiet Border (
quiet-border): structural boundaries, input outlines, and dividers.
Semantic
- Success Mint (
success-mint): completed and ready states. - Navigation Active (
navigation-active): the one application surface currently in the foreground. It shares Instrument Red's hue but uses a lighter, lower-chroma fill, so location is visible without carrying the full weight of a primary action. - Warning Amber (
warning-amber): waiting, attention, and in-progress states. - Information: neutral text and indicators for dates, protocols and ordinary status. The legacy
--infotoken resolves to muted foreground, not an additional blue accent.
The dark theme keeps the same semantic mapping with neutral near-black surfaces and a slightly lighter red accent. Do not introduce a second visual identity for dark mode.
The One Voice Rule. Instrument Red should occupy no more than roughly ten percent of a screen. Its rarity is what makes it authoritative.
The State Has a Name Rule. Success, warning, information, and destructive colors are reserved for their named states. Color is never the only state indicator.
Typography
UI Font: locally bundled Manrope Variable, with Manrope and native sans-serif fallbacks. Technical Font: SF Mono or Cascadia Code, with Menlo and Consolas fallbacks.
Manrope covers headings, labels, controls, navigation and document reading. Monospace is reserved for SQL, code, paths and machine identifiers, never for ordinary UI labels or status headings.
Hierarchy
- Headline (600,
1.5rem,1.3): page or artifact titles,--text-page. - Title (600,
1.25rem,1.4): section hierarchy,--text-section. - Body (400,
1rem,1.6): operational prose,--text-body, with a target line length of 65 to 75 characters where the surface controls width. - Control (400–600,
0.875rem,1.5): buttons, inputs, tables, tabs and compact subheadings,--text-control. - Metadata (400–600,
0.75rem,1.5): secondary status, counts and timestamps,--text-meta. Labels use sentence case and normal tracking. Ordinary operational text never falls below 12px.
Typography uses fixed sizes. Responsive changes happen at structural breakpoints, not through fluid type scaling. Numeric data and identifiers use tabular numerals where comparison matters.
The One Family Rule. The UI and document readers use sans-serif throughout. The legacy
--font-heading alias resolves to --font-sans. Preserve technical monospace without turning it
into a second decorative hierarchy. Do not shrink text to solve layout constraints.
The Read Once Rule. A heading, label, and body must be distinguishable on first glance through size and weight. Do not repeat headings in explanatory copy.
Elevation
The system is flat by default and layered when necessary. Borders mark structure. Warm, diffuse shadows mark actual elevation for popovers, dialogs, and selected containers. Tonal layering should solve most hierarchy before a shadow is introduced.
Shadow Vocabulary
- Contact Shadow (
--shadow-xs): a one-pixel contact shadow for controls and code blocks. - Panel Shadow (
--shadow-sm): a small two-stage shadow for cards that need separation from the canvas. - Overlay Shadow (
--shadow-md): a broad, low-opacity shadow for dialogs and floating layers.
Focus uses an explicit three-pixel ring. Waiting-for-input state may use a success-tinted ring, but
must retain a textual or structural cue. Motion for button state changes lasts 140ms with
cubic-bezier(0.22, 1, 0.36, 1). Dialog transitions last 100ms. Activity pulses may run at
1.5s, and must be disabled under prefers-reduced-motion.
The Flat by Default Rule. A resting surface has no shadow unless it is physically above another surface. If every panel floats, none of them has hierarchy.
The Borders Structure, Shadows Elevate Rule. Never use shadow as a substitute for grouping or a border as a decorative accent.
Components
Components are familiar, compact, and state-complete. Every interactive primitive must define default, hover, focus, active, disabled, loading, and error behavior where those states apply.
Buttons
- Shape: gently curved rectangle (
8px) with a one-pixel transparent or structural border. - Primary: Instrument Red, porcelain text,
32pxdefault height, and14pxhorizontal padding. - Hover / Focus: shift to Instrument Red Pressed; show a three-pixel focus ring at 25 percent
opacity. Active state scales to
0.97for140msand removes elevation. - Secondary / Outline: porcelain card surface, Quiet Border, Warm Graphite text, and a Warm Surface hover.
- Ghost: transparent at rest, Warm Surface on hover. Use only where surrounding structure makes the hit target obvious.
Badges and Status Indicators
- Style: compact (
20pxheight), gently curved (6px), and semibold. - State: pair semantic color with text, icon, or position. A colored dot alone is insufficient when the state affects workflow decisions.
Cards and Containers
- Corner Style: softly rounded (
12px), with16pxdefault internal padding. - Background: Porcelain Card over Porcelain Background or Warm Surface.
- Shadow Strategy: Panel Shadow only when the card must read as elevated.
- Border: one-pixel Quiet Border at partial opacity.
- Nesting: nested cards are forbidden. Use headings, dividers, spacing, or tonal regions.
Inputs and Fields
- Style:
40pxheight,8pxcorners, Porcelain Background, Quiet Border, and Manrope body text. - Focus: three-pixel Instrument Red ring with a clear border shift.
- Error / Disabled: errors combine destructive color with explanatory text; disabled controls retain readable contrast and use 50 percent opacity.
- Global context: the collapsible top shelf is the sole workspace/model selector for Core and Admin. Preserve independent remembered choices, installation defaults, operation locks and unsaved edit guards. Never introduce a separate metadata-generation default or selector.
Navigation
- Style: compact session rows use
8pxcorners and restrained vertical padding. - Default / Hover / Active: porcelain at rest, Sunken Surface on hover, and a muted Navigation Active red with a defined border when current. Exactly one top-level navigation control is current.
- Administrative controls: the admin-only Administration accordion groups Database, Memory, Evidence, a structural divider, Workspace, and Pi configuration in that order. Its trigger exposes expanded state and starts collapsed by default, while non-admin users do not receive the accordion or its navigation actions.
- Responsive: collapse navigation structurally at the application breakpoint. Do not shrink labels into illegibility. Below 768px, Memory and Evidence management use the full content width; a Navigation button opens the shared accessible dialog. Selecting another archive page or pressing Escape closes it. Desktop retains the right session sidebar and its My sessions / All sessions tabs. Core retains question/answer, eight phases, reviewer gates and the left log. The portal owns the red header and left sidebar; ThothII must not duplicate them. Size to the actual application container. Narrow session document panels may use the available width.
Tabs
- Shape: compact label tabs sit on a shared baseline with rounded top corners and a two-pixel lower edge. Inactive labels retain a complete Quiet Border and Porcelain Card surface, so every label reads as a tab before interaction; hover feedback reinforces clickability.
- Current: the selected tab uses the muted Navigation Active red for its fill, text, and defined border.
It must expose
aria-selected, participate in a labelledtablist/tabpanel, and be the only tab in the roving keyboard tab order. - Keyboard: Left/Right move between adjacent tabs with wrapping; Home/End select the first or last tab.
Tooltips
- Row actions: icon-action tooltips open three pixels below the trigger and align to its trailing edge, so they never cover the icon row. They use a dark slate surface, porcelain text, and a defined border rather than the light popover treatment.
- Interaction: tooltip layers never receive pointer events. They appear on hover and keyboard focus with a short ease-out transition, while the icon button keeps its complete accessible name.
- Scope: this treatment is shared by database, table, column, and relationship row actions. Toolbar and navigation hints may use separate collision-aware placement.
Curated Evidence Documents
Curated evidence follows a fixed reading order: title, compact type and purpose summary, scope, typed content, supporting excerpts, review items, then technical provenance. Curated v4 files use short, visible YAML frontmatter for identity and classification. The Markdown title and body are authoritative; hidden payload comments are a legacy format converted on consolidation.
applies_to is rendered as “Ambito di applicazione” with separate bullet lists for concepts,
tables, and columns. Enum values also use lists. Tables are forbidden for metadata, scope, or any
one-dimensional collection; reserve tables for genuinely two-dimensional datasets. Long machine
identifiers use inline code. SQL uses fenced code. Supporting excerpts use blockquotes.
The Review Surface Rule. The visible Markdown must be readable without understanding the machine contract. In Administration, explain current and original provenance separately and keep file-editing templates and Git instructions in progressive disclosure. Show actual host paths with copy controls, never browser file links to container-only locations.
Do's and Don'ts
Do:
- Do make every state change unmistakable without interrupting flow.
- Do use Instrument Red only for primary action, current selection, focus identity, or explicit destructive meaning.
- Do preserve information density with headings, rhythm, and progressive disclosure.
- Do keep keyboard focus explicit and pair color with text, shape, icon, or position.
- Do respect
prefers-reduced-motionwhile preserving immediate non-kinetic feedback. - Do use English for interface chrome and the workspace language for persisted document content.
- Do render curated metadata and scope as Markdown prose or lists, never as a frontmatter table.
- Do break long curated rules into paragraphs, labelled subsections, and lists at existing punctuation boundaries while preserving the exact canonical text for machines.
Don't:
- Don't add generic SaaS ornament, conspicuous ripples, bounce or elastic motion, long choreographed transitions, or effects that compete with the analytical task.
- Don't make controls feel playful, sluggish, or visually unstable.
- Don't use gradient text, decorative glassmorphism, or full-saturation accents on inactive states.
- Don't use a colored side stripe greater than one pixel on cards, callouts, list items, or blockquotes. Use a full border, tonal background, icon, or heading instead.
- Don't nest cards or wrap every section in a container.
- Don't use a modal before exhausting inline or progressive alternatives.
- Don't use tables for
applies_to, metadata, enum values, or other one-dimensional content. - Don't use color as the sole carrier of success, warning, error, selection, or progress.
- Don't use display typography for buttons, labels, or data.
- Don't add em dashes to interface copy. Use commas, colons, semicolons, or parentheses.