Build
Section widgetslim: 6 token optionsProposal
The Section widget
Free content = Sections (ours, slim) + columns (Apostrophe's layout widget) + widgets rendered from fragments — the same fragments product pages render from API data.
Use core
Apostrophe columnslayout widget, configuredBuild
Widgets as fragmentsone truth, also for product pagesSettings
Global defaultsno saved blocksNot
Style knobs · own columnsproduct pages stay templatesHow it fits
A page has fixed hero fields and one area. The area only takes Sections. A Section is a band with options; columns and widgets go inside it; every widget renders a fragment.
-
Pagehero fields + one area
-
+ SectionAreaSections only
-
9696Sectionbackground · mobile background · spacing · width · anchor
- WidgetsApostrophe columns · free content · media · CMS pieces
-
Fragmentone template — same HTML for widgets and product pages
{% fragment %}widgetproduct page (API)
Global settings feed some widgets (key figures, contact links, banner texts, legal text) — nothing to rebuild per page.
Try it
The editor's Section panel on the right, the result on the left. Add Columns (Apostrophe's layout widget), a Spacer or any widget from the picker; switch to mobile to see the mobile background, the spacing collapse (96 → 64, 64 → 48) and columns going full width.
What the CMS stores for this section
A real page: Recrutement
The Figma page rebuilt as five Sections — each row shows the settings an editor picks, the desktop band and the mobile band.
Page fields, not a Section. Its anchor buttons come from the sections' anchors.
Columns 6 / 6: rich text | image. The image column's mobile order puts it on top. Grey band, white on mobile.
Primary band: rich text (bracket title + intro) above the job grid. Anchor “Nos offres”.
Columns 4 / 8: rich text (bracket title + intro) left, form right. Grey, white on mobile. Anchor “Candidature spontanée”.
Layout globals, not Sections.
Columns — Apostrophe's own layout widget
We don't build a column system. Inside a Section, editors get Apostrophe's core @apostrophecms/layout-widget (+ layout-column-widget), exactly as on Safari Legends (Apostrophe 4.31): a 12-column grid, columns resized by dragging, spans set per breakpoint (desktop · tablet · mobile). We only configure it. Image + text, heading + list, heading + form: all Columns, with Image / Rich text / the widget in each column. The FAQ keeps its own sticky left side.
Where it goes
Only inside a Section's content area, in a Layout group at the top of the widget picker. The Section still owns background, spacing and width; the layout only splits the content width.
What can go in a column
Widgets that read well at 4–8 columns.
What stays full width (Section level only)
Designed as full-width compositions in Figma (overlays, sticky parts, sliders, card sets).
Configured like Safari Legends — minus the knobs
| Setting | Safari Legends | Ultramarina |
|---|---|---|
| Grid | 12 columns | 12 columns |
| Spans per breakpoint | desktop · tablet · mobile | same (mobile defaults to 12) |
| Minimum span | 1 | 3 (no sliver columns) |
| Per column, per breakpoint | colstart · colspan · rowstart · rowspan · order · show/hide · align | same — core fields (order = image on top on mobile) |
| Nested layouts | one level (nested-layout) | none |
| Column styles | colour · padding · margin · border · shadow | none — tokens come from the Section |
| Column widget groups | Layout · Content · Media · CMS · VCT | the 7 column-friendly widgets above |
The whole configuration: two small overrides of the core modules (same files as Safari Legends: modules/@apostrophecms/layout-widget and modules/@apostrophecms/layout-column-widget).
// modules/@apostrophecms/layout-widget/index.js
export default {
options: { minSpan: 3, defaultSpan: 6 }
};
// modules/@apostrophecms/layout-column-widget/index.js
export default {
fields: {
add: {
content: {
type: 'area',
options: {
widgets: {
'@apostrophecms/rich-text': {}, '@apostrophecms/image': {}, '@apostrophecms/video': {},
'cta-cards': {}, 'facts-table': {}, agencies: {}, form: {}, spacer: {}
}
}
}
}
}
// no `styles`: background and spacing stay on the Section
};
// modules/@apostrophecms/rich-text-widget/index.js — headings are rich-text styles
// { tag: 'h2', label: 'Title', class: 'title' },
// { tag: 'h2', label: 'Title — bracket', class: 'bracket-title' }, …
// (the light part of a bold + light title: an inline style — check the rich-text options)
// section-widget content area, first group
layout: { label: 'Layout', widgets: { '@apostrophecms/layout': {}, spacer: {} } }
One truth: fragments
In Apostrophe we use fragments only — no macros. Every widget's markup lives in a fragment. The widget template is only a render call. Product pages fed by the API render the same fragment with mapped data — one template, one stylesheet, one script, identical HTML wherever the block appears.
CMS editor
Section → widget
Widget fields (data.widget) map 1 : 1 to the fragment params.
Victoury API
Product page template
API data goes through one mapping helper per source, then the same render call.
One truth
{% fragment factsTable(rows, title, variant) %}
- markup
- SCSS (module ui/src)
- JS (if any)
- variants = params
Same HTML + classes on a guide page and on a boat page.
{# modules/facts-table-widget/views/fragments.html — the one truth #}
{% fragment factsTable(rows, title = null, variant = 'spec') %}
<div class="spec-table spec-table--{{ variant }}"> … </div>
{% endfragment %}
{# modules/facts-table-widget/views/widget.html — editor content (no markup here) #}
{% import 'facts-table-widget:fragments.html' as f %}
{% render f.factsTable(data.widget.rows, data.widget.title, data.widget.variant) %}
{# modules/boat-page/views/show.html — Victoury API content #}
{% import 'facts-table-widget:fragments.html' as f %}
{% render f.factsTable(apos.um.specRows(data.piece.boat), 'Caractéristiques du bateau') %}
Rules
- One fragment per visual block;
widget.htmlholds only the render call. - Fragments only — no macros anywhere in Apostrophe. Fragment params = the widget's field names = what the API helpers produce: one contract.
- Product templates never copy markup: a mapping helper turns API data into the params, then renders the fragment.
- Styles and scripts belong to the fragment's module and load once, whoever renders it.
- Variants are params (
variant,layout…), never a second template. - Product templates can't use Apostrophe's layout widget (it lives in editor areas). Where they need image + text, a small
twoColumnsfragment renders the Image and Rich text fragments with the same grid markup — identical HTML, assembled by the template.
Shared between widgets and product pages
| Fragment | As a widget (CMS) | On product pages (API) |
|---|---|---|
| Facts table | formalités ↗ | boat specs ↗ |
| Rich text | content ↗ | boat text ↗ centre ↗ |
| Notice | notice ↗ | À savoir ↗ |
| FAQ / accordion | FAQ ↗ | cabins ↗ |
| Gallery · Video | gallery ↗ video ↗ | trip page ↗ |
| Testimonials | testimonials ↗ | trip page ↗ |
| Image + Rich text (two-column) | image + text ↗ (Columns) | trip page ↗ (two-column fragment) |
Widgets that go in a Section
Each one is a fragment with its own inner layout — the Section owns the space around it. Variants are params. The yellow badge marks fragments product pages render too.
Layout
Columns (Apostrophe core)
@apostrophecms/layout-widget · 12-col grid · spans per breakpoint (6/6, 4/4/4, 8/4…)
Spacer
space inside a section: S 24 · M 48 · L 96 (mobile 16 · 32 · 48) — breaks content without a new band
Free content
Rich text
same fragment on product pages
text and every heading: bracket title · bold + light title · notice box — also the left side of any left / right layout
FAQ
same fragment on product pages
full width, keeps its own left side (title, intro, button) — sticky on scroll, the only sticky element in the free-content design
Media
Image
same fragment on product pages
locked crop (682 × 448 for image + text), rounded corners, caption — image + text = Columns 6 / 6 with Rich text
CMS pieces — picked, not typed
Global defaults
What repeats across pages is site data — set once, read by the widgets. No saved blocks needed.
Key figures
The 4 numbers every Key figures widget shows.
Contact links
Devis · Appel · RDV — CTA strip, mobile quick actions.
Banner texts
“Organisons ensemble votre voyage / croisière” presets.
Legal text
The RGPD paragraph under every form.
Not in this system: our own column widgets (we use Apostrophe's), saved blocks, style knobs on sections or columns (colour pickers, free pixel spacing, borders, shadows). Product pages stay fixed templates — they reuse the fragments, not the Section.