ranui 0.2.0-alpha.2 → 0.2.0-alpha.4

package/dist/{utils-D4pPF77E.js → utils-DBfrRFoE.js}

@@ -1,5 +1,5 @@
 import "./ssr-DSGwPtEd.js";
-var O = class {
+var R = class {
   _events = /* @__PURE__ */ new Map();
   tap = (e, t) => {
     this._events.get(e) && e !== /* @__PURE__ */ Symbol.for("NEW_LISTENER") && this.call(/* @__PURE__ */ Symbol.for("NEW_LISTENER"), e);
@@ -16,8 +16,8 @@ var O = class {
   callSync = async (e, ...t) => {
     const r = this._events.get(e) || /* @__PURE__ */ new Set();
     for (const a of r) {
-      const { callback: o } = a;
-      await o(...t);
+      const { callback: s } = a;
+      await s(...t);
     }
     return this;
   };
@@ -34,8 +34,8 @@ var O = class {
       const { callback: a } = t;
       r = {
         name: e,
-        callback: (...o) => {
-          a(...o), this.off(e, r);
+        callback: (...s) => {
+          a(...s), this.off(e, r);
         },
         initialCallback: a
       };
@@ -46,49 +46,42 @@ var O = class {
     const r = [...this._events.get(e) || /* @__PURE__ */ new Set()].filter((a) => {
       if (typeof t == "function") return a.callback !== t && a.initialCallback !== t;
       {
-        const { callback: o } = t;
-        return a.callback !== o && a.initialCallback !== o;
+        const { callback: s } = t;
+        return a.callback !== s && a.initialCallback !== s;
       }
     });
     return this._events.set(e, new Set(r)), this;
   };
-};
-var C = (e = 8) => Math.random().toString(36).substring(2, e + 2);
-var H = (e = "") => {
+}, y = (e = 8) => Math.random().toString(36).substring(2, e + 2), L = (e = "") => {
   if (e.length === 0) return 0;
   if (e.endsWith("%")) {
     const t = Number(e.replace("%", ""));
     return t > 1 ? t / 100 : t;
   }
   return Number(e);
-}, $ = (e, t = 0, r = 1) => Math.min(r, Math.max(t, e));
-var E = (e) => typeof e == "function";
-function f(e) {
+}, O = (e, t = 0, r = 1) => Math.min(r, Math.max(t, e)), C = (e) => typeof e == "function";
+function h(e) {
   return e < 10 ? `0${e}` : e;
 }
-var W = (e) => {
+var B = (e) => {
   if (e === 0) return "00:00";
   if (!e) return "";
-  const t = Math.trunc(e / 3600), r = Math.trunc(e % 3600 / 60), a = f(Math.trunc(e - 3600 * t - 60 * r));
-  return t === 0 ? `${f(r)}:${a}` : `${f(t)}:${f(r)}:${a}`;
-};
-var K = () => {
+  const t = Math.trunc(e / 3600), r = Math.trunc(e % 3600 / 60), a = h(Math.trunc(e - 3600 * t - 60 * r));
+  return t === 0 ? `${h(r)}:${a}` : `${h(t)}:${h(r)}:${a}`;
+}, T = () => {
   if (typeof window < "u") {
     const e = navigator.userAgent.toLowerCase();
     return /ipad|ipod/.test(e) ? "ipad" : /android/.test(e) ? "android" : /iphone/.test(e) ? "iphone" : "pc";
   }
   return "pc";
-}, k = typeof window < "u";
-var G = () => {
-  if (!k) return !1;
+}, E = typeof window < "u", U = () => {
+  if (!E) return !1;
   const e = window.navigator.userAgent;
   return !!/Android|webOS|iPhone|iPod|iPad|BlackBerry/i.test(e);
-};
-var V = (e) => {
+}, $ = (e) => {
   const t = e.backingStorePixelRatio || e.webkitBackingStorePixelRatio || e.mozBackingStorePixelRatio || e.msBackingStorePixelRatio || e.oBackingStorePixelRatio || 1;
-  return (k && window.devicePixelRatio || 1) / t;
-};
-var A = 12e4, L = "__ranuts_bridge__", U = "default", S = new class {
+  return (E && window.devicePixelRatio || 1) / t;
+}, M = 12e4, A = "__ranuts_bridge__", q = "default", m = new class {
   bridges = /* @__PURE__ */ new Set();
   attachedWindow = null;
   handleMessage = (e) => {
@@ -100,7 +93,7 @@ var A = 12e4, L = "__ranuts_bridge__", U = "default", S = new class {
   remove(e) {
     this.bridges.delete(e), this.bridges.size === 0 && this.attachedWindow && (this.attachedWindow.removeEventListener("message", this.handleMessage), this.attachedWindow = null);
   }
-}(), B = class {
+}(), P = class {
   targetWindow;
   targetOrigin;
   messageHandlers;
@@ -108,13 +101,13 @@ var A = 12e4, L = "__ranuts_bridge__", U = "default", S = new class {
   channel;
   senderId;
   available;
-  constructor(e, t = "*", r = U) {
-    this.targetOrigin = t, this.channel = r, this.senderId = C(12), this.messageHandlers = /* @__PURE__ */ new Map(), this.pendingRequests = /* @__PURE__ */ new Map(), this.available = typeof window < "u", this.available ? (this.targetWindow = e ?? window, S.add(this)) : this.targetWindow = void 0;
+  constructor(e, t = "*", r = q) {
+    this.targetOrigin = t, this.channel = r, this.senderId = y(12), this.messageHandlers = /* @__PURE__ */ new Map(), this.pendingRequests = /* @__PURE__ */ new Map(), this.available = typeof window < "u", this.available ? (this.targetWindow = e ?? window, m.add(this)) : this.targetWindow = void 0;
   }
   post(e, t) {
     const r = {
       ...t,
-      __bridge: L,
+      __bridge: A,
       channel: this.channel,
       senderId: this.senderId
     };
@@ -124,28 +117,28 @@ var A = 12e4, L = "__ranuts_bridge__", U = "default", S = new class {
     if (!this.available || this.targetOrigin !== "*" && e.origin !== this.targetOrigin || e.source && e.source !== this.targetWindow) return;
     const t = e.data;
     if (!t || typeof t != "object" || t.__bridge !== "__ranuts_bridge__" || (t.channel ?? "default") !== this.channel) return;
-    const { type: r, payload: a, id: o, isResponse: s, isError: u, senderId: c } = t;
-    if (s && o) {
-      const p = this.pendingRequests.get(o);
-      p && (u ? p.reject(new Error(typeof a == "string" ? a : "Bridge request failed")) : p.resolve(a), this.pendingRequests.delete(o));
+    const { type: r, payload: a, id: s, isResponse: o, isError: w, senderId: d } = t;
+    if (o && s) {
+      const c = this.pendingRequests.get(s);
+      c && (w ? c.reject(new Error(typeof a == "string" ? a : "Bridge request failed")) : c.resolve(a), this.pendingRequests.delete(s));
       return;
     }
-    if (c && c === this.senderId || typeof r != "string" || !this.messageHandlers.has(r)) return;
-    const b = this.messageHandlers.get(r);
-    if (E(b)) {
-      const p = e.source ?? this.targetWindow;
-      Promise.resolve(b(a)).then((l) => {
-        o && this.post(p, {
+    if (d && d === this.senderId || typeof r != "string" || !this.messageHandlers.has(r)) return;
+    const v = this.messageHandlers.get(r);
+    if (C(v)) {
+      const c = e.source ?? this.targetWindow;
+      Promise.resolve(v(a)).then((l) => {
+        s && this.post(c, {
           type: r,
           payload: l,
-          id: o,
+          id: s,
           isResponse: !0
         });
       }).catch((l) => {
-        o && this.post(p, {
+        s && this.post(c, {
           type: r,
           payload: l instanceof Error ? l.message : String(l),
-          id: o,
+          id: s,
           isResponse: !0,
           isError: !0
         });
@@ -160,18 +153,18 @@ var A = 12e4, L = "__ranuts_bridge__", U = "default", S = new class {
   };
   send = async (e, t) => {
     if (!this.available) return Promise.reject(/* @__PURE__ */ new Error("PostMessageBridge is unavailable outside a browser environment"));
-    const r = C(10);
-    return new Promise((a, o) => {
-      const s = setTimeout(() => {
-        this.pendingRequests.has(r) && (this.pendingRequests.delete(r), o(/* @__PURE__ */ new Error("Request timeout")));
-      }, A), u = (c) => {
-        clearTimeout(s), o(c);
+    const r = y(10);
+    return new Promise((a, s) => {
+      const o = setTimeout(() => {
+        this.pendingRequests.has(r) && (this.pendingRequests.delete(r), s(/* @__PURE__ */ new Error("Request timeout")));
+      }, M), w = (d) => {
+        clearTimeout(o), s(d);
       };
       this.pendingRequests.set(r, {
-        resolve: (c) => {
-          clearTimeout(s), a(c);
+        resolve: (d) => {
+          clearTimeout(o), a(d);
         },
-        reject: u
+        reject: w
       });
       try {
         this.post(this.targetWindow, {
@@ -179,8 +172,8 @@ var A = 12e4, L = "__ranuts_bridge__", U = "default", S = new class {
           payload: t,
           id: r
         });
-      } catch (c) {
-        this.pendingRequests.delete(r), u(c instanceof Error ? c : /* @__PURE__ */ new Error("Failed to post message"));
+      } catch (d) {
+        this.pendingRequests.delete(r), w(d instanceof Error ? d : /* @__PURE__ */ new Error("Failed to post message"));
       }
     });
   };
@@ -194,23 +187,23 @@ var A = 12e4, L = "__ranuts_bridge__", U = "default", S = new class {
     }
   };
   destroy = () => {
-    S.remove(this), this.messageHandlers.clear(), this.pendingRequests.forEach((e) => {
+    m.remove(this), this.messageHandlers.clear(), this.pendingRequests.forEach((e) => {
       e.reject(/* @__PURE__ */ new Error("Bridge destroyed"));
     }), this.pendingRequests.clear();
   };
-}, I = class d {
+}, _ = class u {
   static instance;
   bridges = /* @__PURE__ */ new Map();
   constructor() {
   }
   static getInstance() {
-    return d.instance || (d.instance = new d()), d.instance;
+    return u.instance || (u.instance = new u()), u.instance;
   }
-  connectClient = ({ id: t, targetOrigin: r, targetWindow: a, channel: o }) => {
-    const s = new B(a, r, o);
-    if (t || (t = C(10)), this.bridges.has(t)) throw new Error(`Bridge ${t} already exists`);
-    return this.bridges.set(t, s), {
-      bridge: s,
+  connectClient = ({ id: t, targetOrigin: r, targetWindow: a, channel: s }) => {
+    const o = new P(a, r, s);
+    if (t || (t = y(10)), this.bridges.has(t)) throw new Error(`Bridge ${t} already exists`);
+    return this.bridges.set(t, o), {
+      bridge: o,
       id: t
     };
   };
@@ -230,12 +223,10 @@ var A = 12e4, L = "__ranuts_bridge__", U = "default", S = new class {
     });
   };
   sendTo = (t, r, a) => {
-    const o = this.getClient(t);
-    return o ? o.send(r, a) : Promise.reject(/* @__PURE__ */ new Error(`Bridge ${t} not found`));
+    const s = this.getClient(t);
+    return s ? s.send(r, a) : Promise.reject(/* @__PURE__ */ new Error(`Bridge ${t} not found`));
   };
-}, Y = I.getInstance();
-var J = new O();
-var i = [
+}, F = _.getInstance(), H = new R(), i = [
   1116352408,
   1899447441,
   3049323471,
@@ -300,15 +291,13 @@ var i = [
   2756734187,
   3204031479,
   3329325298
-];
-var n = class {
+], n = class {
   highOrder;
   lowOrder;
   constructor(e, t) {
     this.highOrder = e, this.lowOrder = t;
   }
-};
-var X = [
+}, x = [
   new n(i[0], 3609767458),
   new n(i[1], 602891725),
   new n(i[2], 3964484399),
@@ -389,8 +378,7 @@ var X = [
   new n(1501505948, 4234509866),
   new n(1607167915, 987167468),
   new n(1816402316, 1246189591)
-];
-var Z = [
+], D = [
   new n(0, 1),
   new n(0, 32898),
   new n(2147483648, 32906),
@@ -415,35 +403,32 @@ var Z = [
   new n(2147483648, 32896),
   new n(0, 2147483649),
   new n(2147483648, 2147516424)
-];
-var Q = (e, t = 500) => {
+], j = (e, t = 500) => {
   let r;
   return (...a) => {
     clearTimeout(r), r = setTimeout(() => {
       e.apply(void 0, a);
     }, t);
   };
-}, e0 = (e, t) => {
+}, G = (e, t) => {
   if (typeof document > "u") return;
   const r = e.classList;
   r.contains(t) || r.add(t);
-}, t0 = (e, t) => {
+}, z = (e, t) => {
   if (typeof document > "u") return;
   const r = e.classList;
   r.contains(t) && r.remove(t);
-};
-var r0 = () => {
+}, V = () => {
   let e = 0, t = null;
   return function(r, a = 300) {
-    return function(...o) {
-      const s = Date.now();
-      s - e >= a ? (t != null && (clearTimeout(t), t = null), e = s, r.apply(this, o)) : t ??= window.setTimeout(() => {
-        e = Date.now(), r.apply(this, o), t = null;
-      }, a - (s - e));
+    return function(...s) {
+      const o = Date.now();
+      o - e >= a ? (t != null && (clearTimeout(t), t = null), e = o, r.apply(this, s)) : t ??= window.setTimeout(() => {
+        e = Date.now(), r.apply(this, s), t = null;
+      }, a - (o - e));
     };
   };
-};
-var w = /* @__PURE__ */ new Map([
+}, g = /* @__PURE__ */ new Map([
   [100, "Continue"],
   [101, "Switching Protocols"],
   [102, "Processing"],
@@ -507,18 +492,18 @@ var w = /* @__PURE__ */ new Map([
   [509, "Bandwidth Limit Exceeded"],
   [510, "Not Extended"],
   [511, "Network Authentication Required"]
-]), n0 = {
-  message: w,
+]), K = {
+  message: g,
   code: (function(e) {
     const t = /* @__PURE__ */ new Map();
     for (const [r, a] of e) t.set(a.toLowerCase(), r);
     return t;
-  })(w),
+  })(g),
   codes: (function(e) {
     const t = [];
     for (const [r, a] of e) t.push(r);
     return t;
-  })(w),
+  })(g),
   redirect: {
     300: !0,
     301: !0,
@@ -538,22 +523,22 @@ var w = /* @__PURE__ */ new Map([
     503: !0,
     504: !0
   }
-}, R = [
+}, k = [
   !1,
   "false",
   null,
   void 0
-], i0 = (e) => {
+], X = (e) => {
   const t = e.hasAttribute("disabled"), r = e.getAttribute("disabled");
-  return !!(t && !R.includes(r));
-}, y = /* @__PURE__ */ new Map(), x = /* @__PURE__ */ new Map(), F = (e, t) => {
+  return !!(t && !k.includes(r));
+}, f = /* @__PURE__ */ new Map(), p = /* @__PURE__ */ new Map(), N = (e, t) => {
   if (!(typeof document > "u") && t) {
     if (typeof CSSStyleSheet < "u") try {
-      if (!y.has(t)) {
+      if (!f.has(t)) {
         const a = new CSSStyleSheet();
-        a.replaceSync(t), y.set(t, a);
+        a.replaceSync(t), f.set(t, a);
       }
-      const r = y.get(t);
+      const r = f.get(t);
       e.adoptedStyleSheets.includes(r) || (e.adoptedStyleSheets = [...e.adoptedStyleSheets, r]);
       return;
     } catch {
@@ -563,14 +548,14 @@ var w = /* @__PURE__ */ new Map([
       r.setAttribute("data-ranui", ""), r.textContent = t, e.appendChild(r);
     }
   }
-}, D = (e, t) => {
+}, W = (e, t) => {
   if (!(typeof document > "u") && t) {
     if (typeof CSSStyleSheet < "u") try {
-      if (!x.has(t)) {
+      if (!p.has(t)) {
         const a = new CSSStyleSheet();
-        a.replaceSync(t), x.set(t, a);
+        a.replaceSync(t), p.set(t, a);
       }
-      const r = x.get(t);
+      const r = p.get(t);
       e.adoptedStyleSheets.includes(r) || (e.adoptedStyleSheets = [...e.adoptedStyleSheets, r]);
       return;
     } catch {
@@ -580,110 +565,43 @@ var w = /* @__PURE__ */ new Map([
       r.setAttribute("data-ranui-sheet", ""), r.textContent = t, e.appendChild(r);
     }
   }
-}, _ = /* @__PURE__ */ new WeakMap(), M = "@media (prefers-reduced-motion: reduce){*,*::before,*::after{animation-duration:.01ms !important;animation-iteration-count:1 !important;transition-duration:.01ms !important;scroll-behavior:auto !important}}", a0 = (e, t = "", r = { mode: "closed" }) => {
-  const a = e.shadowRoot || _.get(e) || e.attachShadow(r);
-  return _.set(e, a), F(a, t ? `${t}
-${M}` : M), a;
-}, o0 = (e, t, r) => {
+}, b = /* @__PURE__ */ new WeakMap(), S = "@media (prefers-reduced-motion: reduce){*,*::before,*::after{animation-duration:.01ms !important;animation-iteration-count:1 !important;transition-duration:.01ms !important;scroll-behavior:auto !important}}", Y = (e, t = "", r = { mode: "closed" }) => {
+  const a = e.shadowRoot || b.get(e) || e.attachShadow(r);
+  return b.set(e, a), N(a, t ? `${t}
+${S}` : S), a;
+}, J = (e, t, r) => {
   const a = e.querySelector(t);
   if (a) return a;
-  const o = r();
-  return e.appendChild(o), o;
-}, s0 = (e, t, r = "") => e.getAttribute(t) ?? r, c0 = (e, t, r, a = {}) => {
+  const s = r();
+  return e.appendChild(s), s;
+}, Q = (e, t, r = "") => e.getAttribute(t) ?? r, Z = (e, t, r, a = {}) => {
   if (a.removeEmpty && !r) {
     e.removeAttribute(t);
     return;
   }
   e.setAttribute(t, r ?? "");
-}, p0 = (e, t, r, a, o) => {
-  if (r !== "sheet" || a === o) return;
-  const s = e.getAttribute("sheet") || "";
-  s && D(t, s);
-}, g = "ran-theme", h = null, m = null, v = (e) => {
-  if (e && "style" in e) return e;
-  if (e && "documentElement" in e) return e.documentElement;
-  if (!(typeof document > "u"))
-    return document.documentElement;
-}, T = (e) => {
-  const t = typeof window < "u" && window.matchMedia("(prefers-color-scheme: dark)").matches;
-  e.setAttribute("data-ran-theme", t ? "dark" : "light"), e.setAttribute("theme", t ? "dark" : "light");
-}, P = () => {
-  h && m && (h.removeEventListener("change", m), h = null, m = null);
-}, N = (e, t) => {
-  const r = v(t);
-  if (r) {
-    if (P(), e === "system") {
-      if (typeof window > "u") return;
-      T(r), h = window.matchMedia("(prefers-color-scheme: dark)"), m = () => T(r), h.addEventListener("change", m);
-      try {
-        localStorage.setItem(g, "system");
-      } catch {
-      }
-      return;
-    }
-    r.setAttribute("data-ran-theme", e), r.setAttribute("theme", e);
-    try {
-      localStorage.setItem(g, e);
-    } catch {
-    }
-  }
-}, l0 = (e) => {
-  const t = v(e);
-  if (!t) return "";
-  const r = t.getAttribute("data-ran-theme") || t.getAttribute("theme") || "";
-  if (r === "light" || r === "dark") {
-    try {
-      if (localStorage.getItem(g) === "system") return "system";
-    } catch {
-    }
-    return r;
-  }
-  return "";
-}, z = (e, t, r) => {
-  const a = v(r);
-  a && a.style.setProperty(e, String(t));
-}, q = (e, t) => {
-  const r = v(t);
-  r && r.style.removeProperty(e);
-}, d0 = (e, t) => {
-  Object.entries(e).forEach(([r, a]) => {
-    if (a == null) {
-      q(r, t);
-      return;
-    }
-    z(r, a, t);
-  });
-}, h0 = (e) => {
-  if (!(typeof localStorage > "u"))
-    try {
-      const t = localStorage.getItem(g);
-      (t === "light" || t === "dark" || t === "system") && N(t, e);
-    } catch {
-    }
+}, ee = (e, t, r, a, s) => {
+  if (r !== "sheet" || a === s) return;
+  const o = e.getAttribute("sheet") || "";
+  o && W(t, o);
 };
 export {
-  K as C,
-  r0 as S,
-  V as _,
-  z as a,
-  W as b,
-  a0 as c,
-  p0 as d,
-  R as f,
-  G as g,
-  Q as h,
-  N as i,
-  s0 as l,
-  e0 as m,
-  l0 as n,
-  d0 as o,
-  i0 as p,
-  h0 as r,
-  o0 as s,
-  q as t,
-  c0 as u,
-  t0 as v,
-  O as w,
-  $ as x,
-  H as y
+  T as _,
+  ee as a,
+  G as c,
+  $ as d,
+  z as f,
+  V as g,
+  O as h,
+  Z as i,
+  j as l,
+  B as m,
+  Y as n,
+  k as o,
+  L as p,
+  Q as r,
+  X as s,
+  J as t,
+  U as u,
+  R as v
 };

package/docs/COMPONENTS.md

@@ -6,9 +6,9 @@ shape), slots, and `::part()` names — extracted from source. For CSS variables
 (theming tokens) see [style-tokens-public.md](./style-tokens-public.md); for
 design rules see [DESIGN.md](./DESIGN.md).
 
-Generated at: 2026-07-05T13:14:26.449Z
+Generated at: 2026-07-11T05:42:36.629Z
 
-29 custom elements.
+30 custom elements.
 
 ## `<r-button>`
 
@@ -21,7 +21,7 @@ Source: `components/button/index.ts`
   - `icon: string`
   - `iconSize: string`
   - `sheet: string`
-  - `type: string` — Visual variant: `''` (default) | `'primary'` | `'warning'` | `'text'`. Drives the `:host([type=...])` styles.
+  - `type: string` — Visual variant: `''` (default) | `'primary'` | `'contrast'` | `'warning'` | `'text'`. Drives the `:host([type=...])` styles.
 - **Events**: —
 - **Slots**: `default`
 - **Parts**: `button`, `content`
@@ -30,8 +30,12 @@ Source: `components/button/index.ts`
 
 Source: `components/card/index.ts`
 
-- **Attributes**: `description: string`, `sheet: string`, `title: string`
-- **Properties**: `description: string`, `sheet: string`, `title: string`
+- **Attributes**: `description: string`, `hoverable: boolean`, `sheet: string`, `title: string`
+- **Properties**:
+  - `description: string`
+  - `hoverable: boolean` — Interactive card (Geist): hover darkens the border and lifts to the elevated shadow tier. Purely presentational — gate it to cards that are actually clickable.
+  - `sheet: string`
+  - `title: string`
 - **Events**: —
 - **Slots**: `default`, `extra (named)`, `footer (named)`
 - **Parts**: `body`, `card`, `description`, `extra`, `footer`, `header`, `title`
@@ -322,3 +326,15 @@ Source: `components/tab/index.ts`
 - **Events**: `change` → detail `{ active }`
 - **Slots**: `default`
 - **Parts**: `content`, `content-wrap`, `header`, `indicator`, `nav`, `tabs`
+
+## `<r-theme-switch>`
+
+Source: `components/theme-switch/index.ts`
+
+- **Attributes**: `label-dark`, `label-light`, `label-system`, `sheet: string`
+- **Properties**:
+  - `sheet: string`
+  - `value: RanThemeName` — `<r-theme-switch>` — a three-state (system / light / dark) segmented control
+- **Events**: `change` → detail `{ theme }`
+- **Slots**: —
+- **Parts**: —

package/docs/DESIGN.md

@@ -38,25 +38,27 @@ Scales: `--ran-gray-100..1000`, `--ran-gray-alpha-100..1000` (translucent, layer
 
 **Use the semantic layer, not the scale, in components:**
 
-| Token                                        | Maps to                         | Use for             |
-| -------------------------------------------- | ------------------------------- | ------------------- |
-| `--ran-color-bg`                             | background-100                  | Page background     |
-| `--ran-color-bg-subtle`                      | background-200                  | Subtle page zones   |
-| `--ran-color-bg-elevated`                    | bg-100 / gray-100 (dark)        | Cards, surfaces     |
-| `--ran-color-bg-muted`                       | gray-100                        | Inset / muted fills |
-| `--ran-color-bg-hover`                       | gray-200                        | Hover background    |
-| `--ran-color-bg-active`                      | gray-300                        | Active background   |
-| `--ran-color-text`                           | gray-1000                       | Primary text        |
-| `--ran-color-text-secondary`                 | gray-900                        | Secondary text      |
-| `--ran-color-text-disabled`                  | gray-700                        | Disabled text       |
-| `--ran-color-border`                         | gray-400                        | Default border      |
-| `--ran-color-border-hover`                   | gray-500                        | Hover border        |
-| `--ran-color-border-active`                  | gray-600                        | Active border       |
-| `--ran-color-primary` / `-hover` / `-active` | blue-700 / 800 / 900            | Primary action      |
-| `--ran-color-success` / `warning` / `danger` | green-700 / amber-700 / red-700 | Status              |
-| `--ran-color-link`                           | blue-700                        | Links               |
-
-**Accent meaning:** blue = primary & links · green = success · amber = warning · red = danger/error.
+| Token                                            | Maps to                         | Use for                      |
+| ------------------------------------------------ | ------------------------------- | ---------------------------- |
+| `--ran-color-bg`                                 | background-100                  | Page background              |
+| `--ran-color-bg-subtle`                          | background-200                  | Subtle page zones            |
+| `--ran-color-bg-elevated`                        | bg-100 / gray-100 (dark)        | Cards, surfaces              |
+| `--ran-color-bg-muted`                           | gray-100                        | Inset / muted fills          |
+| `--ran-color-bg-hover`                           | gray-200                        | Hover background             |
+| `--ran-color-bg-active`                          | gray-300                        | Active background            |
+| `--ran-color-text`                               | gray-1000                       | Primary text                 |
+| `--ran-color-text-secondary`                     | gray-900                        | Secondary text               |
+| `--ran-color-text-disabled`                      | gray-700                        | Disabled text                |
+| `--ran-color-border`                             | gray-400                        | Default border               |
+| `--ran-color-border-hover`                       | gray-500                        | Hover border                 |
+| `--ran-color-border-active`                      | gray-600                        | Active border                |
+| `--ran-color-primary` / `-hover` / `-active`     | blue-700 / 800 / 900            | Primary action               |
+| `--ran-color-success` / `warning` / `danger`     | green-700 / amber-700 / red-700 | Status                       |
+| `--ran-color-link`                               | blue-700                        | Links                        |
+| `--ran-color-contrast-bg` / `-hover` / `-active` | gray-1000 / literal steps       | Contrast (monochrome) action |
+| `--ran-color-contrast-text`                      | background-100                  | Text on contrast             |
+
+**Accent meaning:** blue = primary & links · green = success · amber = warning · red = danger/error. The **contrast** pair is the monochrome "highest-contrast" action (Geist contrast button): black-on-white in light, white-on-black in dark — use it when the primary action should carry no hue.
 
 **Light & dark:** same token name, different value. `gray-1000` is `#171717` in light and `#ededed` in dark. Components reference the _semantic name_; dark mode only redefines the base scale (one mixin), and everything re-resolves.
 
@@ -183,6 +185,9 @@ transition:
 - Theme through **CSS variables**, **`::part()`**, or the **`sheet`** attribute (escape hatch). CSS variables cross Shadow DOM; selectors do not.
 - Component tokens default to semantic tokens: `var(--ran-btn-content-background-color, var(--ran-color-primary, #006bff))`.
 - Map states to the color ladder: default → `bg`/`text`; hover → `bg-hover` / `border-hover` / `primary-hover`; active → `bg-active` / `primary-active`; disabled → `text-disabled` + reduced opacity; focus → focus ring.
+- **Interactive cards opt in**: `r-card` only reacts to hover with the `hoverable` attribute (border 400 → 500 + elevated shadow). Non-interactive cards must stay inert — never add hover feedback to something that isn't clickable.
+- **Theme switching UI is a component**: use `<r-theme-switch>` (system / light / dark segmented pill, wired to `setTheme`/localStorage, syncs across instances and updates `theme-color` metas) instead of hand-rolling toggles. Localize with `label` / `label-system` / `label-light` / `label-dark`.
+- **Typography ships with the system**: `import 'ranui/fonts'` (or link `dist/fonts/fonts.css`) self-hosts Geist Sans + Geist Mono (variable, OFL-licensed) — the canonical faces behind `--ran-font-family` / `--ran-font-mono`. Without it the stacks fall back to system fonts.
 - See [THEME_STYLE_SYSTEM_DESIGN.md](./THEME_STYLE_SYSTEM_DESIGN.md) for the token architecture and [style-tokens-public.md](./style-tokens-public.md) for the generated per-component token list.
 
 ---