canvas-component-definition

Canonical definition

A Canvas component is a package of:

1. A React implementation (index.jsx)
2. Canvas metadata/schema (component.yml)
3. Naming and structure compatibility (machineName, folder path, story path)
4. 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.yml includes required top-level keys (name, machineName, status, required, props, slots)
• Folder name exactly matches machineName in component.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.

1. canvas-component-metadata
   • Use when creating/changing component.yml, props/slots, enums, or fixing prop validation errors.
2. canvas-component-composability
   • Use when designing prop/slot structure, decomposing large components, deciding props vs slots, or modeling repeatable list/grid content.
3. 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.
4. canvas-component-utils
   • Use when rendering formatted HTML text or media via FormattedText and Image.
5. canvas-data-fetching
   • Use when fetching/rendering Drupal content with JSON:API, SWR, includes, and filter patterns.
6. canvas-component-upload
   • Use after implementation is complete and validated, when uploading and recovering from upload failures.