From 80bb9495fcad84771fce0eb8a3f434cd14181de7 Mon Sep 17 00:00:00 2001 From: lorentz Date: Thu, 7 May 2026 17:48:10 -0400 Subject: [PATCH] =?UTF-8?q?docs(08):=20fix=20UI-SPEC=20checker=20failures?= =?UTF-8?q?=20=E2=80=94=20typography=20and=20spacing?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- .../08-UI-SPEC.md | 35 ++++++++++--------- 1 file changed, 19 insertions(+), 16 deletions(-) diff --git a/.planning/phases/08-engagement-user-profile-new/08-UI-SPEC.md b/.planning/phases/08-engagement-user-profile-new/08-UI-SPEC.md index 39b340e..72f3953 100644 --- a/.planning/phases/08-engagement-user-profile-new/08-UI-SPEC.md +++ b/.planning/phases/08-engagement-user-profile-new/08-UI-SPEC.md @@ -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 │ ├──
(scrollable, bottom padding for nav) -│ ├──

User display name — page title +│ ├──

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 - `` with `onError` fallback to initials `` -- 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 `
` / `
` / `
` semantics or `flex justify-between` with visible labels — avoid value-only spans - Email link: `` -- 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]` ---