Dual Architecture — CSS Overview

Single SCSS source compiles to both shadow-DOM web components and light-DOM SUIT CSS classes. Three-layer tokens (reference → semantic → component). All page chrome uses --dual-* variables.

§1 — Stats and Performance

§2 — CSS Delivery Model

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

Single SCSS source compiles two outputs via $namespace: .Dual-Button (light DOM CSS classes) and .Button (shadow-scoped web components). Tokens flow reference → semantic → component through both paths identically.

§3 — Token Architecture and Color Examples

Layer	Example	Role
Reference	$dual-teal-500, $dual-navy-900	Raw palette primitives (SCSS only, never emitted)
Semantic	--dual-action-fill-1, --dual-base-1	Meaning-based tokens, emitted as CSS custom properties
Component	--dual-button-fill, --dual-card-border	Per-component tokens defaulting from semantic layer

Live token swatches

Tokens compile from SCSS $primitives → semantic SCSS map → emitted CSS custom properties. Component vars default from semantic and can be overridden per-instance.

§4 — Components (Shadow DOM vs Light DOM)

Both paths use the same token contract. CSS var overrides work identically on both.

Button

Shadow DOM (<dual-button>)

Primary Ghost Text Danger

Light DOM (.Dual-Button)

Primary Ghost Text Danger

Text Field

Shadow DOM (<dual-text-field>)

Light DOM (.Dual-TextField)

Email address

Alert (status variants)

InfoInformational message.

SuccessOperation completed.

WarningCheck this before continuing.

DangerSomething went wrong.

Card · Attribution

Card (.Dual-Card)

Card title

Card body text bound to semantic tokens.

Attribution (.Dual-Attribution)

Jane DoeDesign Systems

Blockquote · Stage

Blockquote (.Dual-Blockquote)

A single SCSS source, two outputs.

Stage (.Dual-Stage)

Stage

Hero banner bound to semantic tokens.

Checkbox group · Radio group (sub-components)

Checkbox group (.Dual-CheckboxGroup)

Choose options

Option A Option B

Radio group (.Dual-RadioGroup)

Pick one

One Two

Tooltip · Typography

Tooltip (.Dual-Tooltip)

Tooltip content on the inverse surface.

Typography (.Dual-Typography)

Title medium bold

§4b — Typography (84 variations · composable utilities)

The 84 variations are 2 families × 16 style-roles × up to 3 weights, reachable via the composable utility axes (iris-font-* · iris-text-* · iris-weight-*) generated from the same type maps — ~21 classes composing to ≥84 combinations (intro roman-only, topline bold-only → 84 not 96).

Each sample composes three utility classes (family + role + weight). Switch the theme in the toolbar — the type re-colors via the semantic --dual-text-* tokens while metrics stay constant.

§5 — Theming and Override Methods

Override method	Scope	Shadow DOM	Light DOM
CSS variable on :root	Global	✓	✓
CSS variable on element	Instance	✓	✓
SCSS $variable (build-time)	Global	✓	✓
.dual-theme-dark class	Global	✓	✓

/* Override any component via CSS vars — works on BOTH paths */
dual-button, .Dual-Button { --dual-button-fill: hotpink; }

/* Or override at the semantic layer (affects all components) */
:root { --dual-action-fill-1: #6b2fb3; }

Both paths are equivalent. The dual architecture ensures a single override surface works for both consumption models.

§6 — Gap Analysis

Feature	Dual	iris	iX
CSS-only usage (no JS)	[x]	[ ]	[ ]
Per-file imports	[x] dist/components/*.css	[ ] monolithic	[x] theme separate
Component token overrides	[x] color-only tier, 14 comps	[ ] 1 var	[x] 25+ vars
Naming convention	[x] SUIT CSS	[ ] generic shadow	[ ] generic shadow
Utility classes	[x] composable type + u-*	[x] 84 typo utils	[ ] none
CSS Grid system	[x] .Grid-cell	[ ] none	[ ] none
Tree-shaking (CSS)	[x] config-driven	[ ] bundled	[ ] bundled
Framework wrapper needed	[ ] no	[x] Stencil	[x] Stencil

§7 — New capabilities (parameterized type · size scales · subtree modes)

Landed in the POC and compiled into the granular dist/css/*.css layers and the dist/preset/full.css barrel: a parameterized composite typography mixin, content-measure + fluid size scales with a dual-space() multiplier, and attribute-scoped theme modes.

Parameterized typography — type($family,$group,$size,$weight) + base element styles

Base element styles (h1–h6, p, blockquote) map onto type() in the base layer (opt-in). The mixin validates its axes with @error.

Size scales — content-measure, fluid clamp(), and dual-space()

Attribute-scoped modes — [data-dual-theme] on a subtree

The theme() mixin now emits both the root .dual-theme-* class and a [data-dual-theme] attribute, so a subtree switches mode independently of the page.

iris keeps its iris-ui-theme-* class names; the attribute form is the portable, nestable pattern the POC demonstrates.

§8 — Explore the POC

This overview is the hub. Each area below is its own interactive demo, all rendering against the same built dist/preset/full.css:

Demo	Shows
Output Architecture	dual architecture + config-gated pipeline stages (iris-core build + consumer presets)
Token Architecture	the reference → semantic → component token pipeline
SCSS Structure	global + component file structure, variable groups, functions, mixins
SUIT CSS & Schemas	SUIT class naming + the three machine-readable naming schemas
Layout & Base	base + utilities + grid + 10 primitives, and how they stack & combine
Consumer Theming	live semantic-vs-component variable override
Benchmarks & Comparison	standardized package benchmarks + adoption impact vs iris & iX