Canvas Grid Section

A.I disclaimer: A.I was used to move from a POC to the complete module, including documentation, use cases and extra necessary code. The architectural decisions were made by myself.

The problem

When using Canvas, you normally get a list of components provided by a theme or module, like cards, buttons, hero banners, ping-pong, etc. However, they normally don't address layout, or they accumulate that responsibility individually, where each component handles viewports, spacings, sizes, and so on. That can create a lack of consistency with the original design, bugs on different viewports, side effects, extra code to maintain, and layout responsibility that should not belong to each component. The principle is: components should be responsible for their style and behaviour, and layout is not their responsibility. A component should be able to adapt to any parent size properly.

A very common solution is to create those layout-specific components, normally called Sections. They are responsible to establish the layout and keep available slots where other components can be used. That is a good start, but it has some limitations:

1. They are presets of row and columns, not a flexible solution
2. They can't adapt to a new layout without extra code.
3. They can't be nested.
4. They don't allow inner components to adapt to their sizes, so the component keep looking to viewport's size.
5. They can't be easily used outside of Canvas.

The Solution

CGS solution is very simple at it's core: Two SDC components, Section and Column. That is it. The Section is a CSS Grid that controls semantics, spacing, 12 columns grid, and sizes. Column is a grid children that knows which column it starts on and how many it spans, separately on phones, tablets and desktops.
Because of this architecture, any layout is a combination of Columns, not a preset.

They are simple SDCs - and nothing else

When I start to draft the solution, one of my goals was to ensure I don't overwrite Canvas or SDCs. They needed to be easy to use, not only on Canvas, but also as a normal SDC, meaning a developer should be able to use them in TWIG templates or render arrays. Another important rule was about properties: no custom properties! They need to work with what Drupal Core and Canvas provides, like Section's background color being linked to Canvas Brand Kit.

Columns are CSS Containers

The Column component is a CSS Container meaning that you can containter queries to make your SDCs to adapt to it's size.

Built-in Grid View

Normally you have a Grid Layout that was used by the designer to properly align items and components. Figma uses it and the Section component has a "Show grid" property that adds the 12 columns overlay so you and the user can precisly view it when editing content to macth the design.

No Framework Dependency

Because the nature of the solution - a section and column components, aiming to be global - I didn't want to rely on any framework as a dependency. The developer should be able to use it with any CSS framework, that is why bto components uses standard CSS Grid.

Features

• Two Canvas components, Section and Column. A Section is a full-width band of the page that holds the grid. Columns go inside it and hold any content.
• Per-viewport placement. Each Column has its own start and span for Mobile, Tablet, Desktop and Large Desktop, set with a visual column picker in the Canvas editor. Stack columns on phones, place them side by side on tablets, give one more room on desktops.
• Any layout without presets. Mix widths, offset or center a Column, or change the visual order per screen size.
• Nested grids. Put a Section inside a Column to split that Column into its own 12-column grid, with Columns that place themselves the same way. Turn on Remove Gutter on the inner Section so the side spacing isn't doubled.
• Every Column is a CSS container. Cards, teasers and other components inside a Column can adapt to the Column's width with @container queries rather than the screen's, so the same component works in a wide Column and a narrow one.
• The editor and the live page always agree. The grid switches at your theme's Canvas viewport widths, the same ones the Canvas editor previews.
• Section options: Boxed (centered, limited width) or Edge to Edge, background color or image, the HTML tag (section, header, aside and more), an anchor ID, safe custom attributes such as aria-label, and spacing for the gap, margins and padding.
• One spacing scale. Spacing is chosen in steps from 1 to 5 instead of free values, so every section on the site keeps the same rhythm.
• Theme-friendly. No CSS framework. Widths and spacing are CSS custom properties that any theme can override, including themes built with Tailwind CSS.
• Accessibility built in. Right-to-left languages mirror automatically, decorative backgrounds are hidden from screen readers, and a background color sets color-scheme so a theme can keep text readable on it.
• Usable from code. The same components render from Twig and PHP render arrays, in templates outside Canvas.

Use it when you build landing pages, marketing pages or any page in Canvas that needs columns, and you want editors to arrange content freely without waiting for a developer to add another layout.

Video

here is a short video showing the concept Canvas Grid Section Video

Post-Installation

There is no configuration page. After installing:

1. Open a page in the Canvas editor. Section and Column are now in the component library.
2. Insert one of the five patterns the module adds (Two Columns, Three Columns, Four Columns, Content and Sidebar, Sidebar and Content), or add a Section and put Columns in it.
3. Select a Column and set its start and span for each viewport. Switch the editor's preview between viewports to see each layout.

The patterns are starting points made of ordinary Columns, not presets: change any Column and the layout follows. They belong to your site once created, and module updates never change them.

Themers can match the site's design by overriding a few CSS custom properties, such as --cgs-space and --cgs-max-width, and can change the breakpoints in the theme's {theme}.canvas.yml. Clear the cache after changing breakpoints.

Additional Requirements

• Drupal 11.3 or later, on PHP 8.3 or later
• Drupal Canvas 1.11 or later

No external libraries or CSS frameworks are needed.

Recommended modules/libraries

None. The module works with any theme. A theme with its own {theme}.canvas.yml viewports gets a grid that switches at the same widths.

Community Documentation

• README
• Section and Column: every option, with examples, including a Section nested in a Column
• Theming: spacing, widths and breakpoints
• Using it in code: Twig and render arrays
• Patterns and Accessibility