Operation 3: List Aesthetics

Input: None (or optional filter by tag) Output: Table of all aesthetics with prose summaries

Step 1: Read Manifest

MANIFEST=".claude/aesthetics/manifest.json"
test -f "$MANIFEST" || { echo "No aesthetics saved"; exit 0; }

Use Read tool to load manifest.json.

Step 2: Display Table

Format as markdown table:

# Aesthetic Library

| ID | Name | Vibe | Source Plugin | Created | Used In |
|----|------|------|---------------|---------|---------|
| vintage-hardware-001 | Vintage Hardware | Warm retro analog | TapeAge | 2025-11-10 | TapeAge, CompCo |
| modern-minimal-002 | Modern Minimal | Clean flat blue/gray | EQPro | 2025-11-11 | EQPro |

For each aesthetic:

• ID
• Name
• Vibe (extract from aesthetic.md "Visual Identity" or metadata description)
• Source plugin
• Created date
• Used in plugins (comma-separated)

Step 3: Show Preview Paths

Preview files:
- vintage-hardware-001: .claude/aesthetics/vintage-hardware-001/preview.html
- modern-minimal-002: .claude/aesthetics/modern-minimal-002/preview.html

Open in browser:
  open .claude/aesthetics/vintage-hardware-001/preview.html

Step 4: Decision Menu

What would you like to do?
1. View aesthetic details - Show full aesthetic.md prose
2. Apply aesthetic to plugin - Choose aesthetic and target
3. Delete aesthetic - Remove from library
4. Exit

Operation 4: Delete Aesthetic

Input: Aesthetic ID Output: Aesthetic removed from library

Step 1: Confirm Deletion

Show usage information:

⚠️  Delete aesthetic "Vintage Hardware" (vintage-hardware-001)?

Currently used in 2 plugins:
- TapeAge
- CompCo

Deleting will NOT affect existing plugins (they have copies of the UI).
This only removes the template from the library.

Are you sure? (yes/no)

Step 2: Remove Files

if confirmed; then
    rm -rf ".claude/aesthetics/$AESTHETIC_ID"
fi

Removes:

• aesthetic.md
• preview.html
• metadata.json
• Directory itself

Step 3: Update Manifest

Remove entry from manifest.json:

# Read manifest.json
# Filter out deleted aesthetic from "aesthetics" array
# Write updated manifest.json

Step 4: Confirmation

✅ Aesthetic "Vintage Hardware" deleted from library.

Plugins using this aesthetic are unaffected (they have independent copies).

Remaining aesthetics: 1

Operation 5: Update Aesthetic

Input:

• Aesthetic ID
• Path to improved mockup HTML

Output: Updated aesthetic.md with refined prose

Process:

1. Run same analysis as Save workflow (Step 2-3)
2. Generate new prose descriptions
3. Merge with existing aesthetic.md (preserve user edits where possible)
4. Update metadata.json (increment version, update modified date)
5. Optionally replace preview.html

Strategy for preserving user edits:

• Parse existing aesthetic.md section by section
• Regenerate each section from new mockup
• Compare old vs new prose
• If user has manually edited a section (detected by non-template language), prompt:

  Section "Knob Style" has manual edits. How to handle?
  1. Keep existing (preserve manual edits)
  2. Replace with regenerated (lose edits)
  3. Show diff and let me merge
  

Integration with ui-mockup Skill

Save operation successful when:

• ✅ aesthetic.md generated following exact template structure
• ✅ All sections filled with interpretable prose (no placeholders)
• ✅ Example color codes provided as concrete reference
• ✅ preview.html copied to aesthetic directory
• ✅ metadata.json created with tags and source info
• ✅ manifest.json updated with new aesthetic entry
• ✅ Format is idempotent (same mockup → same structure every time)

Apply operation successful when:

• ✅ aesthetic.md parsed and interpreted correctly
• ✅ Appropriate layout chosen for parameter count
• ✅ Generated mockup reflects aesthetic visual language
• ✅ Control styling matches prose descriptions
• ✅ Colors, typography, spacing consistent with aesthetic
• ✅ WebView constraints enforced (no viewport units, etc.)
• ✅ Result is recognizably the same aesthetic despite different layout

List operation successful when:

• ✅ All aesthetics shown in readable table
• ✅ Vibe summaries extracted from prose
• ✅ Preview paths provided for visual reference
• ✅ Decision menu presented for next action

Implementation Notes

Why This Approach Works

1. No browser APIs required:

• Pattern matching with grep/sed extracts colors, fonts, values
• String analysis detects control types and styles
• Prose generation transforms patterns into descriptions
• Only requires Read/Write/Bash tools

2. Aesthetics are conceptual:

• "Brass knobs with tick marks" is more transferable than "knob diameter: 70px, border: 2px solid #c8a882"
• Descriptions capture intent and feel, not rigid specifications
• Claude can interpret prose and make appropriate decisions for different contexts

3. Format is idempotent:

• Template structure is always the same (same sections, same order)
• Parsing is predictable and reliable
• Sections are clearly delimited with markdown headers
• Human-editable while remaining machine-parseable

4. Flexible adaptation:

• Apply workflow interprets prose to make context-appropriate decisions
• Same aesthetic works for 3-parameter or 12-parameter plugins
• Layout adapts while visual language remains consistent

Constraints Satisfied

• ✅ NO browser-based operations (getComputedStyle, DOM parsing)
• ✅ NO complex JavaScript execution requirements
• ✅ ONLY uses Read, Write, Bash tools
• ✅ Produces consistent, parseable aesthetic.md format
• ✅ Maintains compatibility with ui-mockup skill invocation patterns

Parsing Strategy

Extracting from aesthetic.md:

1. Section detection:

   # Extract "Knob Style" section
   sed -n '/^### Knob Style$/,/^### /p' aesthetic.md | head -n -1
   

2. Value extraction:

   # Extract color codes from "Example Color Codes" section
   sed -n '/^## Example Color Codes$/,/^## /p' aesthetic.md | \
       grep -oE '#[0-9a-fA-F]{6}'
   

3. Prose interpretation:

   • Read section text into variable
   • Use Claude's reasoning to interpret descriptions
   • Extract key phrases: "generous spacing" → gap: 32px
   • Map descriptive terms: "warm palette" → orange/brown hues

Quality Control

Before saving aesthetic:

• ✅ Verify all template sections are present
• ✅ Check for placeholder text not replaced
• ✅ Validate color codes are valid hex/rgb
• ✅ Ensure prose is descriptive (not just values)

Before applying aesthetic:

• ✅ Verify aesthetic.md exists and is readable
• ✅ Check required sections are present
• ✅ Validate parameter spec is available
• ✅ Ensure generated HTML follows WebView constraints

Reference Documentation

• Pattern extraction: references/pattern-extraction.md - String/regex strategies for extracting visual patterns from HTML
• Prose generation: references/prose-generation.md - Guidelines for transforming patterns into interpretable prose
• Aesthetic interpretation: references/aesthetic-interpretation.md - Strategies for parsing prose and generating CSS/HTML
• Layout generation: references/layout-generation.md - Layout decision trees and control placement strategies

Template Assets

• Aesthetic template: assets/aesthetic-template.md - Complete structured prose template (THE FORMAT SPEC)
• Metadata template: assets/metadata-template.json - Metadata JSON structure
• Manifest init: assets/manifest-init.json - Empty manifest structure for initialization