24 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 full-mode application header matches Omics Portal's --gsd-red-primary
(#CB333B) in both themes. Its complete wordmark, including II, and controls
use a near-white foreground. This header is absent in embedded mode. The sidebar
and welcome wordmarks retain their red suffix. Context editing places workspace,
model and Done in one desktop row, stacking on narrow containers. Session-scope
tabs retain their selected fill and accessible keyboard state with a uniform one-pixel
border on every side, gray when inactive and red when active. Their padding is 11px
horizontal and 3px vertical, with a 38px minimum height and wrapping labels.
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.
Application wordmark: ThothII is a brand mark, not a page title: use Manrope semibold at
48px (3rem) in the Core welcome area and 32px (2rem) in the session sidebar, with the
II suffix in brand red. Preserve these sizes across responsive layouts.
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
- Workspace readiness: the Workspace navigation button carries an 8px dot to the right of its label. Green means a selected workspace with confirmed ready preprocessing and no query error; all other states are red. The button's tooltip and accessible description retain the translated exact state. Do not add a separate readiness text row or change the backend readiness gate.
- Session groups: one accessible single-open accordion contains Active sessions
and Archive, both initially closed. Below the scope tabs, show only their
adjacent section headers, without a redundant Sessions heading. Selection and
bulk-delete controls belong inside each panel and only appear for nonempty
lists. Select all affects that list only, preserves the other list's selection,
and exposes a mixed state for partial selection. Preserve the existing archived
flag as the grouping rule, independent of whether a Pi process is running.
Opening a section closes the other; either can be collapsed, including both.
Empty lists show only the translated "No sessions yet." message.
The open section uses the rail's remaining height; its list scrolls internally
with a cap of
min(18rem, 35dvh), while its trigger remains outside that scroll area. The mobile navigation dialog supplies a bounded viewport-height container. Keyboard users can focus and scroll each labelled panel. - Session entry: one Session button returns to the current unfinished session, including provisional creation, without resetting or reconnecting it. Otherwise it prepares a new question using the normal readiness and unsaved-work guards.
- 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. In embedded mode 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.
Session review and confirmations
Session dialogs use the visible application area, including the portal's header and side rail. Artifact and schema-column review can grow to 80rem wide and the available height; short confirmations use up to 40rem and at least 18rem when space permits. Keep a 24px outer margin on desktop and 8px on small or short screens. Long review content scrolls internally; on very short screens the whole dialog can also scroll so every action remains reachable.
Session forms and review gates repeat their existing primary confirmation above and below the content, sharing selection, validation, pending state and response handlers. Alternate-response inputs follow the same rule. Reserved navigation controls remain below the review. Stop/delete initially focus Cancel; rename initially focuses the name field. Administration dialogs and forms retain their existing layout and actions.
Tabs
- Shape: compact label tabs sit on a shared baseline with rounded top corners and a two-pixel lower edge, except session-scope tabs which use a uniform one-pixel border, rounded corners and a 4px gap without a shared border or negative bottom margin. Inactive labels retain a 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
Memory and Evidence share the thot-knowledge-reader reading contract. Use locally
bundled Manrope with normal tracking for prose and labels, and these fixed roles:
- Card title: 24px, weight 600, line-height 1.3 (
thot-knowledge-title). - Field/section heading, including Scope and Provenance: 20px, weight 600,
line-height 1.4, 8px clearance below (
thot-knowledge-heading). - All narrative text, including scope, lists and provenance: 16px, weight 400, line-height 1.65. Do not apply compact UI text sizes to these fields.
- Authored Markdown subheadings inside a field: 16px, weight 600, line-height 1.5, 24px above/8px below. They remain subordinate to the enclosing field heading; their semantic heading levels and original content are preserved.
- Technical metadata labels/values: 14px/1.5, with weight 600 for labels.
Only code, paths and machine identifiers use the technical monospace family at
14px/1.65, identical for inline and fenced code (never compound
emshrinkage).
Separate reading sections by 24px; keep the first Markdown block flush with its field heading's 8px bottom gap. The same typography applies in light/dark and at all responsive widths. Controls and archive indexes retain their compact UI roles.
Memory and Evidence detail readers use the entire available content width, without the ordinary 72–75ch prose cap. This is the owner's explicit reading-layout choice. Long unstructured paragraphs are split for display at existing sentence/semicolon boundaries outside inline code and links; authored Markdown structure and stored content are unchanged. Paragraph spacing is 1.25em. Scope and provenance share the available width; provenance excerpts render Markdown rather than literal markers. Copy actions use the two-overlapping-sheets icon, an accessible name/tooltip and live success/failure feedback instead of a visible Copy label.
Memory has four explicitly FAKE formatting examples, one per family, in a separate expandable section. They reuse the real detail reader but never enter persistence, indexing, link search or model recall, and expose no edit/delete/save actions.
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 the selected interface language (English by default) for chrome and preserve the workspace language for persisted domain content. Session interaction language remains pinned.
- 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.