Create AI Guidelines Markdowns #1664
+326
−0
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,163 @@ | ||
| # CORD Front-End Development Guidelines | ||
|
|
||
| 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. | ||
|
|
||
| ### Project Structure | ||
|
|
||
| - `src/`: Source code | ||
| - `src/api/`: client setup, caching strategies, schema definitions, and operation management. | ||
| - `src/common/`: Utility TypeScript files (types, interfaces). | ||
| - `src/components/`: Reusable React components (mostly TSX, some with GraphQL files), with subfolders (e.g., `form/` for Final Form components). | ||
| - `src/hooks/`: Custom React hooks (TypeScript). | ||
| - `src/scenes/`: Application-specific, non-reusable components (mostly TSX, some with GraphQL files), with subfolders. | ||
| - `src/server/`: server-side code and configuration files. | ||
| - `src/theme/`: MUI theme configuration files. | ||
|
|
||
| ### Coding Standards | ||
|
|
||
| - Use single quotes for strings, 2 spaces for indentation. | ||
| - Prefer arrow functions for callbacks, async/await for GraphQL queries/mutations. | ||
| - Use `const` for constants, minimize `let` usage (e.g., except in try/catch). | ||
| - Use destructuring for objects/arrays, template literals for strings. | ||
| - Follow SOLID principles for modular, reusable, maintainable code. | ||
| - Avoid code duplication, deeply nested statements, hard-coded values. | ||
| - Use constants/enums instead of magic numbers/strings. | ||
| - Avoid mutations (non-GraphQL): | ||
| - Prefer `const` over `let`. | ||
| - Use spread syntax (e.g., `{ ...object, foo: 'bar' }`) instead of modifying objects. | ||
| - Use strict TypeScript: | ||
| - Define all object shapes in `src/common` or generated GraphQL types in `src/api`. | ||
| - Use optional chaining (`?.`) or type guards for safe property access. | ||
|
|
||
| ### React Guidelines | ||
|
|
||
| - For new small components: | ||
| - Pass most props to wrapping components for reusability. | ||
| - Match designs or comment stop-gap versions. | ||
| - Avoid unnecessary HTML elements for styling (e.g., `<MyCard sx={{ m: 1 }} />` instead of `<Box sx={{ m: 1 }}><MyCard /></Box>`). | ||
| - Use optional chaining (`?.`) or type guards for object properties. | ||
|
|
||
| ### Form Development | ||
|
|
||
| - Use custom form components with Final Form and react-final-form in `src/components/form`. | ||
|
|
||
| ### CSS Guidelines | ||
|
|
||
| - Use `sx` prop for styling; avoid StyledComponents or `makeStyles`. | ||
| - Reference `src/theme` for spacing (1-8), palette colors, typography variants. | ||
| - Comment if using magic numbers/colors/fonts. | ||
| - Ensure styles are minimal, necessary, and responsive across screen sizes. | ||
| - Use `// ai edge-case` for justified deviations (e.g., non-theme colors). | ||
| - **Parent components own layout styles**: Apply layout-related styles (e.g., centering, alignment, spacing) to parent components, not children, to ensure encapsulation and reusability. | ||
| - Example (Correct): | ||
| ```tsx | ||
| // ai example Parent-owned centering | ||
| // src/components/CenteredCard.tsx | ||
| import { Box, Card } from '@mui/material'; | ||
| export const CenteredCard = () => ( | ||
| <Box sx={{ display: 'flex', justifyContent: 'center', p: 2 }}> | ||
| <Card sx={{ width: 300 }}>Content</Card> | ||
| </Box> | ||
| ); | ||
| ``` | ||
| _Why_: Parent `<Box>` controls centering, keeping `<Card>` reusable. | ||
| - Example (Incorrect): | ||
| ```tsx | ||
| // ai anti-pattern Child-owned centering | ||
| // src/components/CenteredCard.tsx | ||
| import { Box, Card } from '@mui/material'; | ||
| export const CenteredCard = () => ( | ||
| <Box sx={{ p: 2 }}> | ||
| <Card sx={{ margin: 'auto', width: 300 }}>Content</Card> | ||
| </Box> | ||
| ); | ||
| ``` | ||
| _Why_: `<Card>` assumes parent’s layout, reducing reusability. | ||
| - **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. | ||
| - Example (Correct): | ||
| ```tsx | ||
| // ai example Ordered sx styles | ||
| // src/components/StyledBox.tsx | ||
| import { Box } from '@mui/material'; | ||
| export const StyledBox = () => ( | ||
| <Box | ||
| sx={{ | ||
| display: 'flex', | ||
| justifyContent: 'center', | ||
| padding: 2, | ||
| width: '100%', | ||
| backgroundColor: 'primary.main', | ||
| color: 'white', | ||
| borderRadius: 1, | ||
| fontSize: 16, | ||
| }} | ||
| > | ||
| Content | ||
| </Box> | ||
| ); | ||
| ``` | ||
| _Why_: Control styles (`display`, `justifyContent`, `padding`, `width`) precede appearance styles (`backgroundColor`, `color`, `borderRadius`, `fontSize`), enhancing readability. | ||
| - Example (Incorrect): | ||
| ```tsx | ||
| // ai anti-pattern Disordered sx styles | ||
| // src/components/StyledBox.tsx | ||
| import { Box } from '@mui/material'; | ||
| export const StyledBox = () => ( | ||
| <Box | ||
| sx={{ | ||
| color: 'white', | ||
| display: 'flex', | ||
| backgroundColor: 'primary.main', | ||
| padding: 2, | ||
| fontSize: 16, | ||
| justifyContent: 'center', | ||
| borderRadius: 1, | ||
| width: '100%', | ||
| }} | ||
| > | ||
| Content | ||
| </Box> | ||
| ); | ||
| ``` | ||
| _Why_: Mixed style order reduces readability and maintainability. | ||
|
|
||
| ### Common Errors to Avoid | ||
|
|
||
| - **Accessing Non-Existent Properties**: | ||
| - Never assume properties exist without type verification. | ||
| - Reference TypeScript interfaces in `src/common` or generated GraphQL types in `src/api`. | ||
| - Use optional chaining (`?.`) or type guards (e.g., `if ('foo' in obj)`). | ||
| - Example (Correct): | ||
| ```tsx | ||
| // ai type-safety Safe property access with optional chaining | ||
| interface User { | ||
| name?: string; | ||
| } | ||
| const user: User = {}; | ||
| const name = user?.name ?? 'Unknown'; | ||
| ``` | ||
| _Why_: Prevents runtime errors by checking property existence. | ||
| - Example (Incorrect): | ||
| ```tsx | ||
| // ai anti-pattern Assumes non-existent property | ||
| const user = {}; | ||
| const name = user.name; // Error: Property 'name' does not exist | ||
| ``` | ||
| _Why_: Causes runtime errors due to unverified property access. | ||
|
|
||
| ### Tagged Comments | ||
|
|
||
| - Use `// ai tag` to mark code for reference: | ||
| - `example`: Best practice or model code. | ||
| - `edge-case`: Necessary deviation from standards. | ||
| - `best-practice`: Adherence to coding standards. | ||
| - `anti-pattern`: Code to avoid (pending refactor). | ||
| - `todo`: Needs improvement or refactoring. | ||
| - `workaround`: Temporary fix for a limitation. | ||
| - `performance`: Optimized code. | ||
| - `security`: Security-critical code. | ||
| - `test`: Exemplary test case. | ||
| - `design-alignment`: Matches or deviates from design specs. | ||
| - `type-safety`: Safe property access. | ||
| - Optionally add notes after the tag (e.g., `// ai example Reusable form with theme-based styling`). | ||
| - Search tags with `git grep "ai "` to collect examples. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,163 @@ | ||
| # CORD Front-End Development Guidelines | ||
|
|
||
| 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. | ||
|
|
||
| ### Project Structure | ||
|
|
||
| - `src/`: Source code | ||
| - `src/api/`: client setup, caching strategies, schema definitions, and operation management. | ||
| - `src/common/`: Utility TypeScript files (types, interfaces). | ||
| - `src/components/`: Reusable React components (mostly TSX, some with GraphQL files), with subfolders (e.g., `form/` for Final Form components). | ||
| - `src/hooks/`: Custom React hooks (TypeScript). | ||
| - `src/scenes/`: Application-specific, non-reusable components (mostly TSX, some with GraphQL files), with subfolders. | ||
| - `src/server/`: server-side code and configuration files. | ||
| - `src/theme/`: MUI theme configuration files. | ||
|
|
||
| ### Coding Standards | ||
|
|
||
| - Use single quotes for strings, 2 spaces for indentation. | ||
| - Prefer arrow functions for callbacks, async/await for GraphQL queries/mutations. | ||
| - Use `const` for constants, minimize `let` usage (e.g., except in try/catch). | ||
| - Use destructuring for objects/arrays, template literals for strings. | ||
| - Follow SOLID principles for modular, reusable, maintainable code. | ||
| - Avoid code duplication, deeply nested statements, hard-coded values. | ||
| - Use constants/enums instead of magic numbers/strings. | ||
| - Avoid mutations (non-GraphQL): | ||
| - Prefer `const` over `let`. | ||
| - Use spread syntax (e.g., `{ ...object, foo: 'bar' }`) instead of modifying objects. | ||
| - Use strict TypeScript: | ||
| - Define all object shapes in `src/common` or generated GraphQL types in `src/api`. | ||
| - Use optional chaining (`?.`) or type guards for safe property access. | ||
|
|
||
| ### React Guidelines | ||
|
|
||
| - For new small components: | ||
| - Pass most props to wrapping components for reusability. | ||
| - Match designs or comment stop-gap versions. | ||
| - Avoid unnecessary HTML elements for styling (e.g., `<MyCard sx={{ m: 1 }} />` instead of `<Box sx={{ m: 1 }}><MyCard /></Box>`). | ||
| - Use optional chaining (`?.`) or type guards for object properties. | ||
|
|
||
| ### Form Development | ||
|
|
||
| - Use custom form components with Final Form and react-final-form in `src/components/form`. | ||
|
|
||
|
Comment on lines
+42
to
+43
There was a problem hiding this comment. 🛠️ Refactor suggestion Expand Form Development section with examples 🤖 Prompt for AI Agents |
||
| ### CSS Guidelines | ||
|
|
||
| - Use `sx` prop for styling; avoid StyledComponents or `makeStyles`. | ||
| - Reference `src/theme` for spacing (1-8), palette colors, typography variants. | ||
| - Comment if using magic numbers/colors/fonts. | ||
| - Ensure styles are minimal, necessary, and responsive across screen sizes. | ||
| - Use `// ai edge-case` for justified deviations (e.g., non-theme colors). | ||
| - **Parent components own layout styles**: Apply layout-related styles (e.g., centering, alignment, spacing) to parent components, not children, to ensure encapsulation and reusability. | ||
| - Example (Correct): | ||
| ```tsx | ||
| // ai example Parent-owned centering | ||
| // src/components/CenteredCard.tsx | ||
| import { Box, Card } from '@mui/material'; | ||
| export const CenteredCard = () => ( | ||
| <Box sx={{ display: 'flex', justifyContent: 'center', p: 2 }}> | ||
| <Card sx={{ width: 300 }}>Content</Card> | ||
| </Box> | ||
| ); | ||
| ``` | ||
| _Why_: Parent `<Box>` controls centering, keeping `<Card>` reusable. | ||
| - Example (Incorrect): | ||
| ```tsx | ||
| // ai anti-pattern Child-owned centering | ||
| // src/components/CenteredCard.tsx | ||
| import { Box, Card } from '@mui/material'; | ||
| export const CenteredCard = () => ( | ||
| <Box sx={{ p: 2 }}> | ||
| <Card sx={{ margin: 'auto', width: 300 }}>Content</Card> | ||
| </Box> | ||
| ); | ||
| ``` | ||
| _Why_: `<Card>` assumes parent’s layout, reducing reusability. | ||
| - **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. | ||
| - Example (Correct): | ||
| ```tsx | ||
| // ai example Ordered sx styles | ||
| // src/components/StyledBox.tsx | ||
| import { Box } from '@mui/material'; | ||
| export const StyledBox = () => ( | ||
| <Box | ||
| sx={{ | ||
| display: 'flex', | ||
| justifyContent: 'center', | ||
| padding: 2, | ||
| width: '100%', | ||
| backgroundColor: 'primary.main', | ||
| color: 'white', | ||
| borderRadius: 1, | ||
| fontSize: 16, | ||
| }} | ||
| > | ||
| Content | ||
| </Box> | ||
| ); | ||
| ``` | ||
| _Why_: Control styles (`display`, `justifyContent`, `padding`, `width`) precede appearance styles (`backgroundColor`, `color`, `borderRadius`, `fontSize`), enhancing readability. | ||
| - Example (Incorrect): | ||
| ```tsx | ||
| // ai anti-pattern Disordered sx styles | ||
| // src/components/StyledBox.tsx | ||
| import { Box } from '@mui/material'; | ||
| export const StyledBox = () => ( | ||
| <Box | ||
| sx={{ | ||
| color: 'white', | ||
| display: 'flex', | ||
| backgroundColor: 'primary.main', | ||
| padding: 2, | ||
| fontSize: 16, | ||
| justifyContent: 'center', | ||
| borderRadius: 1, | ||
| width: '100%', | ||
| }} | ||
| > | ||
| Content | ||
| </Box> | ||
| ); | ||
| ``` | ||
| _Why_: Mixed style order reduces readability and maintainability. | ||
|
|
||
| ### Common Errors to Avoid | ||
|
|
||
| - **Accessing Non-Existent Properties**: | ||
| - Never assume properties exist without type verification. | ||
| - Reference TypeScript interfaces in `src/common` or generated GraphQL types in `src/api`. | ||
| - Use optional chaining (`?.`) or type guards (e.g., `if ('foo' in obj)`). | ||
| - Example (Correct): | ||
| ```tsx | ||
| // ai type-safety Safe property access with optional chaining | ||
| interface User { | ||
| name?: string; | ||
| } | ||
| const user: User = {}; | ||
| const name = user?.name ?? 'Unknown'; | ||
| ``` | ||
| _Why_: Prevents runtime errors by checking property existence. | ||
| - Example (Incorrect): | ||
| ```tsx | ||
| // ai anti-pattern Assumes non-existent property | ||
| const user = {}; | ||
| const name = user.name; // Error: Property 'name' does not exist | ||
| ``` | ||
| _Why_: Causes runtime errors due to unverified property access. | ||
|
|
||
| ### Tagged Comments | ||
|
|
||
| - Use `// ai tag` to mark code for reference: | ||
| - `example`: Best practice or model code. | ||
| - `edge-case`: Necessary deviation from standards. | ||
| - `best-practice`: Adherence to coding standards. | ||
| - `anti-pattern`: Code to avoid (pending refactor). | ||
| - `todo`: Needs improvement or refactoring. | ||
| - `workaround`: Temporary fix for a limitation. | ||
| - `performance`: Optimized code. | ||
| - `security`: Security-critical code. | ||
| - `test`: Exemplary test case. | ||
| - `design-alignment`: Matches or deviates from design specs. | ||
| - `type-safety`: Safe property access. | ||
| - Optionally add notes after the tag (e.g., `// ai example Reusable form with theme-based styling`). | ||
| - Search tags with `git grep "ai "` to collect examples. | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🛠️ Refactor suggestion
Specify tooling for enforcing coding standards
Recommend calling out which linter/formatter configurations (ESLint, Prettier, etc.) enforce these rules automatically. This reduces manual overhead and ensures consistency across commits.
🧰 Tools
🪛 LanguageTool
[formatting] ~30-~30: Did you mean “?”
Context: ...n
src/api. - Use optional chaining (?.) or type guards for safe property acce...(MULTIPLE_PUNCTATION_MARKS_1)
🤖 Prompt for AI Agents