alex/headquarter
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
38d116dcf746be1608246bed94de45cef8d1c4d5
headquarter/openspec/proposals/web-ui-spacing-typography-rework.md
T

6.6 KiB
Raw Blame History

SDD Proposal: Web UI Spacing, Typography & Visual Rhythm Rework

Status

Phase: proposal
Date: 2026-06-16
Owner: el Gentleman
Based on: Scout audit ui-audit-spacing-typography.md

User Story

As a Headquarter user, I want the web UI to feel consistent, readable, and polished across desktop and mobile, so that I can navigate and manage workspaces, projects, and sessions without fighting cramped layouts, broken mobile views, or inconsistent spacing.

Problem Statement

A comprehensive audit of apps/web/src found systemic spacing, typography, margin, and visual-hierarchy issues:

  • Missing primitive styles: dozens of widely-used class names (.btn, .form-error, .alert, .badge, .mobile-detail-*, etc.) are referenced in TSX but have no CSS rules, causing broken or unstyled UI on multiple pages.
  • Completely unstyled mobile detail view: mobile-detail-view.tsx ships layout classes that do not exist in any stylesheet.
  • Mobile layout collisions: the bottom nav, start-tool FAB, and mobile edit sheets can overlap and do not account for safe-area insets.
  • Inconsistent design tokens: the token scale lacks border-radius, line-height, shadow, touch-target, and nav-height primitives. Mixed px/rem/em values and inline style={{...}} blocks bypass the token system.
  • Duplicated systems: two modal/dialog implementations, duplicated .form-field/.form-group patterns, duplicated status-badge/chip styles, and overlapping breakpoints (767px, 768px, 860px).
  • Heavy inline-style usage: editors and sidebars embed layout CSS directly in JSX, making responsive overrides and theming impossible.

This is not a single bug; it is a design-system hygiene issue that affects nearly every page.

Goals

  1. Establish a complete, single-source-of-truth token scale for spacing, typography, radius, shadow, line-height, touch targets, and layout heights.
  2. Add every missing primitive component style so that referenced classes actually render correctly.
  3. Fix mobile layout collisions by deriving FAB/bottom-sheet offsets from a shared nav-height token.
  4. Replace ad-hoc px/rem values and inline styles with token-based utility classes where feasible.
  5. Consolidate duplicated patterns: one modal/dialog system, one form-field pattern, one status-badge family, one card family.
  6. Standardize breakpoints to the existing token scale (--bp-sm, --bp-md, --bp-lg, --bp-xl).
  7. Leave the UI visually improved without changing behavior or user-facing features.

Non-Goals

  • No new user-facing features or workflows.
  • No changes to backend APIs, database schema, or authentication.
  • No redesign of the information architecture or navigation structure.
  • No replacement of Tailwind or CSS-modules; we stay in the existing global-CSS architecture.
  • No runtime theme-engine rewrite; light/dark tokens remain as-is.

High-Level Approach

Split the work into three reviewable passes to stay under the 400-line review budget:

Pass 1: Foundations (P0)

  • Expand tokens.css with missing primitives.
  • Add missing primitive classes to global.css/utilities.css (buttons, alerts, errors, badges, form inputs, loading states, checkbox labels, hints, mobile detail view, etc.).
  • Introduce --mobile-nav-height and fix FAB/bottom-sheet/shell-content collisions.
  • Fix the most critical inline font-size violations (0.7rem → tokens).
  • Add focused :focus visibility to interactive controls.

Pass 2: Component Cleanup (P1)

  • Refactor the highest-volume inline-style offenders into utility classes:
    • manifest-editor.tsx
    • ConfigProfileEditorPanel.tsx
    • ToolTypeEditorPanel.tsx
    • ToolTypeListSidebar.tsx
    • ConfigProfileListSidebar.tsx
    • git-mount-editor.tsx
  • Replace hardcoded 280px sidebars with --sidebar-width token.
  • Unify .form-field/.form-group and migrate callers.
  • Consolidate status badges/chips into a single .status-badge family.

Pass 3: Consolidation & Polish (P2)

  • Deprecate .modal-* in favor of .dialog-* and migrate callers.
  • Consolidate card patterns across page CSS files into global.css modifiers.
  • Standardize breakpoints to --bp-* tokens and remove the 860px one-off.
  • Add token documentation and a lightweight review checklist.

Open Questions

  1. Which pass should include the mobile detail view styles?
    • Recommendation: Pass 1, because it is currently broken.
  2. Should we keep the existing .utilities.css naming convention or introduce BEM-style modifiers (.card--elevated, .status-badge--error)?
    • Recommendation: introduce BEM-style modifiers only for the new consolidated families; keep existing utilities untouched to minimize churn.
  3. Is the terminal page's hardcoded dark palette acceptable long-term, or should it become theme-aware?
    • Recommendation: keep terminal colors hardcoded for now; only convert spacing to tokens.
  4. Should we add a lint rule to block new inline style={{...}} layout declarations?
    • Recommendation: add a code-review checklist in Pass 3, not a blocking lint rule, to avoid false positives.

Risks

Risk Severity Mitigation
Large diff touching many files High Split into three chained PRs; each under 400 changed lines.
Visual regressions on pages not manually tested Medium Rely on typecheck/lint for TSX; do visual spot-checks on representative pages.
Inline-style refactor breaks dynamic values Medium Only refactor static layout styles; keep dynamic values (computed positions) in JS.
Token changes affect existing components unexpectedly Medium Add new tokens only; do not rename existing tokens without a compat layer.
Mobile safe-area behavior varies across devices Medium Use env(safe-area-inset-bottom, 0px) with a sensible fallback.

Effort Estimate

Pass Focus Est. Files Est. Lines Complexity
Pass 1: Foundations tokens, missing primitives, mobile nav/FAB 4–6 ~400 Medium
Pass 2: Component Cleanup inline styles, sidebars, forms, badges 10–14 ~600 High
Pass 3: Consolidation modals, cards, breakpoints, docs 8–12 ~400 Medium
Total 22–32 ~1400 High

Review workload forecast: Each pass should stay near or below the 400-line review budget. Pass 2 may need to be split further if it grows.

Next Recommended Phase

Spec — detail the exact token additions, primitive class API, mobile-nav height calculation, and the migration path for inline styles.

Should I proceed to spec?

Reference in New Issue View Git Blame Copy Permalink