Skip to content

Commit 0df8aab

Browse files
rdonigianrdonigian
committed
create ai guidelines
1 parent ba7fa31 commit 0df8aab

File tree

2 files changed

+316
-115
lines changed

2 files changed

+316
-115
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 153 additions & 115 deletions
Original file line numberDiff line numberDiff line change
@@ -1,116 +1,153 @@
1-
# Copilot Instructions
2-
3-
This project is a web application built with React 18, Material-UI (MUI), and GraphQL, using Yarn as the package manager and Razzle for the custom build process. Follow these guidelines to ensure consistent, high-quality code aligned with our coding standards.
4-
5-
## Coding Standards
6-
7-
- Use camelCase for variables, functions, and methods.
8-
- Use PascalCase for React components, classes, and enums.
9-
- Use kebab-case for new folders and files.
10-
- Use single quotes for strings.
11-
- Use 2 spaces for indentation.
12-
- Prefer arrow functions for callbacks.
13-
- Use async/await for GraphQL queries and mutations.
14-
- Use const for constants, let for reassignable variables.
15-
- Use destructuring for objects and arrays.
16-
- Use template literals for dynamic strings.
17-
- Follow SOLID principles for modular, reusable, and maintainable code.
18-
- Avoid code duplication, deeply nested statements, and hard-coded values (e.g., file paths, usernames).
19-
- Use constants or enums instead of magic numbers/strings for readability and memory efficiency.
20-
21-
## Project Preferences
22-
23-
- Use React with functional components and hooks.
24-
- Use Material-UI (MUI) v5 for UI components and styling:
25-
- Use the `sx` prop as the primary styling method.
26-
- Avoid `useStyles` or `makeStyles` (MUI v4 patterns).
27-
- Reference `src/theme` for custom MUI theme configurations in `sx` (e.g., `sx={{ color: theme.palette.primary.main }}`).
28-
- Use Apollo Client for GraphQL:
29-
- Write type-safe queries and mutations with generated TypeScript types.
30-
- Store queries, mutations, and fragments in `src/api`.
31-
- Use Yarn for package management:
32-
- Run `yarn add` for dependencies, checking for vulnerabilities with Snyk.
33-
- Use `yarn start`, `yarn build`, and `yarn test` for Razzle scripts.
34-
- Custom build process with Razzle:
35-
- Configure Razzle in `razzle.config.js` for build settings.
36-
- Optimize for production with code splitting and server-side rendering (SSR).
37-
- Use `src/server` for Razzle server configurations.
38-
- Use TypeScript for all code:
39-
- Enforce strict mode.
40-
- Define interfaces and types in `src/common`.
41-
- Follow folder structure:
42-
- `src/api`: GraphQL queries, mutations, Apollo Client setup, and API-related files.
43-
- `src/common`: Utility TypeScript files (types, interfaces, general-use TS).
44-
- `src/components`: Reusable React components (mostly TSX, some with GraphQL files), with subfolders.
45-
- `src/hooks`: Custom React hooks (TypeScript).
46-
- `src/scenes`: Application-specific, non-reusable components (mostly TSX, some with GraphQL files), with subfolders.
47-
- `src/server`: Razzle server configuration files.
48-
- `src/theme`: MUI theme configuration files.
49-
50-
## Version Control
51-
52-
- Create branches with format: `type/MondayTicketID-description` (e.g., `enhancement/1234-new-profile-page`).
53-
- Write commit messages:
54-
- First line: `[TicketID] - [Short Title] - Imperative verb` (e.g., `0654 - IRP - Remove/move Impact Report Date`).
55-
- Optional body: Briefly explain why the change is needed or the problem addressed.
56-
- Create PRs for single, specific changes (one user story per PR unless deployable in isolation):
57-
- Link the Monday ticket in the PR description.
58-
- Break changes into bite-sized, logical commits for easier review and potential reversion.
59-
- Demo functionality to reviewers when needed.
60-
61-
## Security Practices
62-
63-
- Sanitize all user inputs to prevent XSS.
64-
- Use Apollo Client’s error handling for GraphQL responses in `src/api`.
65-
- Implement role-based access control (RBAC) via GraphQL context.
66-
- Configure secure cookies (`HttpOnly`, `Secure`, `SameSite=Strict`) in `src/server`.
67-
- Enforce Content Security Policy (CSP) in Razzle’s server configuration in `src/server`.
68-
- Validate data from external sources (APIs, databases) for expected formats.
69-
- Check new dependencies with Snyk for vulnerabilities before adding via Yarn.
70-
71-
## Form Development
72-
73-
- Use custom form components built with Final Form and react-final-form in `src/components/form`:
74-
- Use components like `Form`, `Field`, and custom inputs for consistent behavior.
75-
- Define TypeScript interfaces in `src/common` for form data and props.
76-
- Use `react-final-form` hooks (e.g., `useForm`, `useField`) for form state management.
77-
- Integrate MUI v5 components (`TextField`, `Select`, etc.) within form components:
78-
- Apply `sx` prop, referencing `src/theme` for consistency.
79-
- Use `yup` for validation:
80-
- Store schemas in `src/common/validation`.
81-
- Ensure TypeScript compatibility.
82-
- Integrate with react-final-form for user-friendly error messages.
83-
84-
## General Guidelines
85-
86-
- Write clear, concise code with single-responsibility modules.
87-
- Add JSDoc comments for public functions and components (optional: include purpose and description).
88-
- Optimize performance:
89-
- Use `React.memo`, `useCallback`, `useMemo` for React components.
90-
- Minimize loop iterations, redundant operations, and memory allocations.
91-
- Process data in chunks for large datasets.
92-
- Optimize GraphQL queries in `src/api` for efficient data retrieval.
93-
- Avoid changing code outside the task scope; create separate PRs for refactors.
94-
- Keep responses friendly, informal, and under 1000 characters.
95-
- Reference `styleguide.md` in `docs/` for additional styling rules.
96-
97-
## Testing
98-
99-
- Use Jest and React Testing Library for unit tests:
100-
- Place tests in `__tests__` folders in `src/components` and `src/scenes`.
101-
- Mock GraphQL queries with `@apollo/client/testing` for `src/api` files.
102-
- Mock react-final-form for form tests using `react-final-form` testing utilities.
103-
- Write descriptive tests focusing on user interactions.
104-
- Ensure functional quality:
105-
- Unit testing in development.
106-
- Regression and smoke testing in production or development as needed.
107-
- Validate all acceptance criteria in PR reviews.
108-
109-
## Additional Notes
110-
111-
- Reference GraphQL schemas in `src/api/schema.graphql`.
112-
- Avoid external resource references unless specified.
113-
- If instructions seem ignored, remind Copilot to check this file.- Use tagged comments (`// cp tag`) to mark code for reference:
1+
# CORD Front-End Development Guidelines
2+
3+
This document provides guidelines for developers working on the CORD Field front-end project, a UI built with React, Material-UI (MUI) v5, and GraphQL, using Yarn and Razzle. The front-end connects to the CORD API v3.
4+
5+
### Project Structure
6+
7+
- `src/`: Source code
8+
- `src/api/`: client setup, caching strategies, schema definitions, and operation management.
9+
- `src/common/`: Utility TypeScript files (types, interfaces).
10+
- `src/components/`: Reusable React components (mostly TSX, some with GraphQL files), with subfolders (e.g., `form/` for Final Form components).
11+
- `src/hooks/`: Custom React hooks (TypeScript).
12+
- `src/scenes/`: Application-specific, non-reusable components (mostly TSX, some with GraphQL files), with subfolders.
13+
- `src/server/`: server-side code and configuration files.
14+
- `src/theme/`: MUI theme configuration files.
15+
16+
### Coding Standards
17+
18+
- Use single quotes for strings, 2 spaces for indentation.
19+
- Prefer arrow functions for callbacks, async/await for GraphQL queries/mutations.
20+
- Use `const` for constants, minimize `let` usage (e.g., except in try/catch).
21+
- Use destructuring for objects/arrays, template literals for strings.
22+
- Follow SOLID principles for modular, reusable, maintainable code.
23+
- Avoid code duplication, deeply nested statements, hard-coded values.
24+
- Use constants/enums instead of magic numbers/strings.
25+
- Avoid mutations (non-GraphQL):
26+
- Prefer `const` over `let`.
27+
- Use spread syntax (e.g., `{ ...object, foo: 'bar' }`) instead of modifying objects.
28+
- Use strict TypeScript:
29+
- Define all object shapes in `src/common` or generated GraphQL types in `src/api`.
30+
- Use optional chaining (`?.`) or type guards for safe property access.
31+
32+
### React Guidelines
33+
34+
- For new small components:
35+
- Pass most props to wrapping components for reusability.
36+
- Match designs or comment stop-gap versions.
37+
- Avoid unnecessary HTML elements for styling (e.g., `<MyCard sx={{ m: 1 }} />` instead of `<Box sx={{ m: 1 }}><MyCard /></Box>`).
38+
- Use optional chaining (`?.`) or type guards for object properties.
39+
40+
### Form Development
41+
42+
- Use custom form components with Final Form and react-final-form in `src/components/form`.
43+
44+
### CSS Guidelines
45+
46+
- Use `sx` prop for styling; avoid StyledComponents or `makeStyles`.
47+
- Reference `src/theme` for spacing (1-8), palette colors, typography variants.
48+
- Comment if using magic numbers/colors/fonts.
49+
- Ensure styles are minimal, necessary, and responsive across screen sizes.
50+
- Use `// ai edge-case` for justified deviations (e.g., non-theme colors).
51+
- **Parent components own layout styles**: Apply layout-related styles (e.g., centering, alignment, spacing) to parent components, not children, to ensure encapsulation and reusability.
52+
- Example (Correct):
53+
```tsx
54+
// ai example Parent-owned centering
55+
// src/components/CenteredCard.tsx
56+
import { Box, Card } from '@mui/material';
57+
export const CenteredCard = () => (
58+
<Box sx={{ display: 'flex', justifyContent: 'center', p: 2 }}>
59+
<Card sx={{ width: 300 }}>Content</Card>
60+
</Box>
61+
);
62+
```
63+
_Why_: Parent `<Box>` controls centering, keeping `<Card>` reusable.
64+
- Example (Incorrect):
65+
```tsx
66+
// ai anti-pattern Child-owned centering
67+
// src/components/CenteredCard.tsx
68+
import { Box, Card } from '@mui/material';
69+
export const CenteredCard = () => (
70+
<Box sx={{ p: 2 }}>
71+
<Card sx={{ margin: 'auto', width: 300 }}>Content</Card>
72+
</Box>
73+
);
74+
```
75+
_Why_: `<Card>` assumes parent’s layout, reducing reusability.
76+
- **Order control styles before appearance styles**: In `sx` prop declarations, list control styles (e.g., `display`, `padding`, `width`) before appearance styles (e.g., `color`, `background`, `fontSize`) for readability.
77+
- Example (Correct):
78+
```tsx
79+
// ai example Ordered sx styles
80+
// src/components/StyledBox.tsx
81+
import { Box } from '@mui/material';
82+
export const StyledBox = () => (
83+
<Box
84+
sx={{
85+
display: 'flex',
86+
justifyContent: 'center',
87+
padding: 2,
88+
width: '100%',
89+
backgroundColor: 'primary.main',
90+
color: 'white',
91+
borderRadius: 1,
92+
fontSize: 16,
93+
}}
94+
>
95+
Content
96+
</Box>
97+
);
98+
```
99+
_Why_: Control styles (`display`, `justifyContent`, `padding`, `width`) precede appearance styles (`backgroundColor`, `color`, `borderRadius`, `fontSize`), enhancing readability.
100+
- Example (Incorrect):
101+
```tsx
102+
// ai anti-pattern Disordered sx styles
103+
// src/components/StyledBox.tsx
104+
import { Box } from '@mui/material';
105+
export const StyledBox = () => (
106+
<Box
107+
sx={{
108+
color: 'white',
109+
display: 'flex',
110+
backgroundColor: 'primary.main',
111+
padding: 2,
112+
fontSize: 16,
113+
justifyContent: 'center',
114+
borderRadius: 1,
115+
width: '100%',
116+
}}
117+
>
118+
Content
119+
</Box>
120+
);
121+
```
122+
_Why_: Mixed style order reduces readability and maintainability.
123+
124+
### Common Errors to Avoid
125+
126+
- **Accessing Non-Existent Properties**:
127+
- Never assume properties exist without type verification.
128+
- Reference TypeScript interfaces in `src/common` or generated GraphQL types in `src/api`.
129+
- Use optional chaining (`?.`) or type guards (e.g., `if ('foo' in obj)`).
130+
- Example (Correct):
131+
```tsx
132+
// ai type-safety Safe property access with optional chaining
133+
interface User {
134+
name?: string;
135+
}
136+
const user: User = {};
137+
const name = user?.name ?? 'Unknown';
138+
```
139+
_Why_: Prevents runtime errors by checking property existence.
140+
- Example (Incorrect):
141+
```tsx
142+
// ai anti-pattern Assumes non-existent property
143+
const user = {};
144+
const name = user.name; // Error: Property 'name' does not exist
145+
```
146+
_Why_: Causes runtime errors due to unverified property access.
147+
148+
### Tagged Comments
149+
150+
- Use `// ai tag` to mark code for reference:
114151
- `example`: Best practice or model code.
115152
- `edge-case`: Necessary deviation from standards.
116153
- `best-practice`: Adherence to coding standards.
@@ -121,5 +158,6 @@ This project is a web application built with React 18, Material-UI (MUI), and Gr
121158
- `security`: Security-critical code.
122159
- `test`: Exemplary test case.
123160
- `design-alignment`: Matches or deviates from design specs.
124-
- After the tag, optionally add notes to explain the context (e.g., `// cp example Reusable form with theme-based styling`).
125-
- Search for tags with `git grep "cp "` to collect examples for this document.
161+
- `type-safety`: Safe property access.
162+
- Optionally add notes after the tag (e.g., `// ai example Reusable form with theme-based styling`).
163+
- Search tags with `git grep "ai "` to collect examples.

0 commit comments

Comments
 (0)