A code sample shows a command, configuration file or snippet on a public page. The canonical form is a figure.forma-code-figure with a figcaption and a pre.forma-code holding code. The pre is a bounded scroll container on the inverse surface: long lines scroll inside it instead of widening the page, and tabindex="0" lets keyboard users focus it and scroll with the arrow keys. There is no copy button and no syntax highlighting; those would need application script and validated token roles (GAP-MKT-09).
Use when
Showing install commands, lock files or configuration on a product or documentation page.
The sample must be copied exactly, so lines must not wrap.
Pairing an install procedure in Steps with the command it runs.
Avoid when
A short identifier or command inside a sentence: use inline code in Prose.
Showing changes between two versions: use Diff viewer.
Lines keep their formatting (pre) and scroll horizontally inside the block; tab-size is 2.
The block uses the inverse surface and inverse text on every page tone, so it reads the same inside toned sections.
The caption is visible, in the mono label size, and names the scroll region through aria-labelledby.
Basic example
The smallest correct markup: the canonical pattern from patterns/code-sample.html inside its public tag. Copy this first, then adapt labels, names and state.
Canonical
Minimal code sample
Rendered from the canonical pattern file.
Pin Forma in forma.lock
forma 0.3.0
repository kemiller2002/forma
destination assets/forma
asset forma-marketing.css sha256:<digest>
<forma-code-sample class="forma-component-tag">
<div class="forma-site">
<article class="forma-prose">
<h3>Deploy with pinned assets</h3>
<p>The workflow installs exactly what the lock pins before the site build.</p>
<figure class="forma-code-figure">
<figcaption id="code-sample-workflow-file-caption">.github/workflows/deploy-pages.yml</figcaption>
<pre class="forma-code" tabindex="0" aria-labelledby="code-sample-workflow-file-caption"><code>jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: kemiller2002/forma/actions/install-presentation@v0.3.0
with:
lock: forma.lock
- run: ./build.sh</code></pre>
</figure>
</article>
</div>
</forma-code-sample>
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
Phone lock file
A lock file with a long checksum line at phone width.
Frames narrower than the selected width show the component at the width available.
What changes at narrow widths
The block is capped at 100% of its column; long lines such as checksums scroll inside it and never cause page-level horizontal scrolling.
Swipe horizontally inside the block to read long lines; keyboard users focus it with Tab and scroll with the arrow keys.
Padding comes from the fluid block-space token, so more of each line is visible on narrow screens.
The caption wraps above the block; landscape orientation shows more of each line without changing layout.
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.
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
Attribute
On
Values
Default
Description
tabindex
pre.forma-code
0
—
Makes the scroll region focusable so keyboard users can scroll overflowing lines.
aria-labelledby
pre.forma-code
id of the figcaption
—
Gives the focusable region the caption as its name, so focus does not land on an unnamed stop.
id
figcaption
string
—
Referenced by the pre's aria-labelledby.
CSS hooks (derived from dist/all.css)
Hook
Kind
Values or default
Description
.forma-code
Block class
—
The pre: bounded (max-inline-size: 100%), scrolls on overflow, inverse surface and text, mono small type, tab-size: 2. A code inside inherits its color and size and does not wrap.
.forma-code-figure
Block class
—
The figure wrapper. Removes the default figure margin; its figcaption becomes a muted mono label above the block.
Keyboard interaction
Keys
Result
Tab / Shift+Tab
Focuses the code block (tabindex=0); the shell's focus ring surrounds it.
Arrow keys, Page Up / Page Down, Home / End
Native scrolling of the focused block when its content overflows.
States
Code sample states
State
How it is expressed
Presentation
Fits
content within the column
No scrollbar; the block is still focusable.
Overflowing
overflow: auto
Long lines scroll horizontally inside the block.
Focus
:focus-visible
The shell's outline and halo around the block.
Forced colors
@media (forced-colors: active)
A CanvasText border keeps the block delineated.
Accessibility
Forma provides
Keeps the sample in a bounded region so the page never scrolls horizontally (WCAG 1.4.10 reflow).
Uses inverse text on the inverse surface, a validated contrast pair.
Draws a visible focus ring on the focused block and a border in forced colors; keeps it whole across printed pages.
Your application supplies
Add tabindex="0" and name the block with a visible caption via aria-labelledby.
Escape <, > and & in the sample.
If a copy button is needed, implement it in site or application code; Forma provides none.
Responsive behavior
max-inline-size: 100% with overflow: auto: long lines scroll inside the block at every width.
No breakpoints; padding is fluid.
Motion
No animation: the block is static. Scrolling is native.
Usage guidance
Do
Caption every sample with what it is or where it goes (a file name or purpose).
Keep samples short and runnable as shown.
Avoid
Wrapping or breaking lines of commands that must be copied exactly.