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

Section	Purpose
Header	Version, dates, base reference
Reference Images	Links to visual references (v2.0+)
Brand Colors	Color palette with light/dark modes
Typography	Fonts and type scale
Spacing	Base unit and scale
Component Patterns	Button, input, card styles
Design Rules	DO and DON'T guidelines

Optional Sections

Section	Purpose
Reference URLs	External style guides
Style History	Change log
MANIFEST.md	Detailed image descriptions

Reference Images Integration

Storage Location

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

Supported Formats

Format	Extension	Recommended Use
PNG	.png	Screenshots, UI components
JPEG	.jpg, .jpeg	Photos, complex imagery
WebP	.webp	Modern alternative to PNG/JPEG

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	Features
1.x	Text-only style (legacy)
2.x	Reference images + text style

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