cortex-agents 3.4.0 → 4.0.1

package/.opencode/skills/monitoring-observability/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: monitoring-observability
+description: Structured logging, metrics instrumentation, distributed tracing, health checks, and alerting patterns
+license: Apache-2.0
+compatibility: opencode
+---
+
+# Monitoring & Observability Skill
+
+This skill provides patterns for making applications observable in production through logging, metrics, tracing, and alerting.
+
+## When to Use
+
+Use this skill when:
+- Adding logging to new features or services
+- Instrumenting code with metrics (counters, histograms, gauges)
+- Implementing distributed tracing across services
+- Designing health check endpoints
+- Setting up alerting and SLO definitions
+- Debugging production issues through observability data
+
+## The Three Pillars of Observability
+
+### 1. Logs — What Happened
+Structured, contextual records of discrete events.
+
+### 2. Metrics — How Much / How Fast
+Numeric measurements aggregated over time.
+
+### 3. Traces — The Journey
+End-to-end request paths across service boundaries.
+
+## Structured Logging
+
+### Principles
+- **Always use structured logging** (JSON) — never unstructured `console.log` in production
+- **Log levels matter**: ERROR (action needed), WARN (degraded), INFO (business events), DEBUG (development)
+- **Include context**: correlation IDs, user IDs, request IDs, operation names
+- **Never log secrets**: passwords, tokens, PII, credit card numbers
+
+### Log Levels Guide
+
+| Level | When to Use | Example |
+|-------|-------------|---------|
+| **ERROR** | Something failed and needs attention | Database connection lost, payment failed |
+| **WARN** | Degraded but still functioning | Cache miss fallback, retry attempt, rate limit approaching |
+| **INFO** | Significant business events | User signed up, order placed, deployment completed |
+| **DEBUG** | Development/troubleshooting detail | SQL query executed, cache hit/miss, function entry/exit |
+
+### Structured Log Format
+
+```json
+{
+  "timestamp": "2025-01-15T10:30:00.000Z",
+  "level": "info",
+  "message": "Order placed successfully",
+  "service": "order-service",
+  "traceId": "abc123",
+  "spanId": "def456",
+  "userId": "user_789",
+  "orderId": "order_012",
+  "amount": 99.99,
+  "currency": "USD",
+  "duration_ms": 145
+}
+```
+
+### Correlation IDs
+- Generate a unique request ID at the entry point (API gateway, load balancer)
+- Propagate it through all downstream calls via headers (`X-Request-ID`, `traceparent`)
+- Include it in every log line for cross-service correlation
+
+### What to Log
+
+**DO log:**
+- Request/response boundaries (method, path, status, duration)
+- Business events (user actions, state transitions, transactions)
+- Error details with stack traces and context
+- Performance-relevant data (query times, cache hit rates)
+- Security events (auth failures, permission denials, rate limits)
+
+**DO NOT log:**
+- Passwords, tokens, API keys, secrets
+- Full credit card numbers, SSNs, or PII without masking
+- High-frequency debug data in production (use sampling)
+- Request/response bodies containing sensitive data
+
+## Metrics Instrumentation
+
+### Metric Types
+
+| Type | Use Case | Example |
+|------|----------|---------|
+| **Counter** | Monotonically increasing value | Total requests, errors, orders placed |
+| **Gauge** | Value that goes up and down | Active connections, queue depth, memory usage |
+| **Histogram** | Distribution of values | Request latency, response size, batch processing time |
+| **Summary** | Pre-calculated quantiles | P50/P95/P99 latency (client-side) |
+
+### Naming Conventions
+- Use snake_case: `http_requests_total`, `request_duration_seconds`
+- Include units in the name: `_seconds`, `_bytes`, `_total`
+- Use `_total` suffix for counters
+- Prefix with service/subsystem: `api_http_requests_total`
+
+### Key Metrics to Track
+
+**RED Method (Request-driven services):**
+- **R**ate — Requests per second
+- **E**rrors — Error rate (4xx, 5xx)
+- **D**uration — Request latency distribution
+
+**USE Method (Resource-oriented):**
+- **U**tilization — % of resource capacity used
+- **S**aturation — Queue depth, backpressure
+- **E**rrors — Error count per resource
+
+### Cardinality Warning
+- Avoid high-cardinality labels (user IDs, request IDs, URLs with path params)
+- Keep label combinations < 1000 per metric
+- Use bounded values: HTTP methods (GET, POST), status codes (2xx, 4xx, 5xx), endpoints (normalized)
+
+## Distributed Tracing
+
+### OpenTelemetry Patterns
+- **Span** — A single operation within a trace (e.g., HTTP request, DB query, function call)
+- **Trace** — A tree of spans representing an end-to-end request
+- **Context Propagation** — Passing trace context across service boundaries via headers
+
+### What to Trace
+- HTTP requests (client and server)
+- Database queries
+- Cache operations
+- Message queue publish/consume
+- External API calls
+- Significant business operations
+
+### Span Attributes
+```
+http.method: GET
+http.url: /api/users/123
+http.status_code: 200
+db.system: postgresql
+db.statement: SELECT * FROM users WHERE id = $1
+messaging.system: kafka
+messaging.destination: orders
+```
+
+### Sampling Strategies
+- **Head-based sampling**: Decide at trace start (e.g., sample 10% of requests)
+- **Tail-based sampling**: Decide after trace completes (keep errors, slow requests, sample normal)
+- **Priority sampling**: Always sample errors, high-value transactions; sample routine requests
+
+## Health Check Endpoints
+
+### Liveness vs Readiness
+
+| Check | Purpose | Failure Action |
+|-------|---------|----------------|
+| **Liveness** (`/healthz`) | Is the process alive? | Restart the container |
+| **Readiness** (`/readyz`) | Can it serve traffic? | Remove from load balancer |
+| **Startup** (`/startupz`) | Has it finished initializing? | Wait before liveness checks |
+
+### Health Check Response Format
+```json
+{
+  "status": "healthy",
+  "checks": {
+    "database": { "status": "healthy", "latency_ms": 5 },
+    "cache": { "status": "healthy", "latency_ms": 1 },
+    "external_api": { "status": "degraded", "latency_ms": 2500, "message": "Slow response" }
+  },
+  "version": "1.2.3",
+  "uptime_seconds": 86400
+}
+```
+
+### Best Practices
+- Health checks should be **fast** (< 1 second)
+- Liveness should check the process only — NOT external dependencies
+- Readiness should check critical dependencies (database, cache)
+- Return appropriate HTTP status: 200 (healthy), 503 (unhealthy)
+- Include dependency health in readiness but not liveness
+
+## Alerting & SLOs
+
+### SLO Definitions
+- **SLI** (Service Level Indicator): The metric you measure (e.g., request latency P99)
+- **SLO** (Service Level Objective): The target (e.g., P99 latency < 500ms for 99.9% of requests)
+- **Error Budget**: Allowable failures (e.g., 0.1% of requests can exceed 500ms)
+
+### Alert Design Principles
+- **Alert on symptoms, not causes** — Alert on "users can't log in", not "CPU is high"
+- **Alert on SLO burn rate** — Alert when error budget is being consumed too fast
+- **Avoid alert fatigue** — Every alert should require human action
+- **Include runbook links** — Every alert should link to resolution steps
+
+### Severity Levels
+
+| Severity | Response Time | Example |
+|----------|--------------|---------|
+| **P1 — Critical** | Immediate (< 5 min) | Service down, data loss, security breach |
+| **P2 — High** | Within 1 hour | Degraded performance, partial outage |
+| **P3 — Medium** | Within 1 business day | Non-critical feature broken, elevated error rate |
+| **P4 — Low** | Next sprint | Performance degradation, tech debt alert |
+
+### Useful Alert Patterns
+- Error rate exceeds N% for M minutes
+- Latency P99 exceeds threshold for M minutes
+- Error budget burn rate > 1x for 1 hour (fast burn)
+- Error budget burn rate > 0.1x for 6 hours (slow burn)
+- Queue depth exceeds threshold (backpressure)
+- Certificate expiry within N days
+- Disk usage exceeds N%
+
+## Technology Selection
+
+### Logging
+- **Node.js**: pino, winston, bunyan
+- **Python**: structlog, python-json-logger
+- **Go**: zerolog, zap, slog (stdlib)
+- **Rust**: tracing, log + env_logger
+
+### Metrics
+- **Prometheus** — Pull-based, widely adopted, great with Kubernetes
+- **StatsD/Datadog** — Push-based, hosted
+- **OpenTelemetry Metrics** — Vendor-neutral, emerging standard
+
+### Tracing
+- **OpenTelemetry** — Vendor-neutral standard (recommended)
+- **Jaeger** — Open-source trace backend
+- **Zipkin** — Lightweight trace backend
+
+### Dashboards
+- **Grafana** — Open-source, works with Prometheus/Loki/Tempo
+- **Datadog** — Hosted all-in-one
+- **New Relic** — Hosted APM
+
+## Checklist
+
+When adding observability to a feature:
+- [ ] Structured logging with correlation IDs at request boundaries
+- [ ] Error logging with stack traces and context
+- [ ] Business event logging (significant state changes)
+- [ ] RED metrics for request-driven endpoints
+- [ ] Histogram for latency-sensitive operations
+- [ ] Trace spans for cross-service calls and database queries
+- [ ] Health check endpoint updated if new dependency added
+- [ ] No secrets or PII in logs
+- [ ] Appropriate log levels (not everything is INFO)
+- [ ] Dashboard updated with new metrics
+- [ ] Alerts defined for SLO violations

package/.opencode/skills/ui-design/SKILL.md

@@ -0,0 +1,402 @@
+---
+name: ui-design
+description: Visual design principles, UI patterns, spacing systems, typography, color, motion, and professional polish for web interfaces
+license: Apache-2.0
+compatibility: opencode
+---
+
+# UI Design Skill
+
+This skill provides visual design patterns and aesthetic guidelines for building professionally designed web interfaces. It complements the `frontend-development` skill which covers engineering implementation.
+
+## When to Use
+
+Use this skill when:
+- Building new pages, layouts, or UI components from scratch
+- Improving the visual quality or polish of an existing interface
+- Implementing a design system or component library
+- Making aesthetic decisions (colors, typography, spacing, motion)
+- Creating landing pages, dashboards, or marketing pages
+
+> For accessibility (WCAG, ARIA, keyboard navigation), see `frontend-development`.
+> For component implementation patterns (React, Vue, Svelte), see `frontend-development`.
+
+## Visual Hierarchy & Layout
+
+### Scanning Patterns
+- **F-pattern** — users scan left-to-right, then down the left edge. Place key content in the first two lines and along the left margin.
+- **Z-pattern** — for minimal content pages (landing, hero). Place logo top-left, CTA top-right, key info bottom-left, action bottom-right.
+
+### Visual Weight
+Elements draw attention through: **size** > **color/contrast** > **whitespace** > **position**. Use this hierarchy deliberately.
+
+| Element | Size | Weight | Tailwind Example |
+|---------|------|--------|-----------------|
+| Page title (h1) | 36-48px | Bold (700-800) | `text-4xl font-bold` |
+| Section heading (h2) | 24-30px | Semibold (600) | `text-2xl font-semibold` |
+| Card title (h3) | 18-20px | Medium (500) | `text-lg font-medium` |
+| Body text | 16px | Regular (400) | `text-base` |
+| Caption / helper | 12-14px | Regular (400) | `text-sm text-gray-500` |
+| Label / overline | 12px | Medium, uppercase | `text-xs font-medium uppercase tracking-wide` |
+
+### Content Density
+- **Spacious** (marketing, landing pages) — generous whitespace, large type, one idea per section
+- **Balanced** (SaaS apps, settings) — moderate padding, clear grouping
+- **Dense** (dashboards, data tables, admin panels) — compact spacing, smaller type, more info per viewport
+
+> **When to deviate:** Dense layouts are fine for power-user tools. Spacious layouts hurt productivity in data-heavy interfaces.
+
+## Spacing System
+
+### Default: 8px Base Unit
+
+All spacing derives from an 8px base. This creates visual rhythm and alignment.
+
+| Token | Value | Use For | Tailwind |
+|-------|-------|---------|----------|
+| `space-0.5` | 4px | Icon padding, tight inline gaps | `p-1`, `gap-1` |
+| `space-1` | 8px | Inline element gaps, input padding | `p-2`, `gap-2` |
+| `space-2` | 16px | Card inner padding, form field gaps | `p-4`, `gap-4` |
+| `space-3` | 24px | Card padding, group spacing | `p-6`, `gap-6` |
+| `space-4` | 32px | Section inner padding | `p-8`, `gap-8` |
+| `space-5` | 48px | Section gaps | `py-12`, `gap-12` |
+| `space-6` | 64px | Major section separation | `py-16`, `gap-16` |
+| `space-7` | 96px | Hero/page section padding | `py-24` |
+
+### Container Widths
+- **Prose content** — `max-w-prose` (65ch) for readable line lengths
+- **Form content** — `max-w-lg` (512px) or `max-w-xl` (576px)
+- **Dashboard content** — `max-w-7xl` (1280px) with side padding
+- **Full-bleed sections** — no max-width, content inside a centered container
+
+### The Whitespace Rule
+Generous whitespace signals professionalism. Cramped layouts signal amateur work. When in doubt, add more space between sections, not less.
+
+> **When to deviate:** Data-dense UIs (spreadsheets, trading platforms, IDEs) intentionally minimize whitespace. Follow the density level appropriate for the use case.
+
+## Typography
+
+### Default Type Scale (1.25 ratio)
+
+| Level | Size | Line Height | Weight | Tailwind |
+|-------|------|-------------|--------|----------|
+| Display | 48-60px | 1.1 | Bold (700) | `text-5xl font-bold leading-tight` |
+| H1 | 36px | 1.2 | Bold (700) | `text-4xl font-bold leading-tight` |
+| H2 | 30px | 1.25 | Semibold (600) | `text-3xl font-semibold` |
+| H3 | 24px | 1.3 | Semibold (600) | `text-2xl font-semibold` |
+| H4 | 20px | 1.4 | Medium (500) | `text-xl font-medium` |
+| Body | 16px | 1.5-1.75 | Regular (400) | `text-base leading-relaxed` |
+| Small | 14px | 1.5 | Regular (400) | `text-sm` |
+| Caption | 12px | 1.5 | Regular (400) | `text-xs text-gray-500` |
+
+### Font Recommendations
+
+| Project Type | Font | Tailwind Config |
+|-------------|------|----------------|
+| SaaS / Dashboard | Inter | `font-sans` with Inter loaded via Google Fonts or `@fontsource/inter` |
+| Developer tools | Geist Sans + Geist Mono | Load via `@fontsource/geist-sans` |
+| Marketing / Brand | System font stack | `font-sans` (default Tailwind) |
+| Editorial / Blog | Serif pairing (e.g., Lora + Inter) | Custom `font-serif` in Tailwind config |
+
+### Rules
+- **Max 2 font families** — one for headings (optional), one for body
+- **Max 3 weights** — Regular (400), Medium (500), Bold (700)
+- **Body line length** — 45-75 characters per line (`max-w-prose`)
+- **Body line height** — 1.5 minimum for body text, 1.2-1.3 for headings
+
+> **When to deviate:** Branding may require specific fonts. Always test readability at 16px body size. Never go below 14px for body text.
+
+## Color System
+
+### Default Palette Structure
+
+```
+Primary    → Brand color, CTAs, active states (1 hue, 50-950 scale)
+Accent     → Secondary actions, highlights (1 hue, optional)
+Neutral    → Text, backgrounds, borders (gray scale, 50-950)
+Success    → Confirmations, positive states (green)
+Warning    → Caution, attention needed (amber/yellow)
+Error      → Destructive actions, validation errors (red)
+Info       → Informational, neutral callouts (blue)
+```
+
+### Shade Scale Convention
+
+Generate 50-950 shades for each color. Use the middle ranges (400-600) as the base, lighter shades for backgrounds, darker for text.
+
+| Shade | Light Mode Use | Dark Mode Use |
+|-------|---------------|---------------|
+| 50 | Tinted backgrounds | — |
+| 100 | Hover backgrounds | — |
+| 200 | Borders, dividers | Text (muted) |
+| 300 | — | Borders |
+| 400 | — | Secondary text |
+| 500 | Icons, secondary text | Icons |
+| 600 | Primary text, buttons | Buttons, links |
+| 700 | Headings | Body text |
+| 800 | — | Headings |
+| 900 | — | Primary text |
+| 950 | — | Backgrounds (surface) |
+
+### Contrast Requirements
+- **Normal text** — 4.5:1 minimum (WCAG AA)
+- **Large text** (18px+ or 14px bold) — 3:1 minimum
+- **UI components** (borders, icons, focus rings) — 3:1 minimum
+
+### Dark Mode
+- Invert the neutral scale (light text on dark backgrounds)
+- Reduce saturation by 10-20% — vivid colors are harsh on dark backgrounds
+- Never use pure white (`#fff`) on pure black (`#000`) — use `gray-100` on `gray-900`
+- Semantic colors: slightly lighter variants than light mode (e.g., `green-400` instead of `green-600`)
+
+> **When to deviate:** Brand guidelines may dictate specific colors. Always verify contrast ratios. Use tools like Realtime Colors or Tailwind's built-in dark mode utilities.
+
+## Component Design Patterns
+
+### Cards
+
+```html
+<!-- Standard card -->
+<div class="rounded-xl border border-gray-200 bg-white p-6 shadow-sm">
+  <h3 class="text-lg font-semibold text-gray-900">Title</h3>
+  <p class="mt-2 text-sm leading-relaxed text-gray-600">Description</p>
+</div>
+
+<!-- Interactive card (clickable) -->
+<div class="rounded-xl border border-gray-200 bg-white p-6 shadow-sm
+            transition-shadow duration-200 hover:shadow-md cursor-pointer">
+  <!-- content -->
+</div>
+```
+
+**Defaults:** `rounded-xl` (12px), `border-gray-200`, `shadow-sm`, `p-6` (24px padding).
+
+### Buttons
+
+| Variant | Classes | Use For |
+|---------|---------|---------|
+| Primary | `bg-primary-600 text-white hover:bg-primary-700 rounded-lg px-4 py-2.5 font-medium text-sm` | Main actions |
+| Secondary | `border border-gray-300 bg-white text-gray-700 hover:bg-gray-50 rounded-lg px-4 py-2.5 font-medium text-sm` | Secondary actions |
+| Ghost | `text-gray-600 hover:bg-gray-100 hover:text-gray-900 rounded-lg px-4 py-2.5 font-medium text-sm` | Tertiary actions |
+| Destructive | `bg-red-600 text-white hover:bg-red-700 rounded-lg px-4 py-2.5 font-medium text-sm` | Delete, remove |
+
+**States:** Always implement `disabled:opacity-50 disabled:cursor-not-allowed`. Loading state: replace text with a spinner + "Loading..." or keep the button width stable with a spinner replacing the icon.
+
+### Forms
+
+- Labels **above** inputs (not inline, not floating)
+- Consistent input height: `h-10` (40px) for default, `h-9` (36px) for compact
+- Focus ring: `focus:ring-2 focus:ring-primary-500 focus:ring-offset-2 focus:outline-none`
+- Validation: inline error message below the field in `text-sm text-red-600`
+- Group related fields with spacing `space-y-4` inside a section, `space-y-6` between sections
+
+### Navigation
+
+| Pattern | When | Key Classes |
+|---------|------|-------------|
+| Top navbar | Marketing, simple apps | `sticky top-0 z-50 border-b bg-white/80 backdrop-blur` |
+| Sidebar | Dashboards, admin, complex apps | `fixed inset-y-0 left-0 w-64 border-r bg-white` |
+| Bottom tabs | Mobile-first apps | `fixed bottom-0 inset-x-0 border-t bg-white` |
+
+**Active state:** Use `bg-primary-50 text-primary-700 font-medium` for sidebar items, `border-b-2 border-primary-600` for top nav tabs.
+
+### Tables
+
+- Header: `bg-gray-50 text-xs font-medium uppercase tracking-wide text-gray-500`
+- Rows: alternate `bg-white` / `bg-gray-50` or use `divide-y divide-gray-200`
+- Sticky header: `sticky top-0 z-10`
+- Mobile: horizontal scroll with `overflow-x-auto` or collapse to card layout below `md:`
+
+### Empty States
+
+Always provide: illustration or icon + descriptive message + primary action CTA.
+
+```html
+<div class="flex flex-col items-center justify-center py-12 text-center">
+  <div class="text-gray-400"><!-- icon or illustration --></div>
+  <h3 class="mt-4 text-lg font-medium text-gray-900">No projects yet</h3>
+  <p class="mt-2 text-sm text-gray-500">Get started by creating your first project.</p>
+  <button class="mt-6 rounded-lg bg-primary-600 px-4 py-2.5 text-sm font-medium text-white hover:bg-primary-700">
+    Create Project
+  </button>
+</div>
+```
+
+### Loading States
+
+Prefer **skeleton loaders** over spinners — they communicate layout and reduce perceived wait time.
+
+```html
+<!-- Skeleton card -->
+<div class="animate-pulse rounded-xl border border-gray-200 bg-white p-6">
+  <div class="h-5 w-2/3 rounded bg-gray-200"></div>
+  <div class="mt-3 h-4 w-full rounded bg-gray-200"></div>
+  <div class="mt-2 h-4 w-4/5 rounded bg-gray-200"></div>
+</div>
+```
+
+Use spinners only for inline actions (button loading, saving indicator).
+
+## Shadows, Borders & Depth
+
+### Elevation Model
+
+| Level | Use | Tailwind | When |
+|-------|-----|----------|------|
+| Base | Page background, inset content | — (no shadow) | Default state |
+| Raised | Cards, panels | `shadow-sm` | Resting content containers |
+| Floating | Dropdowns, popovers | `shadow-md` | Overlays triggered by interaction |
+| Overlay | Modals, dialogs | `shadow-lg` | Full-screen overlays |
+| Toast | Notifications, toasts | `shadow-xl` | Highest priority, topmost layer |
+
+### Defaults
+- **Border radius** — `rounded-xl` (12px) for cards/modals, `rounded-lg` (8px) for buttons/inputs, `rounded-full` for avatars/pills
+- **Borders** — `border border-gray-200` for separation, `border-2 border-primary-500` for emphasis/focus
+- **Dividers** — `divide-y divide-gray-200` between list items
+
+> **When to deviate:** Sharper radius (`rounded-md` or `rounded-lg`) suits enterprise/data-heavy UIs. Softer radius (`rounded-2xl`, `rounded-3xl`) suits consumer/playful products.
+
+## Responsive Design
+
+### Mobile-First Approach
+
+Write styles for mobile first, then layer on complexity at larger breakpoints.
+
+| Breakpoint | Tailwind | Target |
+|-----------|----------|--------|
+| Default | — | Mobile (320-639px) |
+| `sm:` | 640px | Large phones / small tablets |
+| `md:` | 768px | Tablets |
+| `lg:` | 1024px | Laptops |
+| `xl:` | 1280px | Desktops |
+| `2xl:` | 1536px | Large monitors |
+
+### Fluid Typography
+
+Use `clamp()` for font sizes that scale smoothly without breakpoints:
+
+```html
+<!-- Fluid heading: 24px at 320px viewport → 48px at 1280px viewport -->
+<h1 class="text-[clamp(1.5rem,1rem+2.5vw,3rem)] font-bold">Heading</h1>
+```
+
+### Responsive Patterns
+
+| Mobile | Desktop | Pattern |
+|--------|---------|---------|
+| Stacked cards | Grid `md:grid-cols-2 lg:grid-cols-3` | Card layout |
+| Hamburger menu | Full navbar | Navigation |
+| Bottom sheet | Sidebar | Secondary nav |
+| Full-width table scroll | Standard table | Data display |
+| Tabs (horizontal scroll) | Sidebar tabs | Settings/filters |
+
+### Touch Targets
+- Minimum **44x44px** for all interactive elements on mobile
+- Use `min-h-[44px] min-w-[44px]` or adequate padding
+
+## Motion & Animation
+
+### Purpose
+Motion should **communicate**, not decorate. Use it for: feedback (click/hover), relationships (parent-child), and state transitions (loading → loaded).
+
+### Duration Scale
+
+| Type | Duration | Easing | Use For |
+|------|----------|--------|---------|
+| Micro | 100-150ms | `ease-out` | Hover, focus, toggle, color change |
+| Standard | 200-300ms | `ease-in-out` | Panel open/close, accordion, tab switch |
+| Emphasis | 300-500ms | `ease-out` | Page transition, modal enter, hero animation |
+
+### Common Patterns
+
+```html
+<!-- Fade in on mount -->
+<div class="animate-in fade-in duration-300">Content</div>
+
+<!-- Hover scale for interactive cards -->
+<div class="transition-transform duration-200 hover:scale-[1.02]">Card</div>
+
+<!-- Smooth color transitions (always add to interactive elements) -->
+<button class="transition-colors duration-150">Button</button>
+
+<!-- Skeleton shimmer -->
+<div class="animate-pulse bg-gray-200 rounded">Loading...</div>
+```
+
+### Reduced Motion (MANDATORY)
+
+Always respect user preferences:
+
+```html
+<div class="motion-safe:animate-in motion-safe:fade-in motion-reduce:opacity-100">
+  Content
+</div>
+```
+
+Or in CSS: `@media (prefers-reduced-motion: reduce) { * { animation: none !important; transition-duration: 0.01ms !important; } }`
+
+> **When to deviate:** Skip animations entirely for data-heavy apps where performance matters more than polish. Loading indicators (spinners, progress bars) should always animate regardless of preference.
+
+## Page Composition Templates
+
+### Landing Page
+```
+Hero (headline + subheadline + CTA + visual)     → py-24, text-center or split layout
+Social proof (logos, "trusted by" bar)            → py-8, grayscale logos, border-y
+Features grid (3-4 cards or icon + text blocks)   → py-16, grid-cols-3
+Detailed feature (alternating text + image)       → py-16, repeat 2-3x
+Testimonials (quotes in cards or carousel)        → py-16, bg-gray-50
+CTA repeat (same CTA as hero)                     → py-16, text-center
+Footer (links, legal, social)                     → py-8, border-t, text-sm
+```
+
+### Dashboard
+```
+Sidebar (w-64, fixed left, logo + nav links)
+Top bar (sticky, breadcrumb + search + user menu)
+Main content:
+  KPI row (grid-cols-4, stat cards)               → gap-6
+  Primary content (charts, tables, activity)      → grid-cols-1 or grid-cols-2
+```
+
+### Settings / Admin
+```
+Sidebar nav (vertical tabs or grouped links)
+Content area:
+  Section heading + description                   → border-b, pb-6
+  Form group (labeled inputs)                     → space-y-4
+  Action buttons (right-aligned Save/Cancel)      → pt-6, flex justify-end gap-3
+```
+
+### Blog / Article
+```
+Header (title + meta + author)                    → max-w-prose, mx-auto
+Body (prose content)                              → max-w-prose, prose class
+TOC sidebar (sticky, lg:block hidden)             → fixed right, top-24
+```
+
+### Authentication
+```
+Centered card on subtle background                → min-h-screen, flex items-center justify-center
+Card (max-w-sm, logo + form + links)              → rounded-xl, shadow-lg, p-8
+Minimal distractions (no nav, no footer)
+```
+
+## Professional Polish Checklist
+
+Before shipping any UI, verify:
+
+- [ ] **Spacing** — all spacing uses the defined scale (no arbitrary pixel values)
+- [ ] **Typography** — max 3 visible text sizes per view, consistent weight usage
+- [ ] **Color** — all colors from the defined palette, no one-off hex values
+- [ ] **Interactive states** — hover, focus, active, disabled on every clickable element
+- [ ] **Loading states** — skeleton or spinner for all async content
+- [ ] **Empty states** — message + action for every zero-data view
+- [ ] **Error states** — inline validation, toast/alert for API errors, error pages (404, 500)
+- [ ] **Responsive** — tested at mobile (375px), tablet (768px), desktop (1280px)
+- [ ] **Motion** — subtle transitions on interactive elements, `prefers-reduced-motion` respected
+- [ ] **Contrast** — all text passes WCAG AA (4.5:1 normal, 3:1 large)
+- [ ] **Border radius** — consistent across all components (same family of values)
+- [ ] **Shadows** — used consistently per the elevation model
+- [ ] **Favicon & metadata** — page titles, favicon, OG tags set
+- [ ] **Content** — no Lorem Ipsum in production, realistic placeholder data