cokit-cli 1.2.7 → 1.4.0

package/skills/ck-frontend-design/references/magicui-components.md

@@ -0,0 +1,129 @@
+# Magic UI - Component Library Reference
+
+> Beautifully designed landing page components built with React & Tailwind CSS. 80+ components.
+> Docs: https://magicui.design | Repo: https://github.com/magicuidesign/magicui
+
+## Installation
+
+```bash
+npx magicui-cli add <component-name>
+```
+
+## Component Categories
+
+### Text Effects
+| Component | Description | Docs |
+|-----------|-------------|------|
+| Animated Gradient Text | Gradient transitions for text | [docs](https://magicui.design/docs/components/animated-gradient-text) |
+| Animated Shiny Text | Light glare shimmer on text | [docs](https://magicui.design/docs/components/animated-shiny-text) |
+| Aurora Text | Aurora borealis text effect | [docs](https://magicui.design/docs/components/aurora-text) |
+| Comic Text | Comic-style text animation | [docs](https://magicui.design/docs/components/comic-text) |
+| Hyper Text | Scramble-then-reveal animation | [docs](https://magicui.design/docs/components/hyper-text) |
+| Line Shadow Text | Moving line shadow on text | [docs](https://magicui.design/docs/components/line-shadow-text) |
+| Morphing Text | Dynamic text morphing | [docs](https://magicui.design/docs/components/morphing-text) |
+| Sparkles Text | Continuous sparkle animation | [docs](https://magicui.design/docs/components/sparkles-text) |
+| Spinning Text | Circular motion text | [docs](https://magicui.design/docs/components/spinning-text) |
+| Text Animate | Multiple text animation types | [docs](https://magicui.design/docs/components/text-animate) |
+| Text Reveal | Fade-in on scroll | [docs](https://magicui.design/docs/components/text-reveal) |
+| Typing Animation | Typewriter effect | [docs](https://magicui.design/docs/components/typing-animation) |
+| Video Text | Video background in text | [docs](https://magicui.design/docs/components/video-text) |
+| Word Rotate | Vertical word rotation | [docs](https://magicui.design/docs/components/word-rotate) |
+| Highlighter | Marker-stroke highlight | [docs](https://magicui.design/docs/components/highlighter) |
+
+### Buttons
+| Component | Description | Docs |
+|-----------|-------------|------|
+| Shimmer Button | Light travels along perimeter | [docs](https://magicui.design/docs/components/shimmer-button) |
+| Shiny Button | Dynamic shiny effect | [docs](https://magicui.design/docs/components/shiny-button) |
+| Pulsating Button | Attention-capturing pulse | [docs](https://magicui.design/docs/components/pulsating-button) |
+| Rainbow Button | Rainbow color animation | [docs](https://magicui.design/docs/components/rainbow-button) |
+| Ripple Button | Click ripple effect | [docs](https://magicui.design/docs/components/ripple-button) |
+| Interactive Hover Button | Hover interaction | [docs](https://magicui.design/docs/components/interactive-hover-button) |
+
+### Backgrounds & Patterns
+| Component | Description | Docs |
+|-----------|-------------|------|
+| Grid Pattern | SVG grid, customizable | [docs](https://magicui.design/docs/components/grid-pattern) |
+| Animated Grid Pattern | Animated SVG grid | [docs](https://magicui.design/docs/components/animated-grid-pattern) |
+| Interactive Grid Pattern | Mouse-interactive grid | [docs](https://magicui.design/docs/components/interactive-grid-pattern) |
+| Dot Pattern | SVG dots background | [docs](https://magicui.design/docs/components/dot-pattern) |
+| Striped Pattern | SVG stripes background | [docs](https://magicui.design/docs/components/striped-pattern) |
+| Flickering Grid | Flickering cells grid | [docs](https://magicui.design/docs/components/flickering-grid) |
+| Retro Grid | Animated scrolling retro grid | [docs](https://magicui.design/docs/components/retro-grid) |
+| Warp Background | Time-warping effect | [docs](https://magicui.design/docs/components/warp-background) |
+| Particles | Interactive particle system | [docs](https://magicui.design/docs/components/particles) |
+| Light Rays | Animated light rays from above | [docs](https://magicui.design/docs/components/light-rays) |
+
+### Cards & Borders
+| Component | Description | Docs |
+|-----------|-------------|------|
+| Magic Card | Spotlight follows cursor | [docs](https://magicui.design/docs/components/magic-card) |
+| Neon Gradient Card | Neon glow effect | [docs](https://magicui.design/docs/components/neon-gradient-card) |
+| Border Beam | Animated light along border | [docs](https://magicui.design/docs/components/border-beam) |
+| Shine Border | Animated shine border | [docs](https://magicui.design/docs/components/shine-border) |
+
+### Layout & Navigation
+| Component | Description | Docs |
+|-----------|-------------|------|
+| Bento Grid | Feature showcase grid | [docs](https://magicui.design/docs/components/bento-grid) |
+| Dock | macOS-style dock | [docs](https://magicui.design/docs/components/dock) |
+| Marquee | Infinite scroll (text/images) | [docs](https://magicui.design/docs/components/marquee) |
+| File Tree | Directory structure display | [docs](https://magicui.design/docs/components/file-tree) |
+| Terminal | Terminal mockup | [docs](https://magicui.design/docs/components/terminal) |
+
+### Animated Effects
+| Component | Description | Docs |
+|-----------|-------------|------|
+| Animated Beam | Light beam along path | [docs](https://magicui.design/docs/components/animated-beam) |
+| Animated List | Sequential item animation | [docs](https://magicui.design/docs/components/animated-list) |
+| Blur Fade | Smooth blur fade-in/out | [docs](https://magicui.design/docs/components/blur-fade) |
+| Confetti | Celebration animations | [docs](https://magicui.design/docs/components/confetti) |
+| Cool Mode | Fun click particle effect | [docs](https://magicui.design/docs/components/cool-mode) |
+| Meteors | Meteor shower effect | [docs](https://magicui.design/docs/components/meteors) |
+| Number Ticker | Count up/down animation | [docs](https://magicui.design/docs/components/number-ticker) |
+| Orbiting Circles | Orbital motion circles | [docs](https://magicui.design/docs/components/orbiting-circles) |
+| Ripple | Background ripple emphasis | [docs](https://magicui.design/docs/components/ripple) |
+| Scroll Based Velocity | Speed-reactive scroll text | [docs](https://magicui.design/docs/components/scroll-based-velocity) |
+| Scroll Progress | Page scroll indicator | [docs](https://magicui.design/docs/components/scroll-progress) |
+| Progressive Blur | Blur gradient for scroll | [docs](https://magicui.design/docs/components/progressive-blur) |
+| Smooth Cursor | Physics-based cursor | [docs](https://magicui.design/docs/components/smooth-cursor) |
+| Pointer | Hover pointer indicator | [docs](https://magicui.design/docs/components/pointer) |
+
+### Device Mockups
+| Component | Description | Docs |
+|-----------|-------------|------|
+| Android | Android device mockup | [docs](https://magicui.design/docs/components/android) |
+| iPhone | iPhone mockup | [docs](https://magicui.design/docs/components/iphone) |
+| Safari | Safari browser mockup | [docs](https://magicui.design/docs/components/safari) |
+
+### Data Display
+| Component | Description | Docs |
+|-----------|-------------|------|
+| Globe | WebGL interactive globe | [docs](https://magicui.design/docs/components/globe) |
+| Icon Cloud | 3D interactive tag cloud | [docs](https://magicui.design/docs/components/icon-cloud) |
+| Animated Circular Progress | Circular gauge | [docs](https://magicui.design/docs/components/animated-circular-progress-bar) |
+| Dotted Map | Map with dot markers | [docs](https://magicui.design/docs/components/dotted-map) |
+| Pixel Image | Pixelated image effect | [docs](https://magicui.design/docs/components/pixel-image) |
+| Lens | Zoom into images/videos | [docs](https://magicui.design/docs/components/lens) |
+
+### Social & Media
+| Component | Description | Docs |
+|-----------|-------------|------|
+| Tweet Card | Display tweet embed | [docs](https://magicui.design/docs/components/tweet-card) |
+| Client Tweet Card | Client-side tweet card | [docs](https://magicui.design/docs/components/client-tweet-card) |
+| Avatar Circles | Overlapping avatar stack | [docs](https://magicui.design/docs/components/avatar-circles) |
+| Hero Video Dialog | Video dialog for hero | [docs](https://magicui.design/docs/components/hero-video-dialog) |
+| Code Comparison | Side-by-side code diff | [docs](https://magicui.design/docs/components/code-comparison) |
+| Theme Toggler | Animated theme switch | [docs](https://magicui.design/docs/components/animated-theme-toggler) |
+
+## Usage Pattern
+
+For docs lookup, use `docs-seeker` skill with Context7:
+```
+context7 query: "magicui <component-name> usage example"
+```
+
+For source code examples, fetch from GitHub:
+```
+https://github.com/magicuidesign/magicui/blob/main/example/<component>-demo.tsx
+```

package/skills/ck-frontend-design/references/performance-guardrails.md

@@ -0,0 +1,169 @@
+# Performance Guardrails
+
+Rules for maintaining smooth animation and rendering performance. These prevent the most common causes of mobile frame drops and layout thrashing.
+
+---
+
+## GPU-Safe Animations
+
+**Only animate these properties:**
+- `transform` (translate, scale, rotate)
+- `opacity`
+
+**Never animate:**
+- `top`, `left`, `right`, `bottom` — triggers layout reflow
+- `width`, `height` — triggers layout + paint
+- `margin`, `padding` — triggers layout
+- `background-color` — triggers paint (acceptable for color transitions, but avoid on frequently animating elements)
+
+**Why:** CSS `transform` and `opacity` are composited on the GPU and don't trigger layout or paint. All other properties cause the browser to recalculate layout on every frame — catastrophic on mobile.
+
+```css
+/* Good */
+.card { transform: translateY(0); transition: transform 300ms; }
+.card:hover { transform: translateY(-4px); }
+
+/* Bad */
+.card { top: 0; transition: top 300ms; }
+.card:hover { top: -4px; }
+```
+
+---
+
+## Blur Constraints
+
+**Apply `backdrop-blur` only to:**
+- Fixed-position elements (sticky navbars, overlays)
+- Modals and dialogs
+- Elements that don't scroll with content
+
+**Never apply blur to:**
+- Scrolling containers
+- Large content areas
+- Elements inside `overflow: auto/scroll` parents
+
+**Why:** `backdrop-blur` triggers continuous GPU compositing on every scroll frame. On a scrolling container with 20+ cards, this causes severe frame drops on mid-range and low-end mobile.
+
+```css
+/* Good — fixed nav */
+.navbar { position: fixed; backdrop-filter: blur(12px); }
+
+/* Bad — scrolling card list */
+.card-list .card { backdrop-filter: blur(8px); } /* kills mobile perf */
+```
+
+---
+
+## Grain and Noise Overlays
+
+**Correct implementation:**
+```css
+/* Fixed, pointer-events-none pseudo-element only */
+body::after {
+  content: '';
+  position: fixed;
+  inset: 0;
+  z-index: 50;
+  pointer-events: none;
+  background-image: url("data:image/svg+xml,..."); /* or CSS noise */
+  opacity: 0.03;
+}
+```
+
+**Never attach grain/noise to:**
+- Scrolling containers
+- Individual cards or sections
+- Any element with `position: relative` inside a scroll context
+
+---
+
+## Z-Index Discipline
+
+**Use systemic layers only. Establish a scale in your theme/variables:**
+
+```css
+:root {
+  --z-base: 0;
+  --z-card: 10;
+  --z-sticky: 100;
+  --z-overlay: 200;
+  --z-modal: 300;
+  --z-tooltip: 400;
+  --z-notification: 500;
+}
+```
+
+**Never:**
+- Use arbitrary values like `z-[9999]` or `z-50` unprompted
+- Stack z-indexes without a documented reason
+- Use z-index to fix stacking without understanding the stacking context
+
+---
+
+## Framer Motion Performance
+
+**Use `useMotionValue` + `useTransform` for continuous animations:**
+```jsx
+// Good — runs outside React render cycle
+const mouseX = useMotionValue(0);
+const rotateY = useTransform(mouseX, [-300, 300], [-15, 15]);
+
+// Bad — triggers re-render on every mouse move
+const [rotation, setRotation] = useState(0);
+```
+
+**For perpetual/infinite animations:**
+- Wrap in `React.memo` to prevent parent re-renders
+- Extract as isolated leaf client components
+- Use `<AnimatePresence>` for enter/exit — don't conditionally render without it
+
+**For scroll-driven reveals:**
+- Use `whileInView` or `IntersectionObserver`
+- Never use `window.addEventListener('scroll')` — causes continuous reflows
+
+**For staggered children:**
+- Parent `variants` and children MUST be in the same Client Component tree
+- If data is async, pass it as props into a centralized parent motion wrapper
+
+---
+
+## RSC Safety (Next.js)
+
+- Global state (Context, providers) works **only** in Client Components
+- Wrap providers in a `"use client"` component
+- If a section uses Framer Motion or any interactive hook, extract it as an isolated leaf component with `'use client'` at the top
+- Server Components render static layout only
+
+---
+
+## Mobile Override Rules
+
+For any asymmetric or complex layout, apply aggressive mobile fallback below 768px:
+
+```jsx
+// All asymmetric layouts collapse to single column
+<div className="grid grid-cols-1 md:grid-cols-[2fr_1fr_1fr] gap-6">
+```
+
+- Remove all rotations, negative margins, and overlaps below `md:`
+- Replace `h-screen` with `min-h-[100dvh]` — prevents iOS Safari viewport jumping
+- Never use `overflow: hidden` on `html`/`body` without testing on actual mobile
+- Test horizontal scroll — asymmetric layouts often cause unintentional x-overflow on small screens
+
+---
+
+## `will-change` Guidance
+
+Use sparingly. `will-change: transform` tells the browser to promote the element to its own GPU layer:
+
+- Apply only to elements that are **actively animating**
+- Remove after animation completes (or use `:hover` scoping)
+- Never apply globally — creates excessive GPU memory pressure
+
+```css
+/* Good — scoped to hover state */
+.card:hover { will-change: transform; }
+
+/* Bad — always promoted */
+.card { will-change: transform; }
+```

package/skills/ck-frontend-design/references/premium-design-patterns.md

@@ -0,0 +1,93 @@
+# Premium Design Patterns: Creative Arsenal
+
+Pull from this library to avoid defaulting to generic UI. These patterns make interfaces visually striking and memorable.
+
+> Framework note: Examples mention Framer Motion as an option for JS-driven patterns. GSAP/ThreeJS are alternatives for scroll storytelling. Never mix both in the same component tree.
+
+---
+
+## Vibe Archetypes (Pick One Before Designing)
+
+Before writing code, commit to a vibe:
+
+1. **Ethereal Glass** (SaaS / AI / Tech) — Deep OLED black `#050505`, radial mesh gradient orbs in background, vantablack cards with heavy `backdrop-blur-2xl`, wide geometric Grotesk typography
+2. **Editorial Luxury** (Lifestyle / Real Estate / Agency) — Warm creams `#FDFBF7`, muted sage, or deep espresso. Variable serif for massive headings, subtle CSS noise/film-grain overlay for a physical paper feel
+3. **Soft Structuralism** (Consumer / Health / Portfolio) — Silver-grey or pure white background, massive bold Grotesk, airy floating components with highly diffused ambient shadows
+
+---
+
+## Navigation
+
+- **Mac Dock Magnification** — Nav icons scale fluidly on hover with spring physics
+- **Magnetic Button** — Buttons physically pull toward the cursor using `useMotionValue` + `useTransform`
+- **Gooey Menu** — Sub-items detach from main button like viscous liquid
+- **Dynamic Island** — Pill-shaped component that morphs to show status/alerts
+- **Fluid Island Nav** — Floating glass pill detached from top (`mt-6`, `mx-auto`, `rounded-full`). On mobile: hamburger lines fluidly rotate to form an X
+- **Contextual Radial Menu** — Circular menu expanding at click coordinates
+- **Mega Menu Reveal** — Full-screen dropdowns that stagger-fade complex content
+- **Floating Speed Dial** — FAB that springs into a curved line of secondary actions
+
+## Layout and Grids
+
+- **Asymmetrical Bento** — Masonry-like CSS Grid with varying card sizes (`col-span-8 row-span-2` next to stacked `col-span-4` cards). Falls back to `grid-cols-1` on mobile
+- **Z-Axis Cascade** — Elements stacked like physical cards with slight overlap and varying depths. Remove rotations below 768px
+- **Editorial Split** — Massive typography on left half, scrollable image pills or staggered cards on right
+- **Split Screen Scroll** — Two halves of the screen sliding in opposite directions on scroll
+- **Curtain Reveal** — Hero section parting in the middle like a curtain on scroll
+- **Masonry Layout** — Staggered grid without fixed row heights (Pinterest-style)
+- **Chroma Grid** — Grid borders or tiles with subtle, continuously animating color gradients
+
+## Cards and Containers
+
+- **Double-Bezel (Doppelrand)** — Cards that look like machined hardware: outer shell (`bg-black/5`, `ring-1 ring-black/5`, `p-1.5`, `rounded-[2rem]`) wrapping an inner core with its own highlight and concentric radius (`rounded-[calc(2rem-0.375rem)]`)
+- **Parallax Tilt Card** — 3D-tilting card tracking mouse coordinates
+- **Spotlight Border Card** — Card borders that illuminate dynamically under the cursor
+- **Glassmorphism Panel** — True frosted glass: `backdrop-blur` + 1px inner border (`border-white/10`) + inner shadow (`shadow-[inset_0_1px_0_rgba(255,255,255,0.1)]`) to simulate edge refraction
+- **Holographic Foil Card** — Iridescent rainbow reflections shifting on hover
+- **Tinder Swipe Stack** — Physical stack of cards the user can swipe away
+- **Morphing Modal** — Button that seamlessly expands into a full-screen dialog
+
+## Scroll Animations
+
+- **Sticky Scroll Stack** — Cards that stick to top and physically stack over each other during scroll
+- **Horizontal Scroll Hijack** — Vertical scroll translates into smooth horizontal gallery pan
+- **Zoom Parallax** — Central background image zooming in/out seamlessly as you scroll
+- **Scroll Progress Path** — SVG lines that draw themselves as user scrolls
+- **Staggered Entry** — Elements cascade in with slight delays, Y-translation + opacity fade. Use `staggerChildren` in Framer Motion or CSS `animation-delay: calc(var(--index) * 100ms)`. Never mount everything at once
+
+## Galleries and Media
+
+- **Coverflow Carousel** — 3D carousel with center focused, edges angled back
+- **Drag-to-Pan Grid** — Boundless grid freely draggable in any direction
+- **Accordion Image Slider** — Narrow strips that expand fully on hover
+- **Hover Image Trail** — Mouse leaves a trail of popping/fading images
+- **Glitch Effect Image** — Brief RGB-channel shift digital distortion on hover
+- **Dome Gallery** — 3D gallery with panoramic dome feel
+
+## Typography and Text
+
+- **Kinetic Marquee** — Endless text bands that reverse direction or speed up on scroll
+- **Text Mask Reveal** — Massive typography as a transparent window to video background
+- **Text Scramble Effect** — Matrix-style character decoding on load or hover
+- **Variable Font Animation** — Interpolate weight/width on scroll or hover for text that feels alive
+- **Outlined-to-Fill Transition** — Text starts as stroke outline, fills with color on scroll entry
+- **Circular Text Path** — Text curved along a spinning circular path
+- **Kinetic Typography Grid** — Grid of letters that dodge or rotate away from cursor
+
+## Micro-Interactions
+
+- **Button-in-Button Trailing Icon** — Arrow icon nested inside its own circular wrapper (`w-8 h-8 rounded-full bg-black/5`) flush with button's inner right padding. Never a naked icon next to text
+- **Particle Explosion Button** — CTAs shatter into particles on success
+- **Directional Hover-Aware Button** — Hover fill enters from the exact side the mouse came from
+- **Ripple Click Effect** — Visual waves rippling precisely from click coordinates
+- **Skeleton Shimmer** — Shifting light reflections across placeholder boxes. Match layout shape exactly
+- **Tactile Press Feedback** — On `:active`, use `scale(0.98)` or `translateY(1px)` to simulate physical push
+- **Eyebrow Tags** — Microscopic pill badge before major headings (`rounded-full px-3 py-1 text-[10px] uppercase tracking-[0.2em]`)
+
+## Surfaces and Effects
+
+- **Grain/Noise Overlay** — Fixed `pointer-events-none` pseudo-element at `z-50`. Never on scrolling containers
+- **Colored Tinted Shadows** — Shadows carry background hue instead of generic black
+- **Mesh Gradient Background** — Organic, lava-lamp-like animated color blobs
+- **Lens Blur Depth** — Dynamic focus blurring background layers to highlight foreground action
+- **Animated SVG Line Drawing** — Vectors draw their own contours in real-time

package/skills/ck-frontend-design/references/redesign-audit-checklist.md

@@ -0,0 +1,114 @@
+# Redesign Audit Checklist
+
+Use when upgrading an existing project. Follow Scan → Diagnose → Fix in order.
+
+## Workflow
+
+1. **Scan** — Read the codebase. Identify framework, styling method (Tailwind, vanilla CSS, styled-components), and current design patterns.
+2. **Diagnose** — Run through each category below. List every generic pattern, weak point, and missing state.
+3. **Fix** — Apply targeted upgrades working with the existing stack. Do not rewrite from scratch.
+
+**Rules:**
+- Work with the existing tech stack. Do not migrate frameworks.
+- Do not break existing functionality. Test after every change.
+- Check `package.json` before adding any new dependency.
+- Keep changes focused and reviewable — small targeted improvements over big rewrites.
+
+---
+
+## Audit Categories
+
+### 1. Typography
+- [ ] Browser default fonts or Inter everywhere → replace with `Geist`, `Outfit`, `Cabinet Grotesk`, or `Satoshi`
+- [ ] Headlines lack presence → tighten tracking, reduce line-height, increase display size
+- [ ] Body text too wide → limit to ~65ch, increase line-height
+- [ ] Only 400 + 700 weights → introduce 500/600 for subtler hierarchy
+- [ ] Numbers in proportional font → use monospace or `font-variant-numeric: tabular-nums`
+- [ ] All-caps subheaders everywhere → try lowercase italic or sentence case
+- [ ] Orphaned last words → fix with `text-wrap: balance` or `text-wrap: pretty`
+- [ ] Serif fonts on dashboard UI → use high-end sans-serif pairs only
+
+### 2. Color and Surfaces
+- [ ] Pure `#000000` → replace with off-black or tinted dark
+- [ ] Oversaturated accents → desaturate below 80%
+- [ ] More than one accent color → reduce to one
+- [ ] Mixing warm and cool grays → pick one family, stay consistent
+- [ ] Purple/blue AI gradient aesthetic → replace with neutral base + singular accent
+- [ ] Generic `box-shadow` → tint shadows to background hue
+- [ ] Flat surfaces with zero texture → add subtle noise/grain overlay
+- [ ] Perfectly even linear gradients → use radial, mesh, or noise-overlaid gradients
+- [ ] Random dark section in light-mode page (or vice versa) → commit to consistent tone or use slightly darker shade of same palette
+
+### 3. Layout
+- [ ] Everything centered and symmetrical → break with offset margins, mixed aspect ratios
+- [ ] Three equal card columns as feature row → use 2-col zig-zag, asymmetric grid, or horizontal scroll
+- [ ] `h-screen` / `height: 100vh` → replace with `min-height: 100dvh`
+- [ ] Complex flexbox `calc()` math → replace with CSS Grid
+- [ ] No max-width container → add 1200-1440px constraint with auto margins
+- [ ] Uniform border-radius everywhere → vary inner/outer elements
+- [ ] No overlap or depth → use negative margins for layering
+- [ ] Dashboard always has left sidebar → consider top nav, command menu, or collapsible panel
+- [ ] Buttons not bottom-aligned in card groups → pin CTAs to card bottom
+- [ ] Missing whitespace on marketing pages → double spacing, let design breathe
+
+### 4. Interactivity and States
+- [ ] No hover states on buttons → add background shift, scale, or translate
+- [ ] No active/pressed feedback → add `scale(0.98)` or `translateY(1px)` on press
+- [ ] Instant transitions → add 200-300ms smooth transitions
+- [ ] Missing focus ring → visible focus indicator (accessibility requirement)
+- [ ] Generic circular spinner → replace with skeleton loader matching layout shape
+- [ ] No empty state → design a composed "getting started" view
+- [ ] No error state → inline error messages on forms (no `window.alert()`)
+- [ ] Dead links (`href="#"`) → link real destinations or visually disable
+- [ ] No current-page indicator in nav → style active link distinctly
+- [ ] Scroll jumping on anchor links → add `scroll-behavior: smooth`
+- [ ] Animations using `top`/`left`/`width`/`height` → switch to `transform` + `opacity`
+
+### 5. Content
+- [ ] Generic placeholder names → use diverse, realistic names
+- [ ] Round fake numbers → use organic messy data
+- [ ] AI copywriting clichés → plain, specific language
+- [ ] Lorem Ipsum → real draft copy
+- [ ] Exclamation marks in success states → remove
+- [ ] Title Case On Every Header → use sentence case
+- [ ] Same avatar for multiple users → unique assets per person
+- [ ] Blog post dates all identical → randomize
+
+### 6. Components and Code
+- [ ] Generic card (border + shadow + white bg) at high density → use spacing/dividers
+- [ ] Always one filled + one ghost button → add text links, reduce visual noise
+- [ ] Lucide/Feather icons only → try Phosphor or Heroicons for differentiation
+- [ ] Cliché icon metaphors (rocketship, shield) → less obvious alternatives
+- [ ] Div soup → use semantic HTML: `nav`, `main`, `article`, `aside`, `section`
+- [ ] Inline styles mixed with CSS classes → move all styling to the project's system
+- [ ] Arbitrary z-index values (`z-[9999]`) → establish a clean z-index scale
+- [ ] Missing alt text on meaningful images → describe content for screen readers
+- [ ] Missing meta tags → add `title`, `description`, `og:image`
+
+---
+
+## Fix Priority Order
+
+Apply in this order for maximum impact with minimum risk:
+
+1. **Font swap** — biggest instant improvement, lowest risk
+2. **Color cleanup** — remove clashing or oversaturated colors
+3. **Hover and active states** — makes interface feel alive
+4. **Layout and spacing** — proper grid, max-width, consistent padding
+5. **Replace generic components** — swap cliché patterns for modern alternatives
+6. **Add loading, empty, error states** — makes it feel finished
+7. **Polish typography scale** — the premium final touch
+
+---
+
+## Strategic Omissions (What AI Typically Forgets)
+
+These are rarely in AI-generated output. Check explicitly:
+
+- **No legal links** → add privacy policy + terms in footer
+- **No "back" navigation** → every page needs a way back
+- **No custom 404 page** → design a helpful branded "not found" experience
+- **No form validation** → client-side validation for emails, required fields, formats
+- **No "skip to content" link** → essential for keyboard users
+- **No favicon** → always include a branded favicon
+- **No social sharing meta** → `og:image`, `og:title`, `twitter:card`

package/skills/ck-frontend-design/references/visual-analysis-overview.md

@@ -0,0 +1,95 @@
+# Visual Analysis Overview
+
+Use AI multimodal vision to analyze generated assets and verify design standards.
+
+## Purpose
+
+- Verify generated assets align with aesthetic direction
+- Ensure professional quality before integration
+- Identify specific improvements needed for iteration
+- Make objective design decisions based on analysis
+- Extract actionable data (hex codes, composition insights)
+
+## Quick Start
+
+### Comprehensive Analysis
+```bash
+python scripts/gemini_batch_process.py \
+  --files docs/assets/generated-hero.png \
+  --task analyze \
+  --prompt "[see analysis-prompts.md for detailed prompt]" \
+  --output docs/assets/analysis-report.md \
+  --model gemini-2.5-flash
+```
+
+### Compare Multiple Variations
+```bash
+python scripts/gemini_batch_process.py \
+  --files docs/assets/option-1.png docs/assets/option-2.png docs/assets/option-3.png \
+  --task analyze \
+  --prompt "[see analysis-prompts.md for comparison prompt]" \
+  --output docs/assets/comparison-analysis.md \
+  --model gemini-2.5-flash
+```
+
+### Extract Color Palette
+```bash
+python scripts/gemini_batch_process.py \
+  --files docs/assets/final-asset.png \
+  --task analyze \
+  --prompt "Extract 5-8 dominant colors with hex codes. Classify as primary/accent/neutral. Suggest CSS variable names." \
+  --output docs/assets/color-palette.md \
+  --model gemini-2.5-flash
+```
+
+## Decision Framework
+
+### Score ≥ 8/10: Proceed to Integration
+**Actions**:
+- Optimize for web delivery
+- Create responsive variants
+- Document implementation guidelines
+- Extract color palette for CSS variables
+
+### Score 6-7/10: Minor Refinements Needed
+**Actions**:
+- Use `media-processing` skill for adjustments (brightness/contrast/saturation)
+- Consider selective regeneration of problem areas
+- May proceed with caution if time-constrained
+
+### Score < 6/10: Major Iteration Required
+**Actions**:
+- Analyze specific failure points from report
+- Refine generation prompt substantially
+- Regenerate with corrected parameters
+- Consider alternative aesthetic approach
+
+## Detailed References
+
+- `analysis-prompts.md` - All analysis prompt templates
+- `analysis-techniques.md` - Advanced analysis strategies
+- `analysis-best-practices.md` - Quality guidelines and pitfalls
+
+## Example Color Extraction Output
+
+```css
+/* Extracted Color Palette */
+:root {
+  /* Primary Colors */
+  --color-primary-600: #2C5F7D;  /* Dark teal - headers, CTAs */
+  --color-primary-400: #4A90B8;  /* Medium teal - links, accents */
+
+  /* Accent Colors */
+  --color-accent-500: #E8B44F;   /* Warm gold - highlights */
+
+  /* Neutral Colors */
+  --color-neutral-900: #1A1A1A;  /* Near black - body text */
+  --color-neutral-100: #F5F5F5;  /* Light gray - backgrounds */
+
+  /* Semantic Usage */
+  --color-text-primary: var(--color-neutral-900);
+  --color-text-on-primary: #FFFFFF;
+  --color-background: var(--color-neutral-100);
+  --color-cta: var(--color-primary-600);
+}
+```