fix: component-architecture.md

Author: tmt823

skills/react-clean-architecture-add-component/references/component-architecture.md

@@ -2,13 +2,46 @@
 
 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.
 
+## 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.
+
 ## 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:
@@ -39,6 +72,32 @@ Ask using these options:
 - Presentation receives props and handles rendering only.
 - Keep logic in `use<ComponentName>.tsx`.
 
+### 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.
@@ -49,8 +108,9 @@ Ask using these options:
 ### ui
 
 - `index.tsx`
-- `index.stories.tsx`
-- `index.module.scss`
+- `presentation.tsx`
+- `presentation.stories.tsx`
+- `presentation.module.scss`
 
 ### features