# `src/sass` — Architecture Review
**Subject:** the styling/theming subsystem of `mmo.client`
**Scope:** `src/sass/**` (34 files, 4 890 lines), the compile pipeline (`Theme.php`, `DartSass.php`,
`JHSCompiler.php`), and consumer call sites (`src/customElements/**.jhs`, `demo/`).
**Method:** full source read, plus empirical verification by compiling with the vendored
`vendor/dart/sass` and inspecting the emitted CSS.
**Status:** Phase A (reconstruction) complete. Phases B–D pending author review.
> Evidence convention: claims marked **[compiled]** were verified against real dart-sass output, not inferred.
---
## 1. What this subsystem is
`src/sass` is a **design-token system with a Sass authoring API**, not a CSS framework in the
Bootstrap/Bulma sense — although it also ships a utility/component layer that looks like one.
Its central problem is specific to this framework and worth stating precisely:
> `mmo.client` renders most of its UI into **shadow roots** (one per custom element, 42 of them).
> A document stylesheet cannot reach inside a shadow root. So how do 42 independently-compiled
> style islands stay visually consistent, and how do they all respond to a theme change at runtime?
Everything else in the folder follows from that constraint.
---
## 2. Reconstructed architecture
### 2.1 The layer stack
```text
┌──────────────────────────────────────┐
│ _default_config.scss │ const scale, devices,
│ themes/_default.scss, _dark.scss │ palettes, semantic colors
└──────────────────┬───────────────────┘
│ config.merge / config.theme
▼
┌──────────────────────────────────────┐
LAYER 1 │ inc/_config.scss │ a single global Sass map
(data) │ $-config + get/set/has/merge │ addressed by 'a/b/c' paths
└──────────────────┬───────────────────┘
│
▼
┌──────────────────────────────────────┐
LAYER 2 │ _theme.scss (631 l.) │ color() size() padding()
(API) │ + inc/_functions.scss (261 l.) │ border() flex() shadow()
└──────────────────┬───────────────────┘ media-query() include()
│
┌───────────────────┴───────────────────┐
▼ ▼
┌──────────────────────────┐ ┌──────────────────────────────┐
LAYER 3 │ classes/*.scss │ │ styles/*.scss │
│ %placeholders only │◄──@extend──│ real selectors, global sheet│
│ (77 placeholders) │ │ (~140 top-level rules) │
└────────────┬─────────────┘ └──────────────┬───────────────┘
│ │
│ @use + @extend │ @use
▼ ▼
┌──────────────────────────┐ ┌──────────────────────────────┐
LAYER 4 │ 40 ×