ThothII/DESIGN.md

---
name: ThothII
description: "A calm, precise clinical analytics workbench for traceable and reviewable SQL workflows."
colors:
  instrument-red: "oklch(55.87% 0.1881 23.2)"
  instrument-red-hover: "oklch(50.95% 0.1812 24.1)"
  porcelain-background: "oklch(99.18% 0.0011 17.2)"
  porcelain-card: "oklch(99.85% 0.0006 17.2)"
  warm-surface: "oklch(97.09% 0.0011 17.2)"
  sunken-surface: "oklch(94.08% 0.0011 17.2)"
  warm-graphite: "oklch(26.78% 0.0097 355.6)"
  muted-graphite: "oklch(51.33% 0.0088 345.6)"
  quiet-border: "oklch(90.93% 0.0035 354.7)"
  success-mint: "oklch(75.77% 0.1581 165)"
  navigation-active: "oklch(92.5% 0.052 23.2)"
  navigation-active-hover: "oklch(89.5% 0.071 23.2)"
  navigation-active-foreground: "oklch(36.5% 0.11 23.2)"
  navigation-active-border: "oklch(60% 0.135 23.2)"
  warning-amber: "oklch(85.23% 0.1386 78.9)"
  information-blue: "oklch(70.35% 0.1128 221.3)"
typography:
  display:
    fontFamily: "Fraunces, Source Serif Pro, Georgia, Times New Roman, serif"
    fontSize: "3rem"
    fontWeight: 600
    lineHeight: 1.03
    letterSpacing: "-0.025em"
  headline:
    fontFamily: "Fraunces, Source Serif Pro, Georgia, Times New Roman, serif"
    fontSize: "1.875rem"
    fontWeight: 600
    lineHeight: 1.15
    letterSpacing: "-0.015em"
  title:
    fontFamily: "Fraunces, Source Serif Pro, Georgia, Times New Roman, serif"
    fontSize: "1.2rem"
    fontWeight: 600
    lineHeight: 1.25
    letterSpacing: "-0.01em"
  body:
    fontFamily: "Manrope, -apple-system, BlinkMacSystemFont, Segoe UI, system-ui, Arial, sans-serif"
    fontSize: "0.9375rem"
    fontWeight: 400
    lineHeight: 1.65
    letterSpacing: "normal"
  control:
    fontFamily: "Manrope, -apple-system, BlinkMacSystemFont, Segoe UI, system-ui, Arial, sans-serif"
    fontSize: "0.875rem"
    fontWeight: 600
    lineHeight: 1.25
    letterSpacing: "0.005em"
  label:
    fontFamily: "ui-monospace, SF Mono, Cascadia Code, Menlo, Consolas, monospace"
    fontSize: "0.6875rem"
    fontWeight: 600
    lineHeight: 1.25
    letterSpacing: "0.06em"
rounded:
  xs: "4px"
  sm: "6px"
  md: "8px"
  lg: "12px"
  xl: "16px"
  full: "9999px"
spacing:
  xs: "4px"
  sm: "8px"
  md: "16px"
  lg: "24px"
  xl: "32px"
components:
  button-primary:
    backgroundColor: "{colors.instrument-red}"
    textColor: "{colors.porcelain-background}"
    typography: "{typography.control}"
    rounded: "{rounded.md}"
    padding: "0 14px"
    height: "32px"
  button-primary-hover:
    backgroundColor: "{colors.instrument-red-hover}"
    textColor: "{colors.porcelain-background}"
    typography: "{typography.control}"
    rounded: "{rounded.md}"
    padding: "0 14px"
    height: "32px"
  button-secondary:
    backgroundColor: "{colors.porcelain-card}"
    textColor: "{colors.warm-graphite}"
    typography: "{typography.control}"
    rounded: "{rounded.md}"
    padding: "0 14px"
    height: "32px"
  input-default:
    backgroundColor: "{colors.porcelain-background}"
    textColor: "{colors.warm-graphite}"
    typography: "{typography.body}"
    rounded: "{rounded.md}"
    padding: "0 12px"
    height: "40px"
  card-default:
    backgroundColor: "{colors.porcelain-card}"
    textColor: "{colors.warm-graphite}"
    rounded: "{rounded.lg}"
    padding: "16px"
  badge-primary:
    backgroundColor: "{colors.instrument-red}"
    textColor: "{colors.porcelain-background}"
    typography: "{typography.control}"
    rounded: "{rounded.sm}"
    padding: "2px 8px"
    height: "20px"
---

# Design System: ThothII

## 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.
- Editorial headings paired with highly legible operational body text.
- 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 Blue** (`information-blue`): informational state when red would imply action.

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

**Display Font:** Fraunces, with Source Serif Pro, Georgia, and Times New Roman fallbacks  
**Body Font:** Manrope, with native system sans-serif fallbacks  
**Label/Mono Font:** SF Mono or Cascadia Code, with Menlo and Consolas fallbacks

**Character:** Fraunces gives persisted artifacts and key headings editorial authority. Manrope
keeps dense controls and prose calm and readable. The mono register separates machine identity,
metadata, SQL, identifiers, and micro-labels from natural-language content.

### Hierarchy

- **Display** (600, `3rem`, `1.03`): authentication and exceptional page-level statements only.
- **Headline** (600, `1.875rem`, `1.15`): major page or artifact titles.
- **Title** (600, `1.2rem`, `1.25`): panel and document section hierarchy.
- **Body** (400, `0.9375rem`, `1.65`): operational prose, with a target line length of 65 to 75
  characters where the surface controls width.
- **Control** (600, `0.875rem`, `1.25`): buttons, inputs, tabs, and compact actions.
- **Label** (600, `0.6875rem`, `0.06em` tracking): uppercase micro-labels, state metadata, and panel
  headers. Labels use the mono family.

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 Three Registers Rule.** Serif means authority, sans means interaction and reading, mono means
machine identity. Do not exchange these roles for novelty.

**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, `32px` default height, and `14px` horizontal padding.
- **Hover / Focus:** shift to Instrument Red Pressed; show a three-pixel focus ring at 25 percent
  opacity. Active state scales to `0.97` for `140ms` and 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 (`20px` height), 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`), with `16px` default 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:** `40px` height, `8px` corners, 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.
- **Metadata catalog model:** Database Management keeps one compact, installation-level
  metadata-generation LLM selector in the application header. The selection persists across
  database, table, column, and relationship views; when no usable profile is configured, the
  disabled control explains: “No metadata-generation LLM model is configured for this installation.”

### Navigation

- **Style:** compact session rows use `8px` corners 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 management,
  Memory management, Evidence management, a structural divider, Workspace management, and Pi
  management 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 session sidebar.

### 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 labelled `tablist`/`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-motion` while 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.