UI Style Format Specification

Overview

The UI Style system provides a standardized way to define project design preferences that the ui agent uses during design reviews. It supports both text-based style definitions and visual reference images.

File Structure

{project}/
  .claude/
    design-style.md              # Main style configuration
    design-references/           # Visual reference images
      {image}.png                # PNG or JPG screenshots
      MANIFEST.md                # Optional metadata

design-style.md Schema

Required Sections

Optional Sections

Reference Images Integration

Storage Location

All reference images MUST be stored in .claude/design-references/.

Supported Formats

Image Table Format

In the style file, reference images are listed in a table:

## Reference Images

| Image | Description | Captured | Mode |
|-------|-------------|----------|------|
| hero-section.png | Homepage hero | 2026-01-08 | light |

Usage Guidelines Section

Each image should have usage notes:

### Usage Guidelines

- **hero-section.png**: Reference for hero layout, gradient, CTA placement

Parsing the Style File

Section Extraction

1. Read .claude/design-style.md with Read tool
2. Split by ## headers
3. Parse tables using Markdown table regex
4. Extract key-value pairs from tables

Reference Image Resolution

Image Name -> .claude/design-references/{image_name}

Example:

hero-section.png -> .claude/design-references/hero-section.png

Validation Checklist

Before using a style file, validate:

1. File exists at .claude/design-style.md
2. Required sections present
3. Referenced images exist in .claude/design-references/
4. Colors are valid hex codes
5. Spacing values are numbers

Integration with ui Agent

Style-Aware Review Flow

When the ui agent performs a review:

1. Load Style: Read .claude/design-style.md
2. Load References: List .claude/design-references/
3. Match Components: Find relevant reference images for review target
4. Comparative Analysis: Pass reference image + target to Gemini
5. Validate Tokens: Check colors, typography, spacing against style

Gemini Prompt with References

Compare this implementation screenshot against the project design reference.

**Reference Image**: .claude/design-references/hero-section.png
**Implementation**: screenshots/current-hero.png

**Style Tokens** (from .claude/design-style.md):
- Primary Color: #2563EB
- Font: Inter 16px
- Spacing: 4px base

**Validate**:
1. Layout matches reference
2. Colors match defined palette
3. Typography follows scale
4. Spacing uses defined tokens

Version Compatibility

Version 2.x is backward compatible - the ui agent handles missing ## Reference Images section gracefully.

Best Practices

Capturing Reference Images

1. Consistent viewport: Use same browser width (e.g., 1440px)
2. Clean state: No modals, tooltips unless intentional
3. Both modes: Capture light and dark variants
4. Component isolation: Crop to relevant area

Writing Usage Guidelines

Be specific about what each image demonstrates:

Good: "Reference for button padding (12px), border-radius (8px), and hover state" Bad: "Button reference"

Updating Styles

When UI changes:

1. Capture new screenshot
2. Replace old image (same name) or add new
3. Update Reference Images table
4. Add entry to Style History