gspec 1.7.0 → 1.11.0

package/starters/stacks/nextjs-vercel-typescript.md

@@ -0,0 +1,264 @@
+---
+gspec-version: 1.8.0
+description: Next.js App Router, TypeScript, Tailwind CSS, deployed on Vercel
+---
+
+# Technology Stack Definition
+
+## 1. Overview
+
+- **Architecture style**: Server-rendered monolith (Next.js App Router with SSR/SSG)
+- **Deployment target**: Cloud — Vercel (edge/serverless rendering with built-in CDN)
+- **Scale & performance**: Core content loads within 2s on typical mobile networks; lean bundles via dynamic imports and tree-shaking; responsive across desktop and mobile viewports
+
+## 2. Open Questions & Clarifications
+
+None — all critical technology decisions are resolved.
+
+## 3. Core Technology Stack
+
+### Programming Languages
+
+- **Primary**: TypeScript 5.x (strict mode enabled)
+  - *Rationale*: Type safety, predictable refactors, first-class Next.js support
+- **Secondary**: N/A
+- **Tooling**: ESLint (TypeScript rules), Prettier (formatting)
+
+### Runtime Environment
+
+- **Runtime**: Node.js 20+ LTS
+  - *Rationale*: Required for Next.js; LTS ensures stability and long-term security patches
+- **Container runtime**: Not required — Vercel manages the runtime environment
+
+## 4. Frontend Stack
+
+### Framework
+
+- **Framework**: Next.js (latest LTS release, App Router)
+  - *Rationale*: Server-rendered defaults with hydration as needed; App Router provides layouts, server components, and streaming out of the box; first-class Vercel deployment support
+- **Update strategy**: Track Next.js LTS releases; upgrade within 30 days of new LTS availability
+
+### Build Tools
+
+- **Bundler**: Next.js built-in (SWC-based compiler + Turbopack for development)
+  - *Rationale*: Zero-config, optimized for the Next.js ecosystem; SWC provides fast TypeScript transpilation
+- **Build optimization**: Dynamic imports for code-splitting, tree-shaking via ES module imports, Next.js image optimization pipeline
+
+### State Management
+
+- **Approach**: Server-first — lean on server components and server-rendered data; client-side state kept minimal
+- **Libraries**: React built-in hooks (`useState`, `useReducer`, `useContext`) for local/client state
+  - *Rationale*: No global state library needed for a content-driven frontend; avoids unnecessary bundle weight
+- **Data fetching**: Next.js `fetch` with caching directives in server components; SWR or server actions for any client-side data needs
+
+### Styling Technology
+
+- **Framework**: Tailwind CSS 4.x with design tokens for spacing, typography, colors, and elevation
+  - *Rationale*: Utility-first approach aligns with component-based architecture; shared configuration keeps styles cohesive; excellent tree-shaking for production
+- **CSS-in-JS**: Not used — Tailwind utilities only; no raw CSS outside Tailwind conventions
+- **Responsive design**: Tailwind responsive prefixes (`sm:`, `md:`, `lg:`, `xl:`) for mobile-first breakpoints
+- **Note**: Icon library choices are defined in `gspec/style.md`. The stack defines the CSS framework and component library; the style defines the icon set.
+
+## 5. Backend Stack
+
+**Not Applicable** — this is a frontend-only / static site project deployed to Vercel. No database, API layer, or server-side auth is required.
+
+### Database
+
+N/A
+
+### Caching Layer
+
+N/A — Vercel edge caching and Next.js built-in caching handle content delivery.
+
+### Message Queue / Event Bus
+
+N/A
+
+## 6. Infrastructure & DevOps
+
+### Cloud Provider
+
+- **Provider**: Vercel
+  - *Key services*: Edge network, serverless functions (if needed), image optimization, analytics
+  - *Rationale*: Purpose-built for Next.js; predictable builds, automatic edge caching, zero-config HTTPS
+
+### Container Orchestration
+
+N/A — Vercel manages scaling and deployment infrastructure automatically.
+
+### CI/CD Pipeline
+
+- **Platform:** GitLab CI
+  - *Rationale:* Aligns with existing team infrastructure and workflow.
+- **Deployment trigger:** Merge to main branch after pipeline passes.
+- **Deployment method:** Vercel Git integration for preview deployments on merge requests; production deploy on main branch merge.
+- **Note:** Pipeline stages and structure (lint → typecheck → test → build → deploy) are defined in `gspec/practices.md`. This section defines the CI technology and deployment configuration.
+
+### Infrastructure as Code
+
+N/A — Vercel manages infrastructure. Project configuration lives in `next.config.ts` and `vercel.json` (if needed).
+
+## 7. Data & Storage
+
+### File Storage
+
+- **Static assets**: Served via Vercel's built-in CDN from the `public/` directory
+- **Images**: Next.js `<Image />` component with automatic optimization (WebP/AVIF, responsive sizing)
+- **Asset management**: Styled placeholders used during development; final assets swapped in before release
+
+### Data Warehouse / Analytics
+
+N/A
+
+## 8. Authentication & Security
+
+N/A — no authentication or authorization layer for this frontend-only project.
+
+### Security Tools
+
+- **Secrets management**: Environment variables via Vercel project settings (build-time and runtime)
+- **Security scanning**: `pnpm audit` for dependency vulnerabilities; Dependabot or Renovate for automated dependency updates
+- **Compliance**: HTTPS enforced by Vercel; no user data collection requiring GDPR/CCPA compliance at this stage
+
+## 9. Monitoring & Observability
+
+Minimal for initial launch — to be revisited as the project scales.
+
+### Application Monitoring
+
+Deferred — Vercel provides basic deployment and function metrics out of the box.
+
+### Logging
+
+Deferred — Vercel function logs available via dashboard for debugging.
+
+### Tracing
+
+N/A
+
+### Error Tracking
+
+Deferred — can add Sentry when needed. Next.js has built-in error boundaries for graceful UI failure handling.
+
+## 10. Testing Infrastructure
+
+### Testing Frameworks
+
+- **Unit / Integration**: Vitest
+  - *Rationale*: Fast, ESM-native, excellent TypeScript support; compatible with React Testing Library
+- **Component testing**: React Testing Library
+  - *Rationale*: Tests components as users interact with them; encourages accessible markup
+- **E2E**: Cypress (headless in CI)
+  - *Rationale*: Mature ecosystem, reliable deterministic tests with `cy.intercept()` for stubbing
+
+### Test Data Management
+
+- **Fixtures**: JSON fixtures in `tests/fixtures/` for consistent test data
+- **Mocks**: Vitest built-in mocking for modules; `cy.intercept()` for network stubbing in E2E
+- **Test isolation**: Each test suite manages its own state; no shared mutable state between tests
+
+### Performance Testing
+
+Deferred — Core Web Vitals monitored via Lighthouse CI or Vercel Analytics when enabled.
+
+## 11. Third-Party Integrations
+
+### External Services
+
+- **Formspree** — Client-side form submission service for contact forms and visitor inquiries. Accepts POST requests directly from the browser — no server-side endpoint or backend code required.
+  - *Rationale*: This is a frontend-only project with no backend logic. Formspree provides form handling without requiring server actions or API routes, keeping the architecture static.
+  - Free tier supports up to 50 submissions per month.
+  - Submissions are forwarded to a configured email address.
+
+### API Clients
+
+- **HTTP client**: Native `fetch` API for Formspree form submissions. No SDK dependency needed — Formspree accepts standard `FormData` POST requests.
+
+## 12. Development Tools
+
+### Package Management
+
+- **Package manager**: pnpm (latest stable)
+  - *Rationale*: Fast installs, strict dependency resolution prevents phantom dependencies, disk-efficient via content-addressable storage
+- **Dependency management**: `pnpm-lock.yaml` committed to version control; `pnpm audit` run in CI
+- **Private registry**: N/A
+
+### Code Quality Tools
+
+- **Linter**: ESLint with `eslint-config-next` and TypeScript rules
+- **Formatter**: Prettier (configured to align with ESLint)
+- **Pre-commit hooks**: Husky + lint-staged for running ESLint and Prettier on staged files
+- **Type checking**: `tsc --noEmit` in CI pipeline
+
+### Local Development
+
+- **Project starter**: `create-next-app` (official Next.js scaffolding tool via `pnpm create next-app`)
+  - *Rationale*: Provides a well-structured starting point with recommended defaults, TypeScript config, and App Router setup
+- **Setup**: `pnpm install` → `pnpm dev` (Next.js dev server with Turbopack)
+- **Hot reload**: Built-in via Next.js Fast Refresh
+- **Environment**: `.env.local` for local environment variables (gitignored)
+
+## 13. Migration & Compatibility
+
+### Legacy System Integration
+
+N/A — greenfield project.
+
+### Upgrade Path
+
+- **Next.js**: Track LTS releases; review changelogs and run codemods when upgrading major versions
+- **Tailwind CSS**: Follow major version migration guides; design tokens minimize breaking changes
+- **Dependencies**: Automated update PRs via Renovate or Dependabot; reviewed weekly
+
+## 14. Technology Decisions & Tradeoffs
+
+### Key Architectural Decisions
+
+| Decision | Choice | Alternatives Considered | Rationale |
+|---|---|---|---|
+| Framework | Next.js (App Router) | Remix, Astro, Nuxt | Best Vercel integration; mature SSR/SSG; React ecosystem |
+| Styling | Tailwind CSS | CSS Modules, Styled Components | Utility-first aligns with component architecture; zero runtime cost; design token support |
+| Testing | Vitest + Cypress | Jest + Playwright | Vitest is faster and ESM-native; Cypress is mature for E2E with reliable stubbing |
+| Package manager | pnpm | npm, yarn | Strict resolution prevents phantom deps; faster installs; disk-efficient |
+| Deployment | Vercel | Netlify, AWS Amplify, Cloudflare Pages | Purpose-built for Next.js; edge caching; zero-config previews |
+| CI/CD | GitLab CI | GitHub Actions | Aligns with existing team infrastructure and workflow |
+
+### Risk Mitigation
+
+| Risk | Mitigation | Fallback |
+|---|---|---|
+| Next.js breaking changes on major upgrade | Pin to LTS; test upgrades in preview branch | Delay upgrade; apply security patches only |
+| Vercel vendor lock-in | Keep Next.js config portable; avoid Vercel-only APIs where possible | Self-host via `next start` on any Node.js platform |
+| Tailwind major version migration | Use design tokens abstraction layer; follow official migration guides | Gradual migration with compatibility layer |
+
+## 15. Technology-Specific Practices
+
+### Framework Conventions & Patterns
+
+- **App Router structure:** Use the `app/` directory with route groups for logical organization (e.g., `(marketing)` for public pages). Keep layouts in `app/layout.tsx` and page-level layouts in route group folders.
+- **Server vs Client Components:** Default to Server Components. Add `"use client"` only when the component needs browser APIs, event handlers, or React hooks (`useState`, `useEffect`). Push interactivity to leaf components.
+- **Static generation:** Prefer static rendering (SSG) for content pages. Use `generateStaticParams()` for dynamic routes if applicable.
+- **Loading and error states:** Use `loading.tsx` and `error.tsx` files at appropriate route levels for streaming UI and error boundaries.
+- **Metadata:** Export `metadata` or `generateMetadata` from every page for SEO (title, description, Open Graph).
+
+### Library Usage Patterns
+
+- **Tailwind conventions:** Use Tailwind utility classes directly in JSX. Avoid `@apply` except in global styles for base resets. Use `cn()` or `clsx()` for conditional class merging. Follow mobile-first responsive design (`sm:`, `md:`, `lg:` breakpoints).
+- **Design token mapping:** Map design tokens from `gspec/style.md` to Tailwind's theme configuration in `tailwind.config.ts` under `theme.extend`. Use CSS custom properties in `app/globals.css` for runtime theme switching (light/dark mode).
+- **Image optimization:** Use Next.js `<Image />` component for all images. Set `priority` on above-the-fold hero images.
+
+### Language Idioms
+
+- **TypeScript strict mode:** `strict: true` in `tsconfig.json`. No `any` types — use `unknown` and narrow with type guards.
+- **Path aliases:** Use `@/` alias (configured in `tsconfig.json`) for imports from the project root. Example: `import { Button } from "@/components/ui/button"`.
+- **Import organization:** Group imports: (1) React/Next.js, (2) third-party libraries, (3) internal modules, (4) relative imports.
+- **Async patterns:** Use `async/await` consistently. Avoid `.then()` chains.
+
+### Stack-Specific Anti-Patterns
+
+- **Don't use `useEffect` for data fetching** when a Server Component can do the same work — causes client-side waterfalls.
+- **Don't add `"use client"` to layout files** unless absolutely necessary — this forces all children to be client components.
+- **Don't import server-only modules in Client Components.** Use the `server-only` package to enforce boundaries.
+- **Don't install a CSS-in-JS library** alongside Tailwind — pick one styling approach.
+- **Don't use inline styles** for values that should be design tokens — map them through Tailwind configuration.

package/starters/styles/clean-professional.md

@@ -0,0 +1,316 @@
+---
+gspec-version: 1.8.0
+description: Clean, professional design with restrained palette and clear typography
+---
+
+# Visual Style Guide
+
+## 1. Overview
+
+- **Design Vision**: A clean, professional interface that communicates expertise and trustworthiness. The design recedes to let content take center stage — clear typography, generous whitespace, and purposeful color usage.
+- **Target Platforms**: Responsive web (Mobile-First, scaling to Desktop/Tablet).
+- **Visual Personality**: Professional, Approachable, Reliable, Pragmatic.
+- **Design Rationale**: A professional services site must project competence and trustworthiness at a glance. The restrained palette and clear typography let the content speak, while strategic use of color draws attention to key actions. The minimal aesthetic avoids visual noise that could undermine credibility.
+
+## 2. Color Palette
+
+High-contrast and professional, designed for readability across devices and lighting conditions.
+
+### Primary Colors
+
+| Color Name | Hex | Usage |
+| :--- | :--- | :--- |
+| **Primary** | `#2563EB` | Primary action color. Used for primary buttons, active states, and key highlights. |
+| **Primary Dark** | `#1D4ED8` | Hover states for primary actions. |
+| **Primary Light** | `#60A5FA` | Accents on dark backgrounds. |
+
+### Secondary Colors
+
+| Color Name | Hex | Usage |
+| :--- | :--- | :--- |
+| **Slate Dark** | `#0F172A` | Dark mode background. |
+| **Slate Surface** | `#1E293B` | Dark mode cards/surfaces. |
+| **Paper White** | `#FFFFFF` | Light mode background. |
+
+### Neutral Colors
+
+| Role | Light Mode | Dark Mode | Usage |
+| :--- | :--- | :--- | :--- |
+| **Text Primary** | `#0F172A` | `#F8FAFC` | Headings, main body text. |
+| **Text Secondary** | `#64748B` | `#94A3B8` | Labels, helper text, supporting content. |
+| **Text Disabled** | `#CBD5E1` | `#475569` | Disabled fields, placeholders. |
+| **Border** | `#E2E8F0` | `#334155` | Dividers, input borders. |
+
+### Semantic Colors
+
+| State | Color | Hex | Usage |
+| :--- | :--- | :--- | :--- |
+| **Success** | Emerald | `#10B981` | Success confirmations, positive feedback. |
+| **Error** | Red | `#EF4444` | Validation errors, destructive actions. |
+| **Warning** | Amber | `#F59E0B` | Non-critical alerts, warnings. |
+| **Info** | Sky | `#0EA5E9` | Informational tooltips, notes. |
+
+---
+
+## 3. Typography
+
+Typography is the primary interface element. It must be legible and convey professionalism.
+
+### Font Families
+
+- **Primary (UI & Headings)**: **Inter** (Google Fonts). Clean, highly legible, with a tall x-height.
+- **Monospace (Code & Data)**: **JetBrains Mono** or system monospace fallback. Used for code snippets or technical content if needed.
+
+### Type Scale (Mobile-First)
+
+| Level | Size (rem/px) | Line Height | Weight | Usage |
+| :--- | :--- | :--- | :--- | :--- |
+| **H1** | `1.875rem` (30px) | `1.2` | Bold (700) | Page titles |
+| **H2** | `1.5rem` (24px) | `1.3` | SemiBold (600) | Section headers |
+| **H3** | `1.25rem` (20px) | `1.4` | Medium (500) | Sub-sections, card titles |
+| **Body Lg** | `1.125rem` (18px) | `1.5` | Regular (400) | Featured text, hero subtitles |
+| **Body Base** | `1rem` (16px) | `1.5` | Regular (400) | Default text, descriptions |
+| **Body Sm** | `0.875rem` (14px) | `1.4` | Regular (400) | Metadata, captions |
+| **Caption** | `0.75rem` (12px) | `1.4` | Medium (500) | Tiny labels, tags |
+
+---
+
+## 4. Spacing & Layout
+
+Standard 4px grid system.
+
+### Spacing Scale
+
+- **xs**: `4px` (0.25rem) — Tight grouping (tags, icon+text)
+- **sm**: `8px` (0.5rem) — Component internal spacing
+- **md**: `16px` (1rem) — Standard separation between elements
+- **lg**: `24px` (1.5rem) — Section separation
+- **xl**: `32px` (2rem) — Major layout breaks
+
+### Grid System
+
+- **Container**: Max-width 1152px centered with horizontal padding for comfortable reading width.
+- **Columns**: Single-column layout on mobile. Multi-column grids on desktop where appropriate.
+
+### Layout Patterns
+
+- **Mobile-first**: Single-column stacked layout.
+- **Desktop**: Multi-column grids for cards and feature sections.
+- **Flex containers**: Always apply `min-width: 0` on flex children that wrap content to prevent the flexbox `min-width: auto` default from causing horizontal overflow on mobile.
+- **Content wrappers**: Use `overflow: hidden` on bounded containers (cards, main content area) to clip any remaining overflow.
+
+---
+
+## 5. Themes
+
+### Light Mode (Default)
+- **Background**: `#FFFFFF`
+- **Surface**: `#F8FAFC` or `#FFFFFF` with borders.
+- **Text**: `#0F172A`
+
+### Dark Mode
+- **Background**: `#0F172A` (Not pure black, reduces contrast strain).
+- **Surface**: `#1E293B`
+- **Primary Action**: `#2563EB` stands out vividly.
+- **Text**: `#F8FAFC` for high legibility.
+
+### Theme Token Mapping
+- Light and dark themes share the same token names. Switching themes swaps the values of `--color-background`, `--color-surface`, `--color-text-primary`, `--color-text-secondary`, `--color-text-disabled`, and `--color-border`.
+
+---
+
+## 6. Component Styling
+
+> **This section defines visual styling only** — colors, borders, typography, and spacing for common UI elements. Component structure, behavior, and layout patterns are defined in feature PRDs.
+
+### Buttons
+
+- **Primary**: Background `#2563EB`, text white, border-radius 6px.
+- **Primary Hover**: Background `#1D4ED8`.
+- **Secondary**: Background transparent, border 1px `#CBD5E1` (Light) / `#475569` (Dark), text `#334155` (Light) / `#CBD5E1` (Dark).
+- **Ghost**: No border, no background. Hover: subtle background fill.
+- **Disabled**: 50% opacity, `cursor: not-allowed`.
+- **Sizes**: Default 40px height, Large 48px height. Minimum touch target 44x44px.
+
+### Form Elements
+
+- **Input Background**: Transparent (Light) / Transparent (Dark).
+- **Input Border**: 1px `#CBD5E1` (Light) / `#334155` (Dark), border-radius 6px.
+- **Focus**: Border `#2563EB` (2px), ring `rgba(37, 99, 235, 0.2)`.
+- **Error**: Border `#EF4444`, helper text in `#EF4444`.
+- **Disabled**: 50% opacity.
+
+### Cards & Containers
+
+- **Background**: `#FFFFFF` (Light) / `#1E293B` (Dark).
+- **Border**: 1px solid `#E2E8F0` (Light) / `#334155` (Dark).
+- **Border-radius**: 8px.
+- **Shadow**: `--shadow-sm` or none. Heavy shadows are avoided for a clean look.
+
+### Navigation Elements
+
+- **Link Color**: `--color-text-secondary` default, `--color-text-primary` on hover.
+- **Active Link**: `--color-primary` text color.
+- **Nav Background**: `--color-background` with optional `--shadow-md` for sticky positioning.
+
+---
+
+## 7. Visual Effects
+
+### Shadows & Elevation
+Minimalist approach.
+- **None**: Most elements.
+- **sm**: `0 1px 2px rgba(0, 0, 0, 0.05)` for cards to lift slightly off background.
+- **md**: `0 4px 6px rgba(0, 0, 0, 0.07)` for floating elements or sticky headers.
+
+### Border Radius
+- **Standard**: 6px for inputs/buttons.
+- **Large**: 8px for cards/containers.
+- **Pills**: 9999px for status tags.
+
+### Transitions & Animations
+- **Speed**: Fast (150ms or 200ms).
+- **Ease**: `cubic-bezier(0, 0, 0.2, 1)` (ease-out).
+- **Feedback**: Immediate visual feedback on interaction (hover color shift, subtle scale reduction on press for buttons).
+- **Loading States**: Skeleton screens or spinner indicators for async operations.
+
+---
+
+## 8. Iconography
+
+### Icon Library
+- **Library**: [HeroIcons](https://heroicons.com/) — MIT-licensed, SVG-based, tree-shakeable inline imports. Maintained by the Tailwind team for consistent pairing with utility-first CSS.
+- **Style**: Outlined, 2px stroke.
+- **Size**:
+    - Small: 16px.
+    - Standard: 20px.
+    - Navigation: 24px.
+
+### Usage Guidelines
+- Pair icons with text labels in navigation for accessibility.
+- Use familiar metaphors for common actions.
+
+---
+
+## 9. Imagery & Media
+
+### Photography Style
+Not applicable for initial launch. If marketing imagery is added later, it should be authentic and professional — not generic stock photography.
+
+### Illustrations
+Not applicable — the UI relies on typography, spacing, and iconography rather than illustrations. Empty states use icon + text patterns.
+
+---
+
+## 10. Accessibility
+
+### Contrast Requirements
+- Maintain WCAG AA standard (4.5:1) for normal text.
+- Large text (18px+ or 14px+ bold) requires 3:1 minimum.
+
+### Focus States
+- Visible focus rings for keyboard/screen reader navigation.
+- Focus ring style: 2px offset ring in primary color.
+
+### Text Accessibility
+- **Touch**: All interactive elements must have at least 44px hit areas.
+- Minimum body font size: 16px (1rem).
+
+---
+
+## 11. Responsive Design
+
+### Breakpoints
+- **Mobile First**: Design for 375px width base.
+- **sm**: 640px (Large phones)
+- **md**: 768px (Tablets)
+- **lg**: 1024px (Desktop)
+
+### Mobile-Specific Patterns
+- Touch targets: minimum 44x44px on all interactive elements.
+- Mobile navigation: Hamburger menu pattern (see Components > Navigation).
+
+---
+
+## 12. Usage Examples
+
+### Design Tokens
+
+Tokens are defined as framework-agnostic CSS custom properties.
+
+- Naming convention: `--color-*`, `--font-*`, `--spacing-*`, `--shadow-*`, `--radius-*`, `--duration-*`
+
+```css
+:root {
+  /* Colors — Primary */
+  --color-primary: #2563EB;
+  --color-primary-dark: #1D4ED8;
+  --color-primary-light: #60A5FA;
+  --color-primary-foreground: #FFFFFF;
+
+  /* Colors — Semantic */
+  --color-success: #10B981;
+  --color-error: #EF4444;
+  --color-warning: #F59E0B;
+  --color-info: #0EA5E9;
+
+  /* Colors — Light Mode (default) */
+  --color-background: #FFFFFF;
+  --color-surface: #F8FAFC;
+  --color-text-primary: #0F172A;
+  --color-text-secondary: #64748B;
+  --color-text-disabled: #CBD5E1;
+  --color-border: #E2E8F0;
+
+  /* Typography */
+  --font-family-sans: 'Inter', sans-serif;
+  --font-family-mono: 'JetBrains Mono', monospace;
+  --font-size-h1: 1.875rem;
+  --font-size-h2: 1.5rem;
+  --font-size-h3: 1.25rem;
+  --font-size-body-lg: 1.125rem;
+  --font-size-body: 1rem;
+  --font-size-body-sm: 0.875rem;
+  --font-size-caption: 0.75rem;
+  --font-weight-regular: 400;
+  --font-weight-medium: 500;
+  --font-weight-semibold: 600;
+  --font-weight-bold: 700;
+
+  /* Spacing */
+  --spacing-xs: 0.25rem;
+  --spacing-sm: 0.5rem;
+  --spacing-md: 1rem;
+  --spacing-lg: 1.5rem;
+  --spacing-xl: 2rem;
+
+  /* Border Radius */
+  --radius-md: 0.375rem;
+  --radius-lg: 0.5rem;
+  --radius-full: 9999px;
+
+  /* Shadows */
+  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
+  --shadow-md: 0 4px 6px rgba(0, 0, 0, 0.07);
+
+  /* Transitions */
+  --duration-fast: 150ms;
+  --duration-medium: 200ms;
+  --ease-out: cubic-bezier(0, 0, 0.2, 1);
+}
+
+/* Dark Mode */
+[data-theme="dark"],
+.dark {
+  --color-background: #0F172A;
+  --color-surface: #1E293B;
+  --color-text-primary: #F8FAFC;
+  --color-text-secondary: #94A3B8;
+  --color-text-disabled: #475569;
+  --color-border: #334155;
+}
+```
+
+### Component Combinations
+
+To be defined.