# Frontend Development Guide

## Before Starting
1. Check assigned issue in git repo: `~/.config/mosaic/rails/git/issue-list.sh -a @me`
2. Create scratchpad: `docs/scratchpads/{issue-number}-{short-name}.md`
3. Review existing components and patterns in the codebase

## Development Standards

### Framework Conventions
- Follow project's existing framework patterns (React, Vue, Svelte, etc.)
- Use existing component library/design system if present
- Maintain consistent file structure with existing code

### Styling
- Use project's established styling approach (CSS modules, Tailwind, styled-components, etc.)
- Follow existing naming conventions for CSS classes
- Ensure responsive design unless explicitly single-platform

### State Management
- Use project's existing state management solution
- Keep component state local when possible
- Document any new global state additions

### Accessibility
- Include proper ARIA labels
- Ensure keyboard navigation works
- Test with screen reader considerations
- Maintain color contrast ratios (WCAG 2.1 AA minimum)

## Testing Requirements (TDD)
1. Write tests BEFORE implementation
2. Minimum 85% coverage
3. Test categories:
   - Unit tests for utility functions
   - Component tests for UI behavior
   - Integration tests for user flows

### Test Patterns
```javascript
// Component test example structure
describe('ComponentName', () => {
  it('renders without crashing', () => {});
  it('handles user interaction correctly', () => {});
  it('displays error states appropriately', () => {});
  it('is accessible', () => {});
});
```

## Code Style
- Follow Google JavaScript/TypeScript Style Guide
- **TypeScript: Follow `~/.config/mosaic/guides/TYPESCRIPT.md` — MANDATORY**
- Use ESLint/Prettier configuration from project
- Prefer functional components over class components (React)
- TypeScript strict mode is REQUIRED, not optional

### TypeScript Quick Rules (see TYPESCRIPT.md for full guide)
- **NO `any`** — define explicit types always
- **NO lazy `unknown`** — only for error catches and external data with validation
- **Explicit return types** on all exported functions
- **Explicit parameter types** always
- **Interface for props** — never inline object types
- **Event handlers** — use proper React event types

## Commit Format
```
feat(#123): Add user profile component

- Implement avatar display
- Add edit mode toggle
- Include form validation

Refs #123
```

## Before Completing
1. Run full test suite
2. Verify build succeeds
3. Update scratchpad with completion notes
4. Reference issue in commit: `Fixes #N` or `Refs #N`