Site and editorial

Code sample

<forma-code-sample>

Technical sample in a captioned, keyboard-scrollable region that never widens the page.

Authoring tag
<forma-code-sample>
Behavior owner
Site content
Canonical source
patterns/code-sample.html

Purpose

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

Behavior to know

  • 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>
HTML · Minimal code sample Raw HTML for HTML · Minimal code sample
<forma-code-sample class="forma-component-tag">
<div class="forma-site">
  <figure class="forma-code-figure">
    <figcaption id="code-caption">Pin Forma in forma.lock</figcaption>
    <pre class="forma-code" tabindex="0" aria-labelledby="code-caption"><code>forma 0.3.0
repository kemiller2002/forma
destination assets/forma
asset forma-marketing.css sha256:&lt;digest&gt;</code></pre>
  </figure>
</div>
</forma-code-sample>

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

Examples

Scenario

Long command line

A single command longer than the column. The line does not wrap; the block scrolls horizontally and can be scrolled from the keyboard once focused.

Download the pinned installer
curl -fsSLO https://raw.githubusercontent.com/kemiller2002/forma/v0.3.0/actions/install-presentation/install.sh
HTML · Long command line Raw HTML for HTML · Long command line
<forma-code-sample class="forma-component-tag">
  <div class="forma-site">
    <figure class="forma-code-figure">
      <figcaption id="code-sample-long-command-caption">Download the pinned installer</figcaption>
      <pre class="forma-code" tabindex="0" aria-labelledby="code-sample-long-command-caption"><code>curl -fsSLO https://raw.githubusercontent.com/kemiller2002/forma/v0.3.0/actions/install-presentation/install.sh</code></pre>
    </figure>
  </div>
</forma-code-sample>

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

Scenario

Deployment workflow file

A multi-line YAML file inside a prose article. Indentation is preserved and the block takes the prose region's block margins.

Deploy with pinned assets

The workflow installs exactly what the lock pins before the site build.

.github/workflows/deploy-pages.yml
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
HTML · Deployment workflow file Raw HTML for HTML · Deployment workflow file
<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.

Viewport 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.
HTML · Phone lock file Raw HTML for HTML · Phone lock file
<forma-code-sample class="forma-component-tag">
  <div class="forma-site">
    <figure class="forma-code-figure">
      <figcaption id="code-sample-mobile-lock-file-caption">forma.lock</figcaption>
      <pre class="forma-code" tabindex="0" aria-labelledby="code-sample-mobile-lock-file-caption"><code>forma 0.3.0
repository kemiller2002/forma
destination assets/forma
asset forma-marketing.css sha256:9f2c4e1a7b3d5c8e0f6a2b4d6e8f0a1c3e5b7d9f1a3c5e7b9d1f3a5c7e9b1d3f</code></pre>
    </figure>
  </div>
</forma-code-sample>

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
tabindexpre.forma-code0—Makes the scroll region focusable so keyboard users can scroll overflowing lines.
aria-labelledbypre.forma-codeid of the figcaption—Gives the focusable region the caption as its name, so focus does not land on an unnamed stop.
idfigcaptionstring—Referenced by the pre's aria-labelledby.
CSS hooks (derived from dist/all.css)
HookKindValues or defaultDescription
.forma-codeBlock 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-figureBlock class—The figure wrapper. Removes the default figure margin; its figcaption becomes a muted mono label above the block.
Keyboard interaction
KeysResult
Tab / Shift+TabFocuses the code block (tabindex=0); the shell's focus ring surrounds it.
Arrow keys, Page Up / Page Down, Home / EndNative scrolling of the focused block when its content overflows.

States

Code sample states
StateHow it is expressedPresentation
Fitscontent within the columnNo scrollbar; the block is still focusable.
Overflowingoverflow: autoLong lines scroll horizontally inside the block.
Focus:focus-visibleThe 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.
  • Placing prose explanations inside the code block.

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.