@zigrivers/scaffold 3.6.0 → 3.8.0

package/content/knowledge/web-app/web-app-data-patterns.md

@@ -0,0 +1,218 @@
+---
+name: web-app-data-patterns
+description: Client-side caching, optimistic updates, real-time sync, pagination strategies, form state management, and file upload patterns
+topics: [web-app, data-fetching, caching, react-query, swr, pagination, forms, file-upload]
+---
+
+Data management in web applications spans from simple fetch-and-display to complex real-time collaborative state. The wrong patterns here produce stale UIs, conflicting updates, degraded performance under load, and frustrated users. The right patterns make applications feel instantaneous even over slow networks — by understanding the difference between server state, client state, and ephemeral UI state, and applying the appropriate tool to each.
+
+## Summary
+
+### Server State vs Client State
+
+The most important conceptual distinction in modern web data management:
+
+- **Server state** — data owned by the server, shared across clients, and potentially stale as soon as it's fetched: user profiles, product listings, feed items. Use a data-fetching library (React Query, SWR) to manage this.
+- **Client state** — data owned by the current user's session, not persisted to the server: currently selected tab, sidebar open/closed, in-progress form data. Use React local state or Zustand/Jotai/Redux.
+
+Mixing these causes anti-patterns: putting server data in Redux, or making API calls from useEffect without caching. Libraries like React Query exist precisely because server state needs cache management, background refetching, deduplication, and stale-while-revalidate semantics that generic state managers don't provide.
+
+### SWR vs React Query
+
+Both implement stale-while-revalidate caching for server state:
+
+| Concern | SWR | React Query (TanStack Query) |
+|---|---|---|
+| Bundle size | ~6 KB | ~13 KB |
+| Mutations | Manual invalidation | Built-in `useMutation` + auto-invalidation |
+| Infinite scroll | `useSWRInfinite` | `useInfiniteQuery` |
+| Optimistic updates | Manual | First-class via `onMutate` + rollback |
+| DevTools | None built-in | Excellent DevTools panel |
+| Best for | Read-heavy apps, minimal mutations | Apps with complex mutation flows |
+
+**Rule:** Use React Query for most production applications. Use SWR for read-heavy dashboards where its simplicity is a net benefit.
+
+### Optimistic Updates
+
+Update the UI before the server confirms the mutation. If the server rejects, roll back.
+
+Optimistic updates are appropriate when: the mutation has a very high success rate, the latency is noticeable, and the rollback experience is not confusing. They are not appropriate when: the server-side result is unpredictable (e.g., a bid on an auction where you may lose).
+
+### Pagination Strategies
+
+**Cursor-based pagination** (preferred):
+- Each page returns a `nextCursor` opaque token; the next request passes `?cursor=<token>`
+- Stable across concurrent inserts/deletes — no items skipped or duplicated
+- Required for infinite scroll (offset pagination breaks on live data)
+- Cannot jump to arbitrary page numbers
+
+**Offset-based pagination**:
+- `?page=3&limit=20` or `?offset=40&limit=20`
+- Supports "jump to page N" UI
+- Items shift when rows are inserted/deleted — users see duplicates or skipped items on live data
+- Appropriate for admin tables with infrequent writes and explicit page navigation
+
+### Real-Time Data Sync
+
+Three patterns in increasing complexity:
+1. **Polling** — simplest, least efficient: re-fetch every N seconds. Acceptable for dashboards that update every few minutes.
+2. **Server-Sent Events (SSE)** — server pushes updates to client over a single long-lived HTTP connection. One-directional. Excellent for notifications, activity feeds, live counters. No WebSocket negotiation overhead.
+3. **WebSocket** — bidirectional full-duplex. Required for chat, collaborative editing, live games. Higher complexity: connection management, reconnection, presence.
+
+## Deep Guidance
+
+### React Query Patterns
+
+```typescript
+// 1. Standard query with stale time
+const { data: posts, isLoading, error } = useQuery({
+  queryKey: ['posts', { authorId, page }],
+  queryFn: () => fetchPosts({ authorId, page }),
+  staleTime: 5 * 60 * 1000,  // Data considered fresh for 5 minutes
+  gcTime: 10 * 60 * 1000,    // Keep in cache for 10 minutes after unmount
+});
+
+// 2. Optimistic mutation with rollback
+const queryClient = useQueryClient();
+
+const likeMutation = useMutation({
+  mutationFn: (postId: string) => api.likePost(postId),
+
+  onMutate: async (postId) => {
+    // Cancel any in-flight refetches that would overwrite optimistic update
+    await queryClient.cancelQueries({ queryKey: ['posts'] });
+
+    // Snapshot the previous value
+    const previousPosts = queryClient.getQueryData(['posts']);
+
+    // Optimistically update
+    queryClient.setQueryData(['posts'], (old: Post[]) =>
+      old.map(p => p.id === postId ? { ...p, likeCount: p.likeCount + 1, likedByMe: true } : p)
+    );
+
+    // Return context for rollback
+    return { previousPosts };
+  },
+
+  onError: (error, postId, context) => {
+    // Roll back to snapshot on failure
+    queryClient.setQueryData(['posts'], context?.previousPosts);
+  },
+
+  onSettled: () => {
+    // Always refetch to sync with server truth
+    queryClient.invalidateQueries({ queryKey: ['posts'] });
+  },
+});
+
+// 3. Infinite scroll
+const { data, fetchNextPage, hasNextPage, isFetchingNextPage } = useInfiniteQuery({
+  queryKey: ['feed'],
+  queryFn: ({ pageParam }) => fetchFeed({ cursor: pageParam }),
+  getNextPageParam: (lastPage) => lastPage.nextCursor ?? undefined,
+  initialPageParam: undefined as string | undefined,
+});
+```
+
+### File Upload Pattern
+
+Uploads require a different flow from standard JSON mutations: multipart form data, progress tracking, and (for large files) direct-to-storage upload via presigned URLs.
+
+```typescript
+// PATTERN: Presigned URL upload (bypasses app server, goes direct to S3/GCS)
+async function uploadFile(file: File, onProgress: (pct: number) => void) {
+  // Step 1: Get presigned URL from app server
+  const { uploadUrl, fileKey } = await api.getUploadUrl({
+    filename: file.name,
+    contentType: file.type,
+    size: file.size,
+  });
+
+  // Step 2: Upload directly to storage (no app server in the critical path)
+  await new Promise<void>((resolve, reject) => {
+    const xhr = new XMLHttpRequest();
+    xhr.open('PUT', uploadUrl);
+    xhr.setRequestHeader('Content-Type', file.type);
+
+    xhr.upload.onprogress = (event) => {
+      if (event.lengthComputable) {
+        onProgress(Math.round((event.loaded / event.total) * 100));
+      }
+    };
+
+    xhr.onload = () => xhr.status === 200 ? resolve() : reject(new Error(`Upload failed: ${xhr.status}`));
+    xhr.onerror = () => reject(new Error('Network error during upload'));
+    xhr.send(file);
+  });
+
+  // Step 3: Notify app server that upload is complete
+  return api.confirmUpload({ fileKey });
+}
+```
+
+Presigned URL uploads: never proxy large files through your app server. A 100 MB upload through an app server occupies a Node.js worker for the entire transfer duration.
+
+### Form State Management
+
+For most forms: `react-hook-form` + Zod schema validation. This pattern avoids controlled component re-renders (critical for large forms), provides schema-driven validation, and integrates cleanly with TypeScript.
+
+```typescript
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+
+const profileSchema = z.object({
+  displayName: z.string().min(2).max(50),
+  email: z.string().email(),
+  bio: z.string().max(500).optional(),
+});
+
+type ProfileForm = z.infer<typeof profileSchema>;
+
+function ProfileEditor() {
+  const { register, handleSubmit, formState: { errors, isDirty, isSubmitting } } = useForm<ProfileForm>({
+    resolver: zodResolver(profileSchema),
+    defaultValues: { displayName: user.displayName, email: user.email },
+  });
+
+  const onSubmit = async (data: ProfileForm) => {
+    await updateProfile(data);
+  };
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register('displayName')} />
+      {errors.displayName && <span>{errors.displayName.message}</span>}
+      <button type="submit" disabled={!isDirty || isSubmitting}>Save</button>
+    </form>
+  );
+}
+```
+
+Reserve heavier solutions (Formik, final-form) only for highly dynamic form generation requirements. For most product forms, react-hook-form is sufficient and faster.
+
+### Cursor Pagination Implementation
+
+```typescript
+// Server-side cursor pagination (PostgreSQL + Prisma)
+async function getPaginatedPosts(cursor?: string, limit = 20) {
+  const posts = await prisma.post.findMany({
+    take: limit + 1,  // Fetch one extra to determine if there's a next page
+    ...(cursor && {
+      cursor: { id: cursor },
+      skip: 1,  // Skip the cursor item itself
+    }),
+    orderBy: { createdAt: 'desc' },
+  });
+
+  const hasNextPage = posts.length > limit;
+  const items = hasNextPage ? posts.slice(0, -1) : posts;
+
+  return {
+    items,
+    nextCursor: hasNextPage ? items[items.length - 1].id : null,
+  };
+}
+```
+
+Always fetch `limit + 1` to check for next page existence without an extra COUNT query.

package/content/knowledge/web-app/web-app-deployment-workflow.md

@@ -0,0 +1,143 @@
+---
+name: web-app-deployment-workflow
+description: Preview deploys per PR, staging environments, deployment branches, CI/CD pipeline stages, rollback strategies, and canary deployments
+topics: [web-app, deployment, ci-cd, staging, preview, rollback, canary]
+---
+
+A mature deployment workflow transforms deployment from a risky, manual event into a routine, automated step. The goal is to make every merge to main automatically and safely deliverable to production, with fast rollback when something goes wrong. The cost of building this infrastructure up front is trivially small compared to the cost of a major incident caused by a manual deploy process.
+
+## Summary
+
+A mature deployment workflow makes every merge to main automatically deliverable with fast rollback. Every PR gets a preview deploy. CI/CD runs lint, typecheck, test, and build in fail-fast order. Test rollback procedures quarterly. For high-traffic apps, use canary deployments with explicit rollback criteria.
+
+## Deep Guidance
+
+### Preview Deploys Per PR
+
+Every pull request should get its own preview deployment — a fully functional URL that reviewers and QA can use to verify behavior before merging. This is the single highest-ROI practice in modern web deployment:
+
+- **Vercel, Netlify, Railway**: Automatically create preview deploys on PR open/push. Zero configuration for most frameworks.
+- **Custom CI**: Build and deploy to a path-based preview URL (`preview/<pr-number>/`) or a subdomain. Tear down on PR close.
+
+Preview deploys must use isolated environment variables (dev database, dev third-party API keys). Never point a preview deploy at a production database.
+
+### Deployment Branches
+
+Establish a clear branch-to-environment mapping and document it in the repo:
+
+| Branch | Environment | Deploys |
+|--------|-------------|---------|
+| `main` | Production | Automatic on merge |
+| `staging` | Staging | Automatic on merge |
+| `feature/*`, `fix/*` | Preview | Automatic on PR push |
+
+Avoid long-lived branches other than `main` and optionally `staging`. Feature branches merge to `main` via PR. `main` deploys to production. This is the simplest model that works.
+
+If you have a separate `staging` branch: keep it in sync with `main` via regular merges. Staging branches that lag `main` by weeks create false confidence and painful integration surprises.
+
+### CI/CD Pipeline Stages
+
+Every push to a branch should run a pipeline in this order (fast-to-slow, fail-fast):
+
+1. **Install dependencies** (cached; skip if lockfile unchanged)
+2. **Lint** — ESLint, Prettier check (fail fast; ~30 seconds)
+3. **Typecheck** — `tsc --noEmit` (fail fast; ~60 seconds)
+4. **Unit tests** — Vitest/Jest with coverage threshold (1–3 minutes)
+5. **Build** — Production build to verify no build errors (2–5 minutes)
+6. **E2E tests** (optional, on main/staging only) — Playwright or Cypress against preview deploy (5–15 minutes)
+7. **Deploy** — Only if all above pass
+
+Do not run all tests on every PR if the test suite is slow. Use test impact analysis (run only tests related to changed files) or split E2E tests to a separate workflow that runs on merge to `main`.
+
+### Rollback Strategies
+
+Every deployment system must have a tested rollback procedure. "We can just revert the commit and redeploy" is not a rollback strategy — that takes 5+ minutes and requires a developer to execute it under pressure.
+
+- **Vercel/Netlify**: One-click rollback to any previous deployment in the dashboard. Target: under 30 seconds to rollback.
+- **Custom infrastructure**: Maintain the previous two deployment artifacts. Rollback = swap the active artifact. Use blue-green or immutable deployment patterns (see below).
+- **Database migrations**: Rollback is the hard part. Write migrations that are forward-compatible (additive only). Keep destructive changes separate, deployed only after the new code is stable. Use a migration tool that tracks state (Prisma, Flyway, Liquibase).
+
+Test the rollback procedure at least quarterly. A rollback you have never practiced will fail in an incident.
+
+### Canary Deployments
+
+For high-traffic production apps, deploy changes to a small percentage of traffic before full rollout:
+
+- Route 5% of requests to the new version, 95% to the old
+- Monitor error rates, latency, and business metrics for 15–30 minutes
+- Gradually increase the percentage or roll back if metrics degrade
+
+Canary deployments require infrastructure support: feature flag services (LaunchDarkly, Unleash), traffic splitting at the load balancer (AWS ALB weighted routing, Cloudflare Workers), or platform-level support (Vercel edge middleware). Do not implement canaries manually — use the platform's built-in mechanism.
+
+### CI/CD Pipeline Template (GitHub Actions)
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+
+on:
+  push:
+    branches: [main, staging]
+  pull_request:
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci
+      - run: npm run lint
+      - run: npm run typecheck
+      - run: npm run test -- --coverage
+      - run: npm run build
+
+  deploy-preview:
+    needs: quality
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci && npm run build
+      - name: Deploy preview
+        run: npx vercel deploy --prebuilt --token=${{ secrets.VERCEL_TOKEN }}
+```
+
+### Deployment Environment Variables
+
+Separate environment variables by tier and manage them securely:
+
+- **Local**: `.env.local` (gitignored, developer-managed)
+- **Preview**: Vercel/Netlify project environment variables, marked "Preview" tier; use dev API keys only
+- **Staging**: Staging-specific secrets in GitHub Actions or your secrets manager
+- **Production**: Production secrets never visible to developers; managed by infra/ops
+
+Audit who has access to production secrets quarterly. Rotate API keys and tokens on team member offboarding without exception.
+
+### Defining "Deployment Complete"
+
+A deployment is not complete when the deploy command exits. It is complete when:
+
+1. The new version is serving traffic (health check passes)
+2. Error rate is not elevated above baseline
+3. Response latency p95 is not elevated above baseline
+4. At least one synthetic monitor has confirmed the critical user journey works
+
+Automate this check in your deploy pipeline. Do not send "deploy succeeded" notifications until you have validated real traffic behavior.
+
+### Zero-Downtime Deployments
+
+For apps that cannot tolerate downtime:
+
+- **Rolling deployments**: Bring up new instances, drain old instances. Requires stateless services (no in-memory session storage).
+- **Blue-green deployments**: Run two identical environments (blue = current, green = new). Switch traffic at the load balancer level. Old environment stays up as instant rollback target.
+- **Feature flags**: Deploy code to production without enabling it. Enable via flag without a deployment. Fastest and most controllable rollout mechanism.
+
+For stateful workloads (databases, file storage): always plan the data migration before the code migration. Code deploys are reversible; bad data migrations often are not.

package/content/knowledge/web-app/web-app-deployment.md

@@ -0,0 +1,134 @@
+---
+name: web-app-deployment
+description: Static CDN hosting, serverless platforms, container deployments, edge runtimes, long-running servers, and blue-green deploy patterns for web apps
+topics: [web-app, deployment, vercel, netlify, aws, docker, cloudflare, serverless, containers]
+---
+
+Deployment platform selection determines your app's operational cost, performance ceiling, and scaling characteristics. Each platform has a different cost model, latency profile, and runtime constraint. Choose based on your app's rendering strategy, traffic patterns, and team's operational expertise — not on what is fashionable.
+
+## Summary
+
+Web app deployment platforms range from static CDN hosting (cheapest, fastest TTFB) through serverless (pay-per-invocation, cold start concerns), containers (persistent connections, custom runtimes), edge functions (global low-latency transformations), to long-running servers (WebSockets, background jobs). Choose based on rendering strategy, traffic patterns, and operational expertise.
+
+## Deep Guidance
+
+### Static Hosting (CDN)
+
+For SSG applications with no server-side rendering at request time:
+
+- **Best platforms**: Cloudflare Pages, Netlify, Vercel (static tier), AWS S3 + CloudFront, GitHub Pages
+- **Cost**: Near zero for low-to-medium traffic; CDN egress costs at very high traffic
+- **Performance**: Best possible — globally distributed, no cold starts, ~50 ms TTFB from any major city
+- **Limitations**: No request-time server logic, no secrets at request time, data freshness = deploy frequency
+
+Configure aggressive caching headers. Static assets (hashed filenames) get `Cache-Control: immutable, max-age=31536000`. HTML pages get `Cache-Control: no-cache` (validated on every request, served from cache when fresh).
+
+### Serverless (Vercel, Netlify, AWS Lambda)
+
+For SSR apps or API routes that need server logic at request time without managing servers:
+
+- **Best platforms**: Vercel (Next.js-native), Netlify Functions, AWS Lambda + API Gateway, Cloudflare Pages Functions
+- **Cost model**: Pay per invocation and compute time. Typically very cheap at low traffic, can become expensive at sustained high traffic vs. a long-running server.
+- **Cold starts**: The primary performance concern. Lambda cold starts: 100–500 ms (Node.js), 1–3 seconds (container-based). Vercel/Netlify Edge Functions: 0 ms (V8 isolates, not containers).
+- **Limitations**: Execution time limits (Vercel: 10–300 seconds depending on plan; Lambda: 15 minutes max), no persistent memory between invocations, no long-lived connections
+
+Minimize cold start impact: keep bundles small (Lambda-specific: prefer ESM + tree-shaking over CommonJS), use Provisioned Concurrency for latency-critical endpoints, or migrate latency-sensitive APIs to edge functions.
+
+### Container (Docker, AWS ECS/Fargate, Google Cloud Run)
+
+For apps that need more control than serverless, persistent connections, or custom runtime environments:
+
+- **Best platforms**: AWS ECS/Fargate, Google Cloud Run, Azure Container Apps, Railway, Fly.io, self-managed Kubernetes
+- **Cost model**: Per-container-hour (Fargate) or per-request with scale-to-zero (Cloud Run). More expensive than serverless at low traffic, cheaper at sustained high traffic.
+- **Benefits over serverless**: No cold starts with min replicas > 0, persistent WebSocket connections, custom binaries/runtimes, larger memory limits
+- **Operational overhead**: You manage container definitions, health checks, and scaling policies
+
+Use multi-stage Docker builds to minimize image size. Target images under 200 MB:
+
+```dockerfile
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM node:20-alpine AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+COPY --from=builder /app/.next ./.next
+COPY --from=builder /app/public ./public
+COPY --from=builder /app/package.json ./
+RUN npm ci --omit=dev
+USER node
+EXPOSE 3000
+CMD ["npm", "start"]
+```
+
+### Edge (Cloudflare Workers, Vercel Edge Functions)
+
+For global, low-latency request processing with simple logic:
+
+- **Runtime**: V8 isolates (not Node.js). Fast startup (~0 ms), runs at 300+ edge locations globally, ~1–5 ms TTFB worldwide.
+- **Use cases**: Auth token validation, A/B testing, geo-routing, request rewriting, rate limiting, personalized cache headers
+- **Limitations**: No Node.js built-ins (`fs`, `crypto` partially available, `child_process` unavailable), no SQLite, execution time limits (50 ms CPU time on Cloudflare free tier), no persistent file system
+- **Data access**: Use edge-native databases: Cloudflare D1 (SQLite), Cloudflare KV, Upstash Redis, PlanetScale edge
+
+Never put complex business logic in edge functions. Their value is speed and global distribution for request/response transformations, not application logic.
+
+### Long-Running Server (Express, Fastify, Node.js HTTP)
+
+For apps that need WebSockets, background jobs, or full control over the request lifecycle:
+
+- **Best platforms**: AWS EC2 + ALB, Fly.io, Railway, DigitalOcean Droplets, Hetzner (cost-efficient)
+- **When to choose**: Real-time features (WebSockets, SSE), background workers, long-running database transactions, legacy apps that cannot be adapted to serverless constraints
+
+### Blue-Green Deployments
+
+Blue-green deployments eliminate downtime and reduce rollback time to seconds:
+
+1. **Blue** = current production (100% of traffic)
+2. **Green** = new version (deployed but receiving 0% of traffic)
+3. Run smoke tests against the green environment
+4. Switch the load balancer to route 100% of traffic to green
+5. Monitor for 5–15 minutes
+6. If healthy: decommission blue. If unhealthy: switch back to blue (rollback complete in < 30 seconds)
+
+Requirements: stateless app servers (session data in Redis/DB, not in-memory), database schema changes must be backward-compatible with both versions simultaneously.
+
+### Platform Selection Decision Matrix
+
+| Criteria | Static CDN | Serverless | Container | Edge | Long-Running |
+|----------|-----------|------------|-----------|------|--------------|
+| SSG only | Best | Overkill | Overkill | Good | Overkill |
+| SSR with SEO | — | Best | Good | Good | Good |
+| Real-time (WebSocket) | No | No | Best | No | Best |
+| Low traffic / cost | Best | Best | Expensive | Best | Expensive |
+| High sustained traffic | Best | Expensive | Best | Best | Best |
+| Cold start sensitive | N/A | Problem | Solved | Solved | Solved |
+| Ops complexity | Lowest | Low | Medium | Low | High |
+
+### Health Checks and Readiness Probes
+
+Every deployed service must expose health endpoints:
+
+```typescript
+// app/api/health/route.ts
+export async function GET() {
+  try {
+    // Check critical dependencies
+    await db.query("SELECT 1");
+    return Response.json({ status: "healthy", version: process.env.npm_package_version });
+  } catch (error) {
+    return Response.json({ status: "unhealthy", error: String(error) }, { status: 503 });
+  }
+}
+```
+
+Configure your load balancer or container orchestrator to route traffic only to healthy instances. Health check failure should trigger automatic rollback in your deployment pipeline.
+
+### Cost Optimization
+
+- Use serverless for variable or low traffic; switch to containers once monthly serverless cost exceeds 2–3 baseline container instances
+- CDN cache hit rate should be above 90% for SSG content — if it is not, investigate cache-busting headers
+- Set spending alerts at 50% and 100% of monthly budget on cloud providers — auto-remediation (scale down) if the alert fires on unexpected traffic

package/content/knowledge/web-app/web-app-design-system.md

@@ -0,0 +1,158 @@
+---
+name: web-app-design-system
+description: Responsive token systems, dark/light mode, component library patterns, and CSS methodology selection for web applications
+topics: [web-app, design-system, css, tokens, dark-mode, responsive]
+---
+
+A design system is the contract between design and engineering. Without one, components drift, spacing is inconsistent, and every engineer makes independent decisions about color, typography, and layout. A well-structured token system makes that contract explicit, machine-enforceable, and refactorable — changing a spacing scale or switching a brand color becomes a one-line edit rather than a codebase-wide search-and-replace.
+
+## Summary
+
+A design system encodes design decisions as tokens at three tiers: primitive (raw values), semantic (intent-based aliases), and component-scoped overrides. Support dark/light mode via CSS custom properties with both `prefers-color-scheme` and explicit `data-theme` toggle. Commit to a consistent breakpoint scale and CSS methodology. Use headless component libraries for accessible behavior with full visual control.
+
+## Deep Guidance
+
+### Token Architecture
+
+Design tokens are the atoms of a design system. They encode decisions — not values — at three tiers:
+
+1. **Primitive tokens** — Raw values with no semantic meaning: `--color-blue-500: #3b82f6`, `--spacing-4: 16px`, `--font-size-lg: 1.125rem`. Never use primitive tokens directly in components.
+
+2. **Semantic tokens** — Intent-based aliases of primitives: `--color-interactive: var(--color-blue-500)`, `--space-component-padding: var(--spacing-4)`. Components consume semantic tokens.
+
+3. **Component tokens** — Component-scoped overrides: `--button-background: var(--color-interactive)`. Allows per-component theming without touching semantic tokens.
+
+Spacing, typography, and breakpoints belong in this hierarchy. A spacing scale (4/8/12/16/24/32/48/64px) enforced via tokens prevents the "just add a margin-top: 11px" habit that destroys visual rhythm.
+
+### Dark/Light Mode
+
+Use CSS custom properties with `prefers-color-scheme` and an explicit `data-theme` attribute override:
+
+```css
+/* Primitive layer */
+:root {
+  --color-neutral-0: #ffffff;
+  --color-neutral-900: #111827;
+}
+
+/* Semantic layer — light mode defaults */
+:root {
+  --color-surface: var(--color-neutral-0);
+  --color-text-primary: var(--color-neutral-900);
+}
+
+/* Dark mode via media query */
+@media (prefers-color-scheme: dark) {
+  :root {
+    --color-surface: var(--color-neutral-900);
+    --color-text-primary: var(--color-neutral-0);
+  }
+}
+
+/* Manual override via JS toggle */
+[data-theme="dark"] {
+  --color-surface: var(--color-neutral-900);
+  --color-text-primary: var(--color-neutral-0);
+}
+```
+
+Always support both mechanisms: `prefers-color-scheme` for first-visit experience, `data-theme` for user preference stored in `localStorage`.
+
+### CSS Methodology Selection
+
+| Approach | Best For | Trade-offs |
+|---|---|---|
+| Utility-first (Tailwind) | Rapid iteration, small teams, consistent constraints | Verbose JSX, limited custom design expression |
+| CSS Modules | Scoped styles with full CSS power, no runtime cost | Manual naming, no global token enforcement |
+| CSS-in-JS (Emotion, styled-components) | Dynamic theming, colocation, TypeScript safety | Runtime cost, hydration complexity in SSR |
+| Zero-runtime (Vanilla Extract, Linaria) | SSR-safe, type-safe tokens, no runtime overhead | Build-time complexity, less dynamic |
+
+For most production web apps, the recommendation is: **Tailwind + CSS custom properties** for utility-heavy UIs, or **CSS Modules + tokens** for design-system-first projects where designers own the token layer.
+
+### Responsive Breakpoints
+
+Commit to a consistent breakpoint scale and never deviate:
+
+```css
+/* Mobile-first breakpoints */
+--bp-sm: 640px;   /* Large phones */
+--bp-md: 768px;   /* Tablets */
+--bp-lg: 1024px;  /* Small desktops */
+--bp-xl: 1280px;  /* Large desktops */
+--bp-2xl: 1536px; /* Wide screens */
+```
+
+Use `min-width` queries exclusively (mobile-first). Avoid magic numbers in media queries — always reference the token scale.
+
+### Component Library Patterns
+
+A component library is the implementation layer of the design system. Key architectural decisions:
+
+**Compound components over prop explosion:**
+
+```tsx
+// BAD: Props explode as requirements grow
+<Select
+  label="Country"
+  options={countries}
+  placeholder="Select..."
+  isSearchable
+  isClearable
+  isMulti
+  maxSelectedItems={3}
+/>
+
+// GOOD: Compound pattern — composable, extensible
+<Select value={value} onChange={setValue}>
+  <Select.Trigger>
+    <Select.Value placeholder="Select country..." />
+  </Select.Trigger>
+  <Select.Content>
+    <Select.Search />
+    {countries.map(c => (
+      <Select.Item key={c.code} value={c.code}>{c.name}</Select.Item>
+    ))}
+  </Select.Content>
+</Select>
+```
+
+**Headless components for styling flexibility:**
+Use Radix UI, Headless UI, or React Aria as the unstyled behavior layer. Wire your token system on top. This gives accessible keyboard navigation and ARIA semantics for free while preserving full visual control.
+
+**Token enforcement via linting:**
+Use `stylelint-no-invalid-hex` and custom Stylelint rules (or ESLint for CSS-in-JS) to reject hardcoded color values not referencing a token. Automate this in CI.
+
+### Typography Scale
+
+Build a modular type scale with explicit roles:
+
+```css
+:root {
+  /* Scale steps — use a modular scale ratio (1.25 or 1.333) */
+  --text-xs: 0.75rem;    /* 12px — labels, captions */
+  --text-sm: 0.875rem;   /* 14px — body secondary */
+  --text-base: 1rem;     /* 16px — body primary */
+  --text-lg: 1.125rem;   /* 18px — subheadings */
+  --text-xl: 1.25rem;    /* 20px — section headings */
+  --text-2xl: 1.5rem;    /* 24px — page headings */
+  --text-3xl: 1.875rem;  /* 30px — hero headings */
+
+  /* Line heights tied to text size for proper vertical rhythm */
+  --leading-tight: 1.25;
+  --leading-normal: 1.5;
+  --leading-relaxed: 1.75;
+}
+```
+
+Never use pixel values for font sizes in component code — only reference scale tokens. This ensures user font size preferences (browser zoom, accessibility settings) are respected.
+
+### Design Token Pipeline
+
+For teams with a Figma design system, automate the token pipeline:
+
+1. Designers export tokens from Figma using the Tokens Studio plugin as a JSON file
+2. CI runs a token transformer (Style Dictionary) that converts JSON to CSS custom properties, TypeScript constants, and platform-specific formats
+3. The generated files are committed to the repository and reviewed in PRs
+4. Token changes are flagged in design review before code review
+
+This makes "design changed the brand blue" a designer-owned PR rather than an engineering ticket.