Layout primitives

Frame

<forma-frame>

Constrains media to an explicit aspect ratio while keeping content contained.

Authoring tag
<forma-frame>
Behavior owner
Native CSS
Canonical source
patterns/frame.html

Purpose

A frame reserves a box of a declared aspect ratio and fills it with an image, video or SVG, cropping with object-fit: cover rather than distorting. Because the box has a ratio before the media loads, the page does not shift when the image arrives. The frame is a figure, so a caption can travel with the media. It owns proportion and containment only; the media itself, its alt text and its caption are content.

Use when

  • Images of different source sizes must line up at one proportion, such as thumbnails in a grid.
  • Space should be reserved for media before it loads to avoid layout shift.
  • A figure needs a caption associated with its media.

Avoid when

  • The whole image must remain visible (diagrams, screenshots with text at the edges): cover cropping may cut content, so use a plain img or figure.
  • The media is a data visualization with its own layout: use Diagram.
  • The image is a selectable option: use Image choice.

Behavior to know

  • Default ratio is 16 / 9; any ratio is set with --forma-frame-ratio.
  • Media is cropped from the center; nothing overflows the frame.
  • The figure has no margin, so it sits flush in stacks and grids.

Basic example

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

Canonical

Minimal frame

Rendered from the canonical pattern file.

Frame preserves a declared media proportion without making the content itself a component.
HTML · Minimal frame Raw HTML for HTML · Minimal frame
<forma-frame class="forma-component-tag">
<figure class="forma-frame">
  <div class="forma-frame__media"><img src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='800' height='450'%3E%3Crect width='100%25' height='100%25' fill='%23ddd'/%3E%3C/svg%3E" alt=""></div>
  <figcaption>Frame preserves a declared media proportion without making the content itself a component.</figcaption>
</figure>
</forma-frame>

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

Examples

Scenario

Square product thumbnails

Product photos of different source proportions shown as 1 / 1 frames in a grid. Every thumbnail lines up; each image keeps meaningful alt text and the caption names the product.

  • Oak desk with two drawers, front view
    Oak desk
  • Tall bookcase with five shelves
    Bookcase
  • Grey fabric desk chair
    Desk chair
HTML · Square product thumbnails Raw HTML for HTML · Square product thumbnails
<forma-frame class="forma-component-tag">
  <ul class="forma-grid" role="list" aria-label="Recently viewed" style="--forma-grid-min: 9rem">
    <li>
      <figure class="forma-frame" style="--forma-frame-ratio: 1 / 1">
        <div class="forma-frame__media"><img src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='600' height='400'%3E%3Crect width='100%25' height='100%25' fill='%23c9c4b8'/%3E%3C/svg%3E" alt="Oak desk with two drawers, front view"></div>
        <figcaption>Oak desk</figcaption>
      </figure>
    </li>
    <li>
      <figure class="forma-frame" style="--forma-frame-ratio: 1 / 1">
        <div class="forma-frame__media"><img src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='300' height='500'%3E%3Crect width='100%25' height='100%25' fill='%23b5b0a4'/%3E%3C/svg%3E" alt="Tall bookcase with five shelves"></div>
        <figcaption>Bookcase</figcaption>
      </figure>
    </li>
    <li>
      <figure class="forma-frame" style="--forma-frame-ratio: 1 / 1">
        <div class="forma-frame__media"><img src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='500' height='500'%3E%3Crect width='100%25' height='100%25' fill='%23ddd8cc'/%3E%3C/svg%3E" alt="Grey fabric desk chair"></div>
        <figcaption>Desk chair</figcaption>
      </figure>
    </li>
  </ul>
</forma-frame>

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

Scenario

Wide banner with inline SVG

A 21 / 9 frame holding an inline SVG illustration. The SVG has role="img" and a title, so it is announced as one image with a name, and it draws with currentColor so it follows the theme and forced colors.

Three connected servers representing a replicated database
Replication keeps three copies of every write across availability zones.
HTML · Wide banner with inline SVG Raw HTML for HTML · Wide banner with inline SVG
<forma-frame class="forma-component-tag">
  <figure class="forma-frame" style="--forma-frame-ratio: 21 / 9">
    <div class="forma-frame__media">
      <svg viewBox="0 0 210 90" role="img" aria-labelledby="frame-inline-svg-banner-title" preserveAspectRatio="xMidYMid slice">
        <title id="frame-inline-svg-banner-title">Three connected servers representing a replicated database</title>
        <rect x="20" y="30" width="40" height="30" fill="currentColor"/>
        <rect x="85" y="30" width="40" height="30" fill="currentColor"/>
        <rect x="150" y="30" width="40" height="30" fill="currentColor"/>
        <path d="M60 45 H85 M125 45 H150" stroke="currentColor" stroke-width="3"/>
      </svg>
    </div>
    <figcaption>Replication keeps three copies of every write across availability zones.</figcaption>
  </figure>
</forma-frame>

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 article image

A 4 / 3 lead image and caption at phone width. The frame scales down with the column and keeps its proportion.

Viewport width

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

What changes at narrow widths

  • The frame is as wide as its parent, so at 320px the image is 320px minus the page gutter and its height follows the 4 / 3 ratio.
  • The reserved ratio prevents content below from jumping when the image loads on a slow connection.
  • The caption wraps under the image at any width; it never overlaps the media.
  • In landscape the frame widens and grows taller in proportion; cropping stays centered.
HTML · Mobile article image Raw HTML for HTML · Mobile article image
<forma-frame class="forma-component-tag">
  <figure class="forma-frame" style="--forma-frame-ratio: 4 / 3">
    <div class="forma-frame__media"><img src="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='1200' height='800'%3E%3Crect width='100%25' height='100%25' fill='%23c9c4b8'/%3E%3C/svg%3E" alt="Warehouse floor with packing stations along the wall"></div>
    <figcaption>The new packing line in the Rotterdam warehouse handles 4,000 orders a day.</figcaption>
  </figure>
</forma-frame>

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
style.forma-frame--forma-frame-ratio: <ratio>16 / 9Per-instance aspect ratio, for example 1 / 1 or 4 / 3.
altimgstring—Required on images. Describe the content; use alt="" only when the image is decorative and the caption carries the meaning.
rolesvgimg—Makes an inline SVG a single named image.
aria-labelledbysvgid of the SVG title—Names the SVG image from its title element.
aria-labellist wrapperstring—Names a grid of framed images.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-frameBlock class—Figure wrapper with zero margin. Declares the ratio variable.
.forma-frame__mediaElement class—Box with aspect-ratio: var(--forma-frame-ratio) and hidden overflow.
--forma-frame-ratioCustom propertydefault 16 / 9Aspect ratio of the media box. Default 16 / 9.

Form behavior

Not a form control.

No keyboard interaction beyond the browser defaults for the elements in the markup.

States

Frame states
StateHow it is expressedPresentation
Framedimg, video, iframe or svg as a direct child of .forma-frame__mediaMedia fills the box and is cropped with object-fit: cover.

Accessibility

Forma provides

  • Uses figure and figcaption, so the caption is associated with the media.
  • Reserves space before load, avoiding layout shift that moves content under the user's pointer or focus.
  • Adds no roles to the media.

Your application supplies

  • Provide alt text that describes what matters in the image, accounting for any cropping.
  • Do not frame media whose meaning depends on its edges; cover cropping can remove it.
  • Give video captions and controls through the native video element.

Responsive behavior

  • Fluid width: the frame fills its parent and height follows the ratio.
  • No breakpoints; change the ratio per context with --forma-frame-ratio if a different proportion suits narrow screens.
  • Media cannot overflow the frame, so large images never cause horizontal scrolling.

Motion

  • No animation: the frame is static. Video playback is controlled by the native element and the user.

Usage guidance

Do

  • Choose one ratio per collection so items align.
  • Keep the subject of photos centered, since cropping is centered.

Avoid

  • Framing screenshots or charts that contain text near the edges.
  • Putting the media inside extra wrappers; only direct children of .forma-frame__media are sized.

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.