Skip to content

Limitations

What the module deliberately doesn't do, and known rough edges.

Overview

What the module deliberately does not do, known rough edges, and upgrade caveats. Feature-specific limitations (Motion's animation contract, AI's blueprint constraints) live on their own pages and are linked below rather than repeated.

Deliberate scope boundaries

  • No UI to create a custom framework profile. FrameworkProfileManager::saveLiveConfigAsProfile() exists and user profiles are supported by config storage, but no admin form calls it. Only the three shipped profiles (Custom, Bootstrap 5, Tailwind) are selectable from the settings page.
  • Section/Column layout always renders through CSS Grid, under every framework profile — see Frameworks → Columns/Grid always use CSS-grid. A framework's own grid system (Bootstrap's .row/.col) is never used for layout mechanics; framework classes ride alongside it, not instead of it.
  • The Motion engine contract does not offer: nested timelines, a function-per-target/random value grammar, stagger grid/amount modes, width: auto sizing, two-token scroll-position grammar, pointer-follow easing, shared-element transitions, motion-path animation, or shape morphing. Properties locked by an author's !important rule cannot be animated. Full list: Motion engine → Known limitations.
  • AI section building only ever writes governed, validated plans — it never generates markup, and a blueprint's sections are the hard structure; a variation may reorder or omit them but never invent a new one. See AI → Governance and → Blueprints.
  • AI background video is not offered to the model — nothing grounds it with real video URLs, so editors set video backgrounds themselves.

Rough edges

  • Disabling a style plugin does not touch already-stored values. enabled_plugins/isPluginEnabled() is only checked when building the editing form; the render pipeline (CanvasBuilderTrustedCallbacks) never checks it. Turning off Background video, for example, hides the control from the editor, but a component that already had a background video keeps rendering it on the front end until an editor removes the value by hand.
  • gap_classes is legacy. The settings form no longer writes it; gap resolves from layout_maps.<component>.gap instead. The key is retained in schema and profile snapshots only for backward compatibility with existing saved profiles.
  • A Section or Column Motion timeline does not survive duplicating that Section. Component-level targets do; re-add the timeline on the copy. See Motion → Important notes.
  • Content saved before a bug fix can keep the old, wrong value until an editor re-touches it — there is no retroactive data migration for a behavior fix (as opposed to a schema/key-rename migration, which does get an update hook). Check CHANGELOG.md's ### Fixed entries for a release before assuming existing content already reflects a listed fix.

Upgrade caveats

Every breaking change and required manual step is documented under the relevant version's ### Upgrading heading in CHANGELOG.md — read it before deploying a new version, not after. As of 1.0.0-alpha4 in development:

  • The anim_* → motion_* storage rename is a breaking migration with its own recovery command (drush canvas-builder:migrate-motion-keys) for a database restored from before it ran.
  • A config-managed site (drush deploy, or updb/cim in CI) must update its sync directory before deploying, not after — importing a stale sync directory can silently undo the migration. drush canvas-builder:repair-alpha4 recovers from that state.
  • canvas_builder_ai gained hard dependencies on drupal/key plus core media/file/image. A site already running the AI submodule updates straight past the new dependency check (Drupal only enforces dependencies at install time), and stock-photo sourcing degrades gracefully — every provider reports unavailable — rather than fataling.

Not yet verified

TODO — the following claims need an explicit check before they can be stated here with confidence: behavior when two site administrators edit canvas_builder.settings concurrently; behavior of a very large enabled_plugins_overrides table (hundreds of components) on settings-form load time; whether a custom style type (§1 of Custom style types) is exercised by any automated compatibility test across a Canvas core upgrade.