ChatKcal Next — Legacy Design Preservation Baseline
Artifact metadata
- Status: Draft supporting artifact
- Captured: 2026-08-08
- Source branch:
dev - Source commit:
35555a192b535ee812e11112083e460ce18dc5fe - Parent plan: ChatKcal Next Rewrite Plan
- Machine-readable tokens: chatkcal-legacy-design-tokens.json
1. Purpose
ChatKcal Next is a fresh technical implementation, but it is not a fresh visual design. This artifact captures the legacy application's proven visual and interaction language so the Tauri rewrite can reuse the work already invested in the product.
The preservation target is the user's recognizable ChatKcal experience:
- calorie-first information hierarchy;
- calm monochrome structure with nutrient color used semantically;
- compact, rounded controls and cards;
- a desktop two-column dashboard that becomes a deliberate mobile stack;
- meal-period grouping and fast-scanning meal cards;
- simple primary/secondary action hierarchy; and
- restrained motion that communicates state without becoming decorative.
This does not preserve AWS, browser, PWA, or React data-ownership assumptions.
2. Evidence and source anchors
The baseline is derived from implementation evidence, not a reconstructed mock-up.
| Evidence | What it establishes |
|---|---|
frontend/tailwind.config.js:7 |
Font stack and the 200 ms fade/scale entrance animations |
frontend/src/index.css:5 |
Legacy global canvas and body text defaults |
frontend/src/pages/Dashboard.tsx:607 |
White application canvas and strong zinc foreground |
frontend/src/pages/Dashboard.tsx:608 |
1,024 px centered content width and 24 px page gutter |
frontend/src/pages/Dashboard.tsx:675 |
Mobile stack and 12-column desktop composition |
frontend/src/pages/Dashboard.tsx:677 |
Sticky 5/12-to-4/12 control column |
frontend/src/pages/Dashboard.tsx:735 |
Near-black primary CTA contract |
frontend/src/pages/Dashboard.tsx:955 |
7/12-to-8/12 meal-log column |
frontend/src/features/dashboard/components/DailyTotalsVertical.tsx:103 |
Calorie blue and primary metric contract |
frontend/src/features/dashboard/components/DailyTotalsVertical.tsx:116 |
Protein, carbohydrate, and fat semantic colors |
frontend/src/features/dashboard/components/DailyTotalsVertical.tsx:204 |
32/24/12 px metric hierarchy and compact behavior |
frontend/src/features/dashboard/components/DailyTotalsVertical.tsx:273 |
Subtle 16 px-radius totals panel |
frontend/src/components/ProgressBar.tsx:46 |
Multi-lap progress rendering and 15% lap darkening |
frontend/src/features/dashboard/components/MealItem.tsx:38 |
Meal-card surface, expansion, and elevation states |
frontend/src/features/dashboard/components/MealList.tsx:48 |
Dinner/Lunch/Breakfast log structure and empty states |
frontend/src/components/SettingsModal.tsx:102 |
Modal radius, width, elevation, and backdrop |
docs/architecture/ux_definitions.md:73 |
Intentional calorie-first hierarchy and compact-bar rules |
docs/project_management/logs/features/2026-02-12_visual_hierarchy_calorie_focus.md |
Approved reasoning behind calorie emphasis |
docs/project_management/logs/fixes/2026-01-14_progress_bar_text_color.md |
Over-target contrast contract |
3. Captured visual baseline
The existing Playwright suite defines three scenarios across desktop Chrome and an iPhone 12 Chromium profile. The six images below were refreshed from the source commit named above.
| Canonical image | Scenario | Pixels | SHA-256 |
|---|---|---|---|
frontend/test_screenshots/visual-desktop-marketing.png |
Desktop brand/marketing page | 1280 × 2542 | 89092c8e448fb5caaca19a750c7b4c734570eb996cd79d81fe5c911163ad81d5 |
frontend/test_screenshots/visual-desktop-tracker-dashboard.png |
Desktop normal day | 1280 × 720 | d2095e3b2f7a3636b09292e20a5a2500d090cd824743c8bbb1ecadab4da53ebc |
frontend/test_screenshots/visual-desktop-tracker-overshoot.png |
Desktop targets exceeded | 1280 × 720 | 673ac29f3412f471f57cdc147e9ed73b62bf7ed497c3a0b3a5dd316e5b1429f3 |
frontend/test_screenshots/visual-mobile-marketing.png |
Mobile brand/marketing page | 1170 × 13164 | 83af5119c5141ddccb4a0a8af96e3a006c41bb3d700c47b89e48159c699d1057 |
frontend/test_screenshots/visual-mobile-tracker-dashboard.png |
Mobile normal day | 1170 × 3282 | 5f92e64349077412e455cc22f580fa6502a884e820a4a5cf082badd48b84534d |
frontend/test_screenshots/visual-mobile-tracker-overshoot.png |
Mobile targets exceeded | 1170 × 3282 | 8bd9d9ff8022ec6e35b4c335804e1e7dcb88379aad1d9fd7a9624cf599485433 |
These are the canonical preservation set. The other historical PNG files in
frontend/test_screenshots are useful archaeology but are not acceptance
baselines unless promoted explicitly.
3.1 Capture result
task test:visual ran all six scenarios on 2026-08-08. Five passed; the desktop
normal-day case was intermittently blocked by the first-time-use gate while the
suite ran with six workers. The same desktop case passed immediately when run
alone, and a final full serial run passed all six cases in 6.7 seconds. The
manifest above records the images from that single serial pass.
Therefore:
- all six images are current and suitable as a human-reviewed design reference;
- the default parallel suite is not yet deterministic enough to act as an automated pass/fail regression gate, even though the serial suite passes; and
- no parity claim may rely on the current green/red process result until the harness-hardening work below is complete.
3.2 Harness gaps to close in Milestone 0
| Gap | Evidence | Required correction |
|---|---|---|
| Screenshots are captured, not compared | Tests call page.screenshot; configured toHaveScreenshot tolerance is unused |
Adopt Playwright snapshot assertions for the canonical set |
| FTUE is not seeded deterministically | Gate intercepted Configure Targets in the parallel run |
Add an explicit preservation fixture that selects the expert/completed FTUE state |
| IndexedDB deletion is not awaited | deleteDatabase is called without awaiting request completion |
Await deletion success/error/blocked completion before navigation |
| Parallel state is unstable | Six-worker run failed; isolated one-worker run passed | Run visual projects serially until every mutable mock is context-isolated |
| Time affects visible meal sections | MealList uses the live clock |
Freeze timezone and clock for visual scenarios |
| Font availability can drift | Inter is preferred but not bundled by the current CSS |
Bundle the approved font or deliberately baseline the platform font |
| Motion can be captured mid-transition | The UI uses 200/300/500 ms transitions | Disable animations for snapshots and wait for document.fonts.ready |
| Screenshot folder contains legacy duplicates | Multiple older naming schemes are tracked | Retain them as archaeology; promote only the six-item manifest above |
Cleanup of older tracked screenshots is a separate, explicitly approved action.
4. Extracted design-token contract
The authoritative machine-readable values are in
docs/design/chatkcal-legacy-design-tokens.json. The semantic contract below is
the part the native rewrite must consume.
4.1 Typography
| Role | Contract | Current evidence |
|---|---|---|
| Sans family | Inter, then system-ui, -apple-system, sans-serif |
Tailwind theme; Inter is not currently bundled |
| Body | 16 px regular, zinc-600 to zinc-900 depending emphasis | Page and form copy |
| Control | 14 px semibold/bold | Buttons, tabs, meal calories |
| Caption | 12 px medium/bold | Times, empty states, section labels |
| Metric | 10 px black; primary value may use 11 px | Progress-bar labels and values |
| Section label | 12 px bold/semibold, uppercase, 0.1 em tracking | Daily Totals and meal periods |
| Marketing display | 48/60/72 px black with tight tracking and 1.05 line height | Responsive hero only |
The unusually small metric type is acceptable because it is black-weight, high-contrast, and inside large color bars. It should not become a general body text size in ChatKcal Next.
4.2 Color
| Semantic role | Value | Usage |
|---|---|---|
| Canvas | #ffffff |
Main tracker background |
| Subtle surface | #fafafa |
Daily Totals, emoji wells, fields, feature cards |
| Muted surface | #f4f4f5 |
Segmented controls and secondary fills |
| Track/default border | #e4e4e7 |
Progress floors, inputs, secondary buttons |
| Interactive border | #d4d4d8 |
Hover/expanded borders |
| Strong text/action | #18181b |
Headings and primary actions |
| Body text | #52525b |
Supporting copy |
| Secondary text | #71717a |
Labels and secondary controls |
| Muted text | #a1a1aa |
Metadata and uppercase section headings |
| Calorie | #2563eb |
Primary progress metric |
| Protein | #f43f5e |
Protein progress and focus |
| Carbohydrate | #f59e0b |
Carbohydrate progress and focus |
| Fat | #a855f7 |
Fat progress and focus |
| Fiber / sodium / sugar | #10b981 / #0ea5e9 / #ec4899 |
Known extended nutrients |
| Marketing gradient | #2563eb → #7c3aed |
Brand hero accent, not general app chrome |
Nutrient colors encode meaning and must remain stable. They are not a rotating chart palette. Red is reserved for errors/destructive actions; blue, amber, and red pale surfaces communicate information, warning, and danger.
4.3 Spacing, shape, and elevation
| Token | Value | Intended use |
|---|---|---|
| App gutter | 24 px | Desktop and mobile outer padding |
| Card padding | 16 px mobile / 24 px desktop | Daily Totals |
| Desktop column gap | 48 px | Control and log columns |
| Mobile section gap | 24–32 px | Major stacked regions |
| Small radius | 4–6 px | Compact actions and code chips |
| Control radius | 8 px | Tabs, pills, small controls |
| Card radius | 12 px | Buttons, fields, meal cards |
| Panel radius | 16 px | Daily Totals and settings dialog |
| Guided-dialog radius | 28 px | High-emphasis onboarding surface only |
| Pill radius | Full | Progress tracks, compact toggles, emoji wells |
| Resting elevation | shadow-sm |
Totals panel and subtle cards |
| Expanded elevation | shadow-md |
Expanded meal card |
| Primary action elevation | shadow-lg with 10% zinc tint |
Main CTA |
| Dialog elevation | shadow-2xl |
Modal and gate surfaces |
4.4 Layout and responsiveness
The tracker is centered at a maximum width of 1,024 px. Below the 768 px breakpoint it is a single intentional sequence:
- identity/header;
- Daily Totals;
- logging actions;
- quick-add affordance;
- date controls; and
- meal-period log.
At 768 px and above it becomes a 12-column layout. The left control column uses 5/12 columns at medium and 4/12 at large, remains sticky, and the log uses the remaining 7/12 or 8/12. The native rewrite may use a wider desktop window, but the content measure and hierarchy should not stretch without an approved new layout.
The compact launcher controls establish 44 px as the minimum native touch target. Android should preserve that floor even when surrounding desktop density is reduced.
4.5 Motion and progress behavior
| Behavior | Contract |
|---|---|
| Fade/scale entrance | 200 ms ease-out; scale begins at 0.95 |
| Layout disclosure | 300 ms ease-out |
| Progress movement | 500 ms ease-out |
| Primary press | Scale to 0.98 |
| Icon press | Scale to 0.95–0.96 |
| Over-target progress | Each completed lap darkens by another 15% |
| Over-target text | White after the first lap; a 50% white divider marks the live lap |
ChatKcal Next must respect reduced-motion preferences. Motion may explain disclosure, progress, or state change; it must not block logging.
5. Component preservation matrix
| Legacy surface | Decision | ChatKcal Next treatment |
|---|---|---|
| Brand mark, favicon, and identity lock-up | Keep | Copy approved assets and verify Windows/Android icon rendering |
| Daily Totals hierarchy | Keep | Preserve calorie-first order, metric colors, compact states, and settings access |
| Layered multi-lap progress bars | Keep visual behavior | Rust returns validated values/derived progress state; React renders the layers |
| Desktop two-column/mobile-stack composition | Keep | Recreate as the initial Windows/Android responsive shell |
| Meal-period log and meal cards | Keep | Rust supplies already sorted/groupable view data; UI renders cards and disclosure |
| Date navigation | Adapt | Preserve placement and clarity; Rust owns logical-date and timezone rules |
| Settings modal visual grammar | Keep | Replace cloud/API tabs with local targets, sync, security, and device settings |
| Primary/secondary action language | Keep | Preserve near-black primary CTA and bordered secondary actions |
| Quick Add | Adapt | Keep the fast interaction; Rust owns lookup, ranking, and mutation |
| FTUE tutorial and AI-app launcher | Adapt substantially | Re-evaluate against native sharing and direct MCP logging while retaining progressive disclosure |
| Marketing page | Preserve as brand reference | Do not ship it inside the native tracker; retain for a future web property |
| Cognito sign-in/out and guest promotion | Retire | Personal native identity and sync-device authorization replace them |
| API Access settings tied to the legacy backend | Retire | Replace with PAT/MCP/sync credential controls designed in the parent plan |
| Browser/PWA install affordances | Retire | Native installers and Android packaging replace them |
| Floating palm/sun badge visible in captures | Exclude pending provenance | No matching application source was found; do not port an unverified overlay |
No component should be copied wholesale from the 1,074-line Dashboard. Preserve the contracts above while splitting the Tauri UI into focused feature components over Rust commands/view models.
6. Native visual acceptance suite
Milestone 0 must turn the provisional six-image set into a deterministic baseline. Milestone 1 must compare the Windows implementation against it.
6.1 Required legacy parity scenarios
| Scenario | Desktop | Mobile/Android | Acceptance intent |
|---|---|---|---|
| Normal day with one meal | Required | Required | Overall hierarchy, layout, typography, and card geometry |
| Multiple targets exceeded | Required | Required | Nutrient identity, lap darkening, divider, and text contrast |
| Empty day | Required | Required | Date controls, empty-state rhythm, and uncluttered composition |
| Expanded meal | Required | Required | Disclosure, nutrient pills, notes, and actions |
| Settings: general targets | Required | Required | Modal/route surface, fields, focus, and action hierarchy |
| Compact macro/nutrient state | Required | Required | 32/24/12 px hierarchy and persisted disclosure preference |
The marketing screenshots remain brand references and do not block the native application release.
6.2 New native-only scenarios
| Scenario | Acceptance intent |
|---|---|
| Offline with queued mutations | Sync state is visible without dominating logging |
| Sync caught up | Confirmation is quiet and legible |
| Sync/auth failure | Error is actionable and local logging remains available |
| MCP-created meal appears | New card arrives without layout jump or manual refresh |
| Windows narrow/wide window | Hierarchy survives resizing around the 768/1024 px thresholds |
| Android keyboard and system insets | Controls remain reachable and 44 px touch targets are preserved |
| Reduced motion | No essential state or action depends on animation |
6.3 Parity review rule
Automated pixel comparison is a change detector, not the design authority. Milestone 1 exits only when:
- the canonical scenarios run deterministically in CI;
- unexpected pixel differences stay inside the approved threshold;
- Windows and Android screenshots are reviewed side-by-side with the legacy references;
- every intentional difference is recorded as Keep, Adapt, Rebuild, or Retire;
- calorie-first hierarchy and nutrient semantics survive at all target sizes;
- keyboard, focus, contrast, reduced-motion, and touch-target checks pass; and
- the user explicitly approves the resulting native visual baseline.
7. Milestone handoff
The first ChatKcal Next repository setup should copy this JSON token artifact and the six canonical screenshots before feature work begins. The new UI should consume semantic CSS custom properties mapped from the JSON rather than scatter raw Tailwind palette utilities through components.
The legacy repository remains the visual source of truth until the user accepts the Milestone 1 Windows baseline. After that transition, ChatKcal Next owns its tokens and regression images; this repository remains design archaeology.
8. Execution notes
- The
document-software-architectureworkflow was used so visual contracts are anchored to implementation and prior design decisions. - The current UI does not have a centralized token system; the JSON file is the first normalized extraction of repeated Tailwind values.
bdremains unavailable in this environment, so no Beads record could be created for the capture/harness-hardening work.- This artifact does not authorize Tauri implementation. The parent L3 plan remains Draft and retains its explicit approval gate.