contextos-agents 1.7.0 → 2.0.0-beta.3

package/.agents/generated/claude/skills/performance/SKILL.md

@@ -1,121 +0,0 @@
-# Web Performance & Core Web Vitals
-
-## Overview
-
-Enforces high-efficiency frontend and full-stack performance standards to achieve exceptional Core Web Vitals: Largest Contentful Paint (LCP < 2.5s), Interaction to Next Paint (INP < 200ms), and Cumulative Layout Shift (CLS < 0.1).
-
-## When to Use
-
-Activate whenever analyzing, profiling, writing, or optimizing page loading speeds, network waterfalls, script bundling, animation frame rates, or data caching.
-
-## Negative Constraints (What NOT to Do)
-
-1. **NEVER introduce async waterfalls**: Do not chain sequential `await` calls when requests can be executed concurrently via `Promise.all()`.
-2. **NEVER import large full libraries when only a utility is needed**: Never `import _ from 'lodash'`; use `import debounce from 'lodash/debounce'` or native alternatives.
-3. **NEVER render images or videos without explicit aspect ratios**: Always provide `width` and `height` or `aspect-ratio` to avoid Cumulative Layout Shift (CLS).
-4. **NEVER trigger synchronous layout thrashing**: Do not alternate between reading layout properties (`offsetHeight`, `getBoundingClientRect`) and writing styles in loops.
-5. **NEVER animate non-composited properties**: Animate only GPU-composited CSS properties (`transform`, `opacity`). Never animate `width`, `height`, `top`, `left`, or `margin`.
-
-## Rules & Patterns
-
-### 1. Vercel Optimization Hierarchy by Impact
-
-| Priority | Category | Key Optimization Target | Expected Impact |
-|:---|:---|:---|:---|
-| **1. CRITICAL** | **Eliminating Waterfalls** | Parallel data fetching (`Promise.all`), Suspense streaming | **30–60% faster LCP** |
-| **2. CRITICAL** | **Bundle Size Optimization** | Direct submodule imports, `next/dynamic`, deferring 3rd party scripts | **40–70% smaller initial JS** |
-| **3. HIGH** | **Server-Side & RSC Caching** | `React.cache()` request deduplication, edge SSR caching | **Lower TTFB & DB load** |
-| **4. MEDIUM-HIGH** | **Client Query Optimization** | SWR / TanStack Query stale-while-revalidate, deduplication | **Zero redundant network calls** |
-| **5. MEDIUM** | **Render & DOM Optimization** | Virtualization for large lists, state colocation, `:focus-visible` | **Smooth 60 FPS / INP < 100ms** |
-
-### 2. Eliminating Network Waterfalls
-
-```ts
-// [GOOD] Parallel execution
-const [user, notifications] = await Promise.all([
-  fetchUser(),
-  fetchNotifications(),
-]);
-const posts = await fetchPosts(user.id);
-```
-
-### 3. Layout Shift & Visual Stability (CLS < 0.1)
-
-- **Images & Video**: Always supply `width`, `height`, and `sizes` or CSS `aspect-ratio: 16 / 9`.
-- **Dynamic Content**: Reserve layout space for dynamically loaded widgets with min-height placeholders or skeletons.
-- **Tabular Numbers**: Use `font-feature-settings: "tnum"` / `font-variant-numeric: tabular-nums` for counters, clocks, and tables to prevent number width jitter.
-
-## Code Examples
-
-See `EXAMPLES.md` for detailed performance patterns and benchmark snippets.
-
-## Validation Checklist
-
-- [ ] LCP target is < 2.5s with preloaded critical fonts and LCP image `priority`.
-- [ ] No sequential `await` waterfalls in API routes or Server Components.
-- [ ] All animated elements use only `transform` and `opacity`.
-- [ ] `prefers-reduced-motion` media queries are respected.
-- [ ] Large tables / lists (> 100 items) utilize virtualization.
-
-## Common Mistakes
-
-- Chaining independent async requests instead of using `Promise.all`.
-- Animating layout-triggering properties (`height`, `width`, `top`) causing jank.
-- Missing image dimensions causing layout shift when images finish loading.
-
-## Integration Notes
-
-- Pairs with `nextjs` and `react` for App Router caching and component lifecycle tuning.
-- Pairs with `ui-ux-pro` for smooth animations and responsive design tokens.
-
-
-# performance Examples — Anti-patterns vs ContextOS Standard
-
-## Example 1: Dynamic Imports for Heavy Libraries
-
-### Anti-pattern: Static Import of Heavy Visualizers in Initial Bundle
-
-```typescript
-// BAD: Adds 800KB (Monaco editor or Three.js) to the critical first-paint bundle!
-import { CodeEditor } from '@/components/CodeEditor';
-
-export default function Page() {
-  return <div><CodeEditor /></div>;
-}
-```
-
-### Best practice: ContextOS Standard (Lazy Load on Demand)
-
-```typescript
-// GOOD: Dynamic import splits chunk, only downloads when component renders
-import dynamic from 'next/dynamic';
-
-const CodeEditor = dynamic(
-  () => import('@/components/CodeEditor'),
-  { loading: () => <EditorSkeleton />, ssr: false }
-);
-
-export default function Page() {
-  return <div><CodeEditor /></div>;
-}
-```
-
-# performance Troubleshooting & Common Mistakes
-
-## 1. Cumulative Layout Shift (CLS) from Images & Fonts
-
-- **Symptom**: Page content jumps around as images and custom fonts load.
-- **Root Cause**: Missing width and height attributes on image tags and FOUT (Flash of Unstyled Text).
-- **Fix**: Always specify aspect-ratio or width/height on images, and use next/font to preload web fonts with fallback sizing.
-
-## 2. High Interaction to Next Paint (INP)
-
-- **Symptom**: User clicks a button and the UI freezes for 200ms+ before responding.
-- **Root Cause**: Long task blocking the main thread during event dispatch.
-- **Fix**: Defer non-critical state updates using startTransition() or split heavy computation with Web Workers.
-
-## 3. Unoptimized SVG / Icon Overload
-
-- **Symptom**: Huge DOM node count and slow initial render times.
-- **Root Cause**: Rendering 500 inline SVG icons with complex paths.
-- **Fix**: Use SVG sprite sheets, dynamic icon loaders, or lightweight canvas rendering for dense data visualizations.

package/.agents/generated/claude/skills/react/SKILL.md

@@ -1,227 +0,0 @@
-# React Engineering & Performance Best Practices
-
-## Overview
-
-Enforces declarative, component-driven UI architecture with optimal re-render cycles, state colocation, responsive optimistic updates, and robust accessibility standards.
-
-## When to Use
-
-Activate whenever creating, refactoring, or optimizing React functional components, custom hooks, context providers, or UI interaction states.
-
-## Negative Constraints (What NOT to Do)
-
-1. **NEVER use `useEffect` to synchronize or compute derived state**: Calculate derived state inline during render. Use `useMemo` only for computationally intensive derivations.
-2. **NEVER use array indices as `key` props on dynamic or reorderable lists**: Always use stable, unique entity identifiers (`item.id`).
-3. **NEVER mutate React state directly**: Always return new immutable references (`[...prev, newItem]` or `{ ...prev, key: value }`).
-4. **NEVER declare subcomponents inside the render body of parent components**: Declare components at module scope or in dedicated files to prevent DOM node remounting and lost focus state.
-5. **NEVER create memory leaks in `useEffect`**: Always provide clean-up functions for event listeners, `AbortController`, timers, and websocket subscriptions.
-6. **NEVER lift state higher than necessary**: Colocate state to the nearest common ancestor or leaf component to prevent wasteful re-renders of unrelated subtrees.
-
-## Rules & Patterns
-
-### 1. State Colocation & Re-render Optimization
-
-- **State Colocation**: Keep state as close as possible to the components that consume it.
-- **Composition to Prevent Re-renders**: Pass expensive static subtrees as `children` to wrapper components holding state so the children do not re-render when the wrapper updates.
-
-```tsx
-export function ExpandableCard({ title, children }: { title: string; children: React.ReactNode }) {
-  const [isOpen, setIsOpen] = useState(false);
-
-  return (
-    <div className="rounded-xl border p-4">
-      <button 
-        type="button"
-        onClick={() => setIsOpen(v => !v)}
-        className="flex w-full justify-between font-semibold"
-        aria-expanded={isOpen}
-      >
-        <span>{title}</span>
-        <span>{isOpen ? '−' : '+'}</span>
-      </button>
-      {isOpen && <div className="mt-3 pt-3 border-t">{children}</div>}
-    </div>
-  );
-}
-```
-
-### 2. Optimistic UI Updates & Concurrent Actions (`useOptimistic`, `useTransition`)
-
-- Provide instantaneous visual feedback for user actions without waiting for server network roundtrips.
-
-```tsx
-import { useOptimistic, useTransition } from 'react';
-
-export function TodoList({ todos, onAdd }: { todos: Todo[]; onAdd: (text: string) => Promise<void> }) {
-  const [isPending, startTransition] = useTransition();
-  const [optimisticTodos, addOptimisticTodo] = useOptimistic(
-    todos,
-    (state, newText: string) => [...state, { id: 'temp-' + Date.now(), text: newText, isPending: true }]
-  );
-
-  const handleAction = async (formData: FormData) => {
-    const text = formData.get('todo') as string;
-    if (!text?.trim()) return;
-
-    startTransition(async () => {
-      addOptimisticTodo(text);
-      await onAdd(text);
-    });
-  };
-
-  return (
-    <form action={handleAction} className="space-y-4">
-      <input name="todo" placeholder="Add a new task..." className="border p-2 rounded" />
-      <button type="submit" disabled={isPending} className="bg-primary text-white px-4 py-2 rounded">
-        {isPending ? 'Saving...' : 'Add'}
-      </button>
-      <ul className="divide-y">
-        {optimisticTodos.map(todo => (
-          <li key={todo.id} className={todo.isPending ? 'opacity-50 italic' : ''}>
-            {todo.text}
-          </li>
-        ))}
-      </ul>
-    </form>
-  );
-}
-```
-
-### 3. Derived State vs. Effects Anti-Pattern
-
-```tsx
-// [GOOD] Computed directly during render (or memoized if expensive)
-function SearchResults({ query, items }: { query: string; items: Item[] }) {
-  const filtered = useMemo(() => {
-    const q = query.trim().toLowerCase();
-    if (!q) return items;
-    return items.filter(i => i.title.toLowerCase().includes(q));
-  }, [query, items]);
-
-  return <List items={filtered} />;
-}
-```
-
-## Code Examples
-
-See `EXAMPLES.md` for detailed code examples and hook implementations.
-
-## Validation Checklist
-
-- [ ] Zero `useEffect` hooks used for derived calculations.
-- [ ] Every list mapping has a unique, non-index entity ID key.
-- [ ] Subcomponents declared in parent render functions are extracted to top-level scope.
-- [ ] Effects with event listeners, timers, or abortable requests include clean-up returns.
-- [ ] Reusable components are composed cleanly via `children` or render props.
-
-## Common Mistakes
-
-- Setting state inside `useEffect` based on prop changes rather than deriving values inline.
-- Declaring nested components within component bodies.
-- Using index keys causing input focus loss or animations breaking on list mutations.
-
-## Integration Notes
-
-- Pairs with `typescript` for type safety on props, generics, and ref forwarding.
-- Pairs with `ui-ux-pro` and `web-accessibility` for UI tokens and ARIA standards.
-
-
-# React Examples — Anti-patterns vs ContextOS Standard
-
-## Example 1: Derived State vs. useEffect
-
-### Anti-pattern: Anti-pattern (Redundant state + extra render with useEffect)
-
-```tsx
-// BAD: causes an unnecessary extra render cycle and potential state desync
-function OrderSummary({ items }: { items: CartItem[] }) {
-  const [total, setTotal] = useState(0);
-
-  useEffect(() => {
-    const calculated = items.reduce((sum, item) => sum + item.price * item.quantity, 0);
-    setTotal(calculated);
-  }, [items]);
-
-  return <div>Total: ${total}</div>;
-}
-```
-
-### Best practice: ContextOS Standard (Inline derived calculation / useMemo)
-
-```tsx
-// GOOD: calculated instantly during render with zero extra render pass
-function OrderSummary({ items }: { items: CartItem[] }) {
-  const total = useMemo(
-    () => items.reduce((sum, item) => sum + item.price * item.quantity, 0),
-    [items]
-  );
-
-  return <div>Total: ${total.toFixed(2)}</div>;
-}
-```
-
----
-
-## Example 2: Custom Hook Encapsulation
-
-### Anti-pattern: Anti-pattern (Scattered listener logic inside component)
-
-```tsx
-// BAD: window listener logic cluttering UI component
-function NavHeader() {
-  const [isScrolled, setIsScrolled] = useState(false);
-  useEffect(() => {
-    const handleScroll = () => setIsScrolled(window.scrollY > 50);
-    window.addEventListener('scroll', handleScroll);
-    return () => window.removeEventListener('scroll', handleScroll);
-  }, []);
-  return <header className={isScrolled ? 'scrolled' : ''}>Header</header>;
-}
-```
-
-### Best practice: ContextOS Standard (Reusable Custom Hook)
-
-```tsx
-// GOOD: extracted into a reusable, testable custom hook
-export function useScrollThreshold(threshold = 50): boolean {
-  const [isPassed, setIsPassed] = useState(() => typeof window !== 'undefined' && window.scrollY > threshold);
-
-  useEffect(() => {
-    let ticking = false;
-    const handleScroll = () => {
-      if (!ticking) {
-        window.requestAnimationFrame(() => {
-          setIsPassed(window.scrollY > threshold);
-          ticking = false;
-        });
-        ticking = true;
-      }
-    };
-
-    window.addEventListener('scroll', handleScroll, { passive: true });
-    return () => window.removeEventListener('scroll', handleScroll);
-  }, [threshold]);
-
-  return isPassed;
-}
-```
-
-# react Troubleshooting & Common Mistakes
-
-## 1. Infinite Render Loops in useEffect
-
-- **Symptom**: Browser freezes, "Maximum update depth exceeded" error.
-- **Root Cause**: Creating new object or array literals inside component body and passing them to useEffect dependency array.
-- **Fix**: Colocate state, compute derived state during render without useEffect, or use primitive dependency values.
-
-## 2. Stale Closures in Callbacks
-
-- **Symptom**: Event handler or setTimeout accesses outdated state values.
-- **Root Cause**: Callback closing over initial state without updated dependency.
-- **Fix**: Use functional state updates (`setCount(c => c + 1)`) or `useRef` for mutable references.
-
-## 3. Prop Drilling vs Context Performance
-
-- **Symptom**: Changing a small state variable causes the entire component tree to re-render.
-- **Root Cause**: Storing rapidly changing state in a single monolithic React Context.
-- **Fix**: Split contexts by domain or migrate client UI state to Zustand with granular selectors.

package/.agents/generated/claude/skills/react-best-practices/SKILL.md

@@ -1,146 +0,0 @@
-# Vercel React Best Practices
-
-## Overview
-
-Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 70 rules across 8 categories, prioritized by impact to guide automated refactoring, code generation, and production review.
-
-## When to Use
-
-- When authoring new React functional components or Next.js App Router pages.
-- When implementing data fetching (client or server-side Server Actions, RSC).
-- When reviewing pull requests for rendering bottlenecks or memory leaks.
-- When optimizing bundle size, eliminating network waterfalls, or improving Core Web Vitals (LCP, INP, CLS).
-
-## Rules & Patterns
-
-### Rule Categories by Priority
-
-| Priority | Category | Impact | Prefix |
-|----------|----------|--------|--------|
-| 1 | Eliminating Waterfalls | CRITICAL | `async-` |
-| 2 | Bundle Size Optimization | CRITICAL | `bundle-` |
-| 3 | Server-Side Performance | HIGH | `server-` |
-| 4 | Client-Side Data Fetching | MEDIUM-HIGH | `client-` |
-| 5 | Re-render Optimization | MEDIUM | `rerender-` |
-| 6 | Rendering Performance | MEDIUM | `rendering-` |
-| 7 | JavaScript Performance | LOW-MEDIUM | `js-` |
-| 8 | Advanced Patterns | LOW | `advanced-` |
-
-### 1. Eliminating Waterfalls (CRITICAL)
-
-- `async-cheap-condition-before-await` - Check cheap sync conditions before awaiting flags or remote values.
-- `async-defer-await` - Move await into branches where actually used.
-- `async-parallel` - Use `Promise.all()` for independent asynchronous operations.
-- `async-dependencies` - Use better-all for partial dependencies.
-- `async-api-routes` - Start promises early, await late in API routes.
-- `async-suspense-boundaries` - Use Suspense to stream content progressively.
-
-### 2. Bundle Size Optimization (CRITICAL)
-
-- `bundle-barrel-imports` - Import directly from specific modules, avoid broad barrel files (`index.ts`).
-- `bundle-analyzable-paths` - Prefer statically analyzable import paths to avoid bloated traces.
-- `bundle-dynamic-imports` - Use `next/dynamic` or `React.lazy()` for heavy interactive components.
-- `bundle-defer-third-party` - Load analytics and logging scripts after hydration.
-- `bundle-conditional` - Load modules only when feature flags or user actions require them.
-- `bundle-preload` - Preload assets on hover or focus for perceived instant navigation.
-
-### 3. Server-Side Performance (HIGH)
-
-- `server-auth-actions` - Always authenticate server actions like API routes.
-- `server-cache-react` - Use `React.cache()` for per-request deduplication.
-- `server-cache-lru` - Use LRU cache for cross-request caching.
-- `server-dedup-props` - Avoid duplicate serialization in RSC props.
-- `server-hoist-static-io` - Hoist static I/O to module level.
-- `server-no-shared-module-state` - Avoid module-level mutable request state in RSC/SSR.
-- `server-serialization` - Minimize data passed across the server-client boundary.
-- `server-parallel-fetching` - Restructure components to parallelize fetches.
-- `server-after-nonblocking` - Use `after()` for non-blocking operations like analytics logging.
-
-### 4. Client-Side Data Fetching (MEDIUM-HIGH)
-
-- `client-swr-dedup` - Use SWR or TanStack Query for automatic request deduplication.
-- `client-event-listeners` - Deduplicate global event listeners.
-- `client-passive-event-listeners` - Use passive listeners for scroll and touch.
-- `client-localstorage-schema` - Version and minimize data stored in localStorage.
-
-### 5. Re-render Optimization (MEDIUM)
-
-- `rerender-defer-reads` - Don't subscribe to state only used in callbacks.
-- `rerender-memo` - Extract expensive work into memoized components.
-- `rerender-memo-with-default-value` - Hoist default non-primitive props.
-- `rerender-dependencies` - Use primitive dependencies in effects and callbacks.
-- `rerender-derived-state` - Subscribe to derived booleans, not raw high-frequency values.
-- `rerender-derived-state-no-effect` - Derive state during render, never in `useEffect`.
-- `rerender-functional-setstate` - Use functional `setState` for stable callback references.
-- `rerender-lazy-state-init` - Pass initializer functions to `useState` for expensive computations.
-- `rerender-transitions` - Use `startTransition` for non-urgent state updates.
-- `rerender-use-deferred-value` - Defer expensive renders to keep input responsive.
-- `rerender-no-inline-components` - Never define subcomponents inside component render bodies.
-
-### 6. Rendering Performance (MEDIUM)
-
-- `rendering-content-visibility` - Use `content-visibility: auto` for long offscreen lists.
-- `rendering-hoist-jsx` - Extract static JSX elements outside components.
-- `rendering-conditional-render` - Use ternary (`condition ? <Comp /> : null`), not `&&` to avoid 0 rendering.
-- `rendering-usetransition-loading` - Prefer `useTransition` for loading state indicators.
-
-### 7. JavaScript Performance (LOW-MEDIUM)
-
-- `js-index-maps` - Build `Map` for repeated lookups instead of repeated array searches.
-- `js-cache-property-access` - Cache object properties in tight loops.
-- `js-early-exit` - Return early from functions to avoid nested complexity.
-- `js-hoist-regexp` - Hoist RegExp creation outside loops and functions.
-- `js-set-map-lookups` - Use `Set` / `Map` for O(1) lookups.
-
-### 8. Advanced Patterns (LOW)
-
-- `advanced-effect-event-deps` - Don't put `useEffectEvent` results in effect deps.
-- `advanced-event-handler-refs` - Store event handlers in refs for stable listener attachments.
-- `advanced-init-once` - Initialize app singletons once per lifecycle.
-
-## Code Examples
-
-```tsx
-// [GOOD] Parallel server fetching without waterfall
-import { cache } from 'react';
-
-export const getUser = cache(async (id: string) => {
-  return db.user.findUnique({ where: { id } });
-});
-
-export default async function UserPage({ params }: { params: { id: string } }) {
-  // Parallel dispatch
-  const userPromise = getUser(params.id);
-  const postsPromise = getPosts(params.id);
-
-  const [user, posts] = await Promise.all([userPromise, postsPromise]);
-
-  return (
-    <main>
-      <h1>{user.name}</h1>
-      <PostList posts={posts} />
-    </main>
-  );
-}
-```
-
-## Validation Checklist
-
-- [ ] All independent async fetches use `Promise.all()` instead of sequential `await`.
-- [ ] Direct imports used instead of barrel file imports for large libraries.
-- [ ] No `useEffect` used for deriving computed state from props or state.
-- [ ] Heavy interactive modals/drawers loaded dynamically via `next/dynamic`.
-- [ ] Server actions perform authentication checks before data mutations.
-- [ ] Zero subcomponents defined inside the body of parent components.
-
-## Common Mistakes
-
-- Writing sequential `await fetchA(); await fetchB();` creating avoidable network waterfalls.
-- Importing from package root barrel files triggering full bundle inclusion.
-- Setting state inside `useEffect` in response to prop changes.
-- Serializing full database models with sensitive or unused fields to Client Components.
-
-## Integration Notes
-
-- Pairs with `react` and `nextjs` skills for idiomatic App Router patterns.
-- Complements `performance` for Lighthouse and Core Web Vitals verification.

package/.agents/generated/claude/skills/redesign-audit/SKILL.md

@@ -1,112 +0,0 @@
-# Redesign Skill & UI Audit
-
-## Overview
-
-A systematic redesign and auditing protocol designed to elevate existing websites, dashboards, and web applications to world-class agency quality. It diagnoses and eradicates generic AI design fingerprints, sloppy typography, inconsistent palettes, and absent interaction states without breaking business logic or underlying component contracts.
-
-## When to Use
-
-- When auditing an existing UI codebase for design quality, responsiveness, or accessibility.
-- When modernizing a legacy application or uplifting generic templates.
-- When tasked to "redesign", "clean up the layout", "audit UI", or "make it look expensive and modern".
-
-## Rules & Patterns
-
-### 1. Workflow: Scan → Diagnose → Fix
-
-1. **Scan:** Read the codebase. Identify the framework, styling method (Tailwind v3/v4, vanilla CSS, CSS Modules), and established design tokens.
-2. **Diagnose:** Run through the design audit categories. Catalog generic patterns, missing states, and optical alignment flaws.
-3. **Fix:** Apply surgical, targeted upgrades working within the existing stack. Do not rewrite from scratch.
-
-### 2. Design Audit Categories
-
-#### Typography
-
-- **Replace Browser Defaults:** Swap generic `Inter`, `Roboto`, or system fonts with expressive typefaces (`Geist`, `Outfit`, `Cabinet Grotesk`, `Satoshi`).
-- **Presence & Scale:** Increase display text size, tighten letter-spacing (`-0.02em` to `-0.04em`), reduce line-height on headlines.
-- **Reading Comfort:** Limit body text to 65 characters per line (`max-w-prose`), increase line-height to 1.6.
-- **Figures:** Enable tabular figures (`font-variant-numeric: tabular-nums`) for numbers in tables and data readouts.
-- **Orphan Prevention:** Apply `text-wrap: balance` on headlines and `text-wrap: pretty` on paragraphs.
-
-#### Color and Surfaces
-
-- **No Pure Black Backgrounds:** Replace `#000000` with tinted dark charcoal (`#0A0A0A`, `#121212`).
-- **Desaturate Accents:** Keep accent saturation below 80% so it blends harmoniously with neutrals.
-- **Single Accent Color:** Commit to one dominant accent hue; remove conflicting secondary tints.
-- **Tinted Shadows:** Tint shadows to match the background hue rather than harsh black opacity.
-- **Background Depth:** Prevent sterile flat sections by layering subtle noise overlays, ambient gradients, or masked imagery.
-
-#### Layout and Space
-
-- **Asymmetry & Bento Grids:** Break repetitive 3-column Bootstrap grids with asymmetrical spans or offset cards.
-- **Mobile Viewport Bug Fix:** Never use `height: 100vh`; always use `min-height: 100dvh`.
-- **Vertical Alignment:** Pin action buttons to the bottom of card groups (`mt-auto` or grid alignment) to maintain horizontal baseline harmony across differing text heights.
-- **Optical Centering:** Adjust icons, badges, and play buttons optically by 1-2px rather than relying solely on pure mathematical centering.
-
-#### Interactivity and States
-
-- **Interactive Feedback:** Add 200-300ms transitions, distinct hover shifts, and physical active presses (`scale(0.98)`).
-- **Visible Focus Rings:** Mandatory `:focus-visible` styling for keyboard navigation.
-- **States Completeness:** Always provide designed skeleton loaders, empty states, and inline error messages.
-
-#### Content & Code Quality
-
-- **Eradicate AI Clichés:** Remove buzzwords ("Elevate", "Seamless", "Unleash", "Next-Gen") and placeholder latin text.
-- **Semantic HTML:** Replace nested div containers with `<nav>`, `<main>`, `<article>`, `<section>`, `<aside>`.
-- **Relative Units:** Use `rem`, `%`, and CSS Grid rather than hardcoded pixel widths.
-
-### 3. Fix Priority
-
-1. **Font Swap:** Biggest instant aesthetic elevation with lowest regression risk.
-2. **Palette Cleanup:** Eliminate clashing or oversaturated colors.
-3. **States & Feedback:** Add hover, active, focus, loading, and empty states.
-4. **Layout & Alignment:** Fix container widths, baseline alignment, and mobile viewport heights.
-5. **Component Polish:** Replace generic cards and accordion boxes with modern minimal equivalents.
-
-## Code Examples
-
-```tsx
-// [BEFORE] Generic, misaligned card with generic shadow
-<div className="bg-white border rounded shadow p-4">
-  <h2>{title}</h2>
-  <p>{desc}</p>
-  <button className="bg-blue-500 text-white p-2">Click</button>
-</div>
-
-// [AFTER] Polished card with optical baseline alignment, tinted surface, and micro-interaction
-<div className="flex flex-col bg-[#FFFFFF] dark:bg-[#121212] border border-black/5 dark:border-white/10 rounded-2xl p-6 hover:shadow-[0_4px_20px_rgba(0,0,0,0.04)] transition-all duration-200">
-  <h3 className="font-semibold text-lg tracking-tight text-neutral-900 dark:text-neutral-100 text-balance mb-2">
-    {title}
-  </h3>
-  <p className="text-sm text-neutral-600 dark:text-neutral-400 leading-relaxed text-pretty mb-6">
-    {desc}
-  </p>
-  <button 
-    type="button" 
-    className="mt-auto inline-flex items-center justify-center font-medium text-sm px-4 py-2.5 rounded-xl bg-neutral-900 dark:bg-neutral-100 text-white dark:text-black hover:bg-neutral-800 active:scale-[0.98] transition-transform duration-150 focus-visible:ring-2 focus-visible:ring-neutral-400"
-  >
-    Continue
-  </button>
-</div>
-```
-
-## Validation Checklist
-
-- [ ] All headings have `text-wrap: balance` and appropriate negative letter tracking.
-- [ ] No pure black `#000000` backgrounds or oversaturated accent colors (>80% saturation).
-- [ ] All interactive elements include `:hover`, `:active`, and `:focus-visible` styles.
-- [ ] Cards in side-by-side grids align primary CTA buttons along the same bottom baseline.
-- [ ] Viewport containers use `100dvh` instead of `100vh`.
-- [ ] All lists, tables, and feeds have a designed empty state.
-
-## Common Mistakes
-
-- Rewriting components from scratch and breaking existing prop contracts or unit tests.
-- Forcing full-width sections without `max-w` constraints on ultra-wide screens.
-- Leaving action buttons at random heights inside differing text content cards.
-- Introducing external UI libraries without checking existing `package.json` dependencies.
-
-## Integration Notes
-
-- Complements `impeccable-design` for hard 50-rule QA verification.
-- Works alongside `ui-ux-pro` for token generation and color theory.