05 — UI / UX — Design Language

Depends on: 04_API_PLATFORM.md · Next: 06_MODULE_SYSTEM.md

1. Target Quality

Between: Linear · Vercel · Stripe · Raycast · Notion · Framer Inspired by (do not copy): tools.yas.sh, m.elsaadouni.com

Keywords: Minimal, smooth, dense but breathable, dark-mode-first, 60fps, premium SaaS 2026.

Forbidden: Default shadcn look without theming, 2018-era SaaS gradients, generic landing templates, external hotlinked images, stock watermarks.

2. Design Tokens (CSS Variables + Tailwind Theme)

:root {
  /* Brand — YAS.SH */
  --brand: 221 83% 53%; /* Electric indigo — replace with logo-derived */
  --brand-2: 262 83% 58%;
  /* Surface — dark first */
  --bg: 240 10% 3.9%;
  --bg-subtle: 240 6% 10%;
  --fg: 0 0% 98%;
  --muted: 240 5% 64%;
  --border: 240 6% 14%;
  /* Semantic */
  --success: 142 76% 36%;
  --warning: 38 92% 50%;
  --danger: 0 84% 60%;
  /* Radius / shadow / motion */
  --radius: 12px;
  --shadow-soft: 0 8px 30px rgba(0,0,0,0.12);
  --ease-spring: linear(0,0.01,0.04 1.6%,0.16 9.5%,0.29 14%,0.49 19%,0.67 22%,0.86 26%,1);
}

Spacing: 4px grid (--space-1: 4px ... --space-8: 32px)
Type: Variable font (Inter or Geist Sans), self-hosted + subset, clamp() fluid scale
Radii: 8/12/16/24 / Elevation: 0/1/2 shadows

Dark/light via class="dark" + prefers-color-scheme fallback.

3. Components (packages/ui)

Design system in @yas/ui (shadcn vendored, not CDN):

Primitives: Button, Input, Card, Dialog, Dropdown, Tabs, Table, Badge, Tooltip (Radix)
Patterns: Dashboard shell (sidebar + command palette ⌘K), Data table (sort/filter/pagination), Empty states that teach, Skeleton loaders, Optimistic UI
Feedback: Toast (sonner), Inline form errors, Confirm dialogs
Motion: motion for page transitions + micro-interactions; prefers-reduced-motion respected; only transform/opacity
Charts: ECharts with custom theme matching tokens (no default ECharts look)
Docs: Storybook OR /design-system route — must be committed

4. Layouts

Marketing: Centered 1280px, hero with original AI illustration (committed .webp), feature grid, social proof, pricing, FAQ, footer with security.txt link. Dashboard: Sidebar (collapsible) + top bar (search + user) + content 1440px; command palette for quick shorten. Docs: Stripe-like — left nav, center content, right TOC, code blocks with copy, language tabs (curl/JS/TS/Python/PHP/Go). Blog: Card grid → article (TOC + related + author bio + JSON-LD).

Responsive: 360 → 4K, touch targets ≥44px, keyboard complete.

5. Page Inventory — Phase 1

Marketing (SSR/SSG): /, /pricing, /features, /tools, /about, /contact, /terms, /privacy, /security App (SSR + client): /dashboard, /dashboard/links, /dashboard/analytics, /dashboard/qr, /dashboard/keys, /login, /register Content: /blog, /blog/[slug], /blog/category/[slug] System: /docs, /docs/api, /design-system, sitemap.xml, robots.txt, rss.xml, /.well-known/security.txt

6. Phase 1 Shell (Must Be Shipped)

Header + footer + mobile nav + theme toggle
Dashboard shell with module-aware nav (auto from modules/*/menu.ts)
Link creation flow: input → alias → expiry → password → create → QR + copy
Links table: search/filter/sort + pagination
Analytics overview: totals + 30-day chart + per-link breakdown
API keys page: create (show once) + revoke

All 5 Phase-1 features have finished UI, not placeholders.

7. Accessibility (WCAG 2.2 AA)

Keyboard nav + visible focus + aria + labels
Contrast ≥4.5:1 (verified via axe)
Form errors announced, not color-only
pnpm dlx axe --include in Playwright → 0 serious/critical

8. Assets

Generate original hero/illustrations (AI, committed .webp in public/)
No external hotlinks; next/image everywhere
Font self-host + subset; first-load JS <200KB gzip (marketing)

Next: 06_MODULE_SYSTEM.md — adding a feature = adding a folder.

05_UI_UX