VERIFICATION-0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF
Frame
<forma-frame>
Constrains media to an explicit aspect ratio while keeping content contained.
- Authoring tag
<forma-frame>- Category
- Layout primitives
- 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.
Minimal frame
Rendered from the canonical pattern file.
<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
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 -
Bookcase -
Desk chair
<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.
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.
<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 article image
A 4 / 3 lead image and caption at phone width. The frame scales down with the column and keeps its proportion.
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.
<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.
Mobile · 320px
The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.
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.
| Attribute | On | Values | Default | Description |
|---|---|---|---|---|
style | .forma-frame | --forma-frame-ratio: <ratio> | 16 / 9 | Per-instance aspect ratio, for example 1 / 1 or 4 / 3. |
alt | img | string | — | Required on images. Describe the content; use alt="" only when the image is decorative and the caption carries the meaning. |
role | svg | img | — | Makes an inline SVG a single named image. |
aria-labelledby | svg | id of the SVG title | — | Names the SVG image from its title element. |
aria-label | list wrapper | string | — | Names a grid of framed images. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-frame | Block class | — | Figure wrapper with zero margin. Declares the ratio variable. |
.forma-frame__media | Element class | — | Box with aspect-ratio: var(--forma-frame-ratio) and hidden overflow. |
--forma-frame-ratio | Custom property | default 16 / 9 | Aspect 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
| State | How it is expressed | Presentation |
|---|---|---|
| Framed | img, video, iframe or svg as a direct child of .forma-frame__media | Media 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-ratioif 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__mediaare 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.