From 6e0a899b5783e772463f4533868bb091e57ba742 Mon Sep 17 00:00:00 2001 From: Frank Tovar Date: Sat, 21 Mar 2026 12:46:00 +0100 Subject: [PATCH] Refine UX bible theming and action colors --- docs/tables_ux_bible.md | 145 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 144 insertions(+), 1 deletion(-) diff --git a/docs/tables_ux_bible.md b/docs/tables_ux_bible.md index 5771264..a9de95c 100644 --- a/docs/tables_ux_bible.md +++ b/docs/tables_ux_bible.md @@ -154,6 +154,7 @@ Navigation rules: Visual direction: - archival reference tool, not fantasy theme park +- explicit light and dark themes with parity, not one theme treated as secondary - warm neutral base, dark ink text, brass accent, moss success, rust warning, slate utility - strong typographic hierarchy - generous whitespace around decision points @@ -169,7 +170,7 @@ Color roles: - background: warm paper - surface: lifted ivory -- primary action: brass +- primary accent: restrained blue-teal or muted cobalt family that does not clash with red, orange, or green semantic colors - selection: deep slate-blue - curated/safe: moss - needs attention: rust/amber @@ -183,6 +184,140 @@ Component rules: - drawers for inspect/edit context - modals only for destructive confirmation or focused form tasks that must block +## Theming Strategy + +Theme modes: + +- `Light` +- `Dark` +- `System` + +Rules: + +- theme selection is available from the global app bar +- the chosen theme persists across sessions +- `System` is the default for first-time users +- both themes must feel deliberately designed, not algorithmically inverted +- all major surfaces in `Play`, `Tables`, `Curation`, and `Tools` must support both themes equally + +## Color System + +Principles: + +- accent color communicates brand and focus, not validation or danger +- semantic colors communicate outcome and risk +- color hierarchy supports scan speed but never becomes the only signal +- dense data surfaces use restrained color, not decorative color noise + +Required color roles: + +- neutral scale for backgrounds, surfaces, borders, and text +- one central accent ramp for brand, focus, selected state, and non-destructive emphasis +- success ramp for curated/success feedback +- warning ramp for caution, reset-risk, and disruptive-but-recoverable actions +- danger ramp for destructive and irreversible actions +- info ramp for tooling and system messaging when needed + +Rules: + +- accent color must remain distinct from success green, warning orange, and danger red +- accent should be moderately saturated, not loud +- semantic colors override accent when user risk must be communicated +- success green should be used for state and feedback, not as the default primary CTA color +- table symbols and effect badges must be checked against both themes to avoid collisions with system colors + +## Depth And Hierarchy + +Principles: + +- brightness helps communicate nesting, but it is a guide, not a universal law +- hierarchy is conveyed through brightness, border contrast, spacing, typography, and elevation together +- table canvases and other high-density data regions use fewer depth steps than inspectors, drawers, and forms + +Light mode guidance: + +- deeper or nested surfaces usually become slightly darker than their parent surface +- the page background stays brightest, then main surfaces, then nested cards, then inset wells + +Dark mode guidance: + +- deeper or nested surfaces usually become slightly brighter than their parent surface +- the page background stays darkest, then main surfaces, then nested cards, then inset wells + +Rules: + +- avoid stacking too many surface steps inside the table grid +- do not rely on background brightness alone to indicate nesting +- selected state must remain obvious even when surface-depth differences are subtle + +## CSS Variable Guidance + +Base token families: + +- `--bg-*` +- `--surface-*` +- `--text-*` +- `--border-*` +- `--focus-*` +- `--shadow-*` + +Accent token families: + +- `--accent-50` through `--accent-900` +- `--accent-solid` +- `--accent-contrast` +- `--accent-soft` +- `--accent-gradient-subtle` +- `--accent-gradient-strong` + +Semantic token families: + +- `--success-*` +- `--warning-*` +- `--danger-*` +- `--info-*` + +Rules: + +- gradients are optional support tokens, not the foundation of the UI +- subtle accent gradients may be used for shell-level highlights, primary CTAs, selected states, and hero surfaces +- gradients should not be used as the default fill for dense data regions, table cells, or most neutral panels +- component styling should consume semantic tokens by meaning, not by page + +## Button And Action Hierarchy + +Color and emphasis map to user consequence, not to database mutation as an implementation detail. + +Action levels: + +| Level | Purpose | Typical examples | Color behavior | +| --- | --- | --- | --- | +| Neutral | navigation and dismissal | `Back`, `Cancel`, `Close`, `Collapse` | neutral surface or ghost treatment | +| Soft accent | safe helper actions | `Calculate`, `Preview`, `Inspect`, `Jump`, `Open source` | low-to-medium emphasis with restrained accent | +| Strong accent | primary commit actions with expected positive outcome | `Save`, `Apply`, `Mark curated`, `Import`, `Confirm` | highest non-danger emphasis using accent ramp | +| Warning | risky but recoverable actions | `Reset fields`, `Replace`, `Bulk reparse` | amber/orange semantic treatment | +| Danger | destructive or irreversible actions | `Delete`, `Overwrite`, `Destructive reset` | red semantic treatment | + +Rules: + +- the strongest visible button on a surface should be the most likely intended action +- neutral actions should visually recede +- non-destructive helper actions should never compete with commit actions +- strong accent is for commitment, not for danger +- warning and danger styles must remain reserved for meaningful risk +- saturation and contrast increase with action consequence +- labels still carry the meaning; color reinforces it + +## Button Styling Rules + +- primary buttons use filled treatment +- secondary buttons use toned or outline treatment +- tertiary actions use ghost or text treatment +- the same action hierarchy must work in both light and dark themes +- disabled buttons reduce contrast and saturation but remain legible +- loading states preserve the original action color to avoid meaning shifts +- icon-only buttons are reserved for universally recognizable actions + ## Shared Interaction Model Every major page follows the same anatomy: @@ -318,6 +453,8 @@ Cell content rules: - branches summarized, not expanded by default - no full action button stack visible in every resting cell - state color is subtle in `Reference`, stronger in `Curate` +- theme changes must not reduce row/column legibility or active-cell contrast +- nested cell treatments should rely mostly on border, spacing, and focus, not stacked fills ## Cell Actions @@ -345,6 +482,7 @@ Rules: - second click on the selected cell opens inspect detail if needed - double-click is not a required behavior - touch uses the same one-tap select model +- action color follows the global action hierarchy: neutral for dismissal, soft accent for inspect/open, strong accent for save/mark curated, warning for risky bulk actions, danger only for destructive actions ## Inspector @@ -366,6 +504,7 @@ Rules: - can be pinned open or collapsed - keeps primary actions in the same vertical position - never requires opening the full editor just to understand the result +- nested inspector sections follow the theme depth rules with restrained surface stepping ## Reference Flow: Gamemaster @@ -439,6 +578,7 @@ Optimizations: - `Next uncurated` is always in the same spot - quick parse happens in the inspector or split pane before falling back to full editor - save keeps the cursor in the working lane and avoids re-opening context +- warning styling is reserved for disruptive repair actions; standard save-and-advance remains strong accent, not warning ## Diagnostics Flow: Developer @@ -472,6 +612,8 @@ Rules: - full editor opens in a focused drawer on wide screens and a full-screen sheet on small screens - no stacked modal-on-modal flows - save feedback is inline and immediate +- cancel and navigation actions remain neutral even inside forms +- destructive edit operations require danger styling and explicit confirmation ## Search and Deep Links @@ -510,6 +652,7 @@ Examples: - no hover-only discovery - sticky headers must not trap screen-reader or keyboard order - mobile hit targets minimum 44 by 44 px +- theme parity must preserve contrast and distinguish accent from semantic colors in both modes ## Content Rules