Files
kandev/docs/audits/settings-typography/plan.md
T
2026-08-24 11:09:03 +00:00

105 lines
4.8 KiB
Markdown

# Settings typography improvement plan
Status: Reference audit plan
Formal spec: [../../specs/ui/requirements/settings-typography.md](../../specs/ui/requirements/settings-typography.md)
Canonical implementation plan: [../../plans/settings-typography/plan.md](../../plans/settings-typography/plan.md)
Related audit: [README.md](README.md)
## Goal
Create a predictable typography system for every settings page. Users should be
able to distinguish page titles, section titles, field labels, descriptions,
controls, status text, and technical values without each page inventing a
slightly different size or font family.
This plan preserves hierarchy. It does not make every settings string the same
size: each semantic role gets one default, with responsive changes only where
they improve readability or interaction.
## Design checkpoint
- Keep Figtree as the default settings UI family through the existing sans
token.
- Use the existing global or configured monospace family for technical values,
code, tokens, paths, and terminal content.
- Define shared roles for page headers, section/card titles, field labels,
descriptions, helper text, controls, metadata, badges, errors, and code.
- Keep line-height and color paired with each role so a size change does not
create a new one-off visual treatment.
- Use shared settings shells and field primitives instead of repeating local
`text-*` decisions across routes.
## Implementation phases
### 1. Agree on the role contract and inventory
Start with findings 001, 008, and 009. Turn the role map into named shared
tokens or primitives, document the intentional micro-type exceptions, preserve
semantic h2/h3 heading levels, and confirm which technical/editor surfaces use
monospace or existing editor tokens. Record the final decisions in the shared
settings UI guidance before migrating callers.
### 2. Unify page and card hierarchy
Implement findings 002 and 003. Consolidate the duplicated page-header styles
used by the general, system, profile, and workspace shells, including Utility
Agents, legacy Integrations, legacy executor profile routes, and long-name
wrapping. Include SSH, Users, Backups, API Token, and Storage Policy card
headers. Then align card and section titles and descriptions so comparable
settings surfaces have the same hierarchy.
### 3. Migrate fields, helpers, controls, and profiles
Implement findings 004 through 007. Introduce shared label, helper, error, and
control roles. Migrate account, system, preference, and profile forms,
including mobile model/mode selectors and profile-form errors. Remove the
agent-profile compact 10px helper treatment unless it is reclassified as a
deliberate metadata role that remains readable and documented. Migrate account
and system labels, dense-table rows, visible guidance, and primary errors.
### 4. Migrate workspace, provider, and technical surfaces
Implement findings 008 through 011. Apply the contract to workspace sections,
repository and integration forms, plugin/system metadata, code blocks, and the
PTY/Monaco editors. Keep technical values monospace, but do not let technical
styling change ordinary labels or descriptions by accident.
### 5. Verify and prevent regression
Implement findings 012 and 013. Extend computed-style coverage beyond Notifications to
representative preference, system, account, agent, workspace, and integration
routes. Add mobile assertions for semantic roles, anti-zoom control relations,
navigation/search ownership, notification event titles, system/account tables,
SSH cards, licenses, and editor rows where a desktop/mobile drift could
reappear. Keep the tests focused on role contracts rather than fragile
implementation class names.
## Mobile contract
- Preserve the same semantic roles and hierarchy on desktop and mobile.
- Keep navigation and controls at least 44px tall; do not use a smaller font as
a substitute for a touch target.
- Use the canonical `md`/768px responsive boundary for settings composition
changes unless a component has a documented reason to differ.
- Allow only deliberate responsive type changes, such as a compact navigation
label, and test them as role variants.
- Preserve one clear scroll owner and avoid typography changes that cause
clipped labels, cramped tablet layouts, or horizontal overflow.
## Tracking and validation
| Phase | Findings | Status |
| --- | --- | --- |
| Role contract and exceptions | 001, 008, 009 | Proposed |
| Page and card hierarchy | 002, 003 | Proposed |
| Fields, helpers, controls, profiles | 004, 005, 006, 007 | Proposed |
| Workspace, providers, technical surfaces | 008, 009, 011 | Proposed |
| Verification and regression protection | 010, 012, 013 | Proposed |
Before implementation is considered complete, run the focused settings unit
and Playwright tests, the web typecheck, and the i18n checks. Update each
finding's status and evidence in [README.md](README.md) as work lands.