Layout primitives

Mosaic

<forma-mosaic>

Asymmetric editorial composition using explicit spans and deterministic narrow-screen reflow.

Authoring tag
<forma-mosaic>
Behavior owner
Application content
Canonical source
patterns/mosaic.html

Purpose

A mosaic is a four-column editorial grid in which the author gives some items more width with data-span="2" or data-span="full". It suits landing pages, report overviews and collections where one feature item leads and others support it. The rhythm is deliberate rather than content-driven: four columns on wide screens, two at 48rem and below, one at 30rem and below. Emphasis comes only from span; the source order is always the reading order. The application decides which items are featured.

Use when

  • An overview needs a featured item and several smaller supporting items with a designed rhythm.
  • Editorial or report content should look composed rather than a uniform grid.
  • The author, not the data volume, decides which items get more space.

Avoid when

  • Items are equal peers whose count varies: use Grid.
  • Column count should follow the container width rather than fixed breakpoints: use Responsive grid.
  • The layout is a marketing card collection inside the site shell: use Card grid.

Behavior to know

  • Four equal minmax(0, 1fr) columns, so items never force overflow.
  • data-span="2" takes half the row; data-span="full" takes the whole row.
  • At one column every span resets to auto, so no item can create an extra track.

Basic example

The smallest correct markup: the canonical pattern from patterns/mosaic.html inside its public tag. Copy this first, then adapt labels, names and state.

Canonical

Minimal mosaic

Rendered from the canonical pattern file.

Featured story

Visual emphasis through span, without semantic reordering.

Research

Supporting item.

Example

Supporting item.

Next step

Full-width region returns to one column on narrow screens.

HTML · Minimal mosaic Raw HTML for HTML · Minimal mosaic
<forma-mosaic class="forma-component-tag">
<section class="forma-mosaic" aria-label="Editorial collection">
  <article class="forma-surface" data-span="2"><h2>Featured story</h2><p>Visual emphasis through span, without semantic reordering.</p></article>
  <article class="forma-surface"><h2>Research</h2><p>Supporting item.</p></article>
  <article class="forma-surface"><h2>Example</h2><p>Supporting item.</p></article>
  <article class="forma-surface" data-span="full"><h2>Next step</h2><p>Full-width region returns to one column on narrow screens.</p></article>
</section>
</forma-mosaic>

Click or tap the code once to select all of it, then copy.

Examples

Scenario

Quarterly report overview

A featured summary takes two of four columns, two supporting items fill the row, and a full-width methodology note closes the section. Reading order is summary, revenue, retention, methodology.

Q3 in summary

Revenue grew 14% on the previous quarter, driven by the Team plan. Support response times improved for the third quarter running.

Revenue

$2.1M, up 14%.

Retention

94% of accounts renewed.

Methodology

Figures are unaudited and exclude one-off professional services revenue.

HTML · Quarterly report overview Raw HTML for HTML · Quarterly report overview
<forma-mosaic class="forma-component-tag">
  <section class="forma-mosaic" aria-label="Q3 report overview">
    <article class="forma-surface forma-stack" data-span="2" aria-labelledby="mosaic-quarterly-report-summary">
      <h2 id="mosaic-quarterly-report-summary">Q3 in summary</h2>
      <p>Revenue grew 14% on the previous quarter, driven by the Team plan. Support response times improved for the third quarter running.</p>
    </article>
    <article class="forma-surface" aria-labelledby="mosaic-quarterly-report-revenue">
      <h2 id="mosaic-quarterly-report-revenue">Revenue</h2>
      <p>$2.1M, up 14%.</p>
    </article>
    <article class="forma-surface" aria-labelledby="mosaic-quarterly-report-retention">
      <h2 id="mosaic-quarterly-report-retention">Retention</h2>
      <p>94% of accounts renewed.</p>
    </article>
    <article class="forma-surface" data-span="full" aria-labelledby="mosaic-quarterly-report-method">
      <h2 id="mosaic-quarterly-report-method">Methodology</h2>
      <p>Figures are unaudited and exclude one-off professional services revenue.</p>
    </article>
  </section>
</forma-mosaic>

Click or tap the code once to select all of it, then copy.

Scenario

Two featured stories

Two items each span two columns to form a balanced first row, followed by four single-column items. A tighter gap is set with --forma-mosaic-space.

How we cut build times in half

Remote caching and smaller test shards.

Designing for 200% zoom

Lessons from auditing every settings page.

Release 5.1

Offline drafts.

Status page changes

Clearer incident timelines.

Hiring

Two platform roles open.

Office hours

Every second Thursday.

HTML · Two featured stories Raw HTML for HTML · Two featured stories
<forma-mosaic class="forma-component-tag">
  <section class="forma-mosaic" style="--forma-mosaic-space: 0.75rem" aria-label="Engineering blog">
    <article class="forma-surface" data-span="2"><h2>How we cut build times in half</h2><p>Remote caching and smaller test shards.</p></article>
    <article class="forma-surface" data-span="2"><h2>Designing for 200% zoom</h2><p>Lessons from auditing every settings page.</p></article>
    <article class="forma-surface"><h3>Release 5.1</h3><p>Offline drafts.</p></article>
    <article class="forma-surface"><h3>Status page changes</h3><p>Clearer incident timelines.</p></article>
    <article class="forma-surface"><h3>Hiring</h3><p>Two platform roles open.</p></article>
    <article class="forma-surface"><h3>Office hours</h3><p>Every second Thursday.</p></article>
  </section>
</forma-mosaic>

Click or tap the code once to select all of it, then copy.

Mobile

Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.

Mobile example

Mobile single column

The report overview at phone width. At 30rem and below the mosaic is one column and every span resets, so items stack in source order at full width.

Viewport width

Frames narrower than the selected width show the component at the width available.

What changes at narrow widths

  • At 30rem and below the grid has one column and data-span items are reset to grid-column: auto.
  • Between 30rem and 48rem there are two columns: data-span="2" then fills the whole row, the same as full.
  • The featured item stays first only because it is first in the source.
  • All items are full width at 320px, so nothing scrolls horizontally and links inside keep full-width targets.
HTML · Mobile single column Raw HTML for HTML · Mobile single column
<forma-mosaic class="forma-component-tag">
  <section class="forma-mosaic" aria-label="Report on the go">
    <article class="forma-surface" data-span="2" aria-labelledby="mosaic-mobile-single-column-summary">
      <h2 id="mosaic-mobile-single-column-summary">Q3 in summary</h2>
      <p>Revenue up 14% on the previous quarter.</p>
    </article>
    <article class="forma-surface" aria-labelledby="mosaic-mobile-single-column-retention">
      <h2 id="mosaic-mobile-single-column-retention">Retention</h2>
      <p>94% renewed.</p>
    </article>
    <article class="forma-surface" data-span="full" aria-labelledby="mosaic-mobile-single-column-method">
      <h2 id="mosaic-mobile-single-column-method">Methodology</h2>
      <p>Unaudited figures.</p>
    </article>
  </section>
</forma-mosaic>

Click or tap the code once to select all of it, then copy.

Baseline

Mobile · 320px

The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.

Viewport width

Frames narrower than the selected width show the component at the width available.

API and configuration

Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.

Native and ARIA attributes
AttributeOnValuesDefaultDescription
data-spandirect child of .forma-mosaic2 | fullabsent (one column)Visual width of an item. Not a data-forma-* hook; it is presentation only.
aria-label.forma-mosaicstring—Names the composed section.
aria-labelledbyitemsid of the item heading—Names each article by its heading.
style.forma-mosaic--forma-mosaic-space: <length>—Per-instance gap override.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-mosaicBlock class—Four-column grid (two at 48rem and below, one at 30rem and below); children get min-inline-size: 0.
--forma-mosaic-spaceCustom propertydefault var(--forma-primitive-spacing-4, 1rem)Gap between items. Default --forma-primitive-spacing-4 (1rem).
[data-span]Attribute hook—On a direct child: 2 spans two columns, full spans all columns. Reset to auto at one column.
Keyboard interaction
KeysResult
Tab / Shift+TabMoves through items in source order; spans never change focus order.

Form behavior

Not a form control.

States

Mosaic states
StateHow it is expressedPresentation
Four columnsviewport above 48remFull editorial rhythm with spans.
Two columnsviewport at or below 48remdata-span="2" and full both fill the row.
One columnviewport at or below 30remSpans reset; items stack in source order.

Accessibility

Forma provides

  • Spans change width only, never DOM, reading or focus order.
  • Columns use minmax(0, 1fr) and children min-inline-size: 0, preventing horizontal overflow.
  • Adds no roles or landmarks.

Your application supplies

  • Order items in the source by importance; span is invisible to assistive technology.
  • Give every item a heading so the structure is navigable.
  • Avoid gaps in the row rhythm by planning spans for the four-column layout; auto-placement will not backfill.

Responsive behavior

  • Viewport breakpoints at 48rem (two columns) and 30rem (one column).
  • Because the column count is fixed per breakpoint, a mosaic in a narrow pane on a wide screen keeps four narrow columns; use Responsive grid for pane-level layouts.
  • Long headings wrap inside their item.

Motion

  • No animation: the grid changes column count instantly at each breakpoint.

Usage guidance

Do

  • Feature one or two items; more spans flatten the emphasis.
  • Plan rows so spans add up to four columns.

Avoid

  • Using span to signal status, severity or rank.
  • Using a mosaic for data-driven collections of unknown size.

Verification specimens

Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.