Dual-Output CSS Architecture

Live components rendered from the prototype SCSS. Same source compiles to both shadow-DOM (web component) and light-DOM (CSS classes) via a $namespace parameter.

§1 — Architecture Diagram

Config → output map (src/config.yaml)

The build is config-driven: build-css.mjs and build-wc.mjs read one src/config.yaml and emit only the enabled outputs. Global knobs — namespace (Dual-), variablePrefix (dual), style, sourcemap, modes, tokenSubset — apply across them. Each layer compiles once to its own granular file under dist/css/; presets then compose consumer load tiers under dist/preset/ from those layers.

Pipeline stages — where config applies (iris-core side vs consumer side)

The config surface exists at two points: the iris-core build (what the package emits into dist/) and the consumer (what they load / override). Same declarative model, two owners.

Stages 1–4 are the iris-core-side build (a future consumer iris.config + CLI, spec'd in P5, will let a consumer drive stages 2–5 declaratively too). Stages 5–6 are what every consumer controls today with zero tooling.

§2 — Shadow-DOM Use (Web Component Path)

When Stencil builds dual web components, the SCSS compiles with $namespace: '', producing generic class names (.button, .button--primary) that are safely encapsulated inside the shadow DOM. The component variables (--dual-button-*) still inherit through the shadow boundary, allowing consumer overrides.

Live Web Components

These use <dual-*> custom elements with shadow DOM — same compiled CSS, generic class names encapsulated.

Stencil Import (Shadow-DOM SCSS)

// packages/core/src/components/button/button.scss
// (Stencil web component — shadow-DOM path)

@use '@siemens-dual/dual-core/src/components/button/styles' as btn;
@use '@siemens-dual/dual-core/src/mixins/shadow-dom/component' as base;

@include base.dual-component();
@include btn.styles($namespace: '');  // → .button (shadow-safe)

:host { display: inline-flex; }
:host([disabled]) { pointer-events: none; }

// Same variables (--dual-button-*) inherit through shadow boundary
// so consumer overrides work identically.

// The compiled shadow-DOM output contains:
.button {
  background: var(--dual-button-fill);
  color: var(--dual-button-content);
  border: 1px solid var(--dual-button-border-color);
}
.button:hover {
  background: var(--dual-button-fill-hover);
  color: var(--dual-button-content-hover);
}
.button--primary {
  --dual-button-fill: var(--dual-action-fill-1);
  --dual-button-content: var(--dual-action-content-1);
}
// Component tokens are color-only; dimensions bind semantic vars directly.
// No .dual- prefix — encapsulated in shadow DOM.

SCSS Source Flow (Shadow-DOM highlighted)

Shadow-DOM Compile Stats

§3 — Light-DOM Use (CSS Class Path)

When the SCSS compiles with $namespace: 'dual-', the output uses namespaced class names (.Dual-Button, .Dual-Card) that are safe to use in global light DOM without collision. No JavaScript runtime needed — pure CSS.

Live Components (Light-DOM CSS Classes)

These render using compiled .dual-* classes from _all-components.css — no web component runtime, just CSS.

Variable Override Demo

Component variables can be overridden at any scope — component tokens are color-only, so these buttons have a scoped fill/content override:

Consumer Code Examples

// Your app's SCSS — import dual component styles
@use 'dual/src/components/button/styles' as btn;
@use 'dual/src/components/card/styles' as card;

// Emit with default namespace for light-DOM use
@include btn.styles();     // → .Dual-Button, .Dual-Button--primary, ...
@include card.styles();    // → .Dual-Card, .Dual-Card-title, ...

// Override component color vars globally or per-scope:
:root {
  --dual-button-fill: var(--my-brand-primary);
}
.hero {
  --dual-button-fill: var(--my-brand-primary);
  --dual-button-content: #ffffff;
}

<!-- Load token layer + component CSS -->
<link rel="stylesheet" href="dual/css/components/button.css">

<!-- Use classes directly — no web component needed -->
<button class="Dual-Button Dual-Button--primary">
  Save changes
</button>

<button class="Dual-Button Dual-Button--ghost Dual-Button--small">
  Cancel
</button>

<!-- Override via scope (component tokens are color-only) -->
<section style="--dual-button-fill: #6d28d9;">
  <button class="Dual-Button Dual-Button--primary">Recolored</button>
</section>

SCSS Source Flow (Light-DOM highlighted)

Light-DOM Compile Stats

New capabilities — parameterized type · size scales · subtree modes

Both output paths (shadow-DOM components and light-DOM CSS) inherit these from the single SCSS source compiled into the granular dist/css/*.css layers and the dist/preset/full.css barrel.

Config-gated dist — granular layers → preset barrels

src/config.yaml compiles each layer once to its own file under dist/css/, then a presets: block composes three consumer load tiers under dist/preset/. A layer disabled in cssCompiled emits nothing and drops out of every barrel — so one toggle changes what a tier contains. Tiers below carry their real built sizes (this page loads preset/full.css).

See also: SUIT CSS Conventions — utilities, grid, and SUIT naming applied to this architecture.