chore: update skill
This commit is contained in:
parent
bbf84069c9
commit
79304d1009
|
|
@ -51,6 +51,7 @@ TanStack Query is implied by `configs/react-query.ts`; confirm the repo uses it
|
|||
The rules below are enough for work inside existing projects and features. Read the rest only when its trigger applies:
|
||||
|
||||
- Project structure (full trees, Nx tags, the env flow, export mechanics), only when you add an Nx project, a feature, or a top-level folder, or change tags or exports: [references/project-structure.md](references/project-structure.md)
|
||||
- Component placement (its atomic level and the project and folder it belongs in), before you add or move a component: only the "Choosing where a component goes" section of [references/project-structure.md](references/project-structure.md#choosing-where-a-component-goes)
|
||||
- Code patterns, one section at a time: read only the section for the layer you write (island component, tokens, repository, action, form and model, mutation, store, persisted store, env), as its Contents line lists. Copy an existing file of the same kind when the repo has one: [references/code-patterns.md](references/code-patterns.md)
|
||||
|
||||
Shared libs have full specs. Read the matching one only when you build or change the lib itself, or when a feature needs lib behavior that "Env, HTTP, cookies, and storage" below doesn't describe. To use a lib from a feature, that section and code-patterns.md are enough:
|
||||
|
|
@ -123,6 +124,7 @@ Error handling, patterns, and refactoring have their own references. Read each o
|
|||
**Design system (island)**
|
||||
|
||||
- Build UI from island. Never fork or restyle an island component inside a feature; add a variant to island and use it.
|
||||
- Place every new component in three steps: reuse or add a variant first, then pick its level by what it renders and imports (never by its size), then its owner by whether it knows a domain. A domain-free organism that one route uses stays in that route's `organisms/` until a second route needs it, then moves to island. Details: [references/project-structure.md](references/project-structure.md#choosing-where-a-component-goes).
|
||||
- Components use semantic tokens (`--color-surface-card`, `--color-text-muted`, `--color-action-primary`) layered over primitive tokens in `theme.css`. That layering is what makes theming and dark mode possible without a rewrite.
|
||||
- Every component defines its variants, sizes, and states (default, hover, focus-visible, active, disabled, loading, error, selected) and its accessibility behavior. Enabled interactive elements show `cursor: pointer` and disabled ones `cursor: not-allowed`, built into the component so no page can forget them.
|
||||
- Complex organisms are compound components (`<DataTable>`, `<DataTable.Toolbar>`, `<DataTable.Pagination>`) that share state through context, with slots or render props for the parts that vary per entity, such as cells, empty states, and toolbars.
|
||||
|
|
@ -139,12 +141,12 @@ Error handling, patterns, and refactoring have their own references. Read each o
|
|||
|
||||
## 4. Workflow
|
||||
|
||||
Follow these steps for any design or implementation task. Write a short plan in the PR description: affected projects and paths, data types, each route's streamed, deferred, and auth-dependent parts, each rendering override the developer asked for, and each new non-obvious pattern.
|
||||
Follow these steps for any design or implementation task. Write a short plan in the PR description: affected projects and paths, each new component's path, level, and reason, data types, each route's streamed, deferred, and auth-dependent parts, each rendering override the developer asked for, and each new non-obvious pattern.
|
||||
|
||||
1. **Clarify the job.** Who uses it, how often, and what they finish with it. State assumptions.
|
||||
2. **Read the playbook** ([b2c-b2b.md](references/b2c-b2b.md)), plus [ui-rules.md](references/ui-rules.md) for UI work.
|
||||
3. **Map the data.** Entities, repository types (`*Args`, `*Dto`, `*ResponseDto`, `*Payload`), caches and how each client part gets its server data, page and part models, actions and their events, query keys, and how the query cache is updated after each mutation.
|
||||
4. **Place the code.** List the Nx projects and folders that change. Reuse what exists before creating anything. For each part you add or move, decide whether it depends on the viewer, where it renders, and when its code loads ([rendering-patterns.md](references/rendering-patterns.md)), and add a pattern only for a signal you can name ([design-patterns.md](references/design-patterns.md)). When existing code resists the change, refactor it first, in its own commit ([refactoring.md](references/refactoring.md)).
|
||||
4. **Place the code.** List the Nx projects and folders that change. Reuse what exists before creating anything. Give each component you add or move its level and owner with "Choosing where a component goes" ([project-structure.md](references/project-structure.md#choosing-where-a-component-goes)). For each part you add or move, decide whether it depends on the viewer, where it renders, and when its code loads ([rendering-patterns.md](references/rendering-patterns.md)), and add a pattern only for a signal you can name ([design-patterns.md](references/design-patterns.md)). When existing code resists the change, refactor it first, in its own commit ([refactoring.md](references/refactoring.md)).
|
||||
5. **Design every state first:** loading, empty (no data, no results, not found, no access), error, in progress, then populated.
|
||||
6. **Build in layer order,** with island components, adding variants to island when needed:
|
||||
1. Setup: Nx projects, tags, subpath exports, and new env variables.
|
||||
|
|
@ -179,6 +181,7 @@ Copy this into the PR description, add the list from the playbook, and tick ever
|
|||
```
|
||||
Structure
|
||||
[ ] Code is in the right project and folder, under src/, named per the naming rules
|
||||
[ ] Each new or moved component went through "Choosing where a component goes"; its path, level, and reason are in the PR
|
||||
[ ] Public API is exported by name from index.ts (and server.ts); no export *
|
||||
[ ] ESLint boundaries pass; no upward or cross-product imports
|
||||
[ ] Repositories have no client-side dependencies; UI and stores use *Payload types only
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
`<placeholders>` are names you choose. `@project` stands for the workspace's npm scope.
|
||||
|
||||
Contents: Top level · App · Platform · Feature anatomy · Shared · island · libs, integrations, and tools packages · Env flow · Nx tags and boundaries · Exports and tree-shaking
|
||||
Contents: Top level · App · Platform · Feature anatomy · Shared · island · Choosing where a component goes · libs, integrations, and tools packages · Env flow · Nx tags and boundaries · Exports and tree-shaking
|
||||
|
||||
## Top level
|
||||
|
||||
|
|
@ -230,6 +230,36 @@ Tools:
|
|||
- `icon-sprite-plugin` is a build and dev plugin. It optimizes the SVGs with svgo and writes the final sprite into each app's `public/` folder. Build-time tools are imported only from build configs, never from app code.
|
||||
- `icon-name-extraction` extracts icon names from the Icomoon files, for example to type the `Icon` component's `name` prop.
|
||||
|
||||
## Choosing where a component goes
|
||||
|
||||
Run these three steps for every component you add or move. Write one line per component in the plan: its path, its level, and the reason, for example `packages/island/src/molecules/form-field/: molecule; a label, an input, and an error text for one field; domain-free`.
|
||||
|
||||
**1. Reuse.** A component that already does the job is imported, not rebuilt. An island component that does the job but looks different gets a variant in its `variants.ts`, never a new component or a copy.
|
||||
|
||||
**2. Level.** Decide by what the component renders and what it imports, never by its size. First match wins.
|
||||
|
||||
1. It renders no UI of its own, only structure or behavior (a portal, an error boundary, `LoadOnVisible`) → primitive.
|
||||
2. It wraps one native element or draws one visual unit, and uses only other atoms (`Button` shows the `Spinner` atom) → atom: `Button`, `Input`, `Badge`, `Icon`, `Skeleton`.
|
||||
3. It groups atoms for one job and holds no more than UI state, such as open or focused → molecule: `FormField`, `SearchBox`, `EmptyState`.
|
||||
4. It's a distinct section of a screen: it composes molecules, owns interaction state or a context, or is a compound component → organism: `Tabs`, `DataTable`, `ProductRail`.
|
||||
5. It arranges organisms into a page layout through slots and holds no data → template, such as a route's mobile or desktop template.
|
||||
|
||||
Then check the imports: nothing the component imports sits above its level. A component that needs a higher level belongs at that level. Move it up; never import upward.
|
||||
|
||||
**3. Owner.** A component is domain-free when it takes only plain props (strings, numbers, its own prop types, `ReactNode` slots, and callbacks) and imports only island, libs, and tools. It knows a domain when it takes a `*Payload` type, calls a model or an action, reads a store, or shows a feature's text. First match wins.
|
||||
|
||||
1. Only one organism, template, or primitive uses it → that module's private `components/`, shaped like an atom.
|
||||
2. It's a route's mobile or desktop template → that route's `templates/`.
|
||||
3. It knows a domain:
|
||||
- Navigation UI → `platforms/<app>/src/app/navigation/components/`.
|
||||
- Third-party UI, such as a chat widget or its facade → the integration's `components/`.
|
||||
- One route uses it → that route's `organisms/`.
|
||||
- Several routes use it → the `organisms/` of the nearest route level they share, such as `app/(shop)/organisms/`.
|
||||
4. It's a domain-free organism that one route uses → that route's `organisms/`. When a second route needs it, move it to island's `organisms/` at once, as [refactoring.md](refactoring.md#when-and-how) describes; never copy it.
|
||||
5. Otherwise → island, in the folder of its level. Route levels hold only `organisms/` and `templates/`, so every domain-free atom and molecule goes to island at once.
|
||||
|
||||
A piece that knows a domain but is smaller than an organism, such as a price line that formats a `*Payload`, is a private component of the organism that uses it. When other code needs it too, give it plain props instead and put it in island. A component that two products need also moves to island with plain props, because one product never imports another's code.
|
||||
|
||||
## libs, integrations, and tools packages
|
||||
|
||||
```
|
||||
|
|
|
|||
|
|
@ -40,7 +40,7 @@ When to refactor:
|
|||
- Before a feature the code resists: reshape the code until the feature is a small, obvious edit, then make that edit.
|
||||
- While fixing a bug, in the layer that owns the fault ([SKILL.md](../SKILL.md#4-workflow)), and only as far as the fix needs.
|
||||
- In review (see Review comments).
|
||||
- At the third duplication, not the second (the rule of three), because by then the copies show what actually varies. island is the exception: a component that needs a second style gets an island variant at once, never a copy ([SKILL.md](../SKILL.md#3-architecture-rules)).
|
||||
- At the third duplication, not the second (the rule of three), because by then the copies show what actually varies. island is the exception: a component that needs a second style gets an island variant at once, never a copy ([SKILL.md](../SKILL.md#3-architecture-rules)). A route's organism that a second route needs also moves at once, never as a copy: to island when it's domain-free, or to the nearest route level both share when it knows a domain ([project-structure.md](project-structure.md#choosing-where-a-component-goes)).
|
||||
|
||||
Refactor only the code the change touches, unless the plan says otherwise. Record other smells you notice as debt in the PR's trade-offs note.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue