Ultramarina Design system View site

Proposal

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.

Build

Section widgetslim: 6 token options

Use core

Apostrophe columnslayout widget, configured

Build

Widgets as fragmentsone truth, also for product pages

Settings

Global defaultsno saved blocks

Not

Style knobs · own columnsproduct pages stay templates

How 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.

  1. Pagehero fields + one area
  2. + Section
    AreaSections only
  3. 9696
    Sectionbackground · mobile background · spacing · width · anchor
  4. WidgetsApostrophe columns · free content · media · CMS pieces
  5. {% fragment %}widgetproduct page (API)
    Fragmentone template — same HTML for widgets and product pages

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.

Nos offres
next section
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.

Section settingsDesktop 1512Mobile 390
Hero

Page fields, not a Section. Its anchor buttons come from the sections' anchors.

Nos offresCandidature spontanée
Nos offresCandidature…
1 · Presentation

Columns 6 / 6: rich text | image. The image column's mobile order puts it on top. Grey band, white on mobile.

  • grey → white on mobile
  • space 96 / 64
  • container
  • columns · 6-6 → rich · plain | image
96
64
64
48
2 · Key figures

Site figures from global settings.

  • grey
  • space 64 / 120
  • container
  • figures
64
120
48
64
3 · Staff quotes

Full-bleed photo band — the widget brings its own background.

  • white
  • space 0 / 0
  • full
  • staff
4 · Job offers

Primary band: rich text (bracket title + intro) above the job grid. Anchor “Nos offres”.

  • primary
  • space 96 / 96
  • container
  • # Nos offres
  • rich · bracket
  • jobs
96
96
# Nos offres
64
64
# Nos offres
5 · Application form

Columns 4 / 8: rich text (bracket title + intro) left, form right. Grey, white on mobile. Anchor “Candidature spontanée”.

  • grey → white on mobile
  • space 96 / 96
  • container
  • # Candidature spontanée
  • columns · 4-8 → rich · bracket | form · application
96
96
# Candidature spontanée
64
64
# Candidature spontanée
Pre-footer + footer

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.

48
48
6 / 6 — Image + text, image left — image | rich text (title, text, list, buttons); stacks image first. Columns go full width on mobile. Figma ↗ mobile ↗
48
48
6 / 6 — Image + text, image right — rich text | image; the image column's mobile order (1) puts it on top, as in Figma. Columns go full width on mobile. Figma ↗ mobile ↗
48
48
6 / 6 — Agencies — rich text (bracket title, intro, button) | Agencies cards. Columns go full width on mobile. agencies ↗
48
48
4 / 8 — Form — rich text (bracket title, intro) | Form. Columns go full width on mobile. quote form ↗ application ↗
48
48
4 / 4 / 4 — free arrangement — three rich texts. Columns go full width on mobile.

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

  • Rich text
  • Image
  • Video
  • Calls to action
  • Facts table
  • Agencies
  • Form
  • Spacer

Widgets that read well at 4–8 columns.

What stays full width (Section level only)

  • FAQ (own sticky left side)
  • Banner
  • Key figures
  • Gallery
  • Articles
  • Testimonials
  • Staff quotes
  • Team
  • Job offers

Designed as full-width compositions in Figma (overlays, sticky parts, sliders, card sets).

Configured like Safari Legends — minus the knobs

SettingSafari LegendsUltramarina
Grid12 columns12 columns
Spans per breakpointdesktop · tablet · mobilesame (mobile defaults to 12)
Minimum span13 (no sliver columns)
Per column, per breakpointcolstart · colspan · rowstart · rowspan · order · show/hide · alignsame — core fields (order = image on top on mobile)
Nested layoutsone level (nested-layout)none
Column stylescolour · padding · margin · border · shadownone — tokens come from the Section
Column widget groupsLayout · Content · Media · CMS · VCTthe 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.

map to props

One truth

{% fragment factsTable(rows, title, variant) %}
  • markup
  • SCSS (module ui/src)
  • JS (if any)
  • variants = params
render

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

  1. One fragment per visual block; widget.html holds only the render call.
  2. Fragments only — no macros anywhere in Apostrophe. Fragment params = the widget's field names = what the API helpers produce: one contract.
  3. Product templates never copy markup: a mapping helper turns API data into the params, then renders the fragment.
  4. Styles and scripts belong to the fragment's module and load once, whoever renders it.
  5. Variants are params (variant, layout…), never a second template.
  6. Product templates can't use Apostrophe's layout widget (it lives in editor areas). Where they need image + text, a small twoColumns fragment renders the Image and Rich text fragments with the same grid markup — identical HTML, assembled by the template.

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

Video

same fragment on product pages

—

CMS pieces — picked, not typed

Staff quotes

default · big title

Agencies

cards · rows — the heading goes in a rich-text column next to it (Columns 6 / 6)

Global defaults

What repeats across pages is site data — set once, read by the widgets. No saved blocks needed.

Contact links

Devis · Appel · RDV — CTA strip, mobile quick actions.

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.