VERIFICATION-0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF
Character grid
<forma-character-grid>
Fixed rows-by-columns grid of equal-width cells where every run declares its cell coordinates and source order is row-major order; contained horizontal scroll by default.
- Authoring tag
<forma-character-grid>- Category
- Command and keyboard-first
- Behavior owner
- Application / Limen
- Canonical source
patterns/character-grid.html
Purpose
The character grid is the presentation primitive for keyboard-first screens laid out on equal-width character cells: 3270 and 5250 style screens, DOS and TUI tools, and modern character-grid interfaces. Each run (a heading, a value, a field, a key, a message) is a real HTML element that declares its origin cell and length with data-forma-row, data-forma-col and data-forma-len. Runs are written in row-major order, so reading order, focus order and visual order are the same sequence without any tabindex. Forma owns geometry, placement, typography, state cues, narrow-screen containment and profiles. The application owns content, key processing, input inhibition, initial focus and screen transitions.
Use when
- Positions on the screen carry meaning to trained operators, such as a host screen being re-platformed without retraining.
- A keyboard-first data entry or inquiry screen must keep fields, labels and function keys at fixed cells.
- A tool deliberately presents a terminal-style layout and needs the grid to scale with text size rather than viewport width.
Avoid when
- Ordinary forms and detail pages: use Text field, Key-value list and Facts, which reflow naturally.
- Tabular data that users sort, filter or select: use Data grid or Dense ledger.
- Showing source code or command output: use Code sample.
- Wide-glyph (two-cell) or right-to-left content: the grid does not assign two cells to wide glyphs (GAP-TCG-06 is open).
Behavior to know
- One cell is
1chof the grid's monospaced face and the row pitch is at least 1.5rem (24px), so positions stay exact at 200% text size. - Coordinates are attributes, not inline styles, so a strict
style-srcContent-Security-Policy is kept. - The viewport is a named, focusable region that scrolls horizontally inside itself; the page never scrolls sideways.
- Overlong text widens its column tracks instead of being clipped, so authoring errors stay visible.
- Field, key, message and reveal presentation are documented on the family pages; this page owns the grid and every
data-forma-*hook.
Basic example
The smallest correct markup: the canonical pattern from patterns/character-grid.html inside its public tag. Copy this first, then adapt labels, names and state.
Minimal character grid
Rendered from the canonical pattern file.
<forma-character-grid class="forma-component-tag">
<div class="forma-character-grid" data-forma-rows="8" data-forma-columns="40" data-forma-narrow="contained">
<div class="forma-character-grid__viewport" role="region" aria-labelledby="character-grid-title" tabindex="0">
<div class="forma-character-grid__surface">
<h2 class="forma-character-grid__text" id="character-grid-title" data-forma-row="1" data-forma-col="13" data-forma-len="15" data-forma-emphasis="intensified">SYSTEM OVERVIEW</h2>
<p class="forma-character-grid__text" data-forma-row="3" data-forma-col="2" data-forma-len="37">Positioned protected text, row-major.</p>
<dl class="forma-character-grid__group">
<dt class="forma-character-grid__text" data-forma-row="5" data-forma-col="2" data-forma-len="11">Region . :</dt>
<dd class="forma-character-grid__value" data-forma-row="5" data-forma-col="14" data-forma-len="10">NORTH-EAST</dd>
<dt class="forma-character-grid__text" data-forma-row="6" data-forma-col="2" data-forma-len="11">Nodes . . :</dt>
<dd class="forma-character-grid__value" data-forma-row="6" data-forma-col="14" data-forma-len="4" data-forma-align="end">12</dd>
<dt class="forma-character-grid__text" data-forma-row="7" data-forma-col="2" data-forma-len="11">Updated . :</dt>
<dd class="forma-character-grid__value" data-forma-row="7" data-forma-col="14" data-forma-len="10">2026-09-27</dd>
</dl>
</div>
</div>
</div>
</forma-character-grid>
Click or tap the code once to select all of it, then copy.
Examples
Print queue with repeated rows
A 10 by 60 screen with a positioned table run. Column widths come from th[data-forma-len] and a two-cell gutter from data-forma-gutter; the table keeps native table semantics and a visually hidden caption.
<forma-character-grid class="forma-component-tag">
<div class="forma-character-grid" data-forma-rows="10" data-forma-columns="60" data-forma-narrow="contained">
<div class="forma-character-grid__viewport" role="region" aria-labelledby="character-grid-print-queue-title" tabindex="0">
<div class="forma-character-grid__surface">
<h2 class="forma-character-grid__text" id="character-grid-print-queue-title" data-forma-row="1" data-forma-col="22" data-forma-len="18" data-forma-emphasis="intensified">PRINT QUEUE STATUS</h2>
<span class="forma-character-grid__text" data-forma-row="3" data-forma-col="2" data-forma-len="11">Queue<span class="forma-character-grid__leader" aria-hidden="true"> . . :</span></span>
<span class="forma-character-grid__value" data-forma-row="3" data-forma-col="14" data-forma-len="8">PRTQ01</span>
<span class="forma-character-grid__text" data-forma-row="3" data-forma-col="30" data-forma-len="11">Printer<span class="forma-character-grid__leader" aria-hidden="true"> . :</span></span>
<span class="forma-character-grid__value" data-forma-row="3" data-forma-col="42" data-forma-len="10">FLOOR3-HP</span>
<div class="forma-character-grid__table" data-forma-row="5" data-forma-col="2" data-forma-len="57" data-forma-height="5">
<table data-forma-gutter="2">
<caption>Jobs in queue PRTQ01, oldest first</caption>
<thead><tr><th scope="col" data-forma-len="8">Job</th><th scope="col" data-forma-len="10">Owner</th><th scope="col" data-forma-len="5" data-forma-align="end">Pages</th><th scope="col" data-forma-len="10">Status</th><th scope="col" data-forma-len="16">Submitted</th></tr></thead>
<tbody>
<tr><td>J004812</td><td>OKAFOR</td><td data-forma-align="end">12</td><td>PRINTING</td><td>2026-09-30 08:14</td></tr>
<tr><td>J004815</td><td>RIVERA</td><td data-forma-align="end">3</td><td>WAITING</td><td>2026-09-30 08:16</td></tr>
<tr><td>J004817</td><td>NAKAMURA</td><td data-forma-align="end">21</td><td>HELD</td><td>2026-09-30 08:21</td></tr>
<tr><td>J004820</td><td>RIVERA</td><td data-forma-align="end">2</td><td>WAITING</td><td>2026-09-30 08:25</td></tr>
</tbody>
</table>
</div>
<p class="forma-character-grid__text" data-forma-row="10" data-forma-col="2" data-forma-len="16" data-forma-emphasis="muted">4 jobs, 38 pages</p>
</div>
</div>
</div>
</forma-character-grid>
Click or tap the code once to select all of it, then copy.
Missing data and grouped values
A description list placed with forma-character-grid__group, so its terms and values keep absolute coordinates. A contact that is not on file is shown in words with data-forma-state="missing", and amounts are end-aligned inside their runs.
<forma-character-grid class="forma-component-tag">
<div class="forma-character-grid" data-forma-rows="9" data-forma-columns="50" data-forma-narrow="contained">
<div class="forma-character-grid__viewport" role="region" aria-labelledby="character-grid-supplier-profile-title" tabindex="0">
<div class="forma-character-grid__surface">
<h2 class="forma-character-grid__text" id="character-grid-supplier-profile-title" data-forma-row="1" data-forma-col="17" data-forma-len="16" data-forma-emphasis="intensified">SUPPLIER PROFILE</h2>
<dl class="forma-character-grid__group">
<dt class="forma-character-grid__text" data-forma-row="3" data-forma-col="2" data-forma-len="12">Supplier<span class="forma-character-grid__leader" aria-hidden="true"> . :</span></dt>
<dd class="forma-character-grid__value" data-forma-row="3" data-forma-col="15" data-forma-len="20">HARBOR FREIGHT CO</dd>
<dt class="forma-character-grid__text" data-forma-row="4" data-forma-col="2" data-forma-len="12">Contact<span class="forma-character-grid__leader" aria-hidden="true"> . :</span></dt>
<dd class="forma-character-grid__value" data-forma-row="4" data-forma-col="15" data-forma-len="20" data-forma-state="missing">not on file</dd>
<dt class="forma-character-grid__text" data-forma-row="5" data-forma-col="2" data-forma-len="12">Balance<span class="forma-character-grid__leader" aria-hidden="true"> . :</span></dt>
<dd class="forma-character-grid__value" data-forma-row="5" data-forma-col="15" data-forma-len="12" data-forma-align="end">4,210.00</dd>
<dt class="forma-character-grid__text" data-forma-row="6" data-forma-col="2" data-forma-len="12">Overdue<span class="forma-character-grid__leader" aria-hidden="true"> . :</span></dt>
<dd class="forma-character-grid__value" data-forma-row="6" data-forma-col="15" data-forma-len="12" data-forma-align="end">0.00</dd>
</dl>
<p class="forma-character-grid__text" data-forma-row="8" data-forma-col="2" data-forma-len="45" data-forma-emphasis="muted">Contact details are maintained by Purchasing.</p>
</div>
</div>
</div>
</forma-character-grid>
Click or tap the code once to select all of it, then copy.
Reflow for a modern tool
A build summary whose positions carry no meaning opts into data-forma-narrow="reflow". When the grid's container is narrower than 82 cells the runs stack in source order; at wider sizes it is an ordinary grid.
<forma-character-grid class="forma-component-tag">
<div class="forma-character-grid" data-forma-rows="7" data-forma-columns="60" data-forma-narrow="reflow">
<div class="forma-character-grid__viewport" role="region" aria-labelledby="character-grid-build-summary-title" tabindex="0">
<div class="forma-character-grid__surface">
<h2 class="forma-character-grid__text" id="character-grid-build-summary-title" data-forma-row="1" data-forma-col="2" data-forma-len="18" data-forma-emphasis="intensified">BUILD 2231 SUMMARY</h2>
<span class="forma-character-grid__text" data-forma-row="3" data-forma-col="2" data-forma-len="11">Branch<span class="forma-character-grid__leader" aria-hidden="true"> . :</span></span>
<span class="forma-character-grid__value" data-forma-row="3" data-forma-col="14" data-forma-len="16">release/2026.10</span>
<span class="forma-character-grid__text" data-forma-row="4" data-forma-col="2" data-forma-len="11">Commit<span class="forma-character-grid__leader" aria-hidden="true"> . :</span></span>
<span class="forma-character-grid__value" data-forma-row="4" data-forma-col="14" data-forma-len="7">4f9c2e1</span>
<span class="forma-character-grid__text" data-forma-row="5" data-forma-col="2" data-forma-len="11">Duration<span class="forma-character-grid__leader" aria-hidden="true"> :</span></span>
<span class="forma-character-grid__value" data-forma-row="5" data-forma-col="14" data-forma-len="6">6m 42s</span>
<p class="forma-character-grid__text" data-forma-row="7" data-forma-col="2" data-forma-len="56">All 1,482 checks passed. Artifacts retained for 30 days.</p>
</div>
</div>
</div>
</forma-character-grid>
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.
Contained node list on a phone
A 7 by 60 screen plus one device status row (data-forma-status-rows="1"). At phone width the grid keeps every position and the named viewport scrolls sideways inside itself.
What changes at narrow widths
- The grid keeps its 60 columns; the viewport scrolls horizontally inside its border and the page itself never scrolls sideways.
- Below 40rem, or on a coarse pointer, the row pitch grows to 2.75rem (44px) so rows are comfortable touch targets. Columns stay one
chwide, so positions are preserved. - The viewport has
tabindex="0"and a name, so keyboard users can focus it and scroll with the arrow keys; touch users swipe inside it. - Rotating to landscape shows more columns before scrolling is needed; no run moves.
<forma-character-grid class="forma-component-tag">
<div class="forma-character-grid" data-forma-rows="7" data-forma-status-rows="1" data-forma-columns="60" data-forma-narrow="contained">
<div class="forma-character-grid__viewport" role="region" aria-labelledby="character-grid-node-list-mobile-title" tabindex="0">
<div class="forma-character-grid__surface">
<h2 class="forma-character-grid__text" id="character-grid-node-list-mobile-title" data-forma-row="1" data-forma-col="22" data-forma-len="17" data-forma-emphasis="intensified">CLUSTER NODE LIST</h2>
<dl class="forma-character-grid__group" aria-label="Node states">
<dt class="forma-character-grid__text" data-forma-row="3" data-forma-col="2" data-forma-len="11">NODE-01<span class="forma-character-grid__leader" aria-hidden="true"> . :</span></dt>
<dd class="forma-character-grid__value" data-forma-row="3" data-forma-col="14" data-forma-len="8">ONLINE</dd>
<dt class="forma-character-grid__text" data-forma-row="4" data-forma-col="2" data-forma-len="11">NODE-02<span class="forma-character-grid__leader" aria-hidden="true"> . :</span></dt>
<dd class="forma-character-grid__value" data-forma-row="4" data-forma-col="14" data-forma-len="8">DRAINING</dd>
<dt class="forma-character-grid__text" data-forma-row="5" data-forma-col="2" data-forma-len="11">NODE-03<span class="forma-character-grid__leader" aria-hidden="true"> . :</span></dt>
<dd class="forma-character-grid__value" data-forma-row="5" data-forma-col="14" data-forma-len="8">ONLINE</dd>
</dl>
<p class="forma-character-grid__text" data-forma-row="7" data-forma-col="2" data-forma-len="33" data-forma-emphasis="muted">Last refresh 2026-09-30 08:15 UTC</p>
<p class="forma-character-grid__status" role="status" data-forma-row="8" data-forma-col="2" data-forma-len="58"><span class="forma-character-grid__indicator"><span>READY</span></span></p>
</div>
</div>
</div>
</forma-character-grid>
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 |
|---|---|---|---|---|
role | .forma-character-grid__viewport | region | — | Required. Makes the contained scroller a named landmark region. |
aria-labelledby | .forma-character-grid__viewport | id of the screen title run | — | Required. Names the region after the screen title so each screen is identifiable. |
tabindex | .forma-character-grid__viewport | 0 | — | Required. Lets keyboard users focus and scroll the contained region. Positive values are prohibited everywhere in the grid (CG-11). |
scope | th in a table run | col | row | — | Native table header scope. Row headers read as data (no underline). |
aria-label | .forma-character-grid__group | string | — | Names a semantic group such as a dl or role="group" when it has no visible heading. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-character-grid | Block class | — | Grid scope and container-query container. Holds the geometry attributes, profile, reveal state and the --forma-grid-* presentation tokens. |
.forma-character-grid__field | Element class | — | Native editable input run. See Character grid field. |
.forma-character-grid__group | Element class | — | Semantic container (dl, div role="group", section) that spans the grid as a subgrid, so its children keep absolute coordinates. |
.forma-character-grid__indicator | Element class | — | Status indicator word such as READY or X SYSTEM. |
.forma-character-grid__key | Element class | — | Native button presenting an action key. See Character grid keys. |
.forma-character-grid__label | Element class | — | A label for run that precedes its field. See Character grid field. |
.forma-character-grid__leader | Element class | — | Decorative leader characters inside a label or text run. Mark it aria-hidden="true" so the accessible name stays clean. |
.forma-character-grid__message | Element class | — | Live message run with a severity word. See Character grid status. |
.forma-character-grid__severity | Element class | — | Visible severity word at the start of a message. |
.forma-character-grid__status | Element class | — | System status run, usually on a device status row. |
.forma-character-grid__surface | Element class | — | The cell grid. A form when the screen has editable fields, otherwise a div. Every direct child is a positioned run. |
.forma-character-grid__table | Element class | — | A positioned run that holds a native table of repeated rows. Whitespace collapses inside it and its caption is visually hidden. |
.forma-character-grid__text | Element class | — | Protected text: headings, labels without a field, prose. Never focusable. |
.forma-character-grid__value | Element class | — | Protected value in the emphasis color. Never render protected values as readonly inputs (CG-9). |
.forma-character-grid__viewport | Element class | — | The contained horizontal scroller with a border and focus outline. Requires role="region", a name and tabindex="0". |
[aria-invalid] | Attribute hook | "true" | true on a field, set by the application after validation, draws dashed rules above and below the field. |
[data-forma-align] | Attribute hook | "end" | end right-aligns a value or table cell within its cells, for amounts. |
[data-forma-columns] | Attribute hook | 1–132 | Columns of the grid, integer 1-132. Sets --forma-grid-columns. |
[data-forma-emphasis] | Attribute hook | "intensified", "muted" | On protected text: intensified (emphasis color, bold) or muted (secondary color). |
[data-forma-narrow] | Attribute hook | "reflow" | contained (default) keeps geometry and scrolls inside the viewport. reflow stacks runs in source order when the container is narrower than 82 cells. |
[data-forma-profile] | Attribute hook | "ibm-3270" | Presentation profile. ibm-3270 is the only shipped profile; it changes tokens only, never geometry or order. See Character grid 3270 profile. |
[data-forma-reveal] | Attribute hook | "sequential" | sequential enables the SequentialReveal mask; complete and static are static. See Character grid reveal. |
[data-forma-reveal-rows] | Attribute hook | 1–50 | Limits the reveal timing window to the first N rows. |
[data-forma-reveal-run] | Attribute hook | — | Opts one protected text run into the reveal. Other run types never reveal. |
[data-forma-rows] | Attribute hook | 1–50 | Application rows of the grid, integer 1-50. Sets --forma-grid-rows. |
[data-forma-severity] | Attribute hook | "error", "success", "validation", "warning" | On a message: information, success, warning, validation or error; sets the message color and severity-word shape cue. |
[data-forma-state] | Attribute hook | "inhibited", "missing" | On a value: missing italicizes explicit missing-data words. On an indicator: inhibited draws reverse video (an outlined box in forced colors). |
[data-forma-status-rows] | Attribute hook | "1", "2" | Optional device status rows (1 or 2) after the application rows, for forma-character-grid__status runs only (CG-18). Omit when the application draws its own status. |
[data-forma-row] | Attribute hook | — | 1-based origin row of a run. Maps to the registered, non-inheriting --forma-row. |
[data-forma-col] | Attribute hook | — | 1-based origin column of a run. Maps to --forma-col. |
[data-forma-len] | Attribute hook | — | Run length in cells. Maps to --forma-len. On a field it equals maxlength; on a table header it sets the column width. |
[data-forma-height] | Attribute hook | — | Run height in rows (default 1), used by table runs and messages that reserve extra rows. Maps to --forma-height. |
[data-forma-gutter] | Attribute hook | — | On the table inside a table run: cells between columns, 0-4 (default 1). Maps to --forma-gutter. |
--forma-grid-font-size | Custom property | — | Grid text size. Default 1rem. Cells are 1ch of this face. |
--forma-grid-line-height | Custom property | — | Line height factor for the row pitch. Default 1.25; the pitch never drops below 1.5rem. |
--forma-grid-inset | Custom property | — | Padding around the cell grid. Default 1ch. |
--forma-grid-background | Custom property | — | Screen background. Defaults to the primary surface token, so it follows light and dark themes. |
--forma-grid-protected | Custom property | — | Protected text color. |
--forma-grid-emphasis | Custom property | — | Values, intensified text, key names and table cells. |
--forma-grid-muted | Custom property | — | Muted text, leaders and status text. |
--forma-grid-field | Custom property | — | Editable field text color. |
--forma-grid-field-surface | Custom property | — | Editable field background. |
--forma-grid-boundary | Custom property | — | Field underline color. |
--forma-grid-focus | Custom property | — | Focus outline color for fields and keys. |
--forma-reveal-char-ms | Custom property | — | Reveal time per cell. Default 12. |
--forma-reveal-line-ms | Custom property | — | Extra reveal time per row. Default 40. |
--forma-reveal-max-ms | Custom property | — | Cap for the whole reveal. Default 1500. |
| Keys | Result |
|---|---|
| Tab / Shift+Tab | Moves to the viewport, then through fields and keys in source order, which is row-major order. Tab can always leave the grid. |
| Arrow keys | Scroll the contained viewport while it has focus (native scrolling of a focusable overflow region). |
| F1-F24, Escape, Pause and other function keys | No built-in behavior. The application or Limen maps physical keys to the presented key buttons. |
| Event | Description |
|---|---|
submit | Native event on a form surface. The application reads SubmitEvent.submitter to learn which key was used. Forma adds no events. |
Form behavior
A form surface is an ordinary native form: fields submit by name, the first submit key receives implicit submission, and required and formnovalidate behave natively. Protected runs are never form controls and never submit.
States
| State | How it is expressed | Presentation |
|---|---|---|
| Contained | data-forma-narrow="contained" (default) | Geometry is preserved at every width; the viewport scrolls horizontally when narrower than the grid. |
| Reflowed | data-forma-narrow="reflow" and a container narrower than 82 cells | Runs stack in source order and wrap; positions are not preserved. Table runs keep their own contained scroll. |
| Touch pitch | viewport narrower than 40rem or pointer: coarse | Row pitch grows to 2.75rem; fields and keys get a 2.75rem minimum width that paints into blank cells. |
| Viewport focus | :focus-visible on the viewport | A 2px focus outline with offset around the region. |
| Missing value | data-forma-state="missing" on a value | Missing data is stated in words and italicized, never left blank. |
| Profiled | data-forma-profile="ibm-3270" | Presentation tokens change; geometry, order and semantics do not. |
Accessibility
Forma provides
- Row-major source order makes reading order, focus order and visual order identical; no CSS reordering is applied in any mode.
- The viewport is a named, focusable region with a visible focus outline, so contained content is reachable by keyboard.
- Rows are at least 24px (1.5rem), and 44px on narrow or coarse-pointer screens, meeting WCAG 2.2 target-size guidance.
- Column and row tracks grow under WCAG 1.4.12 text-spacing overrides, so runs never overlap and shared columns stay aligned.
- Viewport border, table header underline, field boundaries and focus use system colors in forced-colors mode.
- Table captions are visually hidden but remain available to assistive technology.
Your application supplies
- Write runs in row-major order and never use positive
tabindex; check markup withnode tools/character-grid-conformance.mjs <file>. - Give every screen a title run and reference it from the viewport's
aria-labelledby. - Justify contained layout: positions must carry meaning (WCAG 1.4.10 two-dimensional exception). Otherwise use
data-forma-narrow="reflow". - Render missing data as explicit words and keep protected values as text, not readonly inputs.
- Decide initial focus when a screen appears; Forma only needs native
autofocusif you use it.
Responsive behavior
- The grid sizes in character cells:
inline-size: max-contentofcolumnstracks ofminmax(1ch, min-content)plus the inset. It scales with text size, not viewport width. - Contained (default): the viewport has
overflow-x: autoandoverscroll-behavior-inline: contain, so the page never scrolls horizontally. - Reflow (opt-in): an
@containerquery stacks runs when the grid's container is narrower than 82ch; wider geometries still use the contained scroller between 82 cells and their full width. - Below 40rem or on a coarse pointer the row pitch grows to 2.75rem; columns stay one
chso positions do not change. - Overlong content widens intrinsic tracks rather than clipping; the conformance check reports it as an authoring error.
Motion
- No animation in the base grid: placement, scrolling and state cues are static.
- The optional SequentialReveal mask is off unless the grid has
data-forma-reveal="sequential"and a run hasdata-forma-reveal-run; it is removed underprefers-reduced-motion: reduceand in print. See Character grid reveal.
Usage guidance
Do
- Start small: declare the real geometry of the screen being modeled (24 by 80, 32 by 80, or any size up to 50 by 132).
- Use a
formsurface for screens with fields and adivotherwise. - Wrap
dl, labelled groups and sections informa-character-grid__groupso their children keep absolute coordinates.
Avoid
- Inline
styleattributes inside the grid (CG-10); coordinates belong indata-forma-*attributes. - Two runs that share a cell (CG-5) or text longer than its run (CG-7).
- Using the grid only for a retro look when positions carry no meaning and reflow is not enabled.
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.