iris-core — CSS Overview

How CSS is delivered, the shadow-DOM web component experience, and what happens when you load component CSS directly in the light DOM. All page chrome uses --iris-* variables.

§1 — Stats and Performance

185 KB

iris.css

663

--iris-* vars

components

typo utilities

theme modes

840 KB

font assets

1 file

monolithic

5×

:root repeats

§2 — CSS Delivery Model

Click any node to highlight downstream delivery. SCSS source → compiled CSS → web components → page.

iris-core delivers one monolithic CSS file (iris.css) containing 663 tokens across 5 theme scopes, plus 84 typography utility classes. Components are Stencil web components with shadow-scoped CSS that is NOT exported for direct consumption.

§3 — Token Architecture and Color Examples

Layer	Example	Role
Base (SCSS only)	`$iris-teal-500`, `$iris-navy-900`	Raw palette primitives — never emitted as CSS custom properties
Semantic	`--iris-base-1`, `--iris-text-1`, `--iris-action-fill-1`	Meaning-based tokens, emitted × 5 theme scopes
Component	none exported yet — proposed DESYS-434	Per-component tokens (not yet available in iris-core)

Live token swatches

--iris-base-1

--iris-base-2

--iris-text-1

--iris-text-2

--iris-ui-interactive-1

--iris-action-fill-1

--iris-status-success

--iris-status-danger

Tokens compile from SCSS $primitives → semantic CSS custom properties. No component-token layer exists yet — DESYS-434 proposes one. The 663 vars repeat across 5 mode scopes (:root + 4 .iris-ui-theme-* selectors).

§4 — Components (Shadow DOM vs Light DOM)

Shadow DOM (supported)

Primary

Ghost

Text

Danger

Light DOM (unsupported — internal CSS loaded directly)

⚠️ Not a supported pattern. These are iris-core's internal shadow-DOM stylesheets using generic class names (.button, .primary, .text) that collide with other CSS. This exists to show why namespacing + the component-variable tier is needed.

§5 — Theming and Override Methods

Override method	Scope	Shadow DOM	Light DOM
CSS variable on `:root`	Global	✓	✓
`.iris-ui-theme-*` class	Global	✓	✓
Per-element CSS var	Instance	limited	✓
SCSS `$variable` (build-time)	Not exposed	—	—

/* Override the primary accent globally */
:root { --iris-ui-interactive-1: #6b2fb3; }

/* Override just the dark theme */
.iris-ui-theme-dark { --iris-ui-interactive-1: #b98cff; }

iris exposes only global CSS variable overrides. No component-level variable tier or SCSS consumer API is exported. Per-element overrides work but only affect tokens the component reads through its shadow boundary.

§6 — Gap Analysis

Feature	iris	Dual	iX
CSS-only usage (no JS)	[ ]	[x]	[ ]
Per-file imports	[ ] monolithic	[ ] monolithic	[x] theme separate
Component token overrides	[ ] 1 var	[x] 118 vars	[x] 25+ vars
Naming convention	[ ] generic shadow	[x] SUIT CSS	[ ] generic shadow
Utility classes	[x] 84 typo utils	[x] 73 u-*	[ ] none
CSS Grid system	[ ] none	[x] .Grid-cell	[ ] none
Tree-shaking (CSS)	[ ] bundled	[ ] bundled	[ ] bundled
Framework wrapper needed	[x] Stencil	[ ] no	[x] Stencil