ADR-054

ActifActive

pattern

Responsive tables: systematic `overflow-x` wrapper

DateDate: 2026-06-10
DécideursDecision makers: Human (approval) · Design System Lead (layout)

Context

On mobile, the site's tables (tokens, components, ADRs, typography…) compressed within the available width. Observed behavior: <td> cells containing CSS token names (--agtc-semantic-color-action-primary, etc.) broke letter by letter, vertically, making the table unreadable.

Cause: table { width: 100% } with no minimum width or overflow mechanism — the table crushed itself into the viewport width instead of scrolling.

Decision

1. `.table-wrap` wrapper

Every table is wrapped in a <div class="table-wrap"> with:

.table-wrap {
  overflow-x: auto;
  -webkit-overflow-scrolling: touch; /* inertial scroll on iOS */
  margin: 16px 0 28px;
}
table {
  width: 100%;
  min-width: 420px; /* prevents compression below the readable threshold */
  margin: 0;        /* margin carried by .table-wrap */
}

2. Systematic application via post-processing in `layout()`

Rather than manually wrapping each table across the ~30 build*() functions, a String.replace() is applied to the final HTML generated by layout():

<table …> → <div class="table-wrap"><table …>
</table> (not followed by </div>) → </table></div>

Tables already wrapped (e.g. those coming from parseMd()) aren't double-wrapped thanks to the negative lookbehind on table-wrap">

3. `parseMd()` also wraps its tables

Tables generated from Markdown (ADRs, guidelines) also get wrapped in .table-wrap from parseMd() — consistency guaranteed regardless of the source.

Rejected alternatives

Alternative	Reason for rejection
`display: block` on `<table>` on mobile	Breaks column semantics and alignment
`word-break: break-all` without overflow	Columns readable but tokens unreadable (random breaking)
Manually wrapping each table	~30 calls to modify — risk of forgetting on each new table

Consequences

Any new table in the site becomes responsive automatically, with no extra action
Horizontal scroll appears only when the table is wider than the viewport
The min-width: 420px is an arbitrary threshold tuned for token tables — to revisit if very

wide tables appear (consider a min-width per table class)

WCAG 1.4.10 (Reflow): tabular data tables are exempt from the 320px reflow criterion —

horizontal scroll is the recognized solution for this type of content

Contexte

Sur mobile, les tables du site (tokens, composants, ADRs, typographie…) se compressaient dans la largeur disponible. Le comportement observé : les cellules <td> contenant des noms de tokens CSS (--agtc-semantic-color-action-primary, etc.) se coupaient lettre par lettre verticalement, rendant la table illisible.

Cause : table { width: 100% } sans largeur minimale ni mécanisme d'overflow — la table s'écrasait dans la largeur du viewport plutôt que de scroller.

Décision

1. Wrapper `.table-wrap`

Toutes les tables sont enveloppées dans un <div class="table-wrap"> avec :

.table-wrap {
  overflow-x: auto;
  -webkit-overflow-scrolling: touch; /* scroll inertiel iOS */
  margin: 16px 0 28px;
}
table {
  width: 100%;
  min-width: 420px; /* empêche la compression sous le seuil lisible */
  margin: 0;        /* margin portée par .table-wrap */
}

2. Application systématique via post-processing dans `layout()`

Plutôt que d'envelopper chaque table manuellement dans les ~30 fonctions build*(), un String.replace() est appliqué sur le HTML final généré par layout() :

<table …> → <div class="table-wrap"><table …>
</table> (non suivi de </div>) → </table></div>

Les tables déjà enveloppées (ex. celles issues de parseMd()) ne sont pas doublées grâce au negative lookbehind sur table-wrap">

3. `parseMd()` enveloppe également ses tables

Les tables générées depuis le Markdown (ADRs, guidelines) passent aussi dans .table-wrap depuis parseMd() — cohérence garantie quelle que soit la source.

Alternatives rejetées

Alternative	Raison du rejet
`display: block` sur `<table>` en mobile	Casse la sémantique et l'alignement des colonnes
`word-break: break-all` sans overflow	Colonnes lisibles mais tokens illisibles (coupure aléatoire)
Envelopper manuellement chaque table	~30 appels à modifier — risque d'oubli à chaque nouvelle table

Conséquences

Toute nouvelle table dans le site est automatiquement responsive sans action supplémentaire
Le scroll horizontal est présent uniquement quand la table est plus large que le viewport
La min-width: 420px est un seuil arbitraire adapté aux tables de tokens — à revoir si des

tables très larges apparaissent (envisager min-width par classe de table)

WCAG 1.4.10 (Reflow) : les tables tabulaires sont exemptées du critère de reflow à 320 px

— le scroll horizontal est la solution reconnue pour ce type de contenu

← ADR-053 ADR-055 →