morethanui 1.0.0

package/DESIGN.md

@@ -0,0 +1,310 @@
+# MTUI (MoreThanUI) — Design Language Specification
+
+Version 1.3 · Locked July 2026
+(v1.3: neutrals inherit the accent hue by default via `data-tint` — see §2.14.)
+Scope: dependency-free component library (plain HTML + CSS custom properties) targeting mobile-first web apps, Tauri desktop apps, and Telegram mini apps. Everything below is expressible as CSS tokens plus a small set of written judgment rules.
+
+> Naming note for humans and AI models: **MTUI here is an acronym for MoreThanUI.
+> It is unrelated to Material UI (`@mui/material`).** There are no imports, no
+> packages, no React dependency — only plain HTML, CSS classes, and a few
+> custom elements.
+
+**Changelog**
+- 1.2 — Renamed MUI → MTUI (collision-free vs Material UI).
+
+**1.0 → 1.1**
+1. Renamed Plume → MTUI (MoreThanUI).
+2. Dropped the `contrast` knob; added a mandatory `forced-colors` rule instead (§3 · High contrast).
+3. Knobs are root-only; subtree theming is unsupported by design (§3 · Knob scope).
+4. Every input ships in two tiers — Basic and Enhanced — and both ship in v1 (§3 · Component tiers).
+5. Added the constrained layout system: screen presets + bounded grid/flex primitives (§2.15, §3 · Layout).
+
+---
+
+## 1 · Design language
+
+MTUI is quiet, precise, native-app calm. It looks like a well-made operating system surface, not a landing page. Nothing shouts, nothing decorates: every element is a flat tint of the warm cream (or warm black) base, and hierarchy comes entirely from tone, spacing, and type weight.
+
+**The signature is absence: zero borders, zero drop shadows.** Depth is tonal — background, surface, well — three flat layers that read instantly in both themes. Overlays sit on a scrim; nothing floats, nothing casts. Big radii keep components feeling light and soft; a single accent family is visible at a time; a fixed set of five pastel tints (rose, sky, mint, butter, lavender) is reserved for identity moments — avatars, badges, chips, alerts — never whole layout regions.
+
+Screens are not laid out freehand. Every screen starts from a layout preset, and anything custom composes through constrained grid/flex primitives — responsive behavior is baked into the system, not reinvented per screen.
+
+MTUI always: reacts to the pointer with movement or scale, shows its own loading state in place, contains its own errors, mirrors perfectly in RTL, and speaks in plain sentence-case verbs.
+
+MTUI never: draws a hairline to separate things, fades content in and out (fade belongs to deletion and popovers only), uses uppercase letter-spaced labels, uses more than one accent hue in a view, or lets one broken component take the page down with it.
+
+---
+
+## 2 · Token specification
+
+### 2.1 Neutrals — light theme
+
+| Token | Value | Role |
+|---|---|---|
+| `--bg` | `#F3F0EA` | App background (warm cream) |
+| `--surface` | `#FFFFFF` | Cards, sheets, menus |
+| `--surface-2` | `#EAE6DD` | Wells, fields, secondary buttons, skeletons |
+| `--surface-3` | `#DFD9CD` | Hover state of wells, switch tracks |
+| `--text` | `#1C1A17` | Primary text |
+| `--text-muted` | `#67625A` | Secondary text, hints |
+| `--text-faint` | `#A8A297` | Placeholders, disabled text (decorative only) |
+| `--border` | *unused by design* | Reserved; MTUI separates by tone, not lines (exception: forced-colors mode, §3) |
+| `--inverse` / `--on-inverse` | `#1C1A17` / `#F3F0EA` | Toasts, tooltips |
+| `--scrim` | `rgba(28,26,23,.44)` | Behind dialogs |
+
+### 2.2 Neutrals — dark theme
+
+| Token | Value |
+|---|---|
+| `--bg` | `#161513` |
+| `--surface` | `#211F1C` |
+| `--surface-2` | `#2B2925` |
+| `--surface-3` | `#38352F` |
+| `--text` | `#F0EDE7` |
+| `--text-muted` | `#A39D92` |
+| `--text-faint` | `#6B665D` |
+| `--inverse` / `--on-inverse` | `#F0EDE7` / `#1C1A17` |
+| `--scrim` | `rgba(0,0,0,.55)` |
+
+### 2.3 Accent options (knob: `accent`)
+
+One accent visible at a time. `--on-accent` is always `#FFFFFF`. Same solid values in both themes; only the tint swaps.
+
+| Accent | `--accent` | `--accent-hover` | `--accent-text` | tint (light) | tint (dark) |
+|---|---|---|---|---|---|
+| clay *(default)* | `#BC4B2A` | `#A93F20` | `#8F3016` | `#F3DCD6` | `#3A2723` |
+| cobalt | `#3556C9` | `#2B49B2` | `#2B44A6` | `#DCE3F7` | `#232B45` |
+| fern | `#2F7A50` | `#276A44` | `#245D3D` | `#DCEEE2` | `#22352A` |
+| plum | `#6E46BD` | `#5F3AA8` | `#56349B` | `#E6E0F2` | `#2E2A3C` |
+
+`--focus` = current `--accent`.
+
+**Secondary brand color (§2.3b, v1.3).** `--accent` is the *primary* (buttons, switch-on, focus, selected states, and the surface tint). A second family — `--accent-2`, `--accent-2-hover`, `--accent-2-text`, `--accent-2-tint`, `--on-accent-2` — is the *accent* for a second highlight (e.g. `data-variant="accent"` buttons). By default it **mirrors `--accent`** (`--accent-2: var(--accent)` etc.), so the four presets stay monochrome; the custom-theme generator sets it to a different hue when an app wants a distinct primary + accent. Both families use the identical §2.14 derivation, so `--accent-2` carries the same contrast guarantees. The surface tint always follows the **primary**.
+
+### 2.4 Status colors
+
+| Token | Light | Dark |
+|---|---|---|
+| `--danger` (solid, white text) | `#B3402F` | `#B3402F` *(keep light value — the lighter `#C9553F` fails AA with white)* |
+| `--danger-text` / `--danger-tint` | `#8F3016` / `#F3DCD6` | `#F0A896` / `#3A2723` |
+| `--success-text` / `--success-tint` | `#245D3D` / `#DCEEE2` | `#8ED1AB` / `#22352A` |
+| `--warning-text` / `--warning-tint` | `#7A5600` / `#F2E8D0` | `#E4C27E` / `#383021` |
+
+### 2.5 Identity tints (avatars, chips, alerts — never layout)
+
+| Tint | Light bg / text | Dark bg / text |
+|---|---|---|
+| rose | `#F3DCD6` / `#8F3016` | `#3A2723` / `#F0A896` |
+| sky | `#DCE3F7` / `#2B44A6` | `#232B45` / `#A9C3EC` |
+| mint | `#DCEEE2` / `#245D3D` | `#22352A` / `#8ED1AB` |
+| butter | `#F2E8D0` / `#7A5600` | `#383021` / `#E4C27E` |
+| lavender | `#E6E0F2` / `#56349B` | `#2E2A3C` / `#C9BCF0` |
+
+### 2.6 Contrast ratios (WCAG)
+
+All pairs independently re-verified July 2026 (computed, not estimated).
+
+| Pair | Ratio | Verdict |
+|---|---|---|
+| text / bg (light) | 15.3:1 | AAA |
+| text / surface (light) | 17.4:1 | AAA |
+| text-muted / surface (light) | 6.1:1 | AA |
+| text-muted / bg (light) | 5.3:1 | AA |
+| text-muted / surface-2 (light) | 4.9:1 | AA *(minimal headroom — muted text never goes inside wells at small sizes)* |
+| text / bg (dark) | 15.6:1 | AAA |
+| text / surface (dark) | 14.1:1 | AAA |
+| text-muted / surface (dark) | 6.1:1 | AA |
+| white / clay `#BC4B2A` | 5.0:1 | AA |
+| white / cobalt `#3556C9` | 6.3:1 | AA |
+| white / fern `#2F7A50` | 5.2:1 | AA |
+| white / plum `#6E46BD` | 6.4:1 | AA |
+| white / danger `#B3402F` | 5.7:1 | AA |
+| accent-text / accent-tint (clay, light) | 6.2:1 | AA |
+| tint text / tint bg (all five, both themes) | 5.4–7.9:1 | AA |
+| text-faint | — | decorative only; never carry information |
+
+### 2.7 Type
+
+One family: **Noto Sans** (+ **Noto Sans Arabic** for `ar`, **Noto Sans Mono** for code blocks only). Weight does the hierarchy work — never letter-spacing, never uppercase.
+
+| Style | Spec |
+|---|---|
+| Page title | 800 · 38px / 1.12 · tracking −0.02em |
+| Section title | 700 · 26px / 1.2 · −0.01em |
+| Card title | 700 · 19px / 1.3 |
+| Row title / buttons | 600 · 15–16px / 1.4 |
+| Body | 400 · 16px / 1.6 |
+| Secondary | 400 · 14px / 1.5 · `--text-muted` |
+| Label | 600 · 13px · `--text-muted` |
+| Code | 400 · 13px / 1.7 · Noto Sans Mono, in `--surface-2` block |
+
+### 2.8 Spacing
+
+4px base: **4 · 8 · 12 · 16 · 20 · 24 · 32 · 40 · 48**. Layout is always flex/grid with `gap`. Gap values come exclusively from this scale — arbitrary values are not part of the system (see §2.15).
+
+### 2.9 Radius presets (knob: `radius`)
+
+| Token | sharp | soft | round *(default)* |
+|---|---|---|---|
+| `--r-ctl` (buttons, switches, segmented) | 8px | 14px | 999px |
+| `--r-card` | 12px | 20px | 24px |
+| `--r-input` | 8px | 12px | 16px |
+| `--r-chip` | 6px | 10px | 999px |
+
+### 2.10 Density (knob: `density`)
+
+| Token | comfortable | compact |
+|---|---|---|
+| `--ctl-h` / `--field-h` | 48px | 44px |
+| `--row-h` | 64px | 52px |
+| `--pad` (card padding) | 20px | 14px |
+| `--gap` | 16px | 10px |
+
+44px is the floor — compact never goes below it for anything tappable.
+
+### 2.11 Elevation (tonal levels)
+
+| Level | Means | Used for |
+|---|---|---|
+| 0 | `--bg` | Page |
+| 1 | `--surface` | Cards, menus, popovers |
+| 2 | `--surface-2` | Wells, fields, skeletons, secondary buttons |
+| overlay | `--scrim` + level 1 | Dialogs |
+
+No `box-shadow` for depth, ever. The two sanctioned box-shadow uses are non-depth: the focus ring (`0 0 0 2px surface, 0 0 0 4px accent`) and the 3px surface-colored ring around stacked avatars. Popovers separate from content with a 6px `--bg`-colored ring, not a shadow.
+
+### 2.12 Motion
+
+| Token | Value |
+|---|---|
+| `--ease` | `cubic-bezier(.22,.9,.28,1)` |
+| `--spring` | `cubic-bezier(.34,1.2,.4,1)` |
+| Micro feedback (hover/press, color) | 200–250ms `--ease` |
+| Card lift | 280ms `--ease` |
+| Switch / checkbox / radio knobs | 300ms `--spring` |
+| Popover in/out | transform 300ms `--spring` + opacity 220ms `--ease` |
+| Tab pill slide | 350ms `--spring` |
+| Dialog | 400ms `--spring` (+ scrim color 300ms) |
+| Toast | 500ms `--spring` |
+| Delete fade | 350ms opacity + scale(.96) |
+| Skeleton sheen | 1.5s loop, blurred solid bar translating across |
+
+Animate **transform and opacity only** (60fps rule). Color/background transitions are allowed for state tints since they don't reflow.
+
+### 2.13 Feedback (haptics + sound)
+
+Synthetic sine waves via WebAudio — no audio files. Global mute control required.
+tick 880Hz·50ms · toggle-on 520→784Hz · toggle-off 784→520Hz · success 660→880Hz · error triangle 233Hz·160ms. Gain ≤ 0.06.
+Haptics: `navigator.vibrate(8)` on toggles/confirmations, `[20,40,20]` on errors. Only where it means something: toggles, confirmations, arrivals, failures — never on hover or scroll.
+
+### 2.14 Theme generator guardrails
+
+Brands may generate a custom accent; hue is free, lightness and chroma are clamped so contrast and calm survive:
+
+```
+--accent:        oklch(52% C H)        /* C clamped 0.06–0.17 */
+--accent-hover:  oklch(47% C H)
+--accent-tint:   light  oklch(92% min(0.32·C, 0.05) H)
+                 dark   oklch(30% 0.35·C H)
+--tint-text:     light  oklch(41% 0.85·C H)
+                 dark   oklch(84% 0.45·C H)
+```
+
+52% lightness at any hue keeps ≥4.5:1 with white text. Type, spacing, and motion are not brand-tunable.
+
+**Neutral tinting (`data-tint`, v1.3).** MTUI neutrals were never flat grey — they always carried a low-chroma tint (a fixed warm ~85° hue). As of v1.3 that tint **inherits the accent hue by default** (`data-tint="accent"`), so the whole UI shifts to the brand: a blue accent gives blue-grey surfaces, green gives green-grey — the cohesive behaviour of Telegram/Material, not a warm shell around a foreign accent. `data-tint="warm"` opts back into the fixed warm neutral (the ≤v1.2 look). Only the **hue** follows the accent; every neutral's **lightness and chroma stay fixed**, so the tonal ladder and all §2.6 contrast pairs are unchanged at any accent. Derived with relative-color syntax (`oklch(from var(--accent) L C h)`); webviews without it fall back to the warm neutral, so tinting is a progressive enhancement, never a hard dependency.
+
+Ramp — L and C fixed, H = accent hue:
+
+| token | light (L · C) | dark (L · C) |
+|---|---|---|
+| `--bg` | 95.6% · .010 | 19.6% · .010 |
+| `--surface` | 99% · .006 | 24% · .014 |
+| `--surface-2` | 92.6% · .014 | 28.2% · .018 |
+| `--surface-3` | 88.7% · .018 | 33% · .022 |
+| `--text` | 21.9% · .008 | 94.7% · .008 |
+| `--text-muted` | 49.8% · .014 | 69.8% · .016 |
+| `--text-faint` | 71.4% · .017 | 51.2% · .015 |
+
+### 2.15 Layout system
+
+Layout is a component, not a habit. No screen is laid out with hand-written page CSS; screens start from a **preset**, and custom regions compose through **constrained primitives**. Every value a layout accepts is an enum or a scale step — arbitrary numbers are rejected by omission (there is simply no token for them).
+
+**Screen presets** (one per screen, the outermost element after the shell):
+
+| Preset | Purpose | Baked-in responsive behavior |
+|---|---|---|
+| `shell` | App frame: header + content + navigation | Navigation renders as a bottom tab bar below 768px, a side rail at ≥768px; header is sticky; safe-area insets handled; content region scrolls, frame doesn't |
+| `screen-stack` | Settings, forms, articles, detail pages | Single scrolling column; max-width 40rem centered at ≥768px, full-bleed below; standard `--pad` inline padding; `--gap` stack rhythm |
+| `screen-list` | Feeds, chats, search results | Full-bleed scrolling list region + sticky header slot; list rows manage their own inline padding; pull-to-refresh mounts here |
+| `screen-split` | List + detail (mail, chat apps) | Two panes at ≥900px (side pane 20–24rem, detail flexes); below 900px collapses to a navigation stack (list screen pushes detail screen) |
+| `screen-center` | Auth, onboarding, empty and error states | Content block centered both axes, max-width 24rem, safe-area aware |
+
+**Constrained primitives** (inside presets, for custom composition):
+
+| Primitive | Options (enums only) |
+|---|---|
+| `stack` | gap: scale step (default `--gap`) · align: start / center / stretch |
+| `row` | gap: scale step · align: start / center / end / between · wrap: on/off |
+| `grid` | Fixed column system: 4 columns (<768px) / 8 (768–1199px) / 12 (≥1200px) · gutter fixed 12px · children take integer spans per breakpoint (e.g. span 4, span-md 4, span-lg 6) · spans clamp to the column count — nothing overflows |
+
+Constraints, by design: no arbitrary gap values, no custom grid templates, no absolute positioning in app code (only components position absolutely, internally), no fixed pixel widths on content regions. If a layout can't be expressed with presets + primitives, that's a signal to add a preset to the system — not to hand-roll the screen.
+
+**Diagnostics:** every layout preset and primitive accepts an `outline` option that renders dashed region/column/span overlays (the dashed lines are a build-time diagnostic, not UI, and are exempt from the no-borders rule).
+
+---
+
+## 3 · Look-and-feel rules
+
+**Borders vs shadows.** Neither, on-page. Separation is a change of surface tone. If two areas need dividing, give them different surfaces or more gap — never a line. Inputs are wells (`--surface-2` on `--surface`); when a card sits on `--bg` it is white and needs nothing else.
+
+**Overlay exception (v1.3).** Floating overlay surfaces — the shared `.menu` popover foundation (popover menu, and the `x-select` / `x-datepicker` / `x-colorswatches` / `x-contextmenu` panels) — may carry a single 1px `--surface-3` tonal border. They open over an unpredictable backdrop (another surface, a card, an arbitrary pointer position), where a tone-only edge or the `--ring-popover` bg-ring reads as a stray line; a subtle tonal border reads as intentional against anything. This is the ONLY on-screen border exception — it applies to floating overlays only; every on-page component stays strictly borderless. (`--ring-popover` remains for raised panels that sit on the page background, where the ring works.)
+
+**High contrast (forced-colors).** A sanctioned exception to zero borders. Under `@media (forced-colors: active)`, tonal separation disappears, so every component draws real borders using system colors (`CanvasText`, `ButtonBorder`), the focus ring becomes a standard `outline`, and skeleton sheens/scrims fall back to system defaults. This is a mandatory per-component CSS block, not a knob and not part of the visible design language.
+
+**Knob scope.** All knobs (`theme`, `radius`, `density`, `accent`) are set once, on `<html>`, as data attributes. Subtree theming is unsupported and undocumented by design — this is what structurally enforces "one accent per view" and "never mix radius presets within one screen" instead of relying on prose rules.
+
+**Component tiers.** Every component declares its tier, and inputs ship in two variants — both included in v1:
+- **Basic** — the styled native element (or CSS-only construction). Works with zero JS. This is the fallback that always exists underneath.
+- **Enhanced** — the MTUI-drawn version (custom select panel, date picker, color swatches, context menu, pull-to-refresh, toasts, sound/haptics). Enhanced is the *default face* of the library: apps show MTUI-drawn inputs, never browser chrome. Each Enhanced component progressively upgrades its Basic markup, so removing JS degrades every screen to Basic, functional and on-language.
+
+**Elevation.** Three tonal levels, used in order, never skipped (no well directly on bg without a surface between, except full-screen wells like segmented controls). Anything above the page (menu, select panel, tooltip, toast, dialog) is level 1 on a scrim or bg-colored ring.
+
+**Hover / press / focus.** Everything interactive responds: hover = background tone shift and/or −2px translateY (cards −3px); press = scale(.96–.98); focus-visible = 2px accent ring with a 2px surface gap. Rows may also nudge 3px inline-start. Movement and scale, not fade.
+
+**Loading.** Any action that isn't instant swaps its label for a spinner in place (button keeps its size). Any layout waiting on data shows sheen skeletons matching the final shape — a moving blurred bar, never an opacity pulse. Pull-to-refresh ships with every scrolling list: indicator rotates with the pull, springs back, resolves in a toast.
+
+**Errors.** Every component is its own boundary. Failure renders inside the component's own footprint — tinted rose panel, plain sentence, Retry button that shows a skeleton while retrying. The page around it never re-renders or breaks.
+
+**Toasts.** Drop from the top center like a dynamic island: spring down + scale up, stack vertically (max 3), each leaves by sliding up. Inverse surface, pill radius, one short sentence, optional single action.
+
+**Deletion.** Always confirm in a dialog first; on confirm the element fades + scales to .96 and collapses. Fade is reserved for exactly this (and popover exit).
+
+**Inputs.** Every picker (select, date, color, context menu) is an MTUI-drawn Enhanced component, not browser chrome; the Basic native element remains underneath as the no-JS fallback. Right-click gets the MTUI context menu. Color pickers are curated swatches, never a free wheel.
+
+**Layout.** Screens are composed, not drawn: pick a screen preset, fill its slots with components, use stack/row/grid for custom regions. Responsive behavior lives in the presets — app code never writes media queries for layout. The `outline` diagnostic is the first tool for debugging a layout, and it never ships on.
+
+**RTL.** Only logical properties (`inline-start/end`, `text-align:start`); direction comes from the document. Numerals, emails, and code stay LTR inside RTL rows. Directional chevrons flip with direction.
+
+**Dark mode beyond colors.** Same tonal ladder — surfaces get *lighter* as they rise. The neutral hue follows the accent under `data-tint` (§2.14): warm by default only under `data-tint="warm"`, otherwise blue-grey, green-grey, etc. to match the brand. Tints drop to low-luminance versions with light same-hue text; solid accents stay identical; scrim deepens. Nothing else changes: no dark-only borders, no added glow.
+
+**Density.** Compact tightens padding, rows and gaps but never type sizes or the 44px touch floor. It's a workspace/desktop affordance, not a phone one.
+
+**Icons.** Lucide, 2px stroke, `currentColor`, 15–20px inline with text. No emoji, no filled icon styles, no icon fonts.
+
+---
+
+## 4 · Do / don't
+
+1. **Do** separate regions with tone and gap; **never** draw a border, hairline divider, or outline (exceptions: the floating-overlay border per §2.9 above, forced-colors mode, and the layout `outline` diagnostic — which never ships on).
+2. **Do** move or scale on interaction; **never** fade content in/out except deletion and popover exit.
+3. **Do** show a spinner inside the control and skeletons in the layout while waiting; **never** block the page or show a bare white gap.
+4. **Do** contain failures in the failing component with a Retry; **never** let one error blank or crash the screen.
+5. **Do** use one accent family per app, with tints for identity moments; **never** show two accent hues in one view or tint a whole layout region pastel.
+6. **Do** build hierarchy with Noto Sans weight and size; **never** use uppercase tracking, a second display face, or mono outside code blocks.
+7. **Do** use logical properties everywhere; **never** write `left`/`right`/`margin-left` in component CSS.
+8. **Do** keep every tap target ≥44px and every text/background pair ≥4.5:1; **never** put information in `--text-faint`.
+9. **Do** use pill/round radii by default; **never** mix radius presets within one screen — knobs live on `<html>` only, never on subtrees.
+10. **Do** confirm before destroying, then fade; **never** delete instantly on a single tap, and never play sound or haptics without a matching visible event.
+11. **Do** start every screen from a layout preset and compose custom regions with stack/row/grid; **never** hand-write page layout CSS, media queries, absolute positioning, or arbitrary gaps in app code.
+12. **Do** show MTUI-drawn (Enhanced) inputs as the default face of every app; **never** expose raw browser chrome for pickers — and every Enhanced input keeps its Basic native fallback underneath.

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 MoreThanUI (MTUI) contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+The bundled fonts in fonts/ are licensed separately under the SIL Open Font
+License; see fonts/OFL.txt.

package/README.md

@@ -0,0 +1,119 @@
+# MTUI (MoreThanUI)
+
+A dependency-free, framework-agnostic UI component library: plain HTML + CSS
+custom properties + a few light-DOM **Web Components**. No framework, no
+runtime packages, **no build required to use it**. Targets mobile-first web
+apps, Tauri desktop apps, and Telegram mini apps.
+
+*(MTUI = MoreThanUI. Unrelated to Material UI — there is nothing to import to
+write markup.)*
+
+The whole thing is **~19 KB gzipped** (every component + all CSS), minified;
+the self-hosted fonts are the only larger asset and are optional.
+
+## Install
+
+**Copy the files** (most on-brand — zero tooling): drop `css/`, the `js/`
+files you use, and `fonts/` into your project and link them.
+
+**npm:**
+
+```sh
+npm install morethanui
+```
+
+**CDN** (no install; jsDelivr mirrors npm):
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/morethanui/dist/mtui.min.css">
+<script src="https://cdn.jsdelivr.net/npm/morethanui/dist/mtui.min.js" defer></script>
+```
+
+## Quick start
+
+```html
+<!doctype html>
+<html data-theme="light" data-accent="clay" data-radius="round" data-density="comfortable">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+  <link rel="stylesheet" href="node_modules/morethanui/dist/mtui.min.css">
+</head>
+<body class="shell">
+  <main class="shell-content">
+    <div class="screen-stack">
+      <h1 class="t-page">Settings</h1>
+      <button class="btn" data-variant="primary">Save changes</button>
+    </div>
+  </main>
+  <script src="node_modules/morethanui/dist/mtui.min.js" defer></script>
+</body>
+</html>
+```
+
+The four `data-*` attributes on `<html>` are the theme knobs. Copy any
+component from **`llms.txt`** (the complete API — one canonical example each).
+
+## Two ways to include it
+
+- **Bundle (drop-in / CDN):** `dist/mtui.min.css` + `dist/mtui.min.js` — every
+  component, one file each. `import 'morethanui'` (JS) / `import 'morethanui/style.css'`.
+- **À la carte (only what you use):** each component is its own file with **no
+  imports between them**, so you pull in exactly what you use:
+
+  ```js
+  import 'morethanui/css/tokens.css';
+  import 'morethanui/css/base.css';
+  import 'morethanui/css/components.css';   // one stylesheet, all component classes
+  import 'morethanui/js/x-select.js';       // self-registers <x-select>; import only these
+  ```
+
+  (JS is tree-shakeable by file; CSS ships as one `components.css`.)
+
+## Frameworks
+
+The components are standard Custom Elements (light DOM, no Shadow DOM), so:
+
+- **Svelte / Vue / Solid / Angular / vanilla:** work out of the box — attributes
+  and slots pass straight through; CSS is global.
+- **React 19+:** first-class (properties and custom events supported).
+- **React ≤18:** the markup + CSS work; for a component's `change` / `select`
+  CustomEvent, attach a `ref` + `addEventListener` (React ≤18 doesn't auto-bind
+  custom events). Everything else is plain attributes.
+
+## Theming
+
+Root-only knobs on `<html>`:
+
+| Knob | Values |
+|---|---|
+| `data-theme` | `light` · `dark` |
+| `data-accent` | `clay` · `cobalt` · `fern` · `plum` · `custom` |
+| `data-radius` | `round` · `soft` · `sharp` |
+| `data-density` | `comfortable` · `compact` |
+| `data-tint` | `accent` (default — neutrals follow the accent hue) · `warm` |
+
+Drop in `<x-theme></x-theme>` for a live in-app appearance panel, or generate a
+custom two-color brand in the showcase.
+
+## Docs
+
+- **`llms.txt`** — the complete, copy-pasteable API (optimized for AI models too).
+- **`demo/index.html`** — the interactive showcase: every component, live,
+  driven by the theme controller (`make dev`).
+- **`DESIGN.md`** — the design language (source of truth).
+
+## Develop
+
+```sh
+make dev       # serve the showcase
+make test      # contrast checks + Playwright component suite
+make bundle    # rebuild dist/ (optional; the authored files need no build)
+```
+
+Dev tooling (vite, esbuild, Playwright) is fetched on demand and never becomes
+a runtime dependency — the shipped library stays dependency-free.
+
+## License
+
+Code: MIT. Bundled fonts (`fonts/`): SIL Open Font License (see `fonts/OFL.txt`).

package/css/base.css

@@ -0,0 +1,200 @@
+/* ============================================================================
+   MTUI (MoreThanUI) — base.css
+   Tier: Basic (zero JS). Reset, self-hosted fonts, typography classes
+   (DESIGN.md §2.7), and the accessibility floor every component inherits.
+   Requires tokens.css loaded first.
+   ============================================================================ */
+
+
+/* ============================== @font-face =================================
+   Self-hosted variable fonts (fonts/, OFL licensed). Noto Sans Arabic is
+   registered under the SAME family name "Noto Sans" with an Arabic
+   unicode-range, so the frozen --font token covers Arabic with no extra
+   rules: Latin glyphs resolve from the Latin files, Arabic falls through.  */
+@font-face {
+  font-family: "Noto Sans";
+  font-style: normal;
+  font-weight: 400 800;
+  font-display: swap;
+  src: url("../fonts/noto-sans-latin.woff2") format("woff2");
+  unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6,
+    U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122,
+    U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}
+@font-face {
+  font-family: "Noto Sans";
+  font-style: normal;
+  font-weight: 400 800;
+  font-display: swap;
+  src: url("../fonts/noto-sans-latin-ext.woff2") format("woff2");
+  unicode-range: U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7,
+    U+02DD-02FF, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB,
+    U+20AD-20C0, U+2113, U+2C60-2C7F, U+A720-A7FF;
+}
+@font-face {
+  font-family: "Noto Sans";
+  font-style: normal;
+  font-weight: 400 800;
+  font-display: swap;
+  src: url("../fonts/noto-sans-arabic.woff2") format("woff2");
+  unicode-range: U+0600-06FF, U+0750-077F, U+0870-088E, U+0890-0891,
+    U+0897-08E1, U+08E3-08FF, U+200C-200E, U+2010-2011, U+204F, U+2E41,
+    U+FB50-FDFF, U+FE70-FE74, U+FE76-FEFC;
+}
+@font-face {
+  font-family: "Noto Sans Mono";
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url("../fonts/noto-sans-mono-latin.woff2") format("woff2");
+  unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6,
+    U+02DA, U+02DC, U+0304, U+0308, U+0329, U+2000-206F, U+20AC, U+2122,
+    U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}
+
+
+/* ================================ Reset ==================================== */
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+* {
+  margin: 0;
+}
+
+html {
+  -webkit-text-size-adjust: 100%;
+}
+
+body {
+  min-height: 100dvh; /* shell presets (layout.css) own scroll; frame never does */
+  background: var(--bg);
+  color: var(--text);
+  font-family: var(--font);
+  font-size: var(--fs-body);
+  font-weight: var(--fw-body);
+  line-height: var(--lh-body);
+}
+
+img,
+svg,
+video,
+canvas {
+  display: block;
+  max-inline-size: 100%;
+}
+
+button,
+input,
+select,
+textarea {
+  font: inherit;
+  color: inherit;
+}
+
+/* Plain lists in components (menus, rows) carry their own semantics/styles. */
+ul[role="list"],
+ol[role="list"] {
+  list-style: none;
+  padding: 0;
+}
+
+
+/* ===================== Typography classes (§2.7) ===========================
+   One class per spec row. Hierarchy is weight and size — never uppercase,
+   never letter-spacing beyond the two negative headline trackings.
+   These classes ARE the type API; headings carry whichever class fits.     */
+.t-page {
+  font-size: var(--fs-page);
+  line-height: var(--lh-page);
+  font-weight: var(--fw-page);
+  letter-spacing: var(--ls-page);
+}
+
+.t-section {
+  font-size: var(--fs-section);
+  line-height: var(--lh-section);
+  font-weight: var(--fw-section);
+  letter-spacing: var(--ls-section);
+}
+
+.t-card {
+  font-size: var(--fs-card);
+  line-height: var(--lh-card);
+  font-weight: var(--fw-card);
+}
+
+.t-row {
+  font-size: var(--fs-control);
+  line-height: var(--lh-control);
+  font-weight: var(--fw-control);
+}
+
+.t-body {
+  font-size: var(--fs-body);
+  line-height: var(--lh-body);
+  font-weight: var(--fw-body);
+}
+
+.t-secondary {
+  font-size: var(--fs-secondary);
+  line-height: var(--lh-secondary);
+  font-weight: var(--fw-body);
+  color: var(--text-muted);
+}
+
+.t-label {
+  font-size: var(--fs-label);
+  font-weight: var(--fw-label);
+  color: var(--text-muted);
+}
+
+/* Type style only — the well-styled block is the phase-4 `.code` component.
+   Code, numerals, emails stay LTR inside RTL text (DESIGN.md §3 RTL).      */
+.t-code {
+  font-family: var(--font-mono);
+  font-size: var(--fs-code);
+  line-height: var(--lh-code);
+  direction: ltr;
+  unicode-bidi: isolate;
+  text-align: start;
+}
+
+/* Utility for non-code LTR islands in RTL rows: numbers, emails, URLs.     */
+.t-ltr {
+  direction: ltr;
+  unicode-bidi: isolate;
+}
+
+
+/* ========================= Accessibility floor ============================= */
+
+/* Focus: the token ring, on everything focusable, keyboard-only.           */
+:focus-visible {
+  outline: none;
+  box-shadow: var(--ring-focus);
+}
+
+/* Reduced motion: durations already collapse via the --t-* tokens
+   (tokens.css). --t-skeleton intentionally survives; the skeleton component
+   (components.css) swaps its translating sheen for a non-moving variant
+   under this same query. No component declares its own durations, so no
+   blanket animation kill-switch is needed here.                            */
+
+/* Forced colors: tonal separation disappears, so the floor draws real
+   structure with system colors. Components add their own border blocks
+   (CLAUDE.md checklist); this covers the globals.                          */
+@media (forced-colors: active) {
+  :focus-visible {
+    outline: 2px solid CanvasText;
+    outline-offset: 2px;
+    box-shadow: none;
+  }
+
+  .t-secondary,
+  .t-label {
+    color: CanvasText;
+  }
+}