iris v1.0 — UI Kit

1 · Reference tokens

The primitive tier — raw colour ramps and dimension scales from the $reference SCSS map (src/global/tokens/_reference.scss, sourced from the Figma References mode). These live only in the SCSS source and are called at compile time via the ref() reference functions — they do not emit CSS custom properties and are not intended for direct use in the app. They are shown here purely to illustrate the scales; consumers use the semantic tokens in §2 instead. Rendered from the parsed SCSS source (data/reference-tokens.json), not the loaded stylesheet.

2 · Semantic tokens

The role-based --iris-* custom properties consumers actually use. Rendered live from the compiled CSS: every non-deprecated --iris-* custom property found in the installed iris.css, grouped by tier. Deprecated (--iris-deprecated-*) variables are hidden.

3 · Grid system

The src/global/css-grid/ layer — SUIT-named, de-conflicted so both grids load together: .iris-CssGrid (CSS Grid + bento) and .iris-FlexGrid (flexbox). Light-DOM classes only; never shadow-scoped. Both grids are 12-column; size each cell with a --{1..12}of12 class, optionally with a --{sm,md,lg,xl,xxl}- breakpoint prefix.

Rendered from the candidate grid.css — now installed locally. This demo installs the iris-core v1.0 candidate tarball into its own node_modules and links dist/iris/grid.css directly, so the P5 css-grid/ classes ship for real (base .iris-CssGrid / .iris-FlexGrid, --autoFit, --bento). A small scoped #grid block below still backstops the --{1..12}of12 column scale and the sm/md/lg/xl/xxl responsive prefixes this markup uses, in case the compiled cell naming differs from the demo markup — the loaded grid.css takes precedence where the names match.

.iris-CssGrid — 12-column, spans per cell

Container: <div class="iris-CssGrid"> (12 columns). Cell size: .iris-CssGrid-cell--{1..12}of12.

.iris-CssGrid--autoFit — intrinsic columns, no media queries

Container variant: cells fill down to --iris-grid-min-cell (default 16rem), then wrap.

.iris-CssGrid--bento — dense auto-flow with hero/wide cells

Container variant: .iris-CssGrid-cell--hero (2×2), --wide (span 2), --rowSpan2 (tall).

.iris-FlexGrid — 12-column cells + alignment

Cell sizes: --{1..12}of12, plus --full and --auto (grows to fill). Responsive prefixes --{sm,md,lg,xl,xxl}-{1..12}of12. Alignment: --alignCenter/End/Stretch, --justifyCenter/Between/End.

.iris-FlexGrid — responsive breakpoint variants

Stack the base span with breakpoint prefixes and the widest matching breakpoint wins. Each cell here is --12of12 (full width on mobile), then --md-6of12 (two-up at ≥768px), then --lg-4of12 (three-up at ≥1024px). Resize the window to watch them re-flow.

Spacing — the gutter tool (horizontal and vertical)

Both grids use ONE gutter for row and column gaps: gap: var(--iris-grid-gutter-width, var(--iris-spacer-12)). Override --iris-grid-gutter-width on the container with any --iris-spacer-* step; it drives horizontal and vertical spacing together. FlexGrid fractional widths are gutter-aware (calc(50% − gutter/2)), so cells stay flush as the gutter changes.

4 · Components

The 14 shipped <iris-*> web components. They render live when the loader is reachable (whole-repo preview); when served standalone they degrade to the tag name. Each component's shadow root also adopts shadow.scss (see §5).

5 · Config files & light vs shadow DOM

The P5 config-gated dist. src/iris-compile.config.yaml declares which SCSS surfaces compile into dist and which subpaths publish. A single SCSS source fans out to two composition roots — light.scss (→ iris.css) and shadow.scss (adopted into every component shadow root).

iris-compile.config.yaml — compile toggles

export.* — published subpaths

Note: the two legacy toggles are deliberately separate — CSS-off never implies resolution-off. The file records intent today; wiring the build to read compile.legacyCss is a tracked follow-up (F6.2).

Light DOM vs Shadow DOM