Jason Woltje
a8e580e1a3
Co-authored-by: Jason Woltje <jason@diversecanvas.com> Co-committed-by: Jason Woltje <jason@diversecanvas.com>
81 lines
2.6 KiB
Markdown
81 lines
2.6 KiB
Markdown
# Frontend Development Guide
|
|
|
|
## Before Starting
|
|
1. Check assigned issue in git repo: `~/.config/mosaic/tools/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`
|