Skip to content

Commit 5cc9ad4

Browse files
tyler-danetyler-dane
authored
Merge branch 'main' into feat/onboarding
2 parents 5ac651d + b9b5d0d commit 5cc9ad4

File tree

11 files changed

+824
-450
lines changed

11 files changed

+824
-450
lines changed

‎.cursorrules/README.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
description: Main overview of Compass development rules and project structure
3+
alwaysApply: true
4+
---
5+
6+
# Compass Calendar Development Rules
7+
8+
You are an expert full-stack developer working on Compass, a calendar application built with React, TypeScript, Node.js, and MongoDB.
9+
10+
## Project Overview
11+
12+
This is a monorepo using Yarn workspaces with the following packages:
13+
14+
- `@compass/web` - React/TypeScript frontend with Redux, styled-components, webpack
15+
- `@compass/backend` - Express.js REST API with MongoDB, Google Calendar sync, WebSocket support
16+
- `@compass/core` - Shared utilities, types, and business logic
17+
- `@compass/scripts` - CLI tools for building, database operations, user management
18+
19+
## Rules Organization
20+
21+
This directory contains focused rules for different aspects of development:
22+
23+
- `naming-conventions.md` - File and variable naming standards
24+
- `testing.md` - Testing requirements and best practices
25+
- `styling.md` - Frontend styling and component standards
26+
- `validation.md` - Data validation patterns with Zod
27+
- `development.md` - Development workflow and commands
28+
- `accessibility.md` - Accessibility standards and requirements
29+
- `git-conventions.md` - Branch naming and commit message standards
30+
31+
## Key Principles
32+
33+
1. Prefer minimal modifications over extensive refactoring
34+
2. Always run relevant tests before completing a task
35+
3. Use TypeScript strictly - avoid `any` types
36+
4. Follow existing patterns in the codebase
37+
5. Write self-documenting code with clear variable names
38+
6. Ensure proper error handling for async operations
39+
40+
## File Structure
41+
42+
```
43+
packages/
44+
├── backend/src/ # Express.js API, MongoDB, Google Calendar sync
45+
├── web/src/ # React frontend, Redux state, styled-components
46+
├── core/src/ # Shared utilities, types, business logic
47+
└── scripts/src/ # CLI tools for builds and operations
48+
```
49+
50+
Always reference these rules before making code changes. Write clean, maintainable, well-tested code following these established patterns.

‎.cursorrules/accessibility.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
---
2+
description: Accessibility standards - semantic HTML, keyboard navigation, ARIA labels, refer to skills/a11y-audit/SKILL.md for comprehensive checklist
3+
globs:
4+
- "packages/web/**/*.{ts,tsx}"
5+
---
6+
7+
# Accessibility Standards
8+
9+
This rule defines accessibility requirements for the Compass codebase, especially for `packages/web`.
10+
11+
## Overview
12+
13+
Follow accessibility best practices to ensure the application is usable by everyone, including users with disabilities.
14+
15+
## Key Principles
16+
17+
1. Use semantic HTML elements
18+
2. Provide keyboard navigation support
19+
3. Include proper ARIA labels and attributes
20+
4. Ensure sufficient color contrast
21+
5. Test with screen readers when possible
22+
23+
## Detailed Guidelines
24+
25+
Refer to the comprehensive accessibility audit checklist in:
26+
**`skills/a11y-audit/SKILL.md`**
27+
28+
This skill provides:
29+
30+
- Diff-first accessibility checklist
31+
- Semantic and structure requirements
32+
- Keyboard and focus management
33+
- ARIA correctness guidelines
34+
- Visual and motion considerations
35+
- Testing reliability patterns
36+
37+
## Core Requirements
38+
39+
### Semantic HTML
40+
41+
Use appropriate HTML elements for their intended purpose.
42+
43+
**DO:**
44+
45+
- ✅ Use `<button>` for clickable actions
46+
- ✅ Use `<a>` for navigation links
47+
- ✅ Use `<h1>` through `<h6>` for headings
48+
- ✅ Use `<nav>`, `<main>`, `<header>`, `<footer>` for landmarks
49+
50+
**DON'T:**
51+
52+
- ❌ Use `<div>` with click handlers instead of `<button>`
53+
- ❌ Use `<span>` for interactive elements
54+
- ❌ Skip heading levels
55+
56+
### Labels and Names
57+
58+
All interactive elements must have accessible names.
59+
60+
**Examples:**
61+
62+
```tsx
63+
// Good - Input with label
64+
<label htmlFor="email">Email</label>
65+
<input id="email" type="email" />
66+
67+
// Good - Icon button with aria-label
68+
<button aria-label="Add event">
69+
<PlusIcon />
70+
</button>
71+
72+
// Bad - Input without label
73+
<input type="email" />
74+
75+
// Bad - Icon button without accessible name
76+
<button>
77+
<PlusIcon />
78+
</button>
79+
```
80+
81+
### Keyboard Navigation
82+
83+
All interactive elements must be keyboard accessible.
84+
85+
**Requirements:**
86+
87+
- All buttons and links are reachable via Tab
88+
- Custom interactive elements have `tabIndex={0}`
89+
- Dialogs trap focus and return focus on close
90+
- Avoid `tabIndex > 0` (breaks natural tab order)
91+
92+
### ARIA Attributes
93+
94+
Use ARIA attributes when native semantics are insufficient.
95+
96+
**Common patterns:**
97+
98+
```tsx
99+
// Disclosure/Accordion
100+
<button aria-expanded={isOpen} aria-controls="panel-id">
101+
Toggle
102+
</button>
103+
<div id="panel-id" hidden={!isOpen}>Content</div>
104+
105+
// Dialog
106+
<div role="dialog" aria-modal="true" aria-labelledby="dialog-title">
107+
<h2 id="dialog-title">Dialog Title</h2>
108+
{/* content */}
109+
</div>
110+
```
111+
112+
## Testing for Accessibility
113+
114+
### Use Semantic Queries in Tests
115+
116+
When writing tests in `packages/web`, use accessible queries:
117+
118+
```typescript
119+
// Good - finds elements the way assistive tech does
120+
const button = getByRole('button', { name: /add event/i });
121+
const heading = getByRole('heading', { level: 2 });
122+
const textbox = getByLabelText('Email');
123+
124+
// Bad - relies on implementation details
125+
const button = getByTestId('add-button');
126+
const heading = container.querySelector('.heading');
127+
```
128+
129+
This aligns with the testing standards in `testing.md`.
130+
131+
## Audit Checklist Reference
132+
133+
For comprehensive review of UI changes, refer to:
134+
**`skills/a11y-audit/SKILL.md`**
135+
136+
Key sections:
137+
138+
- Semantics and structure
139+
- Labels and names
140+
- Keyboard and focus
141+
- ARIA correctness
142+
- Visual and motion
143+
- Testing reliability
144+
145+
## Real Examples from Codebase
146+
147+
Review these for accessibility patterns:
148+
149+
- `packages/web/src/components/Button/`
150+
- `packages/web/src/components/Input/`
151+
- `packages/web/src/components/Modal/`
152+
153+
## Summary
154+
155+
- Use semantic HTML (`<button>`, `<a>`, headings, landmarks)
156+
- Provide accessible names (labels, `aria-label`)
157+
- Support keyboard navigation (Tab, Enter, Space)
158+
- Use ARIA when needed (`aria-expanded`, `aria-label`, `role`)
159+
- Test with semantic queries (`getByRole`, `getByLabelText`)
160+
- Refer to `skills/a11y-audit/SKILL.md` for detailed guidance

‎.cursorrules/development.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
---
2+
description: Development workflow - setup commands, dev servers, testing, formatting, and environment requirements
3+
alwaysApply: false
4+
---
5+
6+
# Development Workflow
7+
8+
This rule defines development commands, setup, and workflow for the Compass codebase.
9+
10+
## Initial Setup
11+
12+
### Install Dependencies
13+
14+
```bash
15+
yarn install --frozen-lockfile --network-timeout 300000
16+
```
17+
18+
- Takes ~3.5 minutes
19+
- NEVER CANCEL the installation
20+
- Set timeout to 10+ minutes
21+
22+
### Environment Configuration
23+
24+
```bash
25+
cp packages/backend/.env.example packages/backend/.env
26+
```
27+
28+
Edit `packages/backend/.env` with your credentials.
29+
30+
## Development Servers
31+
32+
### Web (Recommended for Frontend Work)
33+
34+
```bash
35+
yarn dev:web
36+
```
37+
38+
- Starts on http://localhost:9080/
39+
- Takes ~10 seconds to start
40+
- Frontend works standalone without backend services
41+
42+
### Backend (Requires Full Setup)
43+
44+
```bash
45+
yarn dev:backend
46+
```
47+
48+
- Requires Google OAuth credentials
49+
- Requires Supertokens account
50+
- Requires MongoDB connection
51+
- See environment requirements below
52+
53+
## Common Commands
54+
55+
### Testing
56+
57+
```bash
58+
yarn test:core # Run core tests (~2 seconds)
59+
yarn test:web # Run web tests (~15 seconds)
60+
yarn test:backend # Run backend tests (~15 seconds)
61+
```
62+
63+
### Code Formatting
64+
65+
```bash
66+
yarn prettier . --write # Format all code (~15 seconds)
67+
```
68+
69+
### CLI Tools
70+
71+
```bash
72+
yarn cli --help # Shows all available CLI commands
73+
```
74+
75+
## Environment Requirements
76+
77+
### Required Environment Variables (backend/.env)
78+
79+
```bash
80+
BASEURL=http://localhost:3000/api
81+
GOOGLE_CLIENT_ID=your_google_oauth_client_id_here
82+
GOOGLE_CLIENT_SECRET=your_google_oauth_secret_here
83+
SUPERTOKENS_URI=your_supertokens_instance_url_here
84+
SUPERTOKENS_KEY=your_supertokens_api_key_here
85+
MONGO_URI=your_mongodb_connection_string_here
86+
PORT=3000
87+
NODE_ENV=development
88+
TZ=Etc/UTC
89+
```
90+
91+
### External Services
92+
93+
The backend requires:
94+
95+
- Google Cloud Project with OAuth 2.0 credentials
96+
- Supertokens account for user session management
97+
- MongoDB database (cloud or local)
98+
99+
## Pre-commit Hooks
100+
101+
The repository includes Husky hooks that automatically:
102+
103+
- Run `yarn lint-staged` on pre-commit (formats code with Prettier)
104+
- Run `yarn prettier . --write` on pre-push (ensures consistent formatting)
105+
106+
Your commits will pass these checks automatically.
107+
108+
## Important Notes
109+
110+
- The backend requires external service credentials to run
111+
- Frontend works standalone without backend services
112+
- Always use UTC timezone for consistency (`TZ=Etc/UTC`)
113+
- ESLint and Prettier configurations are already set up
114+
- The project uses React 18+ with the new JSX transform
115+
116+
## File Structure
117+
118+
```
119+
packages/
120+
├── backend/src/
121+
│ ├── auth/ # Google OAuth integration
122+
│ ├── calendar/ # Google Calendar API
123+
│ ├── event/ # Event CRUD operations
124+
│ ├── sync/ # Calendar synchronization
125+
│ ├── user/ # User management
126+
│ └── common/ # Shared backend utilities
127+
├── web/src/
128+
│ ├── views/ # React components and pages
129+
│ ├── store/ # Redux state management
130+
│ ├── common/ # Frontend utilities
131+
│ └── assets/ # Images and static files
132+
├── core/src/
133+
│ ├── types/ # TypeScript type definitions
134+
│ ├── constants/ # Shared constants
135+
│ ├── util/ # Utility functions
136+
│ └── mappers/ # Data transformation logic
137+
└── scripts/src/ # CLI tools
138+
```
139+
140+
## Summary
141+
142+
- Install with `yarn install --frozen-lockfile --network-timeout 300000`
143+
- Start frontend: `yarn dev:web` (recommended)
144+
- Run tests: `yarn test:web`, `yarn test:backend`, `yarn test:core`
145+
- Format code: `yarn prettier . --write`
146+
- Pre-commit hooks run automatically

0 commit comments

Comments
 (0)