Refine UX bible theming and action colors

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