Methane@methane-ui/*
CSS LayoutsComponentsSkillsTheme BuilderGitHub

Architecture Decision Records (ADR-001 – ADR-015)

Every Methane package, component spec, and CI lint rule traces directly to these 15 locked architectural decisions.

ADR-001Lit 3 + Human-Owned UIElement & @lit-labs/ssr Over Custom Micro-Kernel
Context
Maintaining a bespoke micro-kernel across 200+ custom elements creates subtle edge-case risk around reactive batching, Trusted Types, and streaming SSR.
Decision
Adopt Lit 3 wrapped in a thin human-owned UIElement base class (tested with fast-check) adding DSD hydration, FACE wiring, :state() helpers, i18n lookup, and dev warnings; wrap @lit-labs/ssr behind @methane-ui/ssr.
Consequence
Cold first-component cost includes lit, while template security, reactive ergonomics, and SSR maturity improve dramatically.
ADR-002Controller-Only Reuse & Strict Acyclic Composition DAG
Context
Subclassing components or importing sibling internals creates brittle coupling across ~250 deliverables.
Decision
Share behavior exclusively via @methane-ui/primitives controllers/cores. Nest <mth-*> elements strictly via public tags, props, slots, events, and ::part(), enforcing tokens/sanitize -> core -> primitives -> ui -> kits -> satellites.
Consequence
Components and shards can be built and refactored in parallel without breaking siblings.
ADR-003Same-Root ARIA Only (Self-Labeled Shadow Controls)
Context
aria-* ID attributes never cross shadow roots, while ariaLabelledByElements and Reference Target are not universally Baseline Widely Available.
Decision
Every aria-* ID resolves within a single DOM root. Controls render internal <label>, hint, and error nodes in Shadow DOM and support external <label for> via ElementInternals.labels. <mth-field> is purely layout and Context.
Consequence
Universal screen-reader reliability across all Baseline browsers today.
ADR-004Declarative Child Elements as Canonical Collection API
Context
Property-only collection APIs fail in static HTML, streaming SSR, and no-JS progressive enhancement.
Decision
Light DOM child elements (<mth-option>, <mth-column>, <mth-tab>, <mth-tree-item>) are canonical; JS arrays and DataSource<T> reconcile into the same model via SlotCollectionController.
Consequence
SSR and plain HTML work natively while JS consumers retain ergonomic array binding.
ADR-005Single DataSource<T> Contract & Shared DataController
Context
Divergent async pagination/filter APIs across Combobox, Table, Tree, Kanban, and Chat fragment app integration.
Decision
Standardize one DataSource<T> interface (query({ cursor | page, sort, filter, signal }) -> { items, total?, nextCursor? }) driven by DataController with caching and AbortController cancellation.
Consequence
One backend adapter integrates cleanly with every async component in Methane.
ADR-006Versioned Community Context Protocol Across Shadow Roots
Context
Prop-drilling theme, locale, field, and form state breaks across arbitrary user DOM and Shadow DOM boundaries.
Decision
Use event-based Community Context Protocol (context-request) with versioned payload schemas for Theme, Locale/Direction, Field->Control, and Form context.
Consequence
Framework-agnostic context works across shadow trees and tolerates minor version skew.
ADR-007Global Runtime Singleton with SemVer Negotiation
Context
Micro-frontends and bundlers can load duplicate copies of core modules, breaking modal Escape stacks, toasts, and registries.
Decision
Store shared coordinators at globalThis[Symbol.for('@methane-ui/runtime')] with semver negotiation (highest compatible version wins) and duplicate-core guard.
Consequence
Shared browser resources coordinate cleanly across separately bundled slices.
ADR-008Hybrid DSD Styles (<link rel="stylesheet"> + < 1 KB Critical Inline CSS)
Context
Repeating full inline <style> blocks inside every DSD shadow root bloats SSR HTML, while unguarded <link> tags risk FOUC.
Decision
Default DSD templates emit a cacheable <link rel="stylesheet"> plus a < 1 KB critical layout <style> shell, with an opt-in inline mode for email/edge. Pure-CSS primitives remain 0 B JS Light DOM.
Consequence
Minimal SSR HTML overhead and single-parse CSS caching with zero FOUC.
ADR-009Explicit Framework SSR Adapters & React 19 Native-First Types
Context
Meta-frameworks have distinct streaming SSR pipelines, and React 19 natively supports custom elements without runtime wrappers.
Decision
Deliver 6 tested SSR packages (@methane-ui/ssr + Next, Nuxt, SvelteKit, Astro, Angular), generate @methane-ui/react as zero-runtime React 19 types, and isolate React 18 shims in @methane-ui/react/legacy.
Consequence
Near-zero wrapper cost on React 19 and turnkey hydration purity across SSR frameworks.
ADR-010Baseline Widely Available Core + Dual-Path Progressive Enhancements
Context
Unguarded Newly/Limited Available APIs break non-supporting engines.
Decision
Target Baseline Widely Available and feature-detect every enhancement (base-select, anchor positioning, interestfor, ::scroll-button, moveBefore, EyeDropper, scoped registries, setHTML) with full fallbacks tested in CI.
Consequence
Honest bundle metrics and rock-solid cross-browser parity without sacrificing modern upgrades.
ADR-011Co-Located English Defaults + Context-Driven i18n Message Catalog
Context
Hardcoded English strings block international apps, while external i18n frameworks bloat bundles.
Decision
Inline tree-shakable English defaults per component in @methane-ui/core, overridable via Locale Context, props/slots, and lazy @methane-ui/locales packs with Intl.PluralRules and RTL bidi isolation.
Consequence
Zero-config English DX plus complete enterprise i18n/RTL support.
ADR-012Mandatory @methane-ui/sanitize & Defense-in-Depth Content Rules
Context
Rich text, Markdown, and streaming AI outputs are primary XSS/mXSS vectors, especially under Trusted Types CSP.
Decision
Ship @methane-ui/sanitize using native setHTML/parseHTML with a parity-configured bundled DOMPurify fallback (RETURN_TRUSTED_TYPE: true), disable raw HTML by default, allowlist http/https/mailto/tel URLs, and render SVGs via <img>.
Consequence
Eliminates DOM XSS sinks and works cleanly under require-trusted-types-for 'script'.
ADR-013Wrap-First Satellites with SemVer-Exempt .engine Escape Hatch
Context
Re-implementing enterprise grids, charts, editors, maps, or PDF viewers from scratch lags mature engines.
Decision
Wrap permissive engines (TanStack, ECharts, ProseMirror, CodeMirror 6, MapLibre, pdf.js, Three.js) behind <mth-*> APIs with token theming, accessible fallbacks, SatelliteEngineSuite tests, and typed .engine.
Consequence
Rapid delivery of heavy components with consistent <mth-*> ergonomics and zero lock-in.
ADR-014Behavior Specs as Data & Mechanical CI Gates for AI-Safe Authoring
Context
Scaling to 275 deliverables risks subtle APG, ARIA, and lifecycle regressions.
Decision
Require machine-readable <tag>.spec.ts files to generate tests, docs, CEM checks, and checklists; enforce 5 Class Conformance Suites, @methane-ui/lint-plugin static/runtime invariants, ariaSnapshot() matrices, and Hydration Purity.
Consequence
Turns parallel AI component authoring into a deterministic, mechanically verified factory.
ADR-015Methane Naming, @methane-ui/* Scope & mth- Prefix Convention
Context
Every package, custom element tag, token, custom event, and runtime symbol needs a terse, collision-free namespace.
Decision
Standardize on @methane-ui/* packages, mth-* tags (configurable via defineComponents({ prefix })), --mth-* tokens, mth-* custom events, .mth-* CSS primitives, and Symbol.for('@methane-ui/runtime').
Consequence
Terse 3-letter prefix minimizes HTML/SSR byte overhead and keeps every layer immediately recognizable.