Canonical definition
A Canvas component is a package of:
- A React implementation (
index.jsx) - Canvas metadata/schema (
component.yml) - Naming and structure compatibility (
machineName, folder path, story path) - Canvas-compatible props/slots modeling
All four parts are required for the component to be usable in Drupal Canvas.
Minimum contract (MUST)
Every Canvas component MUST satisfy all checks below:
- Component folder exists at
<components-root>/<machine-name>/(use the repository's configured components root, which may be defined in.env) - React implementation exists at
<components-root>/<machine-name>/index.jsx - Metadata exists at
<components-root>/<machine-name>/component.yml component.ymlincludes required top-level keys (name,machineName,status,required,props,slots)- Folder name exactly matches
machineNameincomponent.yml(kebab-case) - A matching story exists at
<stories-root>/<machine-name>.stories.jsx(use the repository's configured stories root) - Props/slots follow Canvas rules (for example, avoid unsupported array-of-object prop shapes; use slots for repeatable complex content)
If any item is missing, the component is incomplete for Canvas usage.
Naming guidance
Use references/naming.md for naming rules and examples.
Skill coordination
Evaluate using companion skills in this order.
canvas-component-metadata
- Use when creating/changing component.yml, props/slots, enums, or fixing prop validation errors.
canvas-component-composability
- Use when designing prop/slot structure, decomposing large components, deciding props vs slots, or modeling repeatable list/grid content.
canvas-styling-conventions
- Use for all styling work: new components, style props, Tailwind token usage, CVA variants, class changes, and prop changes that affect styles.
canvas-component-utils
- Use when rendering formatted HTML text or media via FormattedText and Image.
canvas-data-fetching
- Use when fetching/rendering Drupal content with JSON:API, SWR, includes, and filter patterns.
canvas-component-upload
- Use after implementation is complete and validated, when uploading and recovering from upload failures.