lorentz/wulf-pulse
1
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions

docs(08): fix UI-SPEC checker failures — typography and spacing

Browse source 
- Collapse 6 font sizes to 4 (12, 14, 20, 24px): promote display name
  from text-lg (18px) to text-xl (20px); promote avatar initials and
  period chip text from text-[10px] to text-xs (12px)
- Remove non-standard "Additional fixed sizes" block; contract now
  declares exactly 4 canonical sizes
- Drop font-medium (500); breakdown subsection headers move to
  font-semibold (600) — two weights only: 400 + 600
- Replace py-1.5 (6px) with py-2 (8px) throughout breakdown rows;
  note D-16 override with rationale; clarify min-h-[44px] as WCAG
  floor only (not a spacing/padding value)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
lorentz 2026-05-07 17:48:10 -04:00
parent 725fe731ca
commit 80bb9495fc
1 changed files with 19 additions and 16 deletions
Download patch file Download diff file Expand all files Collapse all files

35
.planning/phases/08-engagement-user-profile-new/08-UI-SPEC.md
View file

@ -5,6 +5,8 @@ status: draft
shadcn_initialized: true
preset: "new-york / neutral base / cssVariables: true / Tailwind v4"
created: 2026-05-07
revised: 2026-05-07
revision: 1
---
# Phase 8 — UI Design Contract
@ -36,7 +38,7 @@ Declared values (multiples of 4 only). Reuses Phase 7 established tokens.
| Token | Value | Usage |
|-------|-------|-------|
| xs | 4px | Inline gaps (`gap-1`, `mt-1`), icon-to-text padding |
| sm | 8px | Compact element spacing (`gap-2`, `mt-2`, `space-y-2`) |
| sm | 8px | Compact element spacing (`gap-2`, `mt-2`, `space-y-2`), activity breakdown metric row vertical padding (`py-2`) |
| md | 16px | Default card padding (`px-4`, `py-4`), section padding |
| lg | 24px | Section separation (`space-y-6`), card-to-card gap |
| xl | 32px | Major vertical rhythm between page sections |
@ -45,30 +47,31 @@ Declared values (multiples of 4 only). Reuses Phase 7 established tokens.
Exceptions:
- Avatar: `h-14 w-14` (56px) for identity header — larger than standard row avatar (`h-8 w-8`) to carry header weight
- Row list items: `py-1.5` (6px) vertical padding inside breakdown card metric rows (matches CONTEXT.md D-16 spec)
- Period chip strip: `min-h-[44px]` touch target (matches `EngagementPeriodChips` existing implementation)
- Period chip strip: `min-h-[44px]` touch target floor for WCAG compliance — declared as `min-h` only, never as padding or gap (matches `EngagementPeriodChips` existing implementation)
- Sticky chip bar: `-mx-4 px-4` bleed-to-edge pattern (matches Phase 7 component exactly)
Source: CONTEXT.md D-11, D-16; Phase 7 `EngagementSummaryCard.tsx`, `EngagementUserRow.tsx`
> **D-16 override:** CONTEXT.md D-16 specified `py-1.5` (6px) for metric row vertical padding. This contract supersedes that to `py-2` (8px) — the nearest 4px-grid value. The 2px difference is visually equivalent at row-list scale. Engineers implementing the breakdown card should use `py-2` throughout. The 44px `min-h` touch target on chips is a WCAG floor and is exempt from the 4px grid constraint.
Source: CONTEXT.md D-11, D-16 (overridden as noted above); Phase 7 `EngagementSummaryCard.tsx`, `EngagementUserRow.tsx`
---
## Typography
Four sizes, two weights. Matches Phase 7 established token set exactly.
Four sizes, two weights. Matches Phase 7 established token set with the adjustments noted below.
| Role | Size | Weight | Line Height | Usage |
|------|------|--------|-------------|-------|
| Display | 24px (`text-2xl`) | 600 (`font-semibold`) | none (leading-none) | Hero metric numbers in 2×2 grid |
| Title | 20px (`text-xl`) | 600 (`font-semibold`) | 1.2 | Page H1 (user display name), section H1 (page title) |
| Body | 14px (`text-sm`) | 400 (`font-normal`) | 1.5 | Activity breakdown metric rows, recent-entry row text |
| Label | 12px (`text-xs`) | 400 (`font-normal`) | 1.5 | Card section sub-labels, metric labels under hero numbers, relative timestamps |
| Heading | 14px (`text-sm`) | 500 (`font-medium`) | 1.5 | Breakdown card subsection headers (`text-sm font-medium text-muted-foreground`) |
| Label | 12px (`text-xs`) | 400 (`font-normal`) | 1.5 | Card section sub-labels, metric labels under hero numbers, relative timestamps, avatar initials, period chip text |
Additional fixed sizes (from existing components, do not change):
- Avatar initials: `text-[10px] font-semibold` — inherits from `EngagementUserRow` pattern
- Period chips: `text-[10px] font-semibold` — inherits from `EngagementPeriodChips`
- User display name in identity header: `text-lg font-semibold` (one step above body, carries identity weight)
- Section H1 (page title): `text-xl font-semibold` (matches Phase 7 overview H1 pattern)
> **Typography revision notes (r1):**
> - The user display name in the identity header was previously declared as `text-lg` (18px). It is now `text-xl` (20px), unifying with the page H1 role. The 2px upward change strengthens identity hierarchy and eliminates a fifth size.
> - The Heading role (breakdown card subsection headers) was previously `font-medium` (500). It is now `font-semibold` (600) to hold to a two-weight system. The `text-muted-foreground` colour still softens the visual weight so headers do not feel heavy.
> - Avatar initials and period chip text were previously declared as `text-[10px]` (non-standard). They are promoted to `text-xs` (12px). The 2px change is imperceptible at that scale and removes a non-standard token.
> - Any Phase 7 component that currently renders `text-[10px]` (avatar initials in `EngagementUserRow.tsx`) or `text-lg` should be updated by the implementing engineer to match this contract.
Source: CONTEXT.md D-11, D-16; `EngagementSummaryCard.tsx`, `EngagementUserRow.tsx`, `EngagementPeriodChips.tsx`
@ -140,7 +143,7 @@ Single-column, `'use client'`, phone-first. No sidebars, no multi-column layouts
app/mobile/engagement/[userId]/page.tsx
│
├── <main class="px-4 pb-safe"> (scrollable, bottom padding for nav)
│ ├── <h1> User display name — page title
│ ├── <h1> User display name — text-xl font-semibold
│ ├── EngagementPeriodChips sticky top-0, z-10, edge-to-edge bleed
│ ├── EngagementProfileHeader identity card (avatar + fields)
│ ├── EngagementProfileMetricGrid 2×2 grid, gap-3
@ -157,7 +160,7 @@ app/mobile/engagement/[userId]/page.tsx
**2×2 metric grid**: `grid grid-cols-2 gap-3`
**Activity breakdown subsections**: separated by `border-t border-border` inside the single card, no extra padding headers — just `text-sm font-medium text-muted-foreground mb-2` label followed by metric rows.
**Activity breakdown subsections**: separated by `border-t border-border` inside the single card, no extra padding headers — just `text-sm font-semibold text-muted-foreground mb-2` label followed by metric rows (`flex justify-between text-sm py-2`).
---
@ -172,7 +175,7 @@ app/mobile/engagement/[userId]/page.tsx
### Avatar/photo loading
- `<img src="/api/mobile/engagement/user/[userId]/photo" ...>` with `onError` fallback to initials `<span>`
- Initials rendered in `h-14 w-14 rounded-full bg-muted` with `text-base font-semibold text-foreground`
- Initials rendered in `h-14 w-14 rounded-full bg-muted` with `text-xs font-semibold text-foreground`
- Photo rendered as `h-14 w-14 rounded-full object-cover`
- No FOUC: render initials immediately, upgrade to photo on load success
@ -266,7 +269,7 @@ No third-party registries. `registries: {}` confirmed in `components.json`.
- Collapsible trigger buttons include visible text label (entry date + hours) — no icon-only triggers
- Metric rows in breakdown card: use `<dl>` / `<dt>` / `<dd>` semantics or `flex justify-between` with visible labels — avoid value-only spans
- Email link: `<a href="mailto:{email}" className="text-primary underline-offset-4 hover:underline">`
- Touch targets: all interactive elements (chips, expand triggers, links) meet 44px minimum height
- Touch targets: all interactive elements (chips, expand triggers, links) meet 44px minimum height via `min-h-[44px]`
---