opensource/dify
2
0
Fork 0
mirror of https://github.com/langgenius/dify.git synced 2026-09-05 00:31:19 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(frontend): require component boundary redesigns

Browse Source
This commit is contained in:
Stephen Zhou 2026-09-01 11:48:27 +08:00
parent 9188db85aa
commit 682c76ffbd
No known key found for this signature in database
2 changed files with 18 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
.agents/skills/how-to-write-component/SKILL.md
View File

@ -1,6 +1,6 @@
---
name: how-to-write-component
description: Use when implementing, refactoring, or conducting architecture-oriented reviews of React/TypeScript components involving component ownership, state graphs, props, feature boundaries, data flow, effects, lifecycle/reset behavior, or interaction ownership. Architecture reviews trace the locally owned component tree root-to-leaf and account for every state source and props edge. Do not use for bug, regression, security, or accessibility audits; test-only work; copy-only edits; or styling-only changes.
description: Use when implementing, refactoring, or conducting architecture-oriented reviews of React/TypeScript components involving component ownership, state graphs, props, feature boundaries, data flow, effects, lifecycle/reset behavior, or interaction ownership. Architecture reviews trace the locally owned component tree root-to-leaf, account for every state source and props edge, and re-cut component boundaries from ownership and lifecycle instead of treating current files as fixed. Do not use for bug, regression, security, or accessibility audits; test-only work; copy-only edits; or styling-only changes.
---
# How To Write A Component
@ -50,9 +50,10 @@ Follow this order so component splitting does not precede ownership decisions:
1. **Boundary:** identify the route, tab, workflow, or action surface that owns the behavior and state lifetime.
2. **Data contract:** identify generated API types, URL inputs, Query cache data, and user-input normalization boundaries.
3. **State graph:** list graph inputs, query/mutation nodes, named derived facts, commands, and any scope/reset needs. Keep unrelated local UI state out.
4. **Component contracts:** place data, loading, empty, error, and handlers at the lowest real consumer; define only the props that cross true owner boundaries.
5. **Interaction surfaces:** give forms, menus, dialogs, drawers, and popovers explicit lifecycle owners.
6. **Finish and verify:** remove copied state, unnecessary Effects/wrappers/memoization/nullable coercion, then verify observable behavior at the narrowest sufficient boundary.
4. **Re-cut the component tree:** treat current components and files as evidence, not target constraints. For every current local component, decide whether to keep, split, merge, remove, rename, promote to an owner, or demote to presentation based on state lifetime, behavior ownership, interaction lifecycle, and independently changing visual regions.
5. **Component contracts:** place data, loading, empty, error, and handlers at the lowest real consumer; define only the props that cross true owner boundaries.
6. **Interaction surfaces:** give forms, menus, dialogs, drawers, and popovers explicit lifecycle owners.
7. **Finish and verify:** remove copied state, unnecessary Effects/wrappers/memoization/nullable coercion, then verify observable behavior at the narrowest sufficient boundary.
## Architecture Audit Output
@ -64,8 +65,9 @@ In architecture-audit mode, report:
4. **Props-edge ledger:** every meaningful parent-child props edge and whether each prop is consumed, forwarded, renamed, recomputed, mirrored, or paired with lifecycle state.
5. **Current state graph:** primitive inputs -> queries/mutations -> named facts -> commands -> consumers.
6. **Ownership assessment:** misplaced state, switchboard parents, duplicated owners, mirrored state, prop fan-out, and unclear lifecycle boundaries.
7. **Target architecture:** proposed owners, component contracts, and target state graph.
8. **Migration slices:** ordered refactoring steps with observable verification boundaries.
7. **Component-boundary disposition:** account for every current local component as keep, split, merge, remove, rename, promote to owner, or demote to presentation. Map every current state/workflow owner to a target component, and justify boundary changes by ownership, lifecycle, behavior, or an independently changing visual region.
8. **Target architecture:** redraw the target rendered component tree independently of the current file layout, then report proposed owners, component contracts, reset boundaries, and the target state graph. Do not count a renamed component, facade wrapper, props bag, or provider around the same switchboard as a boundary redesign.
9. **Migration slices:** ordered refactoring steps with explicit component moves/splits/merges and observable verification boundaries.
Do not organize an architecture audit by bug severity unless the user also requests a correctness review. Use compact tables where they make full accounting easier to verify:
@ -75,6 +77,12 @@ Do not organize an architecture audit by bug severity unless the user also reque
| Edge | Prop | Treatment | Real consumer | Assessment |
| --- | --- | --- | --- | --- |
| Current component | Current responsibilities | Target disposition | Target owner(s) | Reason |
| --- | --- | --- | --- | --- |
| Target component | Owned state/workflow | Children | Public contract | Reset boundary |
| --- | --- | --- | --- | --- |
## Patterns To Avoid
- A giant component, switchboard page, or view-model hook that redistributes a large props-and-handlers bag: move single-branch state down and expose focused feature facts and commands for shared workflows.

6
.agents/skills/how-to-write-component/references/ownership.md
View File

@ -11,9 +11,11 @@ For a named component, use it as the audit root. For a refactoring request, use
3. For every value, record its authoritative owner/source, graph role, declaring component, consuming branches, lifetime and reset/isolation requirements, and whether it is local, shared, forwarded, mirrored, or persisted.
4. Inspect every props edge. Mark each prop as consumed by the child, forwarded unchanged, renamed, recomputed, mirrored into local state, or paired with lifecycle fields such as `data/pending/error/retry` and `open/onOpenChange`.
5. Evaluate ownership only after the complete paths are mapped. A value consumed by one branch belongs in the lowest owner in that branch. A parent may own a value when several sibling branches require one live snapshot or coordinated lifecycle. A parent that mainly destructures a workflow hook and redistributes fields is a switchboard, not necessarily the workflow owner.
6. Produce both the current and target architecture before recommending component splits. Group related ownership problems at the highest incorrect owner instead of repeating the same issue for every descendant. Do not replace prop fan-out with a props bag, context, or state graph unless the new boundary becomes the real owner and exposes narrower facts and commands.
6. Produce both the current and target architecture before recommending component splits. Treat the current component and file layout as evidence, not as a constraint on the target tree. Group related ownership problems at the highest incorrect owner instead of repeating the same issue for every descendant. Do not replace prop fan-out with a props bag, context, or state graph unless the new boundary becomes the real owner and exposes narrower facts and commands.
7. Give every current local component an explicit target disposition: keep, split, merge, remove, rename, promote to an owner, or demote to presentation. Map every current state or workflow owner to a target component. A rename, facade wrapper, props bag, or provider around the same switchboard does not count as a new component boundary.
8. Redraw the target rendered tree from the ownership decisions. Split when state lifetime, interaction lifecycle, behavior ownership, or an independently changing visual region establishes a real boundary. Merge or remove components that only forward, rename, or obscure a single owner's contract. Do not split only to reduce line count or make the tree visually symmetrical.
The audit is incomplete until every locally owned rendered path, meaningful props edge, and stateful value is represented in the component tree, state inventory, or props-edge ledger. Correctness bugs may illustrate an ownership defect, but architecture-audit mode does not prioritize or severity-rank bug findings.
The audit is incomplete until every locally owned rendered path, meaningful props edge, and stateful value is represented in the component tree, state inventory, or props-edge ledger; every current local component has a target disposition; and every current state/workflow owner maps to a target component and reset boundary. Correctness bugs may illustrate an ownership defect, but architecture-audit mode does not prioritize or severity-rank bug findings.
## Vertical Modules