Dimensions

The ApollionProvider's dimension prop applies a different density to the spacing and typography of the entire theme. Same visual structure, tighter or airier paddings/gaps and text — without rewriting components or swapping tokens.

Why it exists

A single product rarely lives at a single density. An operational dashboard needs to fit dozens of rows in the viewport (dense). A marketing landing page needs to breathe (airy). And most screens sit somewhere in between.

Instead of maintaining three parallel themes — or forking components per context — Apollion exposes dimension as an orthogonal axis to brand/mode/surface. You change one prop, and the entire spacing responds.

The three values

Value	When to use	Effect on spacing + typography
`compact`	Dashboards, dense tables, internal tools	Paddings/gaps + text ~20% denser
`normal` (default)	Default for most products	The theme's canonical spacing + typography
`spacious`	Marketing pages, hero sections, onboarding	Paddings/gaps + text ~28% airier

The normal default is byte-equivalent to the pre-dimension spacing and typography — existing apps stay identical without changing anything.

Live demo

The same <Paper> + <Text> + <Button> at three densities, side by side. Note how gaps, paddings, and the button respond with no change at all to the children's JSX.

compact

Dense content for dashboards.

normal

Canonical spacing — default.

spacious

Marketing pages, hero sections.

How to use

Entire application

import { ApollionProvider } from '@apollion-dsi/core/themes';
 
<ApollionProvider dimension="compact">
  <App />
</ApollionProvider>;

Subtree (isolated dashboard inside marketing)

<ApollionProvider dimension="spacious">
  <MarketingPage>
    <ApollionProvider dimension="compact">
      <AdminDashboard />
    </ApollionProvider>
  </MarketingPage>
</ApollionProvider>

Nested ApollionProviders are supported — the innermost one wins.

Combining with brand and surface

dimension is independent of theme/brand/surface — combine freely:

<ApollionProvider theme={createTheme({ colors: { main: '#003750' } })} dimension="compact" surface="negative">
  <DashboardScuro />
</ApollionProvider>

Design — what `dimension` affects

dimension scales two token families with the same multiplier (0.20 / 0.25 / 0.32 — a single knob):

Spacing (micro, xs, small, …, giant) — Flex/Grid gaps, container padding, inner space of inputs; any consumption of theme.spacing(...) or theme.foundation.spacing.*.
Typography (theme.font.fontSize.*) — the whole text scale (nano … gargantua), emitted as rem over a fixed 16px root (html { font-size: 100% }). normal maps 1:1 to the design px scale (small = 16px → 1rem); compact shrinks (small → 0.8rem), spacious grows (small → 1.28rem). Spacing and text scale together.

For layout math that needs the effective px (e.g. skeleton height proportional to the font), use theme.font.fontSizePx.* — the resolved px — instead of parsing the rem string.

Fixed root: the root is no longer fluid (clamp by vw) — text and spacing keep a stable density on large monitors; wide screens gain columns/space, not inflated text. Density is chosen by context via dimension, not by viewport width.

What dimension does NOT affect: colors, borders, radius, shadows. The visual identity does not change — only the spatial and typographic density.

API

dimension is declarative at the provider boundary — no hook, no imperative getter. To read the active density inside a component, inspect theme.dimension (string).

const DensityAwareCard = styled.div`
  border: ${({ theme }) => (theme.dimension === 'compact' ? '1px solid' : '2px solid')};
`;