# UI Conventions — {{projectName}}

> **Scope:** Frontend UI development | **Loaded On-Demand**

---

## Design Principles

{{#if designPrinciples}}
{{#each designPrinciples}}
- {{this}}
{{/each}}
{{else}}
- **Clarity over cleverness** — UI should be self-explanatory
- **Progressive disclosure** — Show complexity only when needed
- **Responsive by default** — Mobile-first approach
- **Accessibility first** — WCAG 2.1 AA compliance minimum
{{/if}}

---

## Component Structure

### File Organization
{{#if componentStructure}}
{{componentStructure}}
{{else}}
```
src/
├── components/
│   ├── ui/              # Reusable UI primitives
│   ├── features/        # Feature-specific components
│   └── layouts/         # Layout components
├── hooks/               # Custom React hooks
├── lib/                 # Utility functions
└── styles/              # Global styles
```
{{/if}}

### Component Naming
{{#if componentNaming}}
{{componentNaming}}
{{else}}
- Use PascalCase: `UserProfile.tsx`, `DataTable.tsx`
- One component per file
- Co-locate related files:
  - `UserProfile.tsx`
  - `UserProfile.test.tsx`
  - `UserProfile.stories.tsx`
  - `user-profile.module.css`
{{/if}}

---

## Styling Conventions

{{#if styling}}
{{styling}}
{{else}}
### CSS Approach
- Use CSS Modules or Tailwind (configured in project)
- No inline styles (except dynamic values)
- Scoped styles only

### Tailwind Conventions (if applicable)
- Use utility classes for layout, spacing, colors
- Create `@apply` components for repeated patterns
- Don't override component props with arbitrary values

### Theme Variables
```css
:root {
  --color-primary: ...;
  --color-success: ...;
  --color-error: ...;
  --spacing-unit: ...;
  --radius-sm: ...;
  --radius-md: ...;
}
```
{{/if}}

---

## Form Patterns

{{#if formPatterns}}
{{formPatterns}}
{{else}}
### Form Validation
- Client-side validation before submission
- Show inline errors immediately
- Disable submit button during submission
- Clear errors on input change

### Error Display
- Red outline + error text below field
- Group errors at top for complex forms
- Highlight first error field on load

### Success Feedback
- Toast notification on success
- Redirect or clear form as appropriate
{{/if}}

---

## Loading States

{{#if loadingStates}}
{{loadingStates}}
{{else}}
### Skeleton Loading
- Use skeleton screens for lists, tables
- Maintain same layout as loaded state
- Smooth fade-in when content loads

### Button States
- Show spinner + "Loading..." text
- Disable button during action
- Maintain button width to prevent layout shift
{{/if}}

---

## Empty States

{{#if emptyStates}}
{{emptyStates}}
{{else}}
Every list/table must handle:
1. **Loading** — Skeleton or spinner
2. **Empty** — Friendly message + action button
3. **Error** — Error message + retry button
4. **No Results** — Message when filters return zero results

Example:
```
┌─────────────────────────────┐
│     No users found           │
│                             │
│  Try adjusting your filters  │
│  or create a new user        │
│                             │
│    [Create New User]         │
└─────────────────────────────┘
```
{{/if}}

---

## Responsive Breakpoints

{{#if breakpoints}}
{{breakpoints}}
{{else}}
- Mobile: < 640px
- Tablet: 640px — 1024px
- Desktop: > 1024px
- Large Desktop: > 1280px

Test on real devices or browser dev tools.
{{/if}}

---

## Accessibility

{{#if accessibility}}
{{accessibility}}
{{else}}
### Minimum Requirements
- Keyboard navigation for all interactive elements
- ARIA labels for icon-only buttons
- Focus indicators on all focusable elements
- Screen reader text for status messages
- Color contrast minimum 4.5:1

### Testing
- Test with keyboard only
- Test with screen reader (NVDA/VoiceOver)
- Use axe DevTools extension
{{/if}}

---

## Data Display

### Tables
{{#if tablePatterns}}
{{tablePatterns}}
{{else}}
- Sortable headers
- Pagination (20 rows default)
- Column filtering for complex tables
- Row actions menu (⋮)
- Responsive: card view on mobile

### Status Indicators
Use consistent colors:
- 🟢 Green — Active, Success, Online
- 🟡 Yellow — Pending, Warning, Away
- 🔴 Red — Error, Failed, Offline
- 🔵 Blue — Info, Neutral
- ⚪ Gray — Disabled, Inactive
{{/if}}

---

## Performance

{{#if performance}}
{{performance}}
{{else}}
### Code Splitting
- Route-based splitting (automatic)
- Lazy load heavy components
- Preload critical resources

### Rendering
- Use `React.memo` for expensive components
- Debounce search inputs (300ms)
- Virtualize long lists (> 100 items)
{{/if}}

---

## Icon Usage

{{#if icons}}
{{icons}}
{{else}}
- Use {{iconSet}} for icons
- Standard icon sizes: sm (16px), md (20px), lg (24px), xl (32px)
- Match icon size to adjacent text
- Add aria-label for icon-only buttons
{{/if}}

---

## Typography

{{#if typography}}
{{typography}}
{{else}}
### Font Hierarchy
- Heading 1: 32px (page titles)
- Heading 2: 24px (section titles)
- Heading 3: 18px (card titles)
- Body: 16px (default)
- Small: 14px (labels, metadata)
- XSmall: 12px (captions, timestamps)

### Font Weights
- Regular (400) — body text
- Medium (500) — labels, buttons
- Semibold (600) — headings, emphasized text
- Bold (700) — rarely used
{{/if}}

---

> **Token Budget:** ~1000 tokens max
> **Loaded On-Demand** — Only when working on UI code