Token Architecture Comparison

@siemens-iris/iris-core@0.10.0 (marketing foundation) vs @siemens/ix@5.2.0 (product foundation) — structural analysis of token systems, theme switching, and component theming.

663
iris semantic tokens
~240
iX tokens per theme
1
iris component-level prop
25+41
iX component props + modules
4
iris themes
2×N
iX families × schemas

Token Flow Graphs

Primitives / Core
Semantic / Theme
Emitted Variables
Consumption
Override Layer

iris-core

Marketing

Siemens iX

Product
Click any node in either graph to see its role.

Structural Comparison

Aspectiris-core @0.10.0@siemens/ix @5.2.0
Token prefix --iris-* --theme-*
Token tiers 2 tiers: primitives → semantic → components bind semantic directly 3 tiers: primitives → semantic → component tokens → components
Semantic token count 663 --iris-* (× 5 scopes = 3,376 declarations) ~240 --theme-* per theme (× 2 schemas)
Component-level tokens 1 (--iris-action-content-color) 25 --theme-color-component-* + 41 SCSS modules
Theme switch mechanism Single CSS class: .iris-ui-theme-{light,dark,sand,wireframe} Two HTML attributes: [data-ix-theme=family][data-ix-color-schema=dark|light]
Theme dimensionality 1D — four named modes (flat list) 2D — family × schema (orthogonal, extensible)
Component theming surface Scattered — components bind ~40 semantic tokens directly; override surface = hunt for the right token Explicit — component tokens form the documented API; override one --theme-btn-* prop
State handling Hardcoded in each component's CSS (:hover { background: var(--iris-action-fill-1-hover) }) State modifiers as tokens: --theme-btn-primary--background--hover
Per-component SCSS export None — scss/ has only token layers + 1 mixin 41 modules at scss/theme/core/components/*.scss
Component CSS distribution Shadow-only — no exported light-DOM classes Shadow-only — but variable modules enable re-theming without class access
Encapsulation Shadow DOM (Stencil) — identical model Shadow DOM (Stencil) — identical model
CSS file structure Monolithic iris.css (185 KB, no @layer) Per-theme files (classic-dark.css, classic-light.css)
Token duplication ~5× duplication — :root + 4 mode classes repeat the full token set 2× per family — one file per schema (dark/light), no duplication within a file
Typography delivery 84 utility classes (.iris-sans-*, .iris-slab-*) always shipped Token-only — no utility classes shipped
Consumer brand theme Override --iris-* on :root or under a mode class Author a new theme family emitting --theme-*; ThemeSwitcher selects it

Gap Analysis — Where iris Trails iX

1. No Component Token Tier

  • Gap: iris components bind ~491 semantic token refs directly. No --iris-button-* contract.
  • Impact: Re-theming one component means finding and overriding scattered semantic tokens. No documentation of "which tokens a button uses."
  • iX solution: 25 --theme-color-component-* props + 41 per-component SCSS modules declaring the mapping.
  • Fix (DESYS-434): Introduce --iris-<component>-* tier; components bind only those; defaults resolve from semantic.

2. No Per-Component SCSS Export

  • Gap: scss/ has only token layers. No scss/components/button.scss.
  • Impact: Consumers cannot import component styling independently or use it without the WC runtime.
  • iX solution: scss/theme/core/components/ — 41 modules with @mixin setVars.
  • Fix (DESYS-1287): Per-component scss/components/<name>/_variables.scss + _styles.scss.

3. States Hardcoded, Not Tokenised

  • Gap: :hover, :active, :disabled colours are inline in each component's shadow CSS.
  • Impact: Changing hover colour for one component requires knowing which semantic token that rule binds.
  • iX solution: State modifiers as tokens: --theme-btn-primary--background--hover.
  • Fix: Component tier carries state slots: --iris-button-fill-hover defaulting from semantic.

4. 1D Theme vs 2D Theme

  • Gap: iris has 4 flat named themes. Cannot express "brand X in dark mode" vs "brand X in light mode".
  • Impact: Adding a partner brand means authoring 4 full theme classes (light+dark+sand+wireframe).
  • iX solution: Orthogonal [data-ix-theme=family] × [data-ix-color-schema=dark|light].
  • Fix: Lower priority — consider after the component tier is in place. May adopt data-* attributes.

5. Monolithic CSS vs Per-Theme Files

  • Gap: 185 KB iris.css emits every token × every mode in one file (5× duplication).
  • Impact: Consumers always pay full cost even if using one theme. No tree-shaking.
  • iX solution: Separate classic-dark.css / classic-light.css — load only what's needed.
  • Fix (DESYS-434): Split into base + per-theme + per-component CSS, use @layer.

6. What iris Does Well

  • Richer semantic tier: 663 tokens vs iX's ~240 — more granular naming.
  • Typography utilities: 84 ready-to-use classes (iX has none).
  • Simpler switching: One class toggle vs two attributes — easier for static sites.
  • Same delivery model: Both use Stencil + Shadow DOM + CSS custom properties — alignment is structural, not a rewrite.

Alignment Path — Converging Without Merging

iris and iX serve different contexts (marketing vs product) and will remain separate packages. The goal is structural alignment — the same architectural tiers, so that shared tooling, theme tokens, and consumer patterns work across both without learning two different models.

StepWhatTicket
1Add component-token tier (--iris-<component>-* defaulting from semantic)DESYS-434
2Per-component SCSS modules (scss/components/<name>/)DESYS-1287
3Namespaced light-DOM class distribution (the $namespace dual-output)DESYS-1287
4Layered CSS delivery (@layer, per-theme files, tree-shakeable)DESYS-434
5Consider 2D theme model (data-* family × schema)Future