docs: customize DESIGN.md

Signed-off-by: Dmytro Stanchiev <git@dmytros.dev>

DESIGN.md

@@ -1,8 +1,30 @@
-# Design System Inspired by Vercel
+# Local Cal Design System Inspired by Vercel
+
+## 0. Product Interpretation
+
+This document is not a brief for a Vercel-style marketing homepage. It defines how Vercel's visual language should be adapted to `local-cal`, a utility-first calendar product.
+
+The approved product direction is an `event-first product console with co-equal AI capture`.
+
+### Core Product Rules
+- Keep the app single-page, but lightly restructure hierarchy.
+- Desktop/tablet: AI capture and timeline begin on the same top row and the same vertical start line.
+- Desktop/tablet: the timeline remains the dominant surface through width, depth, and content mass, not by appearing earlier in the layout.
+- Mobile: prioritize `AI capture -> timeline scan -> export`.
+- Mobile: do not create a separate review flow; review happens by scanning the timeline.
+- Text input and file attachments are equally important in the AI capture section.
+- Manual event creation is a secondary power-user path and should live behind a quieter `More` or secondary menu.
+- Validation problems must appear inline under affected events in the timeline, not only in forms.
+
+### Product Stance
+- Utility-first, not editorial-first
+- Event-first on desktop/tablet
+- Capture-first in the first mobile viewport
+- Vercel-inspired, but adapted for a working app rather than a product showcase
 
 ## 1. Visual Theme & Atmosphere
 
-Vercel's website is the visual thesis of developer infrastructure made invisible — a design system so restrained it borders on philosophical. The page is overwhelmingly white (`#ffffff`) with near-black (`#171717`) text, creating a gallery-like emptiness where every element earns its pixel. This isn't minimalism as decoration; it's minimalism as engineering principle. The Geist design system treats the interface like a compiler treats code — every unnecessary token is stripped away until only structure remains.
+Vercel's website is the visual thesis of developer infrastructure made invisible — a design system so restrained it borders on philosophical. For `local-cal`, that same restraint should be applied to a dense, working interface rather than a marketing narrative. The app should be overwhelmingly white (`#ffffff`) with near-black (`#171717`) text in light mode, creating a precise product-console feel where every element earns its pixel. This isn't minimalism as decoration; it's minimalism as engineering principle.
 
 The custom Geist font family is the crown jewel. Geist Sans uses aggressive negative letter-spacing (-2.4px to -2.88px at display sizes), creating headlines that feel compressed, urgent, and engineered — like code that's been minified for production. At body sizes, the tracking relaxes but the geometric precision persists. Geist Mono completes the system as the monospace companion for code, terminal output, and technical labels. Both fonts enable OpenType `"liga"` (ligatures) globally, adding a layer of typographic sophistication that rewards close reading.
 
@@ -14,7 +36,7 @@ What distinguishes Vercel from other monochrome design systems is its shadow-as-
 - Shadow-as-border technique: `box-shadow 0px 0px 0px 1px` replaces traditional borders throughout
 - Multi-layer shadow stacks for nuanced depth (border + elevation + ambient in single declarations)
 - Near-pure white canvas with `#171717` text — not quite black, creating micro-contrast softness
-- Workflow-specific accent colors: Ship Red (`#ff5b4f`), Preview Pink (`#de1d8d`), Develop Blue (`#0a72ef`)
+- Functional accent colors used only for real event state and utilities, never decorative workflow chrome
 - Focus ring system using `hsla(212, 100%, 48%, 1)` — a saturated blue for accessibility
 - Pill badges (9999px) with tinted backgrounds for status indicators
 
@@ -25,10 +47,10 @@ What distinguishes Vercel from other monochrome design systems is its shadow-as-
 - **Pure White** (`#ffffff`): Page background, card surfaces, button text on dark.
 - **True Black** (`#000000`): Secondary use, `--geist-console-text-color-default`, used in specific console/code contexts.
 
-### Workflow Accent Colors
-- **Ship Red** (`#ff5b4f`): `--ship-text`, the "ship to production" workflow step — warm, urgent coral-red.
-- **Preview Pink** (`#de1d8d`): `--preview-text`, the preview deployment workflow — vivid magenta-pink.
-- **Develop Blue** (`#0a72ef`): `--develop-text`, the development workflow — bright, focused blue.
+### Functional Accent Colors
+- **Action Blue** (`#0a72ef`): Use for active utility cues, attachment affordances, and recurrence emphasis when blue is semantically useful.
+- **Signal Pink** (`#de1d8d`): Use sparingly for metadata emphasis such as link state or secondary scan cues when pink improves hierarchy.
+- **Warning Red** (`#ff5b4f`): Use for validation problems, destructive intent, and inline event warnings.
 
 ### Console / Code Colors
 - **Console Blue** (`#0070f3`): `--geist-console-text-color-blue`, syntax highlighting blue.
@@ -161,11 +183,17 @@ What distinguishes Vercel from other monochrome design systems is its shadow-as-
 
 ### Distinctive Components
 
-**Workflow Pipeline**
-- Three-step horizontal pipeline: Develop → Preview → Ship
-- Each step has its own accent color: Blue → Pink → Red
-- Connected with lines/arrows
-- The visual metaphor for Vercel's core value proposition
+**AI Capture Surface**
+- A primary product section, not an accessory toolbar
+- Text input and file attachments have equal visual importance
+- On desktop, it lives beside the timeline with aligned top edges
+- On mobile, it becomes the first major surface in the viewport
+
+**Event Timeline**
+- The dominant product surface on desktop/tablet
+- Cards optimized for quick scanning of title, time, recurrence, links, and problem states
+- Review happens by visually scanning the timeline, not by stepping through a separate review stage
+- Validation warnings can appear inline below affected event cards
 
 **Trust Bar / Logo Grid**
 - Company logos (Perplexity, ChatGPT, Cursor, etc.) in grayscale
@@ -187,15 +215,16 @@ What distinguishes Vercel from other monochrome design systems is its shadow-as-
 
 ### Grid & Container
 - Max content width: approximately 1200px
-- Hero: centered single-column with generous top padding
-- Feature sections: 2–3 column grids for cards
+- Main app shell: compact infrastructure bar plus a primary two-section workspace
+- Desktop/tablet workspace: AI capture and timeline aligned on the same top row
+- Mobile workspace: AI capture first, timeline immediately after, export easy to reach
 - Full-width dividers using `border-bottom: 1px solid #171717`
-- Code/dashboard screenshots as full-width or contained with border
+- Cards and tool surfaces can be full-width or contained with shadow-border treatment
 
 ### Whitespace Philosophy
-- **Gallery emptiness**: Massive vertical padding between sections (80px–120px+). The white space IS the design — it communicates that Vercel has nothing to prove and nothing to hide.
-- **Compressed text, expanded space**: The aggressive negative letter-spacing on headlines is counterbalanced by generous surrounding whitespace. The text is dense; the space around it is vast.
-- **Section rhythm**: White sections alternate with white sections — there's no color variation between sections. Separation comes from borders (shadow-borders) and spacing alone.
+- **Balanced precision**: Preserve generous whitespace, but do not let the app drift into gallery-like pacing that slows frequent actions.
+- **Compressed text, usable space**: Headlines can stay dense and compressed while cards, forms, and timelines remain operationally efficient.
+- **Section rhythm**: Separate zones through spacing, surface treatment, and hierarchy, not through loud color blocking.
 
 ### Border Radius Scale
 - Micro (2px): Inline code snippets, small spans
@@ -222,9 +251,9 @@ What distinguishes Vercel from other monochrome design systems is its shadow-as-
 **Shadow Philosophy**: Vercel has arguably the most sophisticated shadow system in modern web design. Rather than using shadows for elevation in the traditional Material Design sense, Vercel uses multi-value shadow stacks where each layer has a distinct architectural purpose: one creates the "border" (0px spread, 1px), another adds ambient softness (2px blur), another handles depth at distance (8px blur with negative spread), and an inner ring (`#fafafa`) creates the subtle highlight that makes the card "glow" from within. This layered approach means cards feel built, not floating.
 
 ### Decorative Depth
-- Hero gradient: soft, pastel multi-color gradient wash behind hero content (barely visible, atmospheric)
-- Section borders: `1px solid #171717` (full dark line) between major sections
-- No background color variation — depth comes entirely from shadow layering and border contrast
+- Decorative gradients should be minimal to nonexistent in the core app shell
+- Section borders: use only where structure benefits from them; default to shadow-border separation first
+- No loud background color variation — depth comes primarily from shadow layering and border contrast
 
 ## 7. Do's and Don'ts
 
@@ -233,17 +262,20 @@ What distinguishes Vercel from other monochrome design systems is its shadow-as-
 - Use shadow-as-border (`0px 0px 0px 1px rgba(0,0,0,0.08)`) instead of traditional CSS borders
 - Enable `"liga"` on all Geist text — ligatures are structural, not optional
 - Use the three-weight system: 400 (body), 500 (UI), 600 (headings)
-- Apply workflow accent colors (Red/Pink/Blue) only in their workflow context
+- Apply accent colors only to real event state, utility emphasis, link state, recurrence, or validation
 - Use multi-layer shadow stacks for cards (border + elevation + ambient + inner highlight)
 - Keep the color palette achromatic — grays from `#171717` to `#ffffff` are the system
 - Use `#171717` instead of `#000000` for primary text — the micro-warmth matters
+- Keep AI capture attachments as visually important as typed input
+- Surface validation issues inline on timeline cards when event data is invalid
 
 ### Don't
 - Don't use positive letter-spacing on Geist Sans — it's always negative or zero
 - Don't use weight 700 (bold) on body text — 600 is the maximum, used only for headings
 - Don't use traditional CSS `border` on cards — use the shadow-border technique
 - Don't introduce warm colors (oranges, yellows, greens) into the UI chrome
-- Don't apply the workflow accent colors (Ship Red, Preview Pink, Develop Blue) decoratively
+- Don't add `Develop / Preview / Ship` tags or section metaphors to the app shell or event cards
+- Don't apply accent colors decoratively or as marketing-style workflow chrome
 - Don't use heavy shadows (> 0.1 opacity) — the shadow system is whisper-level
 - Don't increase body text letter-spacing — Geist is designed to run tight
 - Don't use pill radius (9999px) on primary action buttons — pills are for badges/tags only
@@ -270,12 +302,13 @@ What distinguishes Vercel from other monochrome design systems is its shadow-as-
 
 ### Collapsing Strategy
 - Hero: display 48px → scales down, maintains negative tracking proportionally
-- Navigation: horizontal links + CTAs → hamburger menu
-- Feature cards: 3-column → 2-column → single column stacked
-- Code screenshots: maintain aspect ratio, may horizontally scroll
+- Top-row workspace: aligned desktop two-section layout → stacked mobile flow
+- Mobile order: AI capture → timeline → export, with import/manual create demoted
+- Timeline remains the main review surface at all sizes
+- Attachment affordances stay prominent on mobile rather than collapsing into hidden extras
 - Trust bar logos: grid → horizontal scroll
 - Footer: multi-column → stacked single column
-- Section spacing: 80px+ → 48px on mobile
+- Section spacing: reduce on mobile, but maintain clarity between AI capture and timeline
 
 ### Image Behavior
 - Dashboard screenshots maintain border treatment at all sizes
@@ -295,16 +328,16 @@ What distinguishes Vercel from other monochrome design systems is its shadow-as-
 - Focus ring: Focus Blue (`hsla(212, 100%, 48%, 1)`)
 
 ### Example Component Prompts
-- "Create a hero section on white background. Headline at 48px Geist weight 600, line-height 1.00, letter-spacing -2.4px, color #171717. Subtitle at 20px Geist weight 400, line-height 1.80, color #4d4d4d. Dark CTA button (#171717, 6px radius, 8px 16px padding) and ghost button (white, shadow-border rgba(0,0,0,0.08) 0px 0px 0px 1px, 6px radius)."
-- "Design a card: white background, no CSS border. Use shadow stack: rgba(0,0,0,0.08) 0px 0px 0px 1px, rgba(0,0,0,0.04) 0px 2px 2px, #fafafa 0px 0px 0px 1px. Radius 8px. Title at 24px Geist weight 600, letter-spacing -0.96px. Body at 16px weight 400, #4d4d4d."
-- "Build a pill badge: #ebf5ff background, #0068d6 text, 9999px radius, 0px 10px padding, 12px Geist weight 500."
-- "Create navigation: white sticky header. Geist 14px weight 500 for links, #171717 text. Dark pill CTA 'Start Deploying' right-aligned. Shadow-border on bottom: rgba(0,0,0,0.08) 0px 0px 0px 1px."
-- "Design a workflow section showing three steps: Develop (text color #0a72ef), Preview (#de1d8d), Ship (#ff5b4f). Each step: 14px Geist Mono uppercase label + 24px Geist weight 600 title + 16px weight 400 description in #4d4d4d."
+- "Create a desktop app shell with a thin infrastructure bar and a top-row two-section workspace. The AI capture section and timeline section start on the same vertical level, but the timeline has more width and deeper continuation. Use white surfaces, shadow-borders, Geist headings, and restrained metadata accents."
+- "Design an AI capture panel for a utility app. Text input and file attachments must have equal visual importance. Use a white surface, shadow-border, 8px-10px radius, Geist headings, and a dark primary action."
+- "Design an event card: white background, no CSS border. Use shadow stack: rgba(0,0,0,0.08) 0px 0px 0px 1px, rgba(0,0,0,0.04) 0px 2px 2px, #fafafa 0px 0px 0px 1px. Title at 24px Geist weight 600, letter-spacing -0.96px. Metadata should emphasize time, recurrence, links, and warnings instead of workflow tags."
+- "Create a mobile app view where AI capture comes first, timeline follows immediately after, export stays easy to reach, and manual create is tucked into a More menu."
+- "Design an inline validation warning for an event card using subtle red emphasis, shadow-border treatment, and strong readability in both light and dark themes."
 
 ### Iteration Guide
 1. Always use shadow-as-border instead of CSS border — `0px 0px 0px 1px rgba(0,0,0,0.08)` is the foundation
 2. Letter-spacing scales with font size: -2.4px at 48px, -1.28px at 32px, -0.96px at 24px, normal at 14px
 3. Three weights only: 400 (read), 500 (interact), 600 (announce)
-4. Color is functional, never decorative — workflow colors (Red/Pink/Blue) mark pipeline stages only
+4. Color is functional, never decorative — accent colors mark real event state, utility emphasis, or warnings only
 5. The inner `#fafafa` ring in card shadows is what gives Vercel cards their subtle inner glow
 6. Geist Mono uppercase for technical labels, Geist Sans for everything else