ThothII/DESIGN.md

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