# Design Guidelines

**Project:** [Project Name]
**Last Updated:** YYYY-MM-DD
**Version:** 1.0

---

## Design System Overview

[Design system description and philosophy]

---

## Typography

### Font Guidelines

- **Primary Font:** [Font name] (Google Fonts)
- **Fallback Fonts:** [Font options]
- **Sizes:**
  - Headings: [Size guidelines]
  - Body: [Size guidelines]
  - Small: [Size guidelines]
- **Weights:** [Weight guidelines]
- **Line Height:** [Line height guidelines]

### Usage Rules

- **IMPORTANT:** Predict font names from screenshots, don't default to Inter/Roboto
- Use distinctive fonts that match brand identity
- Ensure readability across all devices

---

## Color Palette

### Primary Colors

- **Primary:** [Hex code] - [Usage description]
- **Secondary:** [Hex code] - [Usage description]
- **Accent:** [Hex code] - [Usage description]

### Neutral Colors

- **Background:** [Hex codes]
- **Text:** [Hex codes]
- **Borders:** [Hex codes]

### Usage Rules

- **IMPORTANT:** Avoid purple gradients on white backgrounds
- Use cohesive color palettes
- Ensure WCAG 2.1 AA contrast minimum

---

## Layout & Spacing

### Grid System

- **Framework:** [Bootstrap 5 / Custom CSS Grid]
- **Columns:** 12-column responsive grid
- **Breakpoints:** [Breakpoint values]

### Spacing Scale

- **Base Unit:** 4px
- **Scale:** 4, 8, 12, 16, 20, 24, 32, 48, 64px
- **Usage:** Consistent spacing throughout components

---

## Components

### Buttons

- **Primary Style:** [Description]
- **Secondary Style:** [Description]
- **States:** Default, Hover, Active, Disabled, Loading
- **Sizes:** Small, Medium, Large

### Forms

- **Layout:** Single column stacking on mobile
- **Validation:** Real-time and on-submit
- **Required Fields:** Marked with asterisk (\*)

### Modals

- **Max Width:** 500px
- **Responsive:** Full-width on mobile
- **Backdrop:** Semi-transparent overlay

---

## Motion & Animation

### Animation Principles

- **Purposeful Motion:** Staggered reveals for page entry
- **Duration:** 200-300ms for UI transitions
- **Easing:** Ease-out for natural movement
- **Avoid:** Scattered micro-interactions

### Guidelines

- Use staggered animations, not random effects
- Layer gradients for background depth
- Respect `prefers-reduced-motion` setting

---

## Accessibility

### Requirements

- **Standard:** WCAG 2.1 AA minimum
- **Contrast:** 4.5:1 ratio for normal text
- **Keyboard:** Full navigation support
- **Screen Readers:** Proper semantic HTML structure

### Implementation

- **ARIA Labels:** Descriptive labels for interactive elements
- **Focus States:** Visible focus indicators
- **Alt Text:** Meaningful descriptions for images

---

## Asset Guidelines

### Images

- **Format:** WebP for photos, PNG for graphics
- **Compression:** Optimized for web delivery
- **Responsive:** Multiple sizes for different screen densities

### Icons

- **System:** [Icon system name]
- **Sizes:** 16px, 24px, 32px, 48px
- **Format:** SVG with fallback PNG

---

## Code Standards

### CSS Architecture

- **Methodology:** BEM (Block, Element, Modifier)
- **Variables:** CSS custom properties for theming
- **Responsive:** Mobile-first approach

### JavaScript

- **Framework:** [Framework name]
- **Pattern:** Component-based architecture
- **Performance:** Lazy loading for heavy components

---

## Brand Guidelines

### Logo Usage

- **Primary Logo:** [Usage guidelines]
- **Clear Space:** Minimum spacing requirements
- **Variations:** Color variations for different backgrounds

### Voice & Tone

- **Personality:** [Brand personality description]
- **Language:** [Language style guidelines]
- **Do:** [Action words]
- **Don't:** [Words to avoid]

---

## Testing & QA

### Cross-Browser

- **Target:** [Browser list]
- **Testing:** Manual testing on each browser
- **Fallbacks:** Graceful degradation

### Device Testing

- **Mobile:** iOS Safari, Chrome Mobile
- **Tablet:** iPad, Android tablets
- **Desktop:** Chrome, Firefox, Safari, Edge

---

## File Organization

### Template Structure

```
assets/
├── images/
│   ├── logos/
│   ├── icons/
│   └── photos/
├── css/
│   ├── base.css
│   ├── components.css
│   └── utilities.css
└── js/
    ├── components/
    └── utils/
```

### Naming Conventions

- **Images:** kebab-case with descriptive names
- **CSS:** BEM methodology with clear purpose
- **JavaScript:** PascalCase for components, camelCase for utilities

---

## Common Patterns

### Header Pattern

[Header component description and usage]

### Footer Pattern

[Footer component description and usage]

### Card Pattern

[Card component description and usage]

### Form Pattern

[Form component description and usage]

---

## Tools & Resources

### Design Tools

- **UI Design:** [Tool names]
- **Prototyping:** [Tool names]
- **Asset Generation:** AI-multimodal skill

### Development Tools

- **Code Editor:** [Editor preferences]
- **Browser DevTools:** Chrome DevTools
- **Version Control:** Git with feature branches

---

## Maintenance

### Update Process

1. Review new components quarterly
2. Update guidelines based on user feedback
3. Archive deprecated patterns
4. Update version number for breaking changes

### Documentation

- Keep examples up-to-date
- Document any exceptions to guidelines
- Maintain changelog for major updates

---

**Last Review:** YYYY-MM-DD  
**Next Review:** YYYY-MM-DD

---

_Design-guidelines.md - Living document for project design standards_
