MadAppGang 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
- Read
.claude/design-style.mdwith Read tool - Split by
##headers - Parse tables using Markdown table regex
- 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:
- File exists at
.claude/design-style.md - Required sections present
- Referenced images exist in
.claude/design-references/ - Colors are valid hex codes
- Spacing values are numbers
Integration with ui Agent
Style-Aware Review Flow
When the ui agent performs a review:
- Load Style: Read
.claude/design-style.md - Load References: List
.claude/design-references/ - Match Components: Find relevant reference images for review target
- Comparative Analysis: Pass reference image + target to Gemini
- 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
- Consistent viewport: Use same browser width (e.g., 1440px)
- Clean state: No modals, tooltips unless intentional
- Both modes: Capture light and dark variants
- 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:
- Capture new screenshot
- Replace old image (same name) or add new
- Update Reference Images table
- Add entry to Style History