This document is the authoritative record of design system decisions, tier assignments, and the token contract. The README covers quick-start usage.
As of 2026-08-25 the EEA design system has one design language: the
editorial family (editorial.css, tokens prefixed --eea-ed-*). Its design
principles — palette, type pairing, pillar system, and contrast reasoning —
originate at intelligence.entethalliance.org,
which is the canonical reference this repo aligns with. No other design
language is referenced by this repo.
| Aspect | Editorial family |
|---|---|
| Ground | Light-only warm paper #EDEAE3 |
| Ink | #16181A, secondary #5A645E (5.11:1 on page) |
| Type | Inter / Kode Mono |
| Accent | #1F5C4A program green |
| Edges | Hard rules, no shadows |
| Pillars | Anticipate #EE9BFC · Work #F3CF2B · Connect #FEABA0 — marks, never text |
| Theming | None — light only |
The former dark-first “core system” (tokens.css + base.css + nav.css +
nav.js + components.css) is deprecated — see
Legacy core system. The 2026-08-16
position that the two were “siblings, not reconcilable” is superseded: the
editorial family is now the system; the core files are a frozen
compatibility layer, not a parallel language.
| Property | How it carries the language today |
|---|---|
| intelligence.entethalliance.org | Origin and canonical reference. Inline <style>, local names (--page, --ink, --mid, --accent) |
| ops-policy-friday | Hand copy. Local names (--paper, --ink, --shop-*) |
| ops-business-scanner | Hand copy of the copy, via PR #19; migration onto editorial.css in PR #22 |
| wg-ethtrust-site | Built directly on editorial.css (WG playbook reference implementation) |
editorial.css exists to end the hand-copy duplication: all three original
properties ship the same site bar — same markup, same 36px mark, same three
pillar bars, same mono links — as independent copies. Drift is already
measurable: the mono label role had spread across nine font sizes and nine
tracking values between the copies before being collapsed onto the
three-step scale in --eea-ed-label-* / --eea-ed-track-*.
If intelligence.entethalliance.org’s design evolves, editorial.css follows
it — alignment PRs cite the site as the source of the change.
The following guarantees apply to all --eea-ed-* tokens on main.
| Guarantee | Detail |
|---|---|
| Names are stable | No token will be renamed without a deprecation period. Old name kept as alias for one release cycle. |
Accent is #1F5C4A |
--eea-ed-accent will not change hue unless intelligence.entethalliance.org itself changes; the site is the source of truth. |
Prefix is --eea-ed- |
No new tokens without the prefix. Avoids collision with any site’s local vars. |
| No visual effect until opt-in | editorial.css never writes :root’s theme tokens and never sets color-scheme on :root. Linking the file changes nothing — a page opts in with <body class="eea-editorial">. This is what lets it be linked next to legacy stylesheets safely. Any change to editorial.css must preserve it. |
| Load-order safe | No @import, no external network calls, no JS. |
| Components are keyboard-reachable | Every :hover state on a component this file styles has a matching :focus-visible state and a legible focus ring. A new component ships both or neither. |
| Pillar colours are semantic | Never decorative, never text — none clears 4.5:1 on the page ground. Text uses the -ink partners. |
editorial.css| Repo | PR | Status | What changed |
|---|---|---|---|
| wg-ethtrust-site | — | live | Built on editorial.css from the start (playbook reference implementation, 2026-08-24) |
| ops-business-scanner | #22 | open | Links editorial.css from Pages; bridge block onto --eea-ed-*; canonical .eea-site-bar / .eea-colophon markup; ~160 lines of duplicated rules deleted |
| ops-policy-friday | — | not started | Still carries its hand copy |
| intelligence.entethalliance.org | — | not started | Origin site; still inline <style> (adopting the file it originated is optional — it is the reference either way) |
Migrating a site onto editorial.css means: swapping local token names for
--eea-ed-* (bridge block), renaming .site-bar → .eea-site-bar in markup,
and removing the duplicated rules. Each is its own PR with its own
screenshots, following Adding a new site.
editorial.css per the README quick start; write page-local CSS only
against --eea-ed-* tokens; use the canonical .eea-site-bar /
.eea-colophon markup (WG playbook §5 has the full page pattern).#EDEAE3, Inter/Kode Mono resolved,
--eea-ed-accent resolution, no stray legacy accent #627eea.Some sites remain permanently outside the design system for regulatory, security, or UX reasons — do not add any design-system import to them, ever:
| Repo | Reason |
|---|---|
| eea-board-portal | Member-only governance tool; auth-gated; board portal conventions take precedence |
| wg-privacy | WG-maintained; external CDN dependency would require WG sign-off on every token update; intentionally self-contained |
The repo previously maintained a dark-first design language: IBM Plex
Sans/Mono, accent #627eea, 12px radii, shadows, data-theme dark/light
theming. Deprecated 2026-08-25. Its files (tokens.css, base.css,
nav.css, nav.js, components.css) remain served from main because the
sites below hot-link them — removal would break live properties.
Rules for the legacy layer:
--eea- prefix, dark default, load-order safety) continues
to hold in freeze — it just no longer grows.editorial.css instead of extending core-system usage.Kept as the record of which sites still consume the frozen files and are pending migration to the editorial family.
| Repo | Former tier | PR | Notes |
|---|---|---|---|
| ops-finance | A — full system | #5 | Full system import; ethereum-101 panel redesign |
| EntEthAlliance.github.io | A — full system | #16 | tokens.css + IBM Plex Sans; accent → #627eea |
| pages-index | A — full system | #1 | tokens.css; bg/accent/badge/font aligned |
| wg-ethereum-institute | B — tokens bridge | #1 | tokens.css + bridge block |
| rnd-rwa-erc3643-eas (Shibui) | B — tokens bridge | #100 | Brand vars → #627eea family; IBM Plex Sans |
| ops-solution-catalog | B — tokens bridge | #21 | Tailwind font stack + brand colour |
editorial.css is served live from main. Adopting sites link to main, so
token updates propagate automatically.
To pin to a specific version, link to a commit SHA:
https://raw.githubusercontent.com/EntEthAlliance/eea-design-system/<sha>/editorial.css
When a breaking token change is needed (name removal, value shift > 10%), a
new major path will be added (/v2/editorial.css) and sites will be migrated
explicitly via PR.
Current version: 1.2.0.
| Version / date | Change |
|---|---|
1.2.0 — 2026-08-25 |
:focus-visible states added to the .eea-site-bar and .eea-colophon links, matching each existing :hover state, plus a focus ring (accent on the bar’s paper ground, --eea-ed-deep-hover mint on the colophon’s deep green — the accent is not legible there). Additive: no token changed, and pages that do not use these components are unaffected. |
| 2026-08-25 | Governance: editorial family declared the sole design language, aligned with intelligence.entethalliance.org; core system deprecated and frozen. No served value changed. |
1.1.0 — 2026-08-16 |
editorial.css added — editorial family tokens + .eea-site-bar / .eea-colophon (#3) |
1.0.0 — 2026-07-22 |
Initial core-system rollout across 6 sites (now the legacy layer) |