mirror of
https://github.com/github/awesome-copilot.git
synced 2026-06-16 04:36:27 +00:00
Hatsumi Kikuchi
6bc861e190
* feat(skill): make react-clean-architecture-add-component self-contained with local references * docs(skill): clarify SCSS rules for z-index tokens and Mantine complement usage * docs(skill): remove ambiguous "when needed" wording for presentation files * docs(skill): generalize build/lint validation wording * refactor(skill): generalize component scaffolding guidance beyond Mantine * fix: component-architecture.md * feat(skill): rename react component skill and clarify container/presentation guidance * fix(skill): replace vscode_askQuestions with ask_user to remove VS Code specific dependency * docs(skill): add TypeScript code examples to typescript-and-scss-rules reference * fix: README
131 lines
5.1 KiB
Markdown
131 lines
5.1 KiB
Markdown
# Component Architecture Reference
|
|
|
|
This reference defines classification, file layout, and dependency direction in `src/components`.
|
|
|
|
## Design Intent and Principles
|
|
|
|
The goal of this skill is not only to add React components, but to apply the Container/Presentation pattern consistently with clear separation of responsibilities and dependency direction.
|
|
|
|
This reference does not define full application-wide architecture. It focuses on design quality at the component boundary.
|
|
|
|
- Separate rendering responsibilities from logic responsibilities.
|
|
- Do not place state management, side effects, or business decisions in the presentation layer.
|
|
- Avoid mixing responsibilities across boundaries and keep dependency direction explicit.
|
|
|
|
## Classification
|
|
|
|
- Place all components under `src/components`.
|
|
- Use only two categories:
|
|
- `ui`: render-only, stateless components.
|
|
- `features`: components that include logic.
|
|
|
|
## Reclassification Rule
|
|
|
|
If the user requests `ui` but the implementation contains any of the following, treat it as `features` and ask for confirmation before creating files:
|
|
|
|
- `useState`, `useReducer`, or `useEffect`.
|
|
- Async behavior (API calls, timers, subscriptions).
|
|
- Reading from or writing to context/store.
|
|
- Business/data transformation logic.
|
|
|
|
Ask using these options:
|
|
|
|
- `Create as features`
|
|
- `Keep ui and move logic/state to parent or features`
|
|
|
|
## Layer Responsibilities
|
|
|
|
This skill defines layers in two stages.
|
|
|
|
### 1. Component Type Layer
|
|
|
|
| Type | Responsibility |
|
|
| ---------- | ------------------------------------------------------------------------------------------------------ |
|
|
| `ui` | Reusable render-only component. Must not include business logic, side effects, or state management. |
|
|
| `features` | Use-case-oriented component. Handles state transitions, event interpretation, and async orchestration. |
|
|
|
|
### 2. Internal Layer in `features`
|
|
|
|
| Layer | Responsibility | Primary files |
|
|
| -------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
|
|
| `container` | Handles state management, side effects, event handling, and data fetching. | `index.tsx`, `use<ComponentName>.tsx`, `types.ts` |
|
|
| `presentation` | Receives props and renders UI only. Must not perform external I/O or state updates. | `presentation.tsx`, `presentation.module.scss`, `presentation.stories.tsx` |
|
|
|
|
Notes:
|
|
|
|
- `ui` is composed of presentation only.
|
|
- `features` must separate container and presentation.
|
|
|
|
## Implementation Rules
|
|
|
|
### ui
|
|
|
|
- Keep components stateless.
|
|
- Accept data and callbacks via props.
|
|
- Do not add side effects or data fetching.
|
|
- Prefer primitives from Mantine or other UI libraries first; use custom JSX/SCSS only when needed.
|
|
|
|
### features
|
|
|
|
- Use the Container/Presentation pattern.
|
|
- Keep logic in `use<ComponentName>.tsx`.
|
|
- Follow `Container/Presentation Separation Rules (Anti-patterns and Decision Examples)` below for detailed responsibility boundaries and anti-patterns.
|
|
|
|
### Container/Presentation Separation Rules (Anti-patterns and Decision Examples)
|
|
|
|
Principles:
|
|
|
|
- Container is responsible for state management, side effects, event interpretation, and async processing.
|
|
- Presentation is responsible only for rendering from received props.
|
|
- Keep business decisions and data transformation in container-side code, not in presentation.
|
|
|
|
Placement rules:
|
|
|
|
- Place in container: `useState` / `useReducer` / `useEffect`, API calls, context/store read-write, business rule application.
|
|
- Place in presentation: JSX rendering and display-only branching (for example: empty, loading, error views).
|
|
- Use `types.ts` to define I/O contracts between container and presentation.
|
|
|
|
Anti-patterns:
|
|
|
|
- Calling APIs or mutations from presentation.
|
|
- Updating context/store directly from presentation.
|
|
- Implementing business decisions (authorization checks, state transition decisions, data shaping) in presentation.
|
|
- Splitting files formally while keeping practical logic in presentation.
|
|
|
|
Good / Bad examples:
|
|
|
|
- Bad: `presentation.tsx` fetches data and manages loading state directly.
|
|
- Good: `use<ComponentName>.tsx` manages data fetching and state, and `presentation.tsx` renders only from props such as `isLoading`, `items`, and `onAction`.
|
|
|
|
## Dependency Direction
|
|
|
|
- `features` -> `ui`: allowed.
|
|
- `ui` -> `features`: forbidden.
|
|
|
|
## File Structure
|
|
|
|
### ui
|
|
|
|
- `index.tsx`
|
|
- `presentation.tsx`
|
|
- `presentation.stories.tsx`
|
|
- `presentation.module.scss`
|
|
|
|
### features
|
|
|
|
- `index.tsx`
|
|
- `use<ComponentName>.tsx`
|
|
- `presentation.tsx`
|
|
- `types.ts`
|
|
- `presentation.stories.tsx`
|
|
- `presentation.module.scss`
|
|
|
|
## Storybook Minimum
|
|
|
|
- Always create `Default`.
|
|
- Add state-specific stories only when distinct states exist.
|
|
- Prefer story sets based on behavior:
|
|
- Interactive controls: `Hover`.
|
|
- Input-like: `Focus`, `Error`, `Disabled`.
|
|
- Layout/open-close: `Open`, `Closed`, `Empty`.
|