14 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
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, current selection, 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. - 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.06emtracking): 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,
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.
Navigation
- Style: compact session rows use
8pxcorners and restrained vertical padding. - Default / Hover / Active: transparent at rest, Sunken Surface on hover, and the same surface with stronger text weight when active.
- Responsive: collapse navigation structurally at the application breakpoint. Do not shrink labels into illegibility.
Curated Evidence Documents
Curated evidence follows a fixed reading order: title, compact type and purpose summary, scope, typed content, supporting excerpts, review items, then collapsed technical provenance. Machine metadata stays in invisible comments so GitHub Preview shows only the reviewable document.
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. Technical metadata belongs in progressive disclosure, not above the title.
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.
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.