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)

save_aesthetic - Analyze mockup HTML and generate structured prose aesthetic.md
apply_aesthetic - Interpret aesthetic.md to generate new mockup with appropriate layout
list_aesthetics - Show all saved aesthetics with prose summaries
delete_aesthetic - Remove aesthetic from library
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

text

.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

<operation name="save_aesthetic"> <purpose>Capture visual design from mockup as structured prose aesthetic.md</purpose>

<critical_sequence> <step id="-1" required="true"> Initialize .claude/aesthetics/ directory if missing (mkdir -p) </step> <step id="0" required="true" depends_on="-1"> Validate mockup file exists and is readable </step> <step id="1" required="true" depends_on="0"> Read mockup HTML file into memory (Read tool) </step> <step id="2" required="true" depends_on="1"> Extract visual patterns using pattern-extraction.md strategies </step> <step id="3" required="true" depends_on="2"> Generate prose descriptions using prose-generation.md guidelines </step> <step id="4" required="true" depends_on="3"> 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) </step> <step id="5" required="true" depends_on="4"> Copy preview.html to aesthetic directory </step> <step id="6" required="true" depends_on="5"> Generate metadata.json with inferred tags </step> <step id="7" required="true" depends_on="6"> Update manifest.json using Read → modify → Write pattern (if missing: initialize from assets/manifest-init.json) </step> <step id="7.5" required="true" depends_on="7"> Commit aesthetic to git using conventional format </step> <step id="8" required="true" depends_on="7.5"> Present confirmation + decision menu </step> </critical_sequence>

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

Operation 1: save_aesthetic

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

<operation name="apply_aesthetic"> <purpose>Generate new mockup by interpreting aesthetic prose and adapting to target plugin</purpose>

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

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

Operation 2: apply_aesthetic

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

<operation name="list_aesthetics"> <critical_sequence> <step id="1" required="true">Read manifest.json</step> <step id="2" required="true">Format as markdown table</step> <step id="3" required="true">Show preview paths</step> <step id="4" required="true">Present decision menu</step> </critical_sequence>

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

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

ui-template-library

NPX Install

Tags

SKILL.md Content