466 lines
24 KiB
Markdown
466 lines
24 KiB
Markdown
---
|
||
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(46% 0.095 160)"
|
||
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(48% 0.09 70)"
|
||
information-neutral: "oklch(51.33% 0.0088 345.6)"
|
||
typography:
|
||
display:
|
||
fontFamily: "Manrope Variable, Manrope, system-ui, sans-serif"
|
||
fontSize: "1.5rem"
|
||
fontWeight: 600
|
||
lineHeight: 1.03
|
||
letterSpacing: "-0.025em"
|
||
headline:
|
||
fontFamily: "Manrope Variable, Manrope, system-ui, sans-serif"
|
||
fontSize: "1.5rem"
|
||
fontWeight: 600
|
||
lineHeight: 1.15
|
||
letterSpacing: "-0.015em"
|
||
title:
|
||
fontFamily: "Manrope Variable, Manrope, system-ui, sans-serif"
|
||
fontSize: "1.25rem"
|
||
fontWeight: 600
|
||
lineHeight: 1.25
|
||
letterSpacing: "-0.01em"
|
||
body:
|
||
fontFamily: "Manrope Variable, Manrope, -apple-system, BlinkMacSystemFont, Segoe UI, system-ui, Arial, sans-serif"
|
||
fontSize: "1rem"
|
||
fontWeight: 400
|
||
lineHeight: 1.65
|
||
letterSpacing: "normal"
|
||
control:
|
||
fontFamily: "Manrope Variable, Manrope, -apple-system, BlinkMacSystemFont, Segoe UI, system-ui, Arial, sans-serif"
|
||
fontSize: "0.875rem"
|
||
fontWeight: 600
|
||
lineHeight: 1.25
|
||
letterSpacing: "0.005em"
|
||
label:
|
||
fontFamily: "Manrope Variable, Manrope, system-ui, sans-serif"
|
||
fontSize: "0.75rem"
|
||
fontWeight: 600
|
||
lineHeight: 1.25
|
||
letterSpacing: "normal"
|
||
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
|
||
|
||
## 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
|
||
`--info` token 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, `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.
|
||
- **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 `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,
|
||
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 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
|
||
|
||
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 `em` shrinkage).
|
||
|
||
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-motion` while 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.
|