canvas-component-composability
GitHub指导设计Canvas兼容的React组件，提倡分解式优先模式。用于优化组件结构、处理大型组件重构、决定使用Props还是Slots，以及构建可复用的列表或网格内容，确保组件的小而专一和灵活组合。
Trigger Scenarios
Install
npx skills add NeverSight/learn-skills.dev --skill canvas-component-composability -g -y
SKILL.md
Frontmatter
{
"name": "canvas-component-composability",
"description": "Design Canvas-ready React components with slots and decomposition-first patterns. Use when (1) Designing a component's prop\/slot structure, (2) A component is growing too large, (3) Deciding between props vs slots, (4) Refactoring monolithic components, (5) Modeling repeatable list\/grid content. Ensures Canvas compatibility."
}
Prefer small, focused components over monolithic ones with many props. When a component starts accumulating many unrelated props, decompose it into smaller, composable pieces.
Reference map
Load references only as needed:
- Repeatable lists/grids and array-to-slot conversion:
references/repeatable-content.md - Slot interactivity in empty flex/grid containers:
references/repeatable-content.md("Slot container minimum size" section)
Signs a component should be decomposed
Consider breaking up a component when it has:
- More than 6-8 props that serve distinct purposes
- Props for elements that make sense as standalone components (breadcrumbs, titles, metadata, navigation)
- Built-in layout assumptions that limit where the component can be used
- Multiple distinct visual sections that could be reused independently
Use slots for flexible composition
Slots are the primary mechanism for composability. Instead of passing complex data through props, use slots to let parent components accept child components. This matches how Canvas users build pages by placing components inside other components.
When to use slots vs props
| Use slots for | Use props for |
|---|---|
| Variable number of child components | Single, required values (text, URL) |
| Content that users should compose | Configuration options (size, color) |
| Complex nested structures | Simple data (strings, booleans) |
| Content that varies between instances | Content consistent across instances |
Declare slots in component.yml
Declare slots in component.yml and render them as named props in JSX.
For exact slot schema and constraints (map vs [], slot keys, children
handling), follow canvas-component-metadata as the source of truth.
Common decomposition patterns
Page-level elements should be separate components
Elements that appear on many pages but are not always needed together should be separate components.
Extract repeated patterns into small components
When the same combination of elements is repeated, extract it:
- Date + category/tag ->
article-meta - Cover image + download button ->
resource-cover - Label + value pairs ->
metadata-item - Icon + text link ->
icon-link
Use layout components instead of built-in layouts
Do not bake two-column or grid layouts into content components. Use layout components and compose content into them.
When not to decompose
Keep components together when:
- They always appear together and never make sense separately
- They share significant internal state that would be awkward to lift up
- The visual design tightly couples them (for example, overlapping elements, shared backgrounds)
- Decomposition would create components with only 1-2 props that are not useful elsewhere
Version History
- e0220ca Current 2026-07-05 23:00
