skill-visual-feedback

> Host: Codex CLI — This skill was designed for Claude Code and adapted for Codex.

> Cross-reference commands use installed skill names in Codex rather than /octo:* slash commands.

> Use the active Codex shell and subagent tools. Do not claim a provider, model, or host subagent is available until the current session exposes it.

> For host tool equivalents, see skills/blocks/codex-host-adapter.md.

Visual Feedback Processing

Overview

Systematic approach to processing image-based UI/UX feedback, identifying visual issues, and implementing fixes.

Core principle: Analyze image → Identify issues → Locate code → Fix systematically → Verify visually.

When to Use

Use this skill when user provides:

• Screenshots with UI/UX problems
• "[Image]" prefix with description of visual issues
• Complaints about "messy UI" or "hot mess UX"
• Button styling or layout issues with visual examples
• "This should look like X but shows as Y" with images

Do NOT use for:

• Pure code issues without visual context
• Feature requests without UI mockups
• Performance or functional bugs
• Backend issues

The Process

Phase 1: Visual Analysis

When user provides image feedback:

Step 1: Acknowledge and Examine

I can see the screenshot showing [describe what you observe].

Let me analyze the visual issues:

**Observed Problems:**
1. [Issue 1: e.g., Button styles inconsistent]
2. [Issue 2: e.g., Layout misaligned]
3. [Issue 3: e.g., Colors don't match design system]

**Expected Behavior (from description):**
- [What user said it should be]

**Actual Behavior (from image):**
- [What the image shows]

Step 2: Categorize Issues

| Issue Type | Examples |

|------------|----------|

| Styling | Colors, fonts, spacing, borders |

| Layout | Alignment, positioning, responsive behavior |

| Component | Wrong component used, missing component |

| State | Hover states, active states, disabled states |

| Consistency | Inconsistent patterns across UI |

**Issue Categories:**
- Styling: [list specific styling issues]
- Layout: [list layout issues]
- Component: [list component issues]
- State: [list state-related issues]
- Consistency: [list inconsistency issues]

Phase 2: Code Investigation

Step 1: Locate Relevant Components

# Search for component files related to the issue
# Example: For settings page issues

Use Glob to find component files:

**/*settings*.{tsx,jsx,ts,js,vue,svelte}
**/*button*.{tsx,jsx,ts,js,vue,svelte}

Use Grep to find specific elements:

# Search for className patterns
pattern: "className.*button|btn-"

# Search for style definitions
pattern: "style={{|styled\.|makeStyles"

Step 2: Identify Styling System

**Styling Approach Detected:**
- [ ] CSS Modules
- [ ] Styled Components
- [ ] Tailwind CSS
- [ ] Emotion/styled
- [ ] Plain CSS
- [ ] CSS-in-JS (other)

**Design System:**
- [ ] Custom design system
- [ ] Material-UI
- [ ] Ant Design
- [ ] Chakra UI
- [ ] Other: [name]

Step 3: Read Affected Files

Read the component files and associated styles to understand current implementation.

Phase 3: Root Cause Analysis

Step 1: Identify Why Issue Exists

Common root causes:

| Root Cause | Indicators |

|------------|------------|

| Inconsistent styling | Multiple ways to style same element |

| Missing design tokens | Hard-coded colors/spacing |

| Wrong component variant | Using primary when should use secondary |

| State not handled | Missing hover/active/disabled styles |

| Responsive issues | Fixed widths, missing breakpoints |

| Override conflicts | Specificity wars, !important overuse |

| Deprecated patterns | Old styling approach still in use |

**Root Cause Analysis:**

Issue: [specific visual problem]
Root Cause: [why it's happening]
Evidence: [code snippet or pattern showing the cause]

Impact:
- Affects: [which pages/components]
- Frequency: [how often users see this]
- Scope: [single instance or systemic]

Step 2: Scope the Fix

**Fix Scope:**

Option 1: **Targeted Fix** (fix just this instance)
- Files to modify: [list]
- Risk: Low
- Coverage: Fixes reported issue only

Option 2: **Systematic Fix** (fix pattern everywhere)
- Files to modify: [list]
- Risk: Medium
- Coverage: Fixes all instances of this pattern

Option 3: **Design System Fix** (update base component)
- Files to modify: [design system files]
- Risk: Higher (affects many components)
- Coverage: Fixes root cause system-wide

**Recommendation:** [which option and why]

Use AskUserQuestion to get user preference on scope.

Phase 4: Implementation

Step 1: Create Fix Plan

For each identified issue:

**Fix Plan:**

Issue: [description]
File: [file path]
Change: [what to change]
Before: [code snippet or description]
After: [code snippet or description]

Step 2: Implement Fixes

Apply fixes one at a time, using Edit tool:

Fixing [Issue 1]...
- File: [path]
- Change: [description]
✓ Fixed

Fixing [Issue 2]...
- File: [path]
- Change: [description]
✓ Fixed

Step 3: Ensure Consistency

If "everywhere" or "all instances" is mentioned:

# Search for all instances of the pattern
# Example: Find all primary buttons

Use Grep to find all instances, then fix each one:

**Pattern Search:** "button.*primary"

Found in:
1. src/components/Header.tsx:45
2. src/pages/Settings.tsx:123
3. src/pages/Dashboard.tsx:67

Fixing all instances...

Fix each file systematically.

Phase 5: Verification

Step 1: Visual Verification Checklist

**Verification Checklist:**

Visual Issues:
- [ ] Button styles consistent
- [ ] Layout aligned properly
- [ ] Colors match design system
- [ ] Spacing is uniform
- [ ] Typography consistent

Responsive:
- [ ] Works on mobile
- [ ] Works on tablet
- [ ] Works on desktop

States:
- [ ] Default state correct
- [ ] Hover state correct
- [ ] Active state correct
- [ ] Disabled state correct
- [ ] Focus state accessible

**How to verify:**
1. Run dev server: `npm run dev`
2. Navigate to [affected page]
3. Check all items above
4. Compare with original screenshot

Step 2: Request User Confirmation

✅ **Fixes Applied**

Changes made:
1. [Change 1]
2. [Change 2]
3. [Change 3]

**Please verify:**
- Open [URL or page]
- Check that [specific issue] is now resolved
- Verify no new issues introduced

Let me know if the visual issues are resolved or if further adjustments are needed.

Common Patterns

Pattern 1: Button Style Consistency

User: "[Image] these button styles need to be fixed everywhere"

Process:
1. Analyze image - identify button style issues
2. Search for all button components
3. Identify design system button component
4. Update base button component OR
5. Update all instances to use correct variant
6. Verify consistency across app

Pattern 2: Layout Misalignment

User: "[Image] When logo position is set to Top right, it shows as Middle right"

Process:
1. Analyze image - see position mismatch
2. Find logo positioning code
3. Identify why "Top right" maps to "Middle right"
4. Fix the mapping or positioning logic
5. Test all position options
6. Verify with user

Pattern 3: Settings UI Issues

User: "[Image] The /settings should be dropdowns not text inputs"

Process:
1. Analyze image - see text inputs instead of dropdowns
2. Navigate to settings component code
3. Identify field definitions
4. Replace input components with select/dropdown
5. Ensure options are populated correctly
6. Verify all settings fields

Pattern 4: General "Hot Mess" Feedback

User: "why is the Display Ad Creator UX still a hot mess?"

Process:
1. Ask for specific issues or screenshot
2. If provided, analyze systematically
3. Create prioritized list of issues
4. Fix highest-impact issues first
5. Verify improvements with user

Integration with Other Skills

With skill-debug

Visual issue that doesn't make sense?
→ Use skill-debug to investigate why visual state is incorrect

With skill-audit

User says "fix these everywhere"?
→ Use skill-audit to find all instances
→ Use skill-visual-feedback to fix each systematically

With flow-tangle

Visual feedback requires new component?
→ Use flow-tangle to implement the component
→ Use skill-visual-feedback to verify it matches design

Best Practices

1. Always Acknowledge the Visual Evidence

Good:

I can see in the screenshot that the button has inconsistent padding and the wrong color scheme compared to other primary buttons in the interface.

Poor:

I'll fix the button.

2. Be Specific About Changes

Good:

Changing:
- Button background: #3498db → #2563eb (primary-600)
- Padding: 8px 12px → 12px 16px
- Border radius: 4px → 6px

Poor:

Updating button styles.

3. Consider Mobile/Responsive

Always check if the fix works across breakpoints:

**Responsive Verification:**
- Mobile (< 768px): [status]
- Tablet (768px - 1024px): [status]
- Desktop (> 1024px): [status]

Red Flags - Don't Do This

| Action | Why It's Wrong |

|--------|----------------|

| Fix without analyzing the image | Might fix wrong thing |

| Change only one instance when user says "everywhere" | Incomplete fix |

| Use !important to force styles | Creates specificity problems |

| Hard-code colors instead of using design tokens | Inconsistent with system |

| Skip verification | User has to report same issue again |

| Make assumptions without asking | Might not match user's vision |

Quick Reference

| User Feedback Pattern | Action Required |

|----------------------|-----------------|

| "[Image] X should be Y" | Analyze image → Find code → Fix → Verify |

| "Button styles everywhere" | Find all instances → Fix systematically |

| "UI is a mess" | Request specifics → Prioritize → Fix incrementally |

| "When X, shows Y instead of Z" | Debug state/logic → Fix mapping → Test all cases |

The Bottom Line

Visual feedback → Image analysis + Systematic fix + Visual verification
Otherwise → Guessing at fixes + Incomplete coverage

See the issue. Understand the root cause. Fix it everywhere. Verify visually.