# Canvas Page Definition

> A Claude skill from drupal-canvas/skills.

- **Type:** Skill
- **Install:** `agentstack add skill-drupal-canvas-skills-canvas-page-definition`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [drupal-canvas](https://agentstack.voostack.com/s/drupal-canvas)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [drupal-canvas](https://github.com/drupal-canvas)
- **Source:** https://github.com/drupal-canvas/skills/tree/main/skills/canvas-page-definition

## Install

```sh
agentstack add skill-drupal-canvas-skills-canvas-page-definition
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

## Canonical definition

A Canvas page is a JSON page spec stored in the repository's configured
`pagesDir`.

Workbench uses these files for local page previews, and the Canvas CLI
`push`/`pull` workflow uses them to sync pages between the local project and
Drupal Canvas.

Page specs should fully mirror what authors can build in Drupal Canvas.

## Minimum contract (MUST)

Every Canvas page MUST satisfy all checks below:

- The page file exists in the configured pages directory (`pagesDir` in
  `canvas.config.json`; default `./pages`)
- The page file is a JSON object
- The page includes a non-empty `title`
- The page includes a `path` that starts with `/` and is unique within the
  project
- The page includes an `elements` object with at least one element
- Every element in `elements` includes a discovered component `type`
- Any `slots` entries reference element IDs defined in the same file

If any item is missing, the page is incomplete for Canvas usage.

## Location and naming

Author the canonical local page specs in the configured pages directory
(`pagesDir` in `canvas.config.json`). If `pagesDir` is not set, Workbench
defaults to the top-level `pages/` directory.

- Place each page in `/.json`
- Keep page files flat in the configured pages directory; nested files are
  ignored
- Use a stable, descriptive filename that mirrors the page title in a
  filename-safe way
- Use a human-readable `title` inside the JSON file for the actual page title

Examples:

- `/homepage.json`
- `/about-us.json`

Treat files in the configured `pagesDir` as the source of truth for local page
definitions that can be previewed in Workbench and synced with Canvas via the
CLI.

Authored page work is incomplete unless the page is previewable from the
configured `pagesDir` and ready for validation.

## Page file format

Each page file must be a JSON object with:

- `title`: the actual page title
- `path`: the page's URL path (e.g., `/about`). Must start with `/` and be
  unique within the project. Other pages link to this page using this value.
- `elements`: an object of authored page elements

The page file may also include:

- `description`: a short plain-text summary of the page. Surfaced as page
  metadata (e.g., for listings or SEO). Leave as an empty string if not set.

Each entry in `elements` must include:

- `type`: a discovered component type

Each entry may also include:

- `props`: root props for that element
- `slots`: a map of slot names to arrays of element IDs from the same file

Workbench preserves `elements` insertion order when building the page. Put
top-level sections in the order you want them rendered.

Use the discovered machine-readable component type for each element, such as
`card`, `heading`, or `js.hero`, depending on what Workbench finds in the local
project.

## Linking between pages

To link to another page in the project, reference the target page's `path`.

## Example

```json
{
  "title": "About",
  "path": "/about",
  "description": "",
  "elements": {
    "hero": {
      "type": "js.hero",
      "props": {
        "heading": "About us",
        "text": "Learn how our team plans, builds, and ships Canvas experiences.",
        "layout": "left_aligned"
      }
    },
    "spacer-lg": {
      "type": "js.spacer",
      "props": {
        "height": "large"
      }
    },
    "body-section": {
      "type": "js.section",
      "props": {
        "width": "normal"
      },
      "slots": {
        "content": ["body-copy"]
      }
    },
    "body-copy": {
      "type": "js.text",
      "props": {
        "content": "Canvas pages should use real component composition rather than custom page wrappers."
      }
    }
  }
}
```

Use stable, descriptive element IDs unless you are intentionally preserving IDs
from another source such as an exported Canvas page.

## Image props in pages

When a component prop is defined as an image in `component.yml`, page JSON must
pass that prop as a single image object. Match the component prop name exactly
and use the Canvas image shape inside `props`.

```json
{
  "type": "js.card",
  "props": {
    "image": {
      "src": "https://placehold.co/400x300/png",
      "alt": "Card placeholder image",
      "width": "400",
      "height": "300"
    },
    "heading": "Featured card"
  }
}
```

Supported authored page image sources:

- External `http://` or `https://` URLs
- `data:image/...` URLs

Do not use local file paths in page JSON. CLI media upload from local files is
not supported.

If page media reconciliation or page sync adds resolved image data such as
`width`, `height`, or `_provenance`, preserve that data unless you are
intentionally changing the image source.

## Format constraints

The page-spec format only supports discovered component elements plus their
`props` and `slots`.

That means page specs cannot directly represent:

- Hand-written React wrappers such as `PageLayout`
- Raw HTML layout elements such as `` or ``
- `className`-driven spacing or custom wrapper styling
- Inline code duplication of an existing component's markup

If you need a layout primitive, look for an existing component first. If none
exists, create it as a component before using it in a page spec.

## Validation

Validate every authored page before finishing.

```bash
npx canvas validate
```

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [drupal-canvas](https://github.com/drupal-canvas)
- **Source:** [drupal-canvas/skills](https://github.com/drupal-canvas/skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-drupal-canvas-skills-canvas-page-definition
- Seller: https://agentstack.voostack.com/s/drupal-canvas
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.