/skill-visual-feedback

name: skill-visual-feedback
description: "Process screenshot-based UI/UX feedback to fix visual issues — use when users share screenshots of bugs"
disable-model-invocation: true

> **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
- [ ] C