feat: revamp site design — introduce a proper design system

[Alimedhat000]

Problem

Codown has no coherent design system. The current UI is a patchwork that blocks UX polish and makes every new feature re-invent visuals:

• Tokens are ad-hoc — client/src/index.css @theme defines ~20 raw colors (#27272a, #2d235e, #512ea8, …) with no semantic scale (no primary/secondary/success/warning/info hierarchy, no light/dark pairing, no spacing/type/radius scale). A large commented-out alternative palette sits unused — evidence of abandoned iteration.
• Primitives ignore tokens — Alert (components/ui/Alert/alert.tsx:23) hardcodes bg-red-50 / border-red-200 / text-red-800 bypassing @theme entirely; Button/Input variants drift from each other (Button/variants.tsx vs Form/variants.ts). No single source for states (hover/focus/disabled/loading).
• Inconsistent layout & typography — Inter loaded with only 400-italic + 700-normal, no type scale; pages compose ad-hoc Tailwind utilities without grid/spacing conventions.
• Landing is a stub — app/routes/landing.tsx:25 is a single paragraph + green button (bg-green-400) unrelated to the dark @theme palette. Tracked separately in add cool landing page 〜(￣▽￣〜) #17.
• UX debt tied to visuals — Build a real 404 page #29 (404 stub), Build a real error boundary UI #30 (error boundary), Blank screen while document loads #32 (blank loading), Fix: Uninteneded Client Visual Errors #21 (visual regressions) all stem from missing loading/empty/error patterns.

Adding features without a system just deepens the drift.

Goal

Introduce a proper, documented design system that makes Codown feel cohesive, accessible, and fast to build on — then migrate the app onto it incrementally.

Scope

1. Design tokens (single source of truth)

• Semantic color system: background / surface / primary / secondary / accent / destructive / success / warning / info + foreground/border/muted variants, with light & dark modes (CSS variables, prefers-color-scheme + manual toggle if desired).
• Spacing, radius, shadow, and typography scales (e.g. --radius-sm/md/lg, --spacing-*, type ramp for display / heading / body / caption).
• Consolidate index.css @theme — remove dead commented palette, document each token.
• Ensure Tailwind 4 @theme + tw-animate-css integration remains correct (no duplicate definitions).

2. Primitive component library (client/src/components/ui/*)

• Audit + normalize existing primitives: Button, Input/Form, Alert, Avatar, Dropdown, Modal, Header, Skeleton, Spinner, Toast, ToggleGroup, Seo.
• Each primitive: variants via cva, token-driven (no hardcoded Tailwind colors), full state coverage (default/hover/focus/active/disabled/loading), a11y (keyboard, ARIA, focus ring via --color-ring), and Storybook stories with autodocs.
• Add missing foundations if needed: Card, Badge, Tabs, Tooltip, EmptyState, PageHeader — only those justified by actual pages (dashboard, editor, auth).
• Fix Alert to use theme tokens (remove red-50 etc.) as a first migration example.

3. Layout & page templates

• App shell (header + content + sidebar where applicable), page grid, and responsive breakpoints.
• Standard patterns for loading (skeletons), empty (“It’s empty in here…”), error (boundary), and not-found — closes Build a real 404 page #29/Build a real error boundary UI #30/Blank screen while document loads #32 in a consistent style.

4. Landing page (#17)

• Rebuild landing.tsx on the new system: hero, feature highlights (real-time collaboration, markdown preview, Yjs sync), social proof/screenshots placeholder, CTA tied to auth state. Should consume primitives, not one-off classes.

5. Documentation & tooling

• Storybook as the system’s living docs (controls, a11y addon, design-token docs page).
• Short docs/client/design-system.md describing token philosophy, component conventions (folder-per-component, PascalCase dirs / kebab-case files, tags: ['\''autodocs'\'']), and migration guide for future components.
• Optional: Figma or token JSON export if a designer is involved — not required for v1.

Acceptance criteria

• Token file (index.css @theme or extracted tokens.css) documents every semantic color/spacing/type/radius token with light/dark values; no hardcoded palette colors remain in ui/*.
• All ui/* primitives render correctly in both themes and pass Storybook a11y checks; Alert/Button/Input stories cover every variant/state.
• Dashboard, editor, auth, landing, 404, and error-boundary routes consume only system tokens/primitives (no ad-hoc bg-green-400 etc.).
• Landing page no longer a stub — ships a real hero/features/CTA built from primitives.
• docs/client/design-system.md exists and Storybook docs reflect the system.
• No visual regression in existing Playwright/E2E flows (auth, dashboard, editor, sharing, collaboration).

Out of scope (follow-ups welcome)

• Full brand identity / logo / marketing copy.
• Per-user theming beyond light/dark.
• Animation/motion system (beyond tw-animate-css shake etc. from Share dialog: graceful revert to last working link when a refetch fails #81).

Constraints & notes

• Client stack stays React 19 + Vite 7 + Tailwind 4 + Radix + CVA — no new UI framework; prefer evolving cva variants over introducing another abstraction.
• Keep client/eslint.config.js conventions: folder-per-component, import/order, JSDoc on exports. Every new primitive needs component-name.stories.tsx with tags: ['\''autodocs'\''].
• Migrate incrementally — token pass first, then primitives, then pages — so PRs stay reviewable.

Related

• add cool landing page 〜(￣▽￣〜) #17 landing page stub
• Build a real 404 page #29 404 page, Build a real error boundary UI #30 error boundary, Blank screen while document loads #32 blank loading, Fix: Uninteneded Client Visual Errors #21 visual errors — all become instances of the system’s loading/empty/error patterns
• Surface failure states across client (toasts, error-vs-empty, no-access) #53 surface failure states (toasts/empty-vs-error) should reuse Toast/Alert/EmptyState from the system