DESIGN.md — CodexGuide Design System Specification

This document is the Single Source of Truth for the visual identity, component architecture, and design tokens of CodexGuide (codexguide.com). All AI coding agents, contributors, and developers must strictly adhere to this specification.

---

1. Visual Theme & Atmosphere

• Design Philosophy: Vercel & Geist Minimalist (极客严谨极简风)
• Atmosphere: Monochrome, High-Density, Razor-Thin Borders, Engineering Precision.
• Core Intent: Avoid generic "AI Slop" (stagnant 2018 corporate templates or pitch-black dark web palettes). Deliver a high-contrast, modern, light-first interface optimized for readability and trust under daytime lighting.

---

2. Color Palette & Roles (60-30-10 Rule)

60% Canvas & Foundation

• Page Canvas: #FFFFFF (white)
• Canvas Ambient Glow: radial-gradient(ellipse at top, rgba(6, 182, 212, 0.05), transparent 70%)
• Subtle Surface: #F1F5F9 (slate-100)

30% Structural Hierarchy

• Card Surface: #FFFFFF (white)
• Card Inset / Sub-container: #F8FAFC (slate-50)
• Primary Text: #18181B (zinc-900) — High contrast without harsh pure black
• Secondary Text: #475569 (slate-600) — Subtitles, table labels
• Muted Text: #94A3B8 (slate-400) — Timestamps, hints, fine print
• Primary Border: #E2E8F0 (slate-200) — Crisp 1px structural line
• Highlight Border: #CBD5E1 (slate-300) — Hover/Focus state

10% Semantic Action & Accents (Spell & Motion Inspired)

• Primary Accent: Focus Electric Blue (#2563EB) — Interactive links, brand highlights, focus rings
• Value & Status: Active Emerald (#16A34A) — Lowest prices, success status, verified warranties
• Warning Amber: #D97706 (amber-600) — Limited inventory, notices
• Danger Rose: #E11D48 (rose-600) — Sold out, urgent alerts

---

3. Typography Rules

• Font Family:

  font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
  font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;

• Tabular Numbers Requirement: MANDATORY: All numeric comparisons, currency figures, percentages, and metrics must include tabular-nums (font-variant-numeric: tabular-nums; font-mono). This ensures perfect vertical decimal alignment.
• Headings:
  • H1: text-3xl sm:text-5xl lg:text-6xl font-black tracking-tight text-slate-900
  • H2: text-2xl sm:text-3xl font-bold tracking-tight text-slate-900
  • H3: text-lg sm:text-xl font-bold text-slate-900

---

4. Component Stylings (Spell UI & Motion UI Inspired)

Cards & Elevation

className="bg-white rounded-2xl border border-slate-200/85 shadow-[0_1px_3px_0_rgba(0,0,0,0.04),0_1px_2px_-1px_rgba(0,0,0,0.02)] hover:shadow-[0_10px_25px_-5px_rgba(0,0,0,0.06),0_8px_10px_-6px_rgba(0,0,0,0.03)] hover:border-slate-300/90 transition-all duration-200"

Pill Badges

• Verified / Savings Badge: bg-emerald-50 text-emerald-700 border border-emerald-200/80 font-semibold px-2.5 py-0.5 rounded-full text-xs
• Brand Accent Badge: bg-cyan-50 text-cyan-700 border border-cyan-200/80 font-semibold px-2.5 py-0.5 rounded-full text-xs
• Live Status Pulse: A 2px indicator with bg-emerald-500 animate-pulse

Buttons & Interactive CTAs (Motion Physics)

• Primary Button:

  className="inline-flex items-center justify-center gap-2 px-4 py-2 bg-slate-900 hover:bg-slate-800 text-white text-sm font-semibold rounded-xl shadow-sm hover:shadow active:scale-[0.98] transition-all duration-150"

• Gradient Highlight Button:

  className="inline-flex items-center justify-center gap-2 px-4 py-2 bg-gradient-to-r from-cyan-600 to-emerald-600 hover:from-cyan-500 hover:to-emerald-500 text-white text-sm font-semibold rounded-xl shadow-sm shadow-cyan-600/15 active:scale-[0.98] transition-all duration-150"

• Secondary / Outline Button:

  className="inline-flex items-center justify-center gap-2 px-4 py-2 bg-white hover:bg-slate-50 text-slate-700 text-sm font-semibold border border-slate-200 rounded-xl shadow-sm active:scale-[0.98] transition-all duration-150"

---

5. Layout Principles & Bento Grids

• Max Container Width: max-w-7xl mx-auto px-4 sm:px-6 lg:px-8
• Concentric Radii Rule: $$\text{outerRadius} = \text{innerRadius} + \text{padding}$$ Example: Container padding 12px + Inner card rounded-xl (12px) = Outer container rounded-2xl (24px).
• Bento Grid Sub-modules: Structure multi-format items or statistics into asymmetrical modular bento boxes.

---

6. Depth & Glassmorphism

• Sticky Navigation Bar:

  className="sticky top-0 z-40 w-full border-b border-slate-200/80 bg-white/85 backdrop-blur-md"

• Layered Transparency: Depth is expressed through soft multi-tier transparent drop shadows rather than heavy 2px dark solid borders.

---

7. Do's and Don'ts (Strict Guardrails)

DO:

• ✅ Strictly enforce tabular-nums on all numbers, currencies, and stats.
• ✅ Guarantee minimum 4.5:1 text contrast for all reading text against white/slate-50.
• ✅ Provide tactile active:scale-[0.98] feedback on all clickable actions.
• ✅ Use concentric radii for nested surface cards.

DON'T:

• ❌ Do NOT use pitch-black #000000 or harsh border-slate-800 on light canvases.
• ❌ Do NOT build generic 2018-era checklists with green checkmarks ("AI Slop").
• ❌ Do NOT allow horizontal content overflow on mobile viewports.

---

8. Responsive & Accessibility

• Mobile touch targets must be at least 44px tall.
• Form controls and dialogs must support keyboard navigation (Escape to close, visible focus rings).
• Focus ring: focus-visible:ring-2 focus-visible:ring-cyan-500 focus-visible:outline-none.

---

9. AI Agent Prompt Guide

When developing, refactoring, or polishing components for this project:

1. Always reference this DESIGN.md specification as the ultimate standard for colors, radii, and shadows.
2. Maintain high-trust aesthetic coherence across all views.
3. Keep code 100% compliant with static export and zero unnecessary heavy UI dependencies.