Files
kandev/docs/specs/settings-typography/spec.md
T
2026-08-16 19:18:21 +00:00

135 lines
7.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
status: building
created: 2026-08-16
owner: Kandev frontend
---
# Consistent settings typography
## Why
Settings pages currently make equivalent content look different. Users move
between labels, helpers, cards, provider forms, and system pages without a
stable visual hierarchy, and narrow screens amplify the problem through
cramped actions, small controls, and inconsistent wrapping.
## What
- Settings pages SHALL use a shared semantic typography contract for page
titles, page descriptions, section headings, card titles, field labels,
helpers, errors, controls, metadata, badges, and technical values.
- The settings contract SHALL preserve the existing application sans family
for normal UI copy and SHALL use the global or configured monospace family
for technical values such as paths, identifiers, tokens, code, logs, and
terminal/editor content.
- Page headers SHALL expose one page-level heading and description per route.
Section headings and card headings SHALL preserve the document's semantic
hierarchy instead of relying on visual classes alone. Card titles SHALL be
rendered as an appropriate heading element when the card represents a
titled content section.
- Equivalent settings cards SHALL share one title, description, weight, and
line-height role. Card titles SHALL remain visually distinct from their
metadata and helper text.
- Equivalent form fields SHALL share one label role, helper role, error role,
and control role. Primary labels SHALL not use muted helper styling unless a
documented metadata variant applies.
- Page and section descriptions SHALL use the readable description role. Field
helpers SHALL use the compact readable helper role. Primary user-facing
errors SHALL remain readable, while inline technical diagnostics MAY use a
documented compact status role.
- Editable controls SHALL preserve the existing coarse-pointer anti-zoom
behavior. Mobile selectors, buttons, standalone actions, and navigation rows
SHALL provide an active hitbox of at least 44px unless an explicitly
documented compact chrome exception applies.
- Settings composition SHALL use the canonical `md`/768px boundary for
mobile/tablet layout changes unless a component documents a different
boundary. Mobile layouts SHALL stack or wrap title/action groups when the
available width would squeeze labels or descriptions.
- Long translated, pseudo-locale, profile-name, path, and provider strings
SHALL wrap or truncate within their owning surface without document-level
horizontal overflow.
- Provider credential/value fields SHALL use one documented family and size
role across GitHub, GitLab, Jira, Linear, Azure DevOps, and Sentry.
- Micro-type SHALL be limited to documented metadata, badges, counts, dense
technical tables, code, logs, and similar specialized surfaces. It SHALL NOT
be used for ordinary field labels, explanatory helpers, or primary errors.
- Existing settings behavior, routes, permissions, state, mutations, and
translated message keys SHALL remain unchanged. Translation lookup SHALL
continue at render time.
- The shared contract SHALL be verified on representative preference,
agent/executor, workspace/provider, system, account, SSH, terminal/editor,
and mobile navigation surfaces.
## Initial role contract
These are the starting roles for implementation. A role may have a named
responsive variant, but pages SHALL not introduce ad hoc values for the same
role.
| Role | Starting treatment | Notes |
| --- | --- | --- |
| Page title | 24px, bold, `h2` | One per settings route |
| Page description | 14px, muted, relaxed line height | Readable explanatory copy |
| Section heading | 18px, semibold, `h3` | Section actions stack on narrow widths |
| Card title | 16px, semibold, semantic heading | Heading level follows containment |
| Field label | 12px, medium, foreground | Compact variant must be explicit |
| Field helper | 12px, muted, relaxed line height | Not smaller than ordinary help |
| Primary error | 14px, destructive, readable line height | Inline technical diagnostics may be compact |
| Control value | One settings control variant | Editable phone controls retain anti-zoom sizing |
| Mobile action/navigation | Minimum 44px active hitbox | Font size does not replace touch geometry |
| Metadata/badge | Named 10–12px roles | No arbitrary 9/10/11px repeats |
| Technical value | Mono with named size role | Paths, IDs, tokens, code, logs, terminals |
## Scenarios
- **GIVEN** a top-level settings route on desktop, **WHEN** the page renders,
**THEN** it shows one page title and description using the page-header roles,
followed by section and card content with a stable hierarchy.
- **GIVEN** the same settings route on a Pixel 5 viewport, **WHEN** the page
renders, **THEN** the same capabilities remain reachable, title/action groups
stack or wrap intentionally, and primary controls meet the 44px hitbox rule.
- **GIVEN** a settings viewport between 640px and 767px, **WHEN** a section
contains actions or add-row controls, **THEN** the canonical mobile/tablet
composition prevents cramped side-by-side content and horizontal overflow.
- **GIVEN** equivalent cards from Preferences, Agents, Executors, Workspace,
System, and Account, **WHEN** their titles and descriptions render, **THEN**
they use the same settings card roles and appropriate semantic headings.
- **GIVEN** a form field with a label, helper, and validation error, **WHEN** it
renders in account, profile, provider, workspace, or system settings,
**THEN** each piece uses its shared role and the label is not visually
downgraded to helper text.
- **GIVEN** a provider credential field, **WHEN** GitHub, GitLab, Jira, Linear,
Azure DevOps, and Sentry forms render, **THEN** equivalent credential values
use the same documented family and size treatment.
- **GIVEN** a long translated label, description, profile name, path, or
pseudo-locale string, **WHEN** it renders on desktop, tablet, or phone,
**THEN** it wraps or truncates within its surface without clipping or
document-level horizontal scrolling.
- **GIVEN** a technical path, token, identifier, code block, log, terminal, or
editor value, **WHEN** it renders, **THEN** it retains an intentional
monospace/technical role without changing neighboring ordinary copy.
- **GIVEN** the combined Terminal Editors route, **WHEN** it renders, **THEN**
it has one page-level title and separate section-level headings rather than
a second page title nested halfway down the page.
- **GIVEN** Notifications and representative system/account/SSH/editor
surfaces, **WHEN** computed-style tests run on desktop and mobile, **THEN**
the tested semantic roles match the contract and remain covered against
future drift.
## Out of scope
- Changing settings behavior, APIs, state management, permissions, persistence,
or route information architecture beyond consolidating duplicate visual
headers.
- Changing the global `@kandev/ui` typography contract for unrelated consumers.
- Rewriting translated content except for punctuation corrections required by
the existing user-facing copy rules.
- Removing intentional technical/code/query/YAML/script/status typography
exceptions.
- Introducing a new theme, color system, or general application-wide design
system.
## Implementation plan
See [docs/plans/settings-typography/plan.md](../../plans/settings-typography/plan.md).