stack/packages/mosaic/framework/guides/FRONTEND.md

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

// 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