@haposoft/cafekit 0.16.0-rc.7 → 0.16.0

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

@@ -1,114 +0,0 @@
-# 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/src/claude/skills/frontend-design/references/technical-accessibility.md

@@ -1,119 +0,0 @@
-# Accessibility Checks
-
-WCAG compliance and accessibility guidelines for generated assets.
-
-## Text Overlay Readability
-
-### Color Contrast Ratios
-- **WCAG AA**: 4.5:1 for normal text, 3:1 for large text
-- **WCAG AAA**: 7:1 for normal text, 4.5:1 for large text
-
-### Testing Requirements
-- Test across image variations
-- Consider adding gradient overlays in code
-- Add text shadows for increased legibility
-
-### Alt Text Guidelines
-- Describe the asset's purpose and mood
-- Don't repeat visible text
-- Keep concise (150 characters max)
-
-## CSS Techniques for Accessibility
-
-### Gradient Overlay for Text Readability
-```css
-.hero {
-  position: relative;
-  background-image: url('hero.webp');
-}
-.hero::before {
-  content: '';
-  position: absolute;
-  inset: 0;
-  background: linear-gradient(
-    to bottom,
-    rgba(0,0,0,0.3) 0%,
-    rgba(0,0,0,0.6) 100%
-  );
-}
-```
-
-### Text Shadow for Contrast
-```css
-.hero-text {
-  text-shadow: 0 2px 4px rgba(0,0,0,0.5);
-}
-```
-
-### Ensure Minimum Contrast
-```css
-.hero-cta {
-  background: var(--color-primary-600);
-  color: white; /* Ensure 4.5:1 contrast */
-}
-```
-
-## Integration Testing Analysis
-
-Analyze how asset works with UI elements:
-
-```bash
-python scripts/gemini_batch_process.py \
-  --files docs/assets/hero-with-text-overlay.png \
-  --task analyze \
-  --prompt "Analyze this design asset with UI elements overlaid:
-
-1. Text Readability: Can all text be read clearly?
-2. Contrast Issues: Identify any WCAG violations
-3. Visual Hierarchy: Do buttons and CTAs stand out?
-4. Spacing Problems: Any crowding or poor breathing room?
-5. Responsive Concerns: Will this work on mobile at 9:16?
-
-Provide specific recommendations for adjustments." \
-  --output docs/assets/integration-analysis.md \
-  --model gemma-4-31b-it
-```
-
-## Next.js Integration Example
-
-```tsx
-// app/components/Hero.tsx
-import Image from 'next/image'
-
-export function Hero() {
-  return (
-    <section className="relative h-screen">
-      {/* Background image with optimization */}
-      <Image
-        src="/assets/hero-desktop.webp"
-        alt="Minimalist desert landscape"
-        fill
-        priority
-        quality={85}
-        className="object-cover"
-        sizes="100vw"
-      />
-
-      {/* Gradient overlay for text readability */}
-      <div className="absolute inset-0 bg-gradient-to-b from-black/30 to-black/60" />
-
-      {/* Content */}
-      <div className="relative z-10 flex h-full items-center justify-center">
-        <h1 className="text-6xl font-bold text-white drop-shadow-lg">
-          Your Headline
-        </h1>
-      </div>
-    </section>
-  )
-}
-```
-
-## Common Issues
-
-### Issue: Poor Text Overlay Readability
-**Symptoms**: Text hard to read over generated background
-**Solutions**:
-- Add CSS gradient overlay (see above)
-- Regenerate with "clean composition for text overlay" in prompt
-- Use darker/lighter areas strategically
-- Add text shadows or backdrop-blur

package/src/claude/skills/frontend-design/references/technical-best-practices.md

@@ -1,97 +0,0 @@
-# Best Practices Checklists
-
-Quality gates and checklists for asset generation workflows.
-
-## Asset Generation Workflow
-
-### Before Generating Assets
-- [ ] Defined clear aesthetic direction from design brief
-- [ ] Extracted color palette and typography character
-- [ ] Identified asset purpose and integration context
-- [ ] Considered accessibility and text overlay needs
-
-### During Generation
-- [ ] Crafted design-driven, contextual prompt
-- [ ] Selected appropriate model and quality level
-- [ ] Specified correct aspect ratio for use case
-- [ ] Generated multiple variations if exploring
-
-### After Generation
-- [ ] Ran comprehensive visual analysis (score ≥ 7/10)
-- [ ] Extracted exact color palette with hex codes
-- [ ] Compared multiple variations and selected best
-- [ ] Tested with overlaid text/UI elements
-- [ ] Optimized file size for web performance
-- [ ] Created responsive variants if needed
-- [ ] Documented asset usage and guidelines
-
-## Design Guideline Extraction Workflow
-
-### When Analyzing Existing Designs
-- [ ] Captured high-quality reference screenshots
-- [ ] Ran comprehensive design analysis with structured prompts
-- [ ] Extracted specific values (hex codes, px sizes, ms timings)
-- [ ] Analyzed multiple screens for pattern consistency
-- [ ] Validated font predictions against Google Fonts
-- [ ] Documented findings in actionable format
-- [ ] Created CSS variable specifications
-- [ ] Saved extracted guidelines in project docs/
-
-## Quality Gates
-
-### Never Proceed to Integration Without
-- [ ] Visual analysis score ≥ 7/10
-- [ ] Extracted color palette documented
-- [ ] Accessibility contrast checks passed
-- [ ] Responsive variants generated
-- [ ] File optimization completed
-- [ ] Asset usage guidelines documented
-
-## Final Checklist
-
-Before considering any asset "done":
-- [ ] Generated with design-driven prompt (not generic)
-- [ ] Analyzed and scored ≥ 7/10
-- [ ] Extracted color palette for CSS implementation
-- [ ] Tested with UI overlays for readability
-- [ ] Optimized for web (WebP/JPEG)
-- [ ] Created responsive variants
-- [ ] Documented usage guidelines
-- [ ] Accessibility checks passed (contrast, alt text)
-- [ ] Integrated into frontend with proper optimization
-
-## Common Issues & Solutions
-
-### Issue 1: Generated Asset Too Generic
-**Symptoms**: Asset looks like stock photography, lacks design character
-**Solution**:
-- Refine prompt with specific aesthetic movements
-- Reference artists/designers/styles explicitly
-- Use more distinctive color directions
-- Add contextual details that make it unique
-
-### Issue 2: Inconsistent Design Language
-**Symptoms**: Each generated asset feels unrelated
-**Solution**:
-- Extract and document design system from first successful generation
-- Reuse color palette keywords in all subsequent prompts
-- Maintain consistent aesthetic direction across generations
-- Reference previous successful assets in new prompts
-
-### Issue 3: Low Analysis Scores
-**Symptoms**: Consistently getting scores < 7/10
-**Solutions**:
-- Review evaluation criteria—are they realistic?
-- Study high-scoring designs for patterns
-- Use design extraction on inspiration to learn what works
-- Iterate prompt with specific improvements from analysis
-
-### Issue 4: Slow Generation Times
-**Symptoms**: Waiting too long for results
-**Solutions**:
-- Use fast model for exploration phase
-- Generate in batches rather than sequentially
-- Reserve ultra model only for final production assets
-- Run analysis while next generation processes
-
-**Remember**: Design first, generate second. Context is king. Iterate ruthlessly. Analysis is mandatory. Demand specifics, not generalities.

package/src/claude/skills/frontend-design/references/technical-optimization.md

@@ -1,44 +0,0 @@
-# Cost & Performance Optimization
-
-Model selection strategies and budget guidelines.
-
-## Model Selection Strategy
-
-### 1. Exploration Phase
-Use fast model (3-5 variations):
-- **Cost**: ~$0.02 per image
-- **Speed**: ~5-10 seconds per generation
-- **Use for**: Rapid iteration, aesthetic exploration
-
-### 2. Refinement Phase
-Use standard model (1-2 variations):
-- **Cost**: ~$0.04 per image
-- **Speed**: ~10-20 seconds per generation
-- **Use for**: Production-ready assets
-
-### 3. Final Polish
-Use ultra model (1 generation):
-- **Cost**: ~$0.08 per image
-- **Speed**: ~20-30 seconds per generation
-- **Use for**: Hero images, marketing materials, critical assets
-
-## Analysis Model Strategy
-
-- Use gemma-4-31b-it for all analysis (vision understanding)
-- **Cost**: ~$0.001 per analysis
-- **Speed**: ~2-5 seconds per analysis
-- **Token-efficient**: Images count as ~258-1548 tokens
-
-## Budget Guidelines
-
-- **Small project**: 10-20 images, ~$2-5 total
-- **Medium project**: 50-100 images, ~$10-20 total
-- **Large project**: 200+ images, ~$50+ total
-
-## Optimization Tips
-
-1. **Use fast model first**: Explore variations cheaply before committing to production quality
-2. **Batch analyze**: Analyze multiple variations simultaneously to save time
-3. **Reuse successful prompts**: Once you find a working prompt, reuse it with variations
-4. **Generate responsive variants separately**: Only create mobile versions for assets that need them
-5. **Skip ultra model unless critical**: Standard quality often sufficient for most assets

package/src/claude/skills/frontend-design/references/technical-overview.md

@@ -1,90 +0,0 @@
-# Technical Guide Overview
-
-Technical considerations and best practices for AI multimodal integration in frontend design.
-
-## Quick Reference
-
-### File Optimization
-```bash
-python scripts/media_optimizer.py \
-  --input docs/assets/hero-image.png \
-  --output docs/assets/hero-optimized.webp \
-  --quality 85
-```
-
-### Format Selection
-- **WebP**: Best for web, 25-35% smaller than PNG, wide browser support
-- **AVIF**: Cutting edge, 50% smaller than WebP, limited support
-- **PNG**: Lossless, large file size, use for transparency
-- **JPEG**: Lossy, smaller than PNG, photos without transparency
-
-### Responsive Variants
-```bash
-# Desktop hero (16:9)
---aspect-ratio 16:9
-
-# Mobile hero (9:16 or 3:4)
---aspect-ratio 9:16
-
-# Square cards (1:1)
---aspect-ratio 1:1
-```
-
-## Detailed References
-
-- `technical-accessibility.md` - WCAG compliance, contrast checks, alt text
-- `technical-workflows.md` - Complete pipeline examples
-- `technical-best-practices.md` - Checklists, quality gates
-- `technical-optimization.md` - Cost strategies, model selection
-
-## Quick Commands
-
-```bash
-# Generate (standard quality)
-python scripts/gemini_batch_process.py --task generate \
-  --prompt "[design-driven prompt]" \
-  --output docs/assets/[name] \
-  --model imagen-4.0-generate-001 \
-  --aspect-ratio 16:9
-
-# Analyze
-python scripts/gemini_batch_process.py --files docs/assets/[image].png \
-  --task analyze \
-  --prompt "[evaluation criteria]" \
-  --output docs/assets/analysis.md \
-  --model gemma-4-31b-it
-
-# Optimize
-python scripts/media_optimizer.py \
-  --input docs/assets/[image].png \
-  --output docs/assets/[image].webp \
-  --quality 85
-
-# Extract colors
-python scripts/gemini_batch_process.py --files docs/assets/[image].png \
-  --task analyze \
-  --prompt "Extract 5-8 dominant colors with hex codes. Classify as primary/accent/neutral." \
-  --output docs/assets/color-palette.md \
-  --model gemma-4-31b-it
-```
-
-## Responsive Image Strategies
-
-**Art Direction (different crops)**:
-```html
-<picture>
-  <source media="(min-width: 768px)" srcset="hero-desktop.webp">
-  <source media="(max-width: 767px)" srcset="hero-mobile.webp">
-  <img src="hero-desktop.jpg" alt="Hero image">
-</picture>
-```
-
-**Resolution Switching (same crop, different sizes)**:
-```html
-<img
-  srcset="hero-400w.webp 400w, hero-800w.webp 800w, hero-1200w.webp 1200w"
-  sizes="(max-width: 600px) 400px, (max-width: 1000px) 800px, 1200px"
-  src="hero-800w.jpg"
-  alt="Hero image"
-/>
-```

package/src/claude/skills/frontend-design/references/technical-workflows.md

@@ -1,150 +0,0 @@
-# Complete Workflow Examples
-
-End-to-end pipeline examples for asset generation and analysis.
-
-## Example 1: Hero Section (Complete Pipeline)
-
-```bash
-# 1. Generate hero image with design context
-python scripts/gemini_batch_process.py \
-  --task generate \
-  --prompt "Minimalist desert landscape, warm beige sand dunes,
-  soft morning light, serene and spacious, muted earth tones
-  (tan, cream, soft ochre), clean composition for text overlay,
-  sophisticated travel aesthetic, 16:9 cinematic" \
-  --output docs/assets/hero-desert \
-  --model imagen-4.0-generate-001 \
-  --aspect-ratio 16:9
-
-# 2. Evaluate aesthetic quality
-python scripts/gemini_batch_process.py \
-  --files docs/assets/hero-desert.png \
-  --task analyze \
-  --prompt "Rate this image 1-10 for: visual appeal, color harmony,
-  suitability for overlaying white text, professional quality.
-  List any improvements needed." \
-  --output docs/assets/hero-evaluation.md \
-  --model gemma-4-31b-it
-
-# 3. If score ≥ 7/10, optimize for web
-python scripts/media_optimizer.py \
-  --input docs/assets/hero-desert.png \
-  --output docs/assets/hero-desktop.webp \
-  --quality 85
-
-# 4. Generate mobile variant (9:16)
-python scripts/gemini_batch_process.py \
-  --task generate \
-  --prompt "Minimalist desert landscape, warm beige sand dunes,
-  soft morning light, serene and spacious, muted earth tones
-  (tan, cream, soft ochre), clean composition for text overlay,
-  sophisticated travel aesthetic, 9:16 portrait" \
-  --output docs/assets/hero-mobile \
-  --model imagen-4.0-generate-001 \
-  --aspect-ratio 9:16
-
-# 5. Optimize mobile variant
-python scripts/media_optimizer.py \
-  --input docs/assets/hero-mobile.png \
-  --output docs/assets/hero-mobile.webp \
-  --quality 85
-```
-
-## Example 2: Extract, Generate, Analyze Loop
-
-```bash
-# 1. Extract design guidelines from inspiration
-python scripts/gemini_batch_process.py \
-  --files docs/inspiration/competitor-hero.png \
-  --task analyze \
-  --prompt "[use extraction prompt from extraction-prompts.md]" \
-  --output docs/design-guidelines/competitor-analysis.md \
-  --model gemma-4-31b-it
-
-# 2. Generate asset based on extracted guidelines
-# (Review competitor-analysis.md for color palette, aesthetic)
-python scripts/gemini_batch_process.py \
-  --task generate \
-  --prompt "[craft prompt using extracted aesthetic and colors]" \
-  --output docs/assets/our-hero \
-  --model imagen-4.0-generate-001 \
-  --aspect-ratio 16:9
-
-# 3. Analyze our generated asset
-python scripts/gemini_batch_process.py \
-  --files docs/assets/our-hero.png \
-  --task analyze \
-  --prompt "Compare to competitor design. Rate differentiation (1-10).
-  Are we too similar or successfully distinct?" \
-  --output docs/assets/differentiation-analysis.md \
-  --model gemma-4-31b-it
-
-# 4. Extract colors from our final asset for CSS
-python scripts/gemini_batch_process.py \
-  --files docs/assets/our-hero.png \
-  --task analyze \
-  --prompt "[use color extraction prompt from visual-analysis-overview.md]" \
-  --output docs/assets/color-palette.md \
-  --model gemma-4-31b-it
-```
-
-## Example 3: A/B Test Assets
-
-```bash
-# Generate 2 design directions
-python scripts/gemini_batch_process.py \
-  --task generate \
-  --prompt "Minimalist approach: [prompt]" \
-  --output docs/assets/variant-a \
-  --model imagen-4.0-fast-generate-001 \
-  --aspect-ratio 16:9
-
-python scripts/gemini_batch_process.py \
-  --task generate \
-  --prompt "Bold approach: [prompt]" \
-  --output docs/assets/variant-b \
-  --model imagen-4.0-fast-generate-001 \
-  --aspect-ratio 16:9
-
-# Compare variants
-python scripts/gemini_batch_process.py \
-  --files docs/assets/variant-a.png docs/assets/variant-b.png \
-  --task analyze \
-  --prompt "A/B comparison for [target audience]:
-  1. Attention capture
-  2. Brand alignment
-  3. Conversion potential
-  Recommend which to test." \
-  --output docs/assets/ab-comparison.md \
-  --model gemma-4-31b-it
-
-# Generate production version of winner
-python scripts/gemini_batch_process.py \
-  --task generate \
-  --prompt "[winning approach prompt]" \
-  --output docs/assets/final-hero \
-  --model imagen-4.0-generate-001 \
-  --aspect-ratio 16:9
-```
-
-## Batch Analysis for Rapid Iteration
-
-```bash
-# Generate 3 variations with fast model
-for i in {1..3}; do
-  python scripts/gemini_batch_process.py \
-    --task generate \
-    --prompt "[prompt with variation-$i twist]" \
-    --output docs/assets/var-$i \
-    --model imagen-4.0-fast-generate-001 \
-    --aspect-ratio 16:9
-done
-
-# Batch analyze all variations
-python scripts/gemini_batch_process.py \
-  --files docs/assets/var-*.png \
-  --task analyze \
-  --prompt "Rank these variations 1-3 with scores. Identify winner." \
-  --output docs/assets/batch-analysis.md \
-  --model gemma-4-31b-it
-```