luckberg/familysync
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e0fb34b2522fed79ff26ea88d14f034ae0e66e2e
familysync/.planning/phases/02-calendar-display/02-UI-SPEC.md
T

19 KiB
Raw Blame History

phase, slug, status, shadcn_initialized, preset, created
phase slug status shadcn_initialized preset created
2 calendar-display draft false none 2026-06-04

Phase 2 — UI Design Contract

Calendar Display

Visual and interaction contract for Phase 2. Generated by gsd-ui-researcher. Verified by gsd-ui-checker before execution begins.

Design System

Property Value
Tool none (shadcn not yet initialized)
Preset not applicable
Component library none — custom components against token layer
Icon library lucide-react (lightweight, tree-shakeable, first-party React SVGs; consistent stroke style)
Font system-ui stack: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif

Note: No components.json exists in the PWA app. The Phase 1 shell uses inline styles. Phase 2 introduces a CSS custom-property token layer (see § Token Layer below) as the primary design system primitive. shadcn may be added in Phase 3 when form components are needed.

Token Layer

This is the load-bearing deliverable of Phase 2 (D-01, D-02). All component styles MUST be written against these tokens. No hard-coded hex values or px measurements in component files.

File location

apps/pwa/src/styles/tokens.css       — CSS custom properties (the "clean" theme)
apps/pwa/src/styles/tokens.ts        — TypeScript token object (mirrors tokens.css)
apps/pwa/src/styles/index.css        — imports tokens.css; global resets; base body styles

Import tokens.css once in main.tsx. Components import from tokens.ts for inline style props; they use var(--token-name) in CSS Modules or className strings.

Calendar config constant

// apps/pwa/src/lib/calendarConfig.ts
export const WEEK_START_DAY = 0  // 0 = Sunday; flip to 1 = Monday with one edit

Pass to Schedule-X's firstDayOfWeek option. Do not hardcode 0 anywhere else.

Color Tokens

Base palette

Token Hex Role
--color-surface #FFFFFF Page background, calendar grid cells
--color-surface-dim #F7F7F8 Off-white wash: week/day off-hours bands, modal backdrop
--color-surface-raised #FFFFFF Cards, popovers (shadow provides elevation)
--color-border #E2E4E9 Grid lines, dividers, input borders
--color-border-subtle #ECEEF2 Secondary separators
--color-text-primary #111318 Body text, event titles
--color-text-secondary #6B7280 Meta text: times, locations, legend labels
--color-text-muted #9CA3AF Placeholder, empty-state body, disabled
--color-focus-ring #4A90D9 Keyboard focus outline (3px, 2px offset)
--color-overlay rgba(0,0,0,0.32) Popover backdrop scrim

Semantic calendar colors

These are the ONLY colors used for event fills. All are derived from member records (users.color) or the reserved shared-family constant.

Token Hex Assigned to Source
--color-member-0 #4A90D9 Lucas (member 1) Phase-1 users.color
--color-member-1 #50C878 Wife (member 2) Phase-1 users.color
--color-member-2 #F5A623 Slot 3 (future) Phase-1 palette
--color-member-3 #9B59B6 Slot 4 (future) Phase-1 palette
--color-member-4 #E67E22 Slot 5 (future) Phase-1 palette
--color-member-5 #1ABC9C Slot 6 (future) Phase-1 palette
--color-shared-family #F25C7A Shared-family calendar (ALL members) Confirmed by user

Implementation note: The calendars configuration object passed to Schedule-X is built dynamically at runtime by mapping users.color values to Schedule-X lightColors.main. The --color-member-* tokens are the canonical source; the Schedule-X config derives from them. The shared-family calendar always uses #F25C7A regardless of any user row.

Color derivation rule for event chips

For each member color MAIN, derive:

Sub-token suffix Derivation Usage
container MAIN at 15% opacity over white Event chip background
onContainer MAIN darkened 40% Event chip text, passed to Schedule-X

These need not be pre-declared for every slot — compute them with a small utility function (colorTokens.ts) at runtime using CSS Color Level 4 or a tiny LCH/hex math helper.

60 / 30 / 10 split

Band Tokens Approximate coverage
60% dominant (surface) --color-surface, --color-surface-dim Calendar grid, page background
30% secondary (structure) --color-surface-raised, --color-border, --color-border-subtle Cards, nav bar, header, popover shells
10% accent --color-shared-family + per-member fills Event chips only

Accent reserved for: event chip fills and the color legend swatches. Accent colors MUST NOT appear on buttons, nav items, headings, or any chrome element.

Destructive

Token Hex Usage
--color-destructive #DC2626 Not used in Phase 2 (read-only). Token declared for Phase 3 reuse.

Spacing Scale

All values are multiples of 4px. Use tokens; never write raw px values in components.

Token Value CSS var Usage
space-1 4px --space-1 Icon gap, badge dot, tight inline padding
space-2 8px --space-2 Event chip inner padding (vertical), color legend row gap
space-3 12px --space-3 Event chip inner padding (horizontal), compact cell padding
space-4 16px --space-4 Default element spacing, popover section gap
space-6 24px --space-6 Section padding, nav bar height rhythm
space-8 32px --space-8 Layout gaps, popover width gutter
space-12 48px --space-12 Major section breaks

Exceptions:

  • Touch targets: minimum 44px height/width on interactive elements (iOS HIG). This is a layout constraint, not a spacing token. Apply via min-height: 44px.
  • Calendar header row height: 48px (--space-12 used as a layout constant).
  • View toolbar height: 48px on phone; 56px on tablet/desktop.

Typography

Font family token: --font-family-base: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif

Role Token Size Weight Line Height Usage
Body --text-body 15px 400 1.5 Popover description, agenda location lines
Label --text-label 13px 400 1.4 Event chip text, time labels, legend labels, secondary meta
Heading --text-heading 18px 600 1.25 Popover title, view section headers (month name + year)
Display --text-display 24px 600 1.2 App name in nav bar (desktop), day number in day-view header

Weights declared: 400 (regular) and 600 (semibold). No other weights permitted.

Day-number size in month grid: 13px label weight. Current day: semibold (600) + colored dot.

Breakpoints

These are the only three breakpoints. Reference them by name in code, never by raw px value.

Name Token Min width Default view Notes
phone --bp-phone 0px Agenda Stacked single-column layout
tablet --bp-tablet 768px Month Two-column possible; nav becomes persistent sidebar
desktop --bp-desktop 1280px Month Full grid width

View default logic (D-05):

const isMobile = window.matchMedia('(max-width: 767px)').matches
const defaultView = isMobile ? 'month-agenda' : 'month-grid'

Last-used view is persisted in Zustand and localStorage, keyed by breakpoint group ('phone' | 'tablet-desktop').

Calendar Rendering Library

Selected: Schedule-X (@schedule-x/react + @schedule-x/calendar)

Rationale:

  • Supports all four required views natively: createViewDay, createViewWeek, createViewMonthGrid, createViewMonthAgenda (agenda).
  • Theming via CSS custom properties — its --sx-color-* vars are overridden by mapping to this spec's token values in tokens.css. No Schedule-X default stylesheet bleeds through.
  • Per-calendar color is first-class (calendars config with lightColors.main / container / onContainer) — maps directly to per-member users.color and the shared-family rose.
  • onRangeUpdate callback fires when the user navigates, enabling TanStack Query to fetch only the visible window from /api/events?start=&end=.
  • Custom eventModal component via customComponents prop — the read-only detail popover is fully owned by this codebase and reusable as the Phase-3 edit surface (D-08).
  • React adapter ships as a first-class package; no wrapper hacks needed.
  • Active maintenance; Temporal-polyfill based (aligns with modern date handling).

Rejected alternatives:

  • react-big-calendar: opinionated CSS (hard to token-ify without !important fights); unmaintained moment / date-fns localization coupling; weak agenda view.
  • FullCalendar: commercial license for premium features; React package adds ~140 KB gzip.
  • Custom grid: correct for simple month-only, but building reliable day/week/agenda from scratch in one phase introduces unacceptable schedule risk.

Schedule-X CSS override strategy: Import @schedule-x/theme-default/dist/index.css, then immediately override all --sx-color-* vars in tokens.css to match this spec's surface/border/text tokens. Result: Schedule-X internal layout engine works; all colors come from this spec's tokens.

Component Inventory

CalendarShell

Top-level layout wrapper.

  • <AppNav> (top bar on phone; left sidebar 240px on tablet/desktop)
  • <ViewToolbar> (Today button, prev/next arrows, date label, view switcher)
  • <ColorLegend> (member → color; always visible on tablet/desktop; collapsible on phone)
  • <ScheduleXCalendar> (fills remaining space)

AppNav

  • Phone: top bar, 48px height, app name left, user avatar/color swatch right
  • Tablet/Desktop: left sidebar, 240px width; app name + color legend + (future) nav items

ViewToolbar

  • Buttons: Today | < | > | [Day] [Week] [Month] [Agenda]
  • Font: 13px label weight
  • Active view button: --color-member-0 (Lucas, current user) background at 12% opacity, semibold label. (Accent not used — active state uses a subtle surface tint.)
  • Touch targets: 44px minimum height

ColorLegend

  • One row per member: color swatch (12px circle) + display name
  • Shared-family row: rose swatch + "Family" label
  • Font: 13px label weight, --color-text-secondary
  • Always rendered; never interactive in Phase 2 (show/hide filter deferred)

EventChip (month grid)

  • Rounded pill, 4px radius
  • Background: member container color (15% opacity)
  • Text: member onContainer color, 13px, weight 400, single line, truncated with ellipsis
  • Left 3px solid border: member main color (the users.color hex directly)
  • Minimum height: 20px; minimum tap target area: 44px via transparent padding

EventBlock (week / day view)

  • Rectangular block, 4px radius
  • Same fill/border as EventChip
  • Displays: title (13px, weight 600) + start time (13px, weight 400) stacked
  • Overflow clips; no ellipsis in short blocks (too short = just color)

AgendaRow

  • Date group header: heading weight (18px/600), --color-text-primary
  • Event row: time (13px, muted) | title (15px, primary) | location (13px, secondary, italic)
  • Left 4px border strip: member color
  • Tap target: full row, min 44px height

EventDetailPopover (read-only in Phase 2; reused as edit surface in Phase 3)

  • Modal-style overlay on phone (full bottom sheet, slides up)
  • Popover anchored to event on tablet/desktop (max-width 360px, 8px radius, shadow)
  • Sections:
    • Color chip + title (heading, 18px/600)
    • Date/time line (label, 13px, secondary)
    • Location line, if present (label, 13px, secondary, with location icon)
    • Description block, if present (body, 15px, primary, max 4 lines before scroll)
    • Calendar name + owner color swatch (label, 13px, muted)
  • Close: X button top-right, 44px touch target; tapping backdrop dismisses
  • Phase 3 note: add edit/delete actions in the footer area (reserved but empty in Phase 2)

SkeletonCalendar

  • Month skeleton: 6×7 grid of rounded rect placeholders, animated shimmer (background: linear-gradient(90deg, --color-surface-dim, --color-border-subtle, --color-surface-dim))
  • Agenda skeleton: 4 date-group blocks, 2–3 rows each, varying widths (60–90% of row)
  • Displayed when TanStack Query isLoading for initial fetch
  • No spinner; shimmer only (matches Fantastical-style)

EmptyState (no events in range)

  • Centered in the calendar viewport
  • Icon: lucide-react CalendarDays (32px, --color-text-muted)
  • Heading + body copy (see § Copywriting)
  • Only shown when fetch succeeded AND zero events returned for the visible window

View Layout Specification

Month view (default: tablet/desktop)

  • 7-column grid, column headers: Sun–Sat (3-letter, label weight)
  • Day cells: 4px border, corner shows day number (13px label)
  • Today's cell: --color-surface-dim background; day number has filled dot indicator
  • Up to 3 event chips per cell; if more: "+N more" label (13px, muted, tappable → day view)
  • All-day events: span full cell width as a chip, no time shown, allDay: true flag
  • Off-month days: day number in --color-text-muted; cells at 60% opacity

Week view

  • Time column 48px wide; columns for each day
  • Current time indicator: 2px --color-member-0 (current user's color) horizontal line
  • All-day banner row at top, above time grid: full-width event blocks
  • Hours displayed: 00:00–23:00 (full 24h); scroll to 08:00 on open
  • Event blocks overlap-handled by Schedule-X internals

Day view

  • Same layout as week, single day column (full width minus time column)
  • Date in header: --text-display (24px/600)

Agenda view (default: phone)

  • Chronological list, grouped by date
  • Infinite scroll or paginated by month (Schedule-X createViewMonthAgenda)
  • Past events: not shown; starts at today
  • No empty date rows; date headers only when events exist on that date

Copywriting Contract

Element Copy
Primary CTA (Phase 2) None — read-only phase; no create action
Empty state heading "Nothing here"
Empty state body "No events in this period. Try a different date or switch views."
Loading state (No text — skeleton shimmer only)
Error state heading "Couldn't load events"
Error state body "Check your connection and try again."
Error action "Retry" (taps queryClient.refetchQueries(['events']))
"+N more" label "+{N} more" (month grid overflow)
Popover close "×" (aria-label="Close")
Today button "Today"
Color legend — shared "Family"
Nav bar — app name "FamilySync"

Destructive actions in Phase 2: None. Phase 2 is read-only.

Interaction Contract

Navigation

  • Prev/next: advance by one unit of current view (day/week/month)
  • Today: jump to today's date, preserve current view
  • View switch: instant; no animation (avoid jank on low-end Android WebViews)
  • All transitions: no slide animations; content replaces in-place

Touch (iOS PWA)

  • All tap targets: minimum 44×44px (enforced via min-height / padding)
  • No hover states on touch devices (use :focus-visible only)
  • Swipe left/right on calendar grid: advance/retreat by one unit (Schedule-X built-in)
  • Tap event chip: open EventDetailPopover
  • Tap backdrop / swipe down: close EventDetailPopover (bottom sheet on phone)

Keyboard / accessibility

  • View toolbar buttons: focusable, role="button", keyboard activated with Enter/Space
  • Event chips: role="button", aria-label="{title}, {date}, {time}"
  • Popover: focus trap while open; Escape closes; focus returns to triggering element
  • Color legend swatches: aria-label="{name}: {color hex}"
  • Month grid cells: role="gridcell", aria-label="{date}"
  • Skeleton: aria-busy="true" on calendar root during loading

Error / retry

  • TanStack Query retry: 2 for events query; after exhaustion show error state
  • Error state replaces calendar grid (not a toast); "Retry" button triggers manual refetch

State Management Contract

State Owner Key Notes
Visible event list TanStack Query ['events', start, end] Invalidated on range change
Current user (/api/me) TanStack Query ['me'] Used for color derivation
Selected view Zustand + localStorage calendarView.{breakpointGroup} Persisted per device category
Selected date (nav) Zustand calendarSelectedDate ISO string; not persisted
Open popover event ID Zustand openEventId null when closed
Visible range Zustand calendarRange { start: string, end: string } — drives Query key

Server events NEVER enter Zustand. Zustand holds only UI-shape state.

Registry Safety

Registry Blocks Used Safety Gate
shadcn official none — shadcn not initialized in Phase 2 not applicable
schedule-x (npm) @schedule-x/react, @schedule-x/calendar, @schedule-x/theme-default npm package — no registry vetting gate required; standard npm supply chain
lucide-react (npm) icon components npm package — standard

No third-party shadcn registries in Phase 2.

Pre-Population Sources

Decision Source
Shared-family color = #F25C7A User-confirmed in phase prompt
WEEK_START_DAY = 0 (Sunday) User-confirmed in phase prompt
Token-layer architecture (D-01/D-02) CONTEXT.md §Theming
Clean theme only (D-02) CONTEXT.md §Theming
All four views (D-04) CONTEXT.md §Views, REQUIREMENTS.md CAL-03
Phone→Agenda / tablet→Month default (D-05) CONTEXT.md §Views
Per-member color from users.color (D-06) CONTEXT.md §Color, CLAUDE.md schema
Color legend, no show/hide filter (D-07) CONTEXT.md §Color
Informational density + tap-to-expand (D-08) CONTEXT.md §Event detail
Server-side recurrence expansion (D-09) CONTEXT.md §Recurrence, CLAUDE.md
Single local timezone, no shift for all-day (D-10) CONTEXT.md §Recurrence
TanStack Query = server state, Zustand = UI state CLAUDE.md, CONTEXT.md §Code patterns
React 19 + Vite stack CLAUDE.md §Recommended Stack
No shadcn yet (Phase 3 adoption) Codebase scan (no components.json)
Schedule-X as rendering library Researcher decision (D-Claude); see §Rendering Library

Checker Sign-Off

  • Dimension 1 Copywriting: PASS
  • Dimension 2 Visuals: FLAG (non-blocking)
  • Dimension 3 Color: PASS
  • Dimension 4 Typography: FLAG (non-blocking)
  • Dimension 5 Spacing: PASS
  • Dimension 6 Registry Safety: PASS

Approval: VERIFIED 2026-06-04 (gsd-ui-checker — 4 PASS / 2 non-blocking FLAG)

Post-Verification Reviewer Notes (non-blocking — apply during implementation)

  • Visuals (apply): Declare the calendar grid (agenda list on phone) as the primary visual focal point, ViewToolbar/AppNav as secondary chrome. Add aria-label="{member name}" + title to the phone-nav avatar/color swatch so the icon-only affordance has a text fallback.
  • Typography (accepted as-is): 13px label / 15px body are 2px apart; keeping 13px (separation carried by weight + context; 13px is also the EventBlock title size). If perceptual blur appears in implementation, drop labels to 12px (chip text, time meta, legend labels) without adding a 5th size.
Reference in New Issue View Git Blame Copy Permalink