Layout & grid

Breakpoints, the grid, and what Titan does and does not decide about page structure.

What it governs

Where things sit on the page and how that changes with viewport width. Two mechanisms — breakpoints and a 12-column grid — and no tokens of its own.

Vocabulary

Axis	Values	Means
attribute	tablet desktop	The named viewport bands
size	min max	Which bound of the band

Sourced from Invoca’s design-token naming specification, confirmed by its owner as the baseline the design language is being built on. This is the vocabulary of record — not inferred from token names.

Breakpoints

Breakpoints are min-width: a rule at md applies at 900px and above. Titan is a desktop-first internal product, so in practice most surfaces live at lg and xl, and xs/sm are rarely exercised. The values are in Token reference below — see Open issues for how they were arrived at and how they relate to the naming specification.

The grid

A 12-column flexbox grid, driven by per-breakpoint span props.

<Grid container spacing={2}>
  <Grid size={{ xs: 12, md: 6, lg: 4 }}>…</Grid>
  <Grid size={{ xs: 12, md: 6, lg: 8 }}>…</Grid>
</Grid>

The grid’s spacing prop is not the Titan spacing scale. It uses a separate 8px multiplier, so spacing={2} resolves to 16px — the same number as spacing-5, by coincidence, through a mechanism that maps to no step on the Titan scale and will not track it if the scale ever changes.

Set gaps from a spacing-* token instead:

<Box sx={{ display: 'grid', gap: 'var(--titan-tokens-spacing-5)' }}>

See TITAN-LAY-03.

Choosing a layout approach

You need…	Use	Not
A row of items that wrap by viewport width	Grid with per-breakpoint spans	A flex row with fixed widths — it will not reflow
Evenly spaced items in one direction	Stack (Components/Stack)	Grid — a 12-column grid for a single row is overhead with no benefit
A page split into a fixed sidebar and a fluid main region	CSS grid with a fixed track and 1fr	Grid spans — a 12-column split cannot express “280px and the rest”
A card that reflows its own contents independent of viewport	A container query	A breakpoint — the viewport does not tell you how wide the card is
Spacing between grid items	gap with var(--titan-tokens-spacing-N)	Grid’s spacing prop — it is not the Titan scale

Token reference

Titan defines no grid specification — no columns-per-breakpoint table, no gutter scale, no page margin scale. See TITAN-DIV-08.

There are no layout tokens. Breakpoints are not part of the token surface, so they are not reachable via $token, theme.vars.tokens[…], or var(--titan-tokens-…). Nothing about layout is currently expressible as a token.

Constraints

ID	Constraint	Rationale
TITAN-LAY-01	Layout responds at the defined breakpoints. Never a hardcoded media query.	A literal @media (min-width: 900px) is invisible to the audit and silently diverges the moment a breakpoint moves.
TITAN-LAY-02	Layout adapts at the defined breakpoints only. No custom intermediate values.	Each additional breakpoint multiplies the states every component must be verified in. Five is already more than most components are checked against.
TITAN-LAY-03	Grid gutters and gaps come from a spacing-* token via gap, not from Grid’s spacing prop.	spacing resolves through a separate 8px multiplier that maps to no step on the Titan scale.
TITAN-LAY-04	Content reflows to a single column at xs. Never horizontal scrolling.	WCAG 2.2 Reflow (AA) requires content to work at 320px equivalent without two-dimensional scrolling.
TITAN-LAY-05	A component that must adapt to its container, not the viewport, uses a container query.	A card in a sidebar and the same card in a main region are the same viewport and different widths. Breakpoints cannot express that.
TITAN-LAY-06	Page structure is a View decision, not a component one.	A component that assumes its page position cannot be reused. Region layout belongs to the view archetype.

Accessibility

• Reflow to 320px without horizontal scrolling is the binding requirement (WCAG 2.2 AA). It is equivalent to a desktop page at 400% zoom, which is how low-vision users actually read — not on a phone. A desktop-only product still has to meet it.
• Visual order must match DOM order. CSS order, row-reverse, and grid placement can reorder content visually while leaving keyboard and screen-reader order unchanged. The result is a focus ring that jumps around the screen. If the visual order is right, fix the DOM.
• Do not hide content at small viewports. display: none at xs removes it for everyone, including the zoomed desktop user who is not on a phone.
• Text must survive 200% zoom without clipping. Fixed-height containers around wrapping text are the usual failure.
• Container queries do not change any of the above — they change which layout applies, not whether it must reflow.

Known issues

Layout & grid: open issues

Divergences, open decisions, and undocumented gaps for Layout & grid.

Related

A generated map of which components consume which foundation does not exist yet.

Why it works this way

Titan does not decide page layout, and that is a real position — though currently an undocumented one. The system supplies components and the space between them; where regions sit belongs to the View tier. That separation is what lets a Button work identically in a wizard and a dashboard.

The cost is that until Views is written, the most consequential layer of any screen has no documentation at all. An agent asked to build a settings page makes a View-level decision first and a Component-level decision last, and today only the second has an answer.

Breakpoints are inherited because Titan is desktop-first internal software. Most surfaces render at lg and xl on a monitor the user cannot resize much. Spending the maintenance budget on validating phone breakpoints for a product used at a desk would buy very little — but that reasoning is inferred from usage, not recorded anywhere.