ui-style-format

# 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: ```markdown ## Reference Images | Image | Description | Captured | Mode | |-------|-------------|----------|------| | hero-section.png | Homepage hero | 2026-01-08 | light | ``` ### Usage Guidelines Section Each image should have usage notes: ```markdown ### 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