ui-template-library

name	ui-template-library
description	Manage aesthetic templates - save visual systems from completed mockups as interpretable prose, apply to new plugins with adaptive layouts
allowed-tools	["Read","Write","Bash"]
preconditions	[".claude/aesthetics/ directory exists (created by system-setup skill or auto-created on first save_aesthetic)"]

ui-template-library Skill

Purpose: Capture and apply aesthetic "vibes" across plugins using structured prose descriptions rather than rigid specifications.

---

Operations

You MUST determine which operation the user is requesting, then execute ONLY that operation.

Operation Routing (match user request to keywords):

• save/capture/extract → save_aesthetic (Operation 1)
• apply/use/generate → apply_aesthetic (Operation 2)
• list/show/browse → list_aesthetics (Operation 3)
• delete/remove → delete_aesthetic (Operation 4)
• update/modify/refine → update_aesthetic (Operation 5)

1. save_aesthetic - Analyze mockup HTML and generate structured prose aesthetic.md
2. apply_aesthetic - Interpret aesthetic.md to generate new mockup with appropriate layout
3. list_aesthetics - Show all saved aesthetics with prose summaries
4. delete_aesthetic - Remove aesthetic from library
5. update_aesthetic - Refine aesthetic.md from improved mockup

---

CRITICAL: Checkpoint Verification Protocol

Before presenting decision menu in ANY operation:

ALL steps must complete successfully. If ANY step fails: HALT, report specific error, DO NOT proceed to decision menu.

Verification checklist (run before showing menu):

• All required files created successfully
• File contents are valid (aesthetic.md not empty, metadata.json valid JSON)
• manifest.json updated successfully
• Git commit completed (if applicable)
• No error states from previous steps

Error handling:

• Steps 1-6 fail → Report error, do not create partial aesthetic directory
• Step 7 fails (manifest) → Aesthetic files exist but not registered, offer retry
• Step 7.5 fails (git) → Non-fatal, warn "Aesthetic saved but not committed"

Note: Always use inline numbered menus (NOT AskUserQuestion tool) to maintain consistency with system-wide Checkpoint Protocol.

---

Directory Structure

.claude/aesthetics/
├── manifest.json                    # Registry of all aesthetics
└── [aesthetic-id]/
    ├── aesthetic.md                 # Structured prose description (THE SOURCE OF TRUTH)
    ├── preview.html                 # Visual reference (original mockup)
    └── metadata.json                # Name, description, source plugin, tags

Key change from previous system:

• aesthetic.yaml → aesthetic.md: YAML specs replaced with structured prose descriptions
• Format is consistent and parseable, but content is interpretable concepts, not rigid values

---

Capture visual design from mockup as structured prose aesthetic.md

<critical_sequence> Initialize .claude/aesthetics/ directory if missing (mkdir -p) Validate mockup file exists and is readable Read mockup HTML file into memory (Read tool) Extract visual patterns using pattern-extraction.md strategies Generate prose descriptions using prose-generation.md guidelines Write aesthetic.md following aesthetic-template.md structure exactly: same section headers in same order, fill all sections with prose (no placeholders) (load template from assets/aesthetic-template.md, if missing: report critical error) Copy preview.html to aesthetic directory Generate metadata.json with inferred tags Update manifest.json using Read → modify → Write pattern (if missing: initialize from assets/manifest-init.json) Commit aesthetic to git using conventional format Present confirmation + decision menu </critical_sequence>

<state_requirement> See "CRITICAL: Checkpoint Verification Protocol" section for complete verification requirements. </state_requirement>

Operation 1: save_aesthetic

See: references/save-operation.md for complete 8-step workflow.

---

Generate new mockup by interpreting aesthetic prose and adapting to target plugin

<critical_sequence> Load aesthetic.md and metadata.json (Read tool) Read target plugin parameter-spec.md or creative-brief.md Interpret aesthetic prose using aesthetic-interpretation.md strategies Choose layout based on parameter count (layout-generation.md) Generate HTML/CSS applying aesthetic to chosen layout Save generated mockup to target plugin mockups directory Update aesthetic metadata.json usedInPlugins array Present decision menu as inline numbered list, NOT AskUserQuestion tool (rationale: consistent with system-wide Checkpoint Protocol - see CLAUDE.md) </critical_sequence>

<decision_gate wait_required="true"> Present decision menu with preview/continue options MUST wait for user response </decision_gate>

Operation 2: apply_aesthetic

See: references/apply-operation.md for complete 8-step workflow.

---

Read manifest.json Format as markdown table Show preview paths Present decision menu

<decision_gate wait_required="true"> Wait for user to select action from menu </decision_gate>

Operation 3: list_aesthetics

Display all saved aesthetics in table format with preview paths. See: references/list-operation.md for complete 4-step workflow.

---

Operation 4: delete_aesthetic

Remove aesthetic from library with confirmation. See: references/delete-operation.md for complete 4-step workflow.

---

Operation 5: update_aesthetic

Refine aesthetic.md from improved mockup while preserving user edits. See: references/update-operation.md for complete 7-step workflow.

---

API Contract

This skill provides operations for managing aesthetic templates. Called by ui-mockup skill.

save_aesthetic(mockup_path, plugin_name, aesthetic_name?):

• Input: Absolute path to mockup HTML, plugin name, optional aesthetic name
• Output: aesthetic_id (string), aesthetic_path (absolute path)
• Process: Analyzes mockup, generates aesthetic.md prose, saves to .claude/aesthetics/

apply_aesthetic(aesthetic_id, plugin_name, parameter_spec_path):

• Input: Aesthetic ID, target plugin name, path to parameter-spec.md
• Output: mockup_path (absolute path to generated mockup)
• Process: Loads aesthetic prose, interprets to CSS, generates mockup with appropriate layout

Invocation: Inline invocation from ui-mockup (both skills are lightweight and stateless).

---

Success Criteria

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

Technical details about parsing, quality control, and constraints. See: references/implementation-notes.md for complete technical documentation.

---

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