From 08ca19d2eb94a6adaf7a0bd8731840da65bb975a Mon Sep 17 00:00:00 2001 From: Dmytro Stanchiev Date: Tue, 21 Apr 2026 17:01:20 -0400 Subject: [PATCH] docs: add local cal redesign spec --- .../2026-04-21-local-cal-redesign-design.md | 253 ++++++++++++++++++ 1 file changed, 253 insertions(+) create mode 100644 docs/superpowers/specs/2026-04-21-local-cal-redesign-design.md diff --git a/docs/superpowers/specs/2026-04-21-local-cal-redesign-design.md b/docs/superpowers/specs/2026-04-21-local-cal-redesign-design.md new file mode 100644 index 0000000..c81be33 --- /dev/null +++ b/docs/superpowers/specs/2026-04-21-local-cal-redesign-design.md @@ -0,0 +1,253 @@ +# Local Cal Redesign Spec + +## Summary + +Redesign the entire app as a Vercel-inspired product console that feels like a new application while preserving the current single-page workflow and all existing calendar behavior. The redesign should replace the current glass-heavy visual language with a strict tokenized system based on `DESIGN.md`: compressed Geist typography, white and near-black surfaces, shadow-as-border treatments, restrained accent usage, and equally polished light and dark themes. + +The core product stance is utility-first, not editorial-first. On desktop, the event timeline remains the dominant product surface while AI capture sits alongside it on the same top row as a first-class input tool. On mobile, the first screen should prioritize fast AI capture, immediate timeline scanning, and easy export, with import and manual creation clearly secondary. + +## Goals + +- Make the app feel substantially new and app-wide, not like a page polish pass. +- Treat `DESIGN.md` as the source of truth for visual language and component styling. +- Rebuild the design system at the token and primitive level so page styling is mostly composition. +- Preserve all existing functional behavior: event CRUD, AI generation, import/export, recurrence, auth, and settings. +- Make desktop and mobile hierarchy intentionally different where product priorities differ. +- Ensure validation problems are visible both in forms and inline in the timeline. + +## Non-Goals + +- No major multi-page IA rewrite. +- No workflow-metaphor UI based on `Develop / Preview / Ship` tags or section chrome. +- No decorative accent-color usage disconnected from real event state. +- No weakening of existing utility behavior in favor of marketing-style presentation. + +## Product Direction + +### Design stance + +The redesign should be a `Vercel product console for a local calendar tool`, not a clone of Vercel's marketing homepage. The app should borrow Vercel's disciplined typography, surface treatments, spacing logic, and neutral palette, but apply them to a working calendar utility. + +### Core hierarchy + +- Desktop and tablet should feel event-first. +- AI capture should be a first-class product tool, but not the dominant product identity. +- Mobile should feel capture-first in the first viewport because the likely phone workflow is to quickly create an event and add it to the calendar. +- Timeline scanning should serve as the implicit review flow on all breakpoints. + +## Information Architecture + +### Overall model + +Keep the current single-page application model, but lightly restructure the screen hierarchy. + +The main app should be organized into these layers: + +1. Top infrastructure bar +2. Primary top-row workspace containing AI capture and timeline sections +3. Secondary utility controls and supporting surfaces + +### Desktop and tablet structure + +Desktop uses a top-row two-section workspace: + +- `AI capture` section +- `Timeline` section + +These two sections must begin at the same vertical level. Their section headers should align horizontally on the same baseline row. The timeline still carries more overall visual dominance through greater width, deeper continuation, and more content mass below that aligned start line. + +This means the desktop hierarchy is not a stacked `AI above timeline` model. It is a horizontally aligned two-section layout where the timeline clearly wins in overall emphasis. + +### Mobile structure + +Mobile should prioritize: + +1. AI capture +2. Timeline scan +3. Export + +Import should be secondary, and manual creation should be hidden behind a quiet power-user path such as a `More` menu. + +There should be no dedicated mobile review panel or separate review stage. Users review by scanning the timeline and inline event details after capture. + +## Visual System + +### Typography + +- Use `Geist Sans` and `Geist Mono` as the core families. +- Apply the aggressive negative tracking from `DESIGN.md` to major headings, section titles, modal titles, and other announcement-level text. +- Preserve the strict role separation between body, UI, and heading weights. +- Use Geist Mono for small technical labels and infrastructure text where appropriate. + +### Color and accents + +- Light mode should be grounded in white surfaces and `#171717` foreground text. +- Dark mode should be equally polished, using the same structural rules rather than a loose inversion. +- Accent colors should be used sparingly and functionally. +- Remove workflow tags such as `Develop`, `Preview`, and `Ship` from event cards and surface labels. +- Accent usage should instead highlight real event information, such as recurrence, link state, time-related metadata, or validation warnings. + +### Surfaces and depth + +- Remove the current glassmorphism-heavy identity as the primary design language. +- Replace it with shadow-as-border treatments and layered Vercel-style card shadows from `DESIGN.md`. +- Use neutral surfaces, disciplined radius values, and subtle depth. +- Avoid traditional visible card borders where the shadow-border technique should be used. + +### Density and rhythm + +- The app should feel balanced, not gallery-like and not cramped. +- Leave enough whitespace to feel premium and precise. +- Preserve efficient scanning and frequent-use ergonomics for event lists, forms, and action surfaces. + +## Main Screen Behavior + +### Top infrastructure bar + +The header should become thinner and quieter than the current shell. It should contain only core infrastructural items: + +- App identity +- Connection state +- Theme control +- Settings entry +- High-value utility actions as appropriate + +It should not compete visually with the AI capture or timeline sections. + +### AI capture section + +The AI capture panel should be one of the two top-row primary sections on desktop and the first main section on mobile. + +Requirements: + +- Text input and file attachments must have equal product importance. +- Attachments must not read as an optional afterthought under the prompt box. +- The section should support pasted content, uploaded images, and ICS-related inputs in a way that feels central to the flow. +- On mobile, file attachments may be even more important than on desktop and should remain equally visible. + +### Timeline section + +The timeline is the main product stage. + +Requirements: + +- It should visually dominate the main experience on desktop. +- It should follow immediately after AI capture on mobile. +- It should serve as the place where users implicitly review generated or imported events. +- It should support fast scanning of event title, time, recurrence, links, and problem states. + +## Event Cards + +Event cards should be redesigned as operational product cards with editorial typography discipline. + +Requirements: + +- No workflow tags. +- Metadata hierarchy should be stronger and easier to scan. +- Accent color should highlight meaningful event attributes such as recurrence, link state, or important time information. +- Event actions should stay available but visually quieter than the content. +- Validation warnings must appear inline under the affected event when possible. + +### Validation visibility + +If an event has validation issues, the timeline must surface that problem directly under the relevant card. This is required in addition to any validation behavior inside edit forms. + +Example classes of issues: + +- End time before start time +- Missing or malformed URL where relevant +- Invalid recurrence data +- Other event-level data inconsistencies already known to the system + +## Dialogs and Forms + +### Event dialog + +The event dialog should move from a soft glass treatment to a more precise console form treatment. + +Requirements: + +- Tighter structure and clearer information grouping +- Stronger label and field hierarchy +- Better grouping for date, time, recurrence, and validation +- Light and dark modes must feel equally resolved + +### Manual creation + +Manual event creation remains supported but should no longer be treated as a primary path on mobile. It should live behind a quieter `More` or secondary menu as a power-user feature. + +## Utility Actions + +- `Export` should remain easy to reach. +- `Import` should be visibly secondary. +- `Manual create` should live in a secondary menu. +- Settings should read as infrastructure, not a co-primary destination. + +## Component System Scope + +The redesign must be implemented system-first, not screen-first. The following primitives and shared components need redesign support: + +- Buttons +- Cards +- Badges +- Inputs +- Textareas +- Dialogs +- Dropdowns +- Selects +- Toolbars +- Event card surfaces +- Empty states +- Validation and warning treatments + +The goal is that page-level code mainly composes redesigned primitives rather than layering one-off classes on top of old components. + +## Responsive Rules + +### Desktop and tablet + +- AI capture and timeline begin on the same vertical start line. +- Timeline gets stronger width and deeper continuation. +- Utility controls stay present but visually quieter. + +### Mobile + +- AI capture appears first. +- Timeline follows immediately after. +- Review is implicit in timeline scanning. +- Export remains easy to reach. +- Import and manual create are secondary. + +## Accessibility and Interaction + +- Preserve strong focus visibility using the focus color guidance from `DESIGN.md`. +- Maintain touch-friendly controls on mobile. +- Keep contrast and interaction affordances clear in both themes. +- Ensure warning and validation states are distinguishable without relying only on color. + +## Implementation Notes + +- The redesign should begin with tokens and surface primitives in `globals.css` and shared UI components. +- Existing shell contract helpers and component primitives should be updated or replaced to reflect the new system. +- The current glass utility classes should no longer define the visual identity of the app. +- Screen composition should be rebuilt around the redesigned primitives after the token layer is in place. + +## Verification Requirements + +Before considering the redesign complete, verify: + +- Desktop hierarchy matches the approved aligned two-section model. +- Mobile hierarchy matches the approved capture-first then timeline model. +- Light and dark themes are both polished and consistent. +- Event CRUD, AI generation, recurrence, import/export, settings, and auth still function. +- Validation problems appear both in forms and inline on timeline cards. +- Manual creation is reachable but clearly secondary. + +## Open Decisions Resolved In This Spec + +- Chosen hierarchy pair: `A. Timeline Lead` +- Desktop correction: top of AI and timeline sections align horizontally on the same vertical level +- Workflow tags: removed +- Review model: folded into timeline scanning +- Attachment importance: equal to text input +- Manual create placement: secondary `More` path