transcription/docs/invariant/ui_style_guide.md

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.
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 for color tokens, semantic utility classes, table styles, and viewer surfaces.
2. 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:

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 and 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
2. src/transcription/ui/components/error_presenter.py
3. 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 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.
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.