- 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.
Architecture Decision Records (ADR-001 – ADR-015)
Every Methane package, component spec, and CI lint rule traces directly to these 15 locked architectural decisions.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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'.
- 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.
- 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.
- 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.