generated from john/python-template
112 lines
4.8 KiB
Markdown
112 lines
4.8 KiB
Markdown
# UI Style Guide (Invariant)
|
|
|
|
## 1. Purpose
|
|
This guide defines non-negotiable UI styling rules for the transcription application.
|
|
|
|
The design system is token-first and class-driven:
|
|
1. Theme tokens are defined in [src/transcription/ui/static/theme.css](src/transcription/ui/static/theme.css).
|
|
2. Python UI code composes semantic classes instead of inline color values.
|
|
3. Pages and components should share a single visual language across Documents, Jobs, People, and Sources flows.
|
|
|
|
## 2. Source of Truth
|
|
Use these files as the style authority:
|
|
1. [src/transcription/ui/static/theme.css](src/transcription/ui/static/theme.css) for color tokens, semantic utility classes, table styles, and viewer surfaces.
|
|
2. [src/transcription/ui/theme.py](src/transcription/ui/theme.py) for runtime NiceGUI theme bridge and shared UI helpers.
|
|
|
|
If this document conflicts with implementation, update this document to match the code immediately after intentional style changes.
|
|
|
|
## 3. Core Design Invariants
|
|
1. Flat, high-density surfaces over decorative depth.
|
|
2. Strong content hierarchy with subdued backgrounds and border-based separation.
|
|
3. Viewer area remains the highest contrast region in image/transcription workflows.
|
|
4. Primary actions are consistent and visually recognizable.
|
|
5. Accessible focus rings are always visible for keyboard users.
|
|
|
|
## 4. Token System
|
|
|
|
### 4.1 Palette Tokens
|
|
Base palette variables live under :root in [src/transcription/ui/static/theme.css](src/transcription/ui/static/theme.css):
|
|
1. --palette-carbon-black: #1c2321
|
|
2. --palette-cool-steel: #7d98a1
|
|
3. --palette-blue-slate: #5e6572
|
|
4. --palette-powder-blue: #a9b4c2
|
|
5. --palette-platinum: #eef1ef
|
|
|
|
### 4.2 Semantic Theme Tokens
|
|
Do not style components directly with palette tokens when a semantic token exists.
|
|
|
|
Semantic tokens currently include:
|
|
1. --theme-text and --theme-text-muted
|
|
2. --theme-page, --theme-surface, --theme-surface-raised, --theme-surface-muted
|
|
3. --theme-border
|
|
4. --theme-primary and --theme-primary-hover
|
|
5. --theme-secondary and --theme-focus
|
|
6. --theme-inverse-text
|
|
7. --theme-viewer, --theme-viewer-border, --theme-viewer-muted
|
|
|
|
## 5. Approved Semantic Classes
|
|
|
|
### 5.1 Text and Background
|
|
1. ui-text-primary
|
|
2. ui-text-muted
|
|
3. ui-text-inverse
|
|
4. ui-bg-page
|
|
5. ui-bg-surface
|
|
6. ui-bg-surface-raised
|
|
7. ui-bg-surface-muted
|
|
8. ui-bg-viewer
|
|
9. ui-bg-viewer-overlay
|
|
10. ui-bg-viewer-overlay-soft
|
|
|
|
### 5.2 Borders and Surfaces
|
|
1. ui-border-subtle
|
|
2. ui-border-viewer
|
|
3. ui-header-divider
|
|
4. ui-card-surface
|
|
5. ui-row-surface
|
|
6. ui-note-box
|
|
|
|
### 5.3 Interactive Elements
|
|
1. ui-btn-primary
|
|
2. ui-btn-secondary
|
|
3. ui-link-primary
|
|
4. ui-text-accent
|
|
|
|
### 5.4 Table Patterns
|
|
1. ui-table
|
|
2. ui-table-header
|
|
3. ui-table-body
|
|
|
|
Use existing class combinations from [src/transcription/ui/components](src/transcription/ui/components) and [src/transcription/ui/pages](src/transcription/ui/pages) as reference implementations.
|
|
|
|
## 6. Legacy Class Policy
|
|
Legacy classes with vibe- prefix still exist in a few components and are allowed only for compatibility while migrating:
|
|
1. Existing usage may remain temporarily.
|
|
2. New usage of vibe- classes is not allowed.
|
|
3. When touching a file that uses vibe- classes, prefer migrating it to ui- semantic classes in the same change when safe.
|
|
|
|
Current legacy usage examples are in:
|
|
1. [src/transcription/ui/components/document_panzoom.py](src/transcription/ui/components/document_panzoom.py)
|
|
2. [src/transcription/ui/components/error_presenter.py](src/transcription/ui/components/error_presenter.py)
|
|
3. [src/transcription/ui/components/transcript.py](src/transcription/ui/components/transcript.py)
|
|
|
|
## 7. Prohibited Patterns
|
|
1. Inline hex colors in Python UI class strings or style blocks, except in isolated bridge code explicitly marked for migration.
|
|
2. Ad-hoc one-off class names that duplicate existing semantic class intent.
|
|
3. Page-specific palette forks that bypass theme tokens.
|
|
4. Hidden or low-contrast focus states on interactive controls.
|
|
|
|
## 8. Implementation Rules For Contributors
|
|
1. Prefer composing existing semantic classes before creating new ones.
|
|
2. If a new class is required, add it to [src/transcription/ui/static/theme.css](src/transcription/ui/static/theme.css) with a semantic name, then reuse it.
|
|
3. Keep behavior ownership in Python and appearance ownership in CSS.
|
|
4. Update UI tests that assert exact text or labels when intentional copy changes are made.
|
|
5. Avoid introducing class churn unrelated to the feature being changed.
|
|
|
|
## 9. Verification Checklist
|
|
Before merging UI changes, verify:
|
|
1. No new inline hex colors were introduced in UI pages/components.
|
|
2. New styles are token-backed and added to [src/transcription/ui/static/theme.css](src/transcription/ui/static/theme.css).
|
|
3. Primary buttons, links, cards, and tables still render with consistent semantics.
|
|
4. Keyboard focus ring visibility is preserved.
|
|
5. Relevant UI and integration tests pass. |