# Design-system audit — September 4, 2026

Three parallel audits covered component structure, accessibility/interaction,
and visual hierarchy/responsiveness. The existing serif/monochrome direction and
unsaved local demos were preserved. No authentication or API behavior was changed.

## Findings resolved

- Extracted a shared `Field` for consistent native controls, labels, and hints;
  the Components specimen now matches the editor and color picker.
- Added configurable semantic heading levels to `Card`; Layout cards are h4
  beneath h3 groups, with appearance independent of heading level.
- Documented the eyebrow type role and introduced a shared medium-weight
  sans-serif role for compact interface headings.
- Replaced compressed annual heatmap cells (5.39px at a 480px viewport) with
  minimum 24px targets in a local horizontal scroller.
- Associated explicit scrolling and keyboard instructions with calendar controls.
- Corrected calendar focus when an editor rejects a selection or changes the
  visible month window; rejected requests cannot steal focus on later updates.
- Reveal the selected calendar date when a previously hidden panel opens or its
  viewport resizes, without stealing focus from the current control.
- Labeled task groups and restored useful focus after adding/removing tasks,
  with live feedback about draft changes.
- Linked editor hints and custom-color validation feedback programmatically.
- Enlarged counters, checkbox labels, month controls, and color choices to 44px.
- Added a higher-contrast shared control-boundary token.
- Allowed palette, spacing, form, toolbar, and chart content to wrap on narrow
  layouts; restored description line breaks and stacked split sections earlier.
- Added native checkbox rendering and visible state boundaries for forced colors.

## Verification

- Full typecheck, test suite, production build, and whitespace checks pass.
- Regression coverage includes semantic headings, Field IDs/hints, mounted-panel
  reference integrity, calendar focus rejection, shifting date windows, task
  focus, color validation, contrast tokens, and minimum target styles.
- Live browser: all seven tabs at 480px and 2560px had document width equal to
  viewport width. Calendar cells measured 24.11px after the change.
- Live interactions: form focus/hints/submission feedback and task add/remove
  focus were verified. The desktop preview reported no console errors/warnings.
- Verified all four calendar ranges, selected-date visibility after tab reveal,
  and matching keyboard focus/selection in the live desktop preview.
- The browser's native unsaved-change confirmation stalled the browser tool;
  rejection behavior was verified in component tests, not end-to-end through
  that dialog. Verification continued in a fresh preview.

The available browser viewport clamps at 480px, so 320px behavior and actual
screen-reader/forced-color rendering have not been manually certified. Responsive
rules and forced-color fallbacks have source-level regression coverage.


## Focused hierarchy and palette follow-up

- Increased `type-ui-heading` from 14/21 to 18/27 using a shared 1.125rem token.
  Specimen headings, component headings, field labels, task/schedule legends, and
  the habit-color legend share it. Supporting text remains 14/21; serif display,
  section, and component-title roles retain their existing sizes.
- Used 8px heading-to-caption spacing in component rows and calendar state keys.
- Removed redundant section introductions, repeated demo notices, and decorative
  encouragement beside working controls. Kept save/cancel, historical-edit,
  calendar keyboard, validation, and preview-scope guidance.
- Replaced ad hoc #737373/#888 with secondary, #777 with control-border, #333
  hover with secondary, and #f3f3f3/#ebebeb with the existing #f5f5f5 surface.
  Named the already-used surface and empty-calendar fills as `--ds-surface` and
  `--ds-empty`. All neutral CSS literals now live in the token declarations;
  calendar progress ramps and habit identity/custom colors are unchanged.
- Updated Foundations specimens and README role guidance alongside the styles.

Follow-up verification: typecheck, production build, all 123 tests (0 failures),
and `git diff --check` passed. A static production preview confirmed 18/27px
interface headings, 14/21px hints, and 8px field gaps. All seven tabs had document
width equal to the 480px viewport; sampled specimen headings, fields, and color
swatches had no internal overflow. Desktop Components and Editing fit at 1440px;
serif card titles remained 32px. Visually inspected desktop Components/Editing
and mobile Components/Layout/Editing. The name-preview submit and counter worked,
and the browser recorded no warnings or errors. The browser clamps requested
mobile widths below 480px, so narrower rendered widths remain unverified.

This follow-up preserved the pre-existing uncommitted work and did not modify
backend code, database state, or habit calculation behavior.