105 lines
4.8 KiB
Markdown
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.
|