madappgang/ui-implement

UI Implementation Skill

Overview

This skill provides patterns for implementing UI improvements based on design analysis. It transforms review findings into code changes following Anti-AI design principles.

Relationship to Other Skills

| Skill | Purpose | Modifies Code? | |-------|---------|----------------| | dev:ui-analyse | Visual analysis, issue detection | No | | dev:ui-implement | Apply improvements from analysis | Yes | | dev:ui-style-format | Style file specification | No | | dev:design-references | Reference image management | No |

Prerequisite

This skill assumes analysis has been completed using:

• dev:ui-analyse skill
• /dev:ui command output
• External design review

Before implementing, ensure you have:

1. A review document with identified issues
2. Component path(s) to modify
3. Understanding of the visual metaphor to apply

Implementation Workflow

Phase 1: Parse Review Document

Extract actionable items from the review document.

# Extract actionable items from review
parse_review() {
  local review_path="$1"

  # Extract CRITICAL and HIGH issues
  grep -A 2 "^\[CRITICAL\]" "$review_path"
  grep -A 2 "^\[HIGH\]" "$review_path"
}

What to Look For:

• CRITICAL issues (fix immediately)
• HIGH issues (fix before release)
• Specific component locations
• Recommended changes

Phase 2: Visual Context (Optional)

If Gemini available and screenshot provided, understand the current visual state.

# Understand current visual state
npx claudish --model "$GEMINI_MODEL" --image "$CURRENT_SCREENSHOT" --quiet --auto-approve <<< "
Describe the current UI implementation:
1. Layout structure
2. Color scheme
3. Typography
4. Animation presence
5. Areas needing improvement

Output as structured data for implementation."

Provider Detection:

# Check providers in priority order
if [[ -n "$GEMINI_API_KEY" ]]; then
  GEMINI_MODEL="g/gemini-3-pro-preview"
elif [[ -n "$OPENROUTER_API_KEY" ]]; then
  GEMINI_MODEL="or/google/gemini-3-pro-preview"
elif [[ -n "$GOOGLE_APPLICATION_CREDENTIALS" ]]; then
  GEMINI_MODEL="vertex/gemini-3-pro-preview"
else
  GEMINI_MODEL=""  # Text-only mode
fi

Phase 3: Apply Anti-AI Improvements

Apply the five core Anti-AI design rules to transform generic UI into distinctive design.

See Anti-AI Design Rules section below for detailed patterns.

Phase 4: Visual Verification (Optional)

If Gemini available after changes, verify improvements were applied correctly.

# Verify improvements
npx claudish --model "$GEMINI_MODEL" --image "$NEW_SCREENSHOT" --quiet --auto-approve <<< "
Verify these improvements were applied:
1. Asymmetric layout: {expected}
2. Texture/depth: {expected}
3. Typography drama: {expected}
4. Micro-interactions: {expected}
5. Bespoke colors: {expected}

Score 1-10 and note any remaining issues."

Anti-AI Design Rules

These rules transform generic, AI-generated looking UI into distinctive, human-crafted designs.

Rule 1: Break Symmetry

Rigid symmetric grids look AI-generated. Break them with asymmetric bento layouts.

// BEFORE: Symmetric grid
<div className="grid grid-cols-3 gap-4">

// AFTER: Asymmetric bento
<div className="grid grid-cols-12 gap-6">
  <div className="col-span-7 row-span-2" />
  <div className="col-span-5" />
  <div className="col-span-3" />
  <div className="col-span-2 -mt-8" />
</div>

Key Techniques:

• Use 12-column grids for flexibility
• Vary column spans (7+5, not 6+6)
• Use negative margins for overlap
• Vary row heights
• Break alignment intentionally

Rule 2: Add Texture

Flat solid colors look AI-generated. Add gradients, glass effects, and depth.

// BEFORE: Flat
<div className="bg-white rounded-lg">

// AFTER: Textured
<div className="
  bg-gradient-to-br from-white/80 to-white/40
  backdrop-blur-xl
  border border-white/20
  shadow-[0_8px_32px_rgba(0,0,0,0.08),inset_0_1px_0_rgba(255,255,255,0.6)]
">

Key Techniques:

• Gradient backgrounds (subtle, directional)
• Glassmorphism (backdrop-blur + semi-transparent)
• Complex shadows with inset highlights
• Border with alpha for subtle edges
• Noise texture overlays

Rule 3: Dramatic Typography

Generic typography looks AI-generated. Create dramatic visual hierarchy.

// BEFORE: Generic
<h1 className="text-2xl font-bold">Welcome</h1>

// AFTER: Dramatic
<h1 className="
  text-[clamp(4rem,15vw,12rem)]
  font-serif font-thin tracking-[-0.04em]
  leading-[0.85]
  bg-gradient-to-r from-zinc-900 via-zinc-600 to-zinc-900
  bg-clip-text text-transparent
">
  Welcome
</h1>

Key Techniques:

• Fluid typography with clamp()
• Extreme size contrasts (body 16px, hero 120px+)
• Tight line-height for headlines (0.85-0.95)
• Negative letter-spacing for large text
• Gradient text with bg-clip-text
• Mix serif/sans-serif for contrast

Rule 4: Micro-Interactions

Static elements look AI-generated. Add motion and feedback.

// BEFORE: Static
<button className="bg-blue-500 hover:bg-blue-600">

// AFTER: Reactive
<motion.button
  whileHover={{ scale: 1.02, y: -2 }}
  whileTap={{ scale: 0.98 }}
  transition={{ type: "spring", stiffness: 400, damping: 17 }}
  className="
    bg-gradient-to-r from-violet-600 to-indigo-600
    hover:shadow-[0_0_40px_rgba(139,92,246,0.4)]
    transition-shadow duration-300
  "
>

Key Techniques:

• Spring physics for natural feel
• Subtle scale on hover (1.02-1.05)
• Y-axis lift effect
• Shadow glow expansion
• Staggered animations for lists
• Exit animations (not just enter)

Rule 5: Bespoke Colors

Default Tailwind colors look AI-generated. Create custom palettes.

// BEFORE: Default palette
<div className="bg-blue-500 text-white">

// AFTER: Bespoke palette
<div className="
  bg-[#0D0D0D]
  text-[#E8E4DD]
  bg-gradient-to-br
  from-[#1a1a2e] via-[#16213e] to-[#0f3460]
">

Key Techniques:

• Custom hex colors (not Tailwind defaults)
• Off-whites instead of pure white (#E8E4DD, #FAF9F6)
• Rich blacks instead of pure black (#0D0D0D, #1a1a2e)
• Color gradients across multiple stops
• Consistent palette derived from style guide

Visual Metaphor Library

When implementing, select an appropriate visual metaphor to guide decisions.

| Metaphor | Use Case | Key Characteristics | |----------|----------|---------------------| | Cyberpunk Glass | Dashboards, tech | Neon accents + glassmorphism + dark backgrounds | | Swiss Minimalist | Professional, B2B | Strict grid + high contrast + precise spacing | | Neo-Brutalism | Creative, bold | Thick borders + clashing colors + raw shapes | | Organic Luxury | Premium, fashion | Warm neutrals + serif typography + slow motion | | Editorial Magazine | Marketing, content | Large display type + asymmetric images + whitespace |

Applying a Metaphor:

1. Choose based on brand/context
2. Apply consistent characteristics across all changes
3. Document choice in implementation log
4. Verify consistency in visual check

Required Dependencies

Ensure these are installed before implementing micro-interactions:

npm install framer-motion lucide-react
# or
bun add framer-motion lucide-react

Dependency Usage:

• framer-motion: All animation and gesture handling
• lucide-react: Icon library (consistent, customizable)

Implementation Log Format

When completing implementation, create a log documenting all changes.

## Implementation Log

**Component**: {component_path}
**Session**: {session_id}
**Date**: {timestamp}

### Changes Applied

1. **{Issue from Review}**
   - Before: {description}
   - After: {description}
   - Code: {file:line}

2. **{Issue from Review}**
   - Before: {description}
   - After: {description}
   - Code: {file:line}

### Visual Metaphor

{metaphor_name}: {brief explanation of why chosen and how applied}

### Anti-AI Rules Applied

- [x] Rule 1: Break Symmetry - {how applied}
- [x] Rule 2: Add Texture - {how applied}
- [x] Rule 3: Dramatic Typography - {how applied}
- [ ] Rule 4: Micro-Interactions - {not applicable or how applied}
- [x] Rule 5: Bespoke Colors - {how applied}

### Dependencies Added

{list if any, or "None"}

### Verification Status

- [ ] Visual verified with Gemini
- [ ] Manual testing recommended
- [ ] Responsive breakpoints checked
- [ ] Accessibility preserved

Best Practices

DO

• Read the full review document before starting
• Apply changes systematically (one rule at a time)
• Preserve existing accessibility features
• Test responsive behavior after changes
• Document all changes in implementation log
• Use Gemini verification when available

DON'T

• Apply all Anti-AI rules blindly (assess what's needed)
• Break existing functionality for aesthetics
• Ignore accessibility for visual appeal
• Skip the implementation log
• Forget to install required dependencies
• Mix multiple visual metaphors inconsistently