@xmesh/system-design 0.0.1

package/dist/lit/components/avatar-group/index.css

@@ -0,0 +1,60 @@
+/* ============================================
+   Avatar group — overlapped stack with +N overflow.
+
+   <xm-avatar-group> lays slotted <xm-avatar> children in an
+   overlapped row (consistent negative offset) and, past `max`,
+   renders a neutral "+N" overflow token in the same circular
+   avatar shape. The overflow ink is the plain on-surface neutral
+   — never coral, never a status hue (AD-11). Each avatar keeps a
+   thin ring so the stack reads as discrete chips, not a blob.
+   ============================================ */
+
+.avatar-group {
+  --avatar-group-overlap: 8px;
+  --avatar-group-size: 32px;
+  --avatar-group-font: var(--md-sys-typescale-label-large-size);
+
+  display: inline-flex;
+  align-items: center;
+}
+
+/* The ring + overlap on each stacked avatar. ::slotted reaches the
+   light-DOM <xm-avatar> children; the ring uses the host surface so
+   the chips separate cleanly on whatever desk tier they sit on. */
+.avatar-group ::slotted(xm-avatar) {
+  margin-left: calc(var(--avatar-group-overlap) * -1);
+  border-radius: var(--md-sys-shape-corner-full);
+  box-shadow: 0 0 0 2px var(--md-sys-color-surface);
+}
+.avatar-group ::slotted(xm-avatar:first-child) {
+  margin-left: 0;
+}
+
+/* +N overflow token — same circle, neutral surface ink. */
+.avatar-group__overflow {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  box-sizing: border-box;
+  width: var(--avatar-group-size);
+  height: var(--avatar-group-size);
+  margin-left: calc(var(--avatar-group-overlap) * -1);
+  flex-shrink: 0;
+  border-radius: var(--md-sys-shape-corner-full);
+  border: 1px solid var(--md-sys-color-outline-variant);
+  box-shadow: 0 0 0 2px var(--md-sys-color-surface);
+  background: var(--md-sys-color-surface-container-highest);
+  color: var(--md-sys-color-on-surface-variant);
+  font-family: var(--md-sys-typescale-label-large-font);
+  font-size: var(--avatar-group-font);
+  font-weight: 600;
+  line-height: 1;
+  letter-spacing: 0;
+  white-space: nowrap;
+}
+
+/* ---------- Sizes — match xm-avatar diameters + scale overlap ---------- */
+.avatar-group--xs { --avatar-group-size: 22px; --avatar-group-font: var(--md-sys-typescale-label-small-size);  --avatar-group-overlap: 6px; }
+.avatar-group--sm { --avatar-group-size: 28px; --avatar-group-font: var(--md-sys-typescale-label-medium-size); --avatar-group-overlap: 7px; }
+.avatar-group--md { --avatar-group-size: 32px; --avatar-group-font: var(--md-sys-typescale-label-large-size);  --avatar-group-overlap: 8px; }
+.avatar-group--lg { --avatar-group-size: 40px; --avatar-group-font: var(--md-sys-typescale-title-small-size);  --avatar-group-overlap: 10px; }

package/dist/lit/components/avatar-group/index.d.ts

@@ -0,0 +1,19 @@
+import { LitElement } from "lit";
+import type { TemplateResult } from "lit";
+type AvatarSize = "xs" | "sm" | "md" | "lg";
+declare class XmAvatarGroup extends LitElement {
+    max: number;
+    size: AvatarSize;
+    private _overflow;
+    updated(): void;
+    private _avatars;
+    private _applyChildren;
+    private _onSlot;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "xm-avatar-group": XmAvatarGroup;
+    }
+}
+export {};

package/dist/lit/components/avatar-group/index.js

@@ -0,0 +1,97 @@
+/*
+  avatar-group/index.ts — <xm-avatar-group>.
+
+  Overlaps slotted <xm-avatar> children into a stack and, when the
+  count exceeds `max`, renders a neutral "+N" overflow token in the
+  same circular shape. Reads slotted children only — never their
+  shadow roots (AD-12).
+
+  Authoring:
+    <xm-avatar-group max="3" size="md">
+      <xm-avatar name="Ada Lovelace"></xm-avatar>
+      <xm-avatar name="Grace Hopper"></xm-avatar>
+      <xm-avatar name="Alan Turing"></xm-avatar>
+      <xm-avatar name="Edsger Dijkstra"></xm-avatar>
+      <xm-avatar name="Barbara Liskov"></xm-avatar>
+    </xm-avatar-group>
+
+  Properties:
+    max    number       — visible avatars before collapsing to "+N" (default 4)
+    size   xs|sm|md|lg  — propagated to children + overflow (default md)
+
+  The "+N" overflow uses neutral surface ink, never coral / status hue
+  (AD-11). Shadow DOM; Lit is a bare `import` (peer dep).
+*/
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { LitElement, html, nothing } from "lit";
+import { customElement, property, state } from "lit/decorators.js";
+const GROUP_CSS = new URL("../avatar-group/index.css", import.meta.url).href;
+let XmAvatarGroup = class XmAvatarGroup extends LitElement {
+    constructor() {
+        super(...arguments);
+        this.max = 4;
+        this.size = "md";
+        this._overflow = 0;
+        this._onSlot = () => {
+            this._applyChildren();
+        };
+    }
+    updated() {
+        this._applyChildren();
+    }
+    _avatars() {
+        return [...this.children].filter((c) => c.tagName.toLowerCase() === "xm-avatar");
+    }
+    _applyChildren() {
+        const avatars = this._avatars();
+        const overflow = Math.max(0, avatars.length - this.max);
+        avatars.forEach((el, i) => {
+            el.setAttribute("size", this.size);
+            el.hidden = i >= this.max;
+        });
+        if (this._overflow !== overflow)
+            this._overflow = overflow;
+    }
+    render() {
+        const cls = `avatar-group avatar-group--${this.size}`;
+        return html `
+      <link rel="stylesheet" href="${GROUP_CSS}" />
+      <style>
+        :host {
+          display: inline-flex;
+        }
+        :host([hidden]) {
+          display: none;
+        }
+      </style>
+      <div class="${cls}">
+        <slot @slotchange=${this._onSlot}></slot>
+        ${this._overflow > 0
+            ? html `<span
+              class="avatar-group__overflow"
+              role="img"
+              aria-label="${this._overflow} more"
+              >+${this._overflow}</span
+            >`
+            : nothing}
+      </div>
+    `;
+    }
+};
+__decorate([
+    property({ type: Number })
+], XmAvatarGroup.prototype, "max", void 0);
+__decorate([
+    property({ type: String })
+], XmAvatarGroup.prototype, "size", void 0);
+__decorate([
+    state()
+], XmAvatarGroup.prototype, "_overflow", void 0);
+XmAvatarGroup = __decorate([
+    customElement("xm-avatar-group")
+], XmAvatarGroup);

package/dist/lit/components/badge/index.css

@@ -0,0 +1,72 @@
+/* ============================================
+   Badge — small count / dot anchored to a child.
+
+   <xm-badge> floats a coral count or a minimal dot at the
+   top-right corner of whatever it wraps (an icon button, an
+   avatar, a label). The coral fill (--md-sys-color-primary /
+   --md-sys-color-on-primary) means "count / attention" — the
+   same functional coral as a selected pill or the active-tab
+   indicator. It is NEVER a severity palette and never references
+   --md-sys-color-error*. Severity is communicated by icon + copy
+   elsewhere, never by this badge's hue.
+
+   The badge paints its own coral surface, so it pairs primary
+   with on-primary independent of the host's surface family
+   (AD-13) — it stays legible floating over any surface.
+   ============================================ */
+
+.badge {
+  position: relative;
+  display: inline-flex;
+}
+
+/* The wrapper the badged child projects into. Establishes the
+   positioning context for the absolutely-placed count/dot. */
+.badge__anchor {
+  display: inline-flex;
+}
+
+/* Shared corner-floated chip — both count and dot inherit this. */
+.badge__count {
+  position: absolute;
+  top: 0;
+  right: 0;
+  transform: translate(35%, -35%);
+  z-index: 1;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  box-sizing: border-box;
+  min-width: 18px;
+  height: 18px;
+  padding: 0 var(--s-1);
+  border-radius: var(--md-sys-shape-corner-full);
+  /* Hairline halo so the chip separates from a same-hued host
+     (e.g. a coral primary button) without a hard border. */
+  border: 1px solid var(--md-sys-color-surface);
+  background: var(--xm-color-primary-fill);
+  color: var(--md-sys-color-on-primary);
+  font-family: var(--md-sys-typescale-label-small-font);
+  font-size: var(--md-sys-typescale-label-small-size);
+  font-weight: var(--md-sys-typescale-label-small-weight);
+  line-height: 1;
+  letter-spacing: var(--md-sys-typescale-label-small-tracking);
+  white-space: nowrap;
+}
+
+/* Dot — no count, just a presence marker. Collapses to a small
+   circle in the same corner. */
+.badge--dot .badge__count {
+  min-width: 0;
+  width: 10px;
+  height: 10px;
+  padding: 0;
+}
+
+/* Standalone badge (no anchored child) — drops the absolute
+   positioning so the chip flows inline beside text. */
+.badge--standalone .badge__count {
+  position: static;
+  transform: none;
+  border: none;
+}

package/dist/lit/components/badge/index.d.ts

@@ -0,0 +1,18 @@
+import { LitElement } from "lit";
+import type { TemplateResult } from "lit";
+declare class XmBadge extends LitElement {
+    count: number | null;
+    dot: boolean;
+    max: number;
+    label: string;
+    private get _hasCount();
+    private get _display();
+    private get _ariaLabel();
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "xm-badge": XmBadge;
+    }
+}
+export {};

package/dist/lit/components/badge/index.js

@@ -0,0 +1,115 @@
+/*
+  badge/index.ts — <xm-badge>.
+
+  A small count or dot anchored to a slotted child. The default slot
+  holds the element being badged (an icon button, an avatar, a chip);
+  the badge floats a coral count/dot at the top-right corner.
+
+  Authoring:
+    <xm-badge count="3">
+      <xm-button icon-only variant="ghost"><svg slot="icon-left">…</svg></xm-button>
+    </xm-badge>
+
+    <xm-badge dot label="Unread messages">
+      <span>Inbox</span>
+    </xm-badge>
+
+  Properties:
+    count   number  — numeric badge; capped at `max` then shown as "max+"
+    dot     boolean — minimal presence dot (used when there's no count)
+    max     number  — overflow cap for the count (default 99 → "99+")
+    label   string  — accessible label for the badge (defaults to the
+                      count, e.g. "3"); required when only a dot shows so
+                      the meaning isn't carried by color alone (NFR-15)
+
+  Coral, never severity (AD-11): the count/dot uses --md-sys-color-primary;
+  it must NOT signal error severity by hue and must NOT reference
+  --md-sys-color-error*.
+
+  Shadow DOM (for <slot> projection); Lit is a bare `import` (peer dep); CSS via <link>
+  resolved relative to the built module (mirrors button/index.ts).
+*/
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { LitElement, html, nothing } from "lit";
+import { customElement, property } from "lit/decorators.js";
+const BADGE_CSS = new URL("../badge/index.css", import.meta.url).href;
+let XmBadge = class XmBadge extends LitElement {
+    constructor() {
+        super(...arguments);
+        this.count = null;
+        this.dot = false;
+        this.max = 99;
+        this.label = "";
+    }
+    get _hasCount() {
+        return typeof this.count === "number" && this.count > 0;
+    }
+    get _display() {
+        if (!this._hasCount)
+            return "";
+        const n = this.count;
+        return n > this.max ? `${this.max}+` : String(n);
+    }
+    get _ariaLabel() {
+        if (this.label)
+            return this.label;
+        if (this._hasCount)
+            return String(this.count);
+        return "";
+    }
+    render() {
+        const isDot = this.dot && !this._hasCount;
+        const isStandalone = this.childNodes.length === 0 ||
+            [...this.childNodes].every((n) => n.nodeType === Node.TEXT_NODE && !(n.textContent ?? "").trim());
+        const cls = [
+            "badge",
+            isDot && "badge--dot",
+            isStandalone && "badge--standalone",
+        ]
+            .filter(Boolean)
+            .join(" ");
+        const marker = isDot || this._hasCount
+            ? html `<span
+            class="badge__count"
+            role="status"
+            aria-label=${this._ariaLabel || nothing}
+            >${this._display}</span
+          >`
+            : nothing;
+        return html `
+      <link rel="stylesheet" href="${BADGE_CSS}" />
+      <style>
+        :host {
+          display: inline-flex;
+        }
+        :host([hidden]) {
+          display: none;
+        }
+      </style>
+      <span class="${cls}">
+        <span class="badge__anchor"><slot></slot></span>
+        ${marker}
+      </span>
+    `;
+    }
+};
+__decorate([
+    property({ type: Number })
+], XmBadge.prototype, "count", void 0);
+__decorate([
+    property({ type: Boolean })
+], XmBadge.prototype, "dot", void 0);
+__decorate([
+    property({ type: Number })
+], XmBadge.prototype, "max", void 0);
+__decorate([
+    property({ type: String })
+], XmBadge.prototype, "label", void 0);
+XmBadge = __decorate([
+    customElement("xm-badge")
+], XmBadge);

package/dist/lit/components/brand-mark/index.css

@@ -0,0 +1,109 @@
+/* ============================================================
+   <BrandMark /> — xmesh logo lockup.
+
+   Owns the canonical brand glyph (three nodes routing to a single
+   hub) and the wordmark. Three sizes:
+     sm — 28px chip · sidebar header
+     md — 40px chip · generic placement
+     lg — 96px chip · brand showcase / about pages
+
+   Pairs with components/brand-mark/index.jsx. The glyph is a single SVG
+   that renders at any size — only the chip dimensions change.
+   ============================================================ */
+
+.brand-mark {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--s-2-5);
+  min-width: 0;
+  color: var(--md-sys-color-on-surface);
+}
+
+.brand-mark__chip {
+  flex-shrink: 0;
+  border-radius: 7px;
+  background: transparent;
+  color: var(--md-sys-color-on-surface);
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.brand-mark__info {
+  display: flex;
+  flex-direction: column;
+  gap: var(--s-1);
+  min-width: 0;
+}
+
+.brand-mark__wordmark {
+  font: 500 15px/1 var(--md-sys-typescale-display-large-font);
+  letter-spacing: -0.01em;
+  text-transform: uppercase;
+  color: var(--md-sys-color-on-surface);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.brand-mark__tagline {
+  font: 400 13px/1.5 var(--md-sys-typescale-body-large-font);
+  color: var(--xm-color-on-surface-soft);
+  max-width: 360px;
+}
+
+/* ---------- Sizes ---------- */
+.brand-mark--sm {
+  gap: var(--s-1);
+}
+.brand-mark--sm .brand-mark__chip {
+  width: 24px; height: 24px;
+  border-radius: 6px;
+}
+.brand-mark--sm .brand-mark__chip svg { width: 20px; height: 20px; }
+
+.brand-mark--md {
+  gap: var(--s-3-5);
+}
+.brand-mark--md .brand-mark__chip {
+  width: 40px; height: 40px;
+  border-radius: 10px;
+}
+.brand-mark--md .brand-mark__chip svg { width: 24px; height: 24px; }
+.brand-mark--md .brand-mark__wordmark { font-size: 20px; }
+
+.brand-mark--lg {
+  gap: var(--s-8);
+}
+.brand-mark--lg .brand-mark__chip {
+  width: 96px; height: 96px;
+  border-radius: 22px;
+}
+.brand-mark--lg .brand-mark__chip svg { width: 60px; height: 60px; }
+.brand-mark--lg .brand-mark__wordmark {
+  font: 600 34px/1 var(--md-sys-typescale-body-large-font);
+  letter-spacing: -0.02em;
+}
+
+/* ---------- Wordmark-only (no glyph) ----------
+   The serif-driven brand wordmark used in the chat sidebar header
+   and editorial brand placements. Display family + medium weight.
+   Sizes scale with the wrapper modifier (--sm | --md | --lg). */
+.brand-mark--wordmark-only { gap: 0; }
+.brand-mark--wordmark-only .brand-mark__wordmark {
+  font:
+    var(--xm-typescale-wordmark-weight)
+    var(--xm-typescale-wordmark-size) /
+    var(--xm-typescale-wordmark-line-height)
+    var(--xm-typescale-wordmark-font);
+  letter-spacing: var(--xm-typescale-wordmark-tracking);
+  text-transform: none;
+  color: var(--md-sys-color-inverse-on-surface);
+}
+.brand-mark--wordmark-only.brand-mark--sm .brand-mark__wordmark { font-size: 16px; }
+.brand-mark--wordmark-only.brand-mark--md .brand-mark__wordmark { font-size: 18px; }
+.brand-mark--wordmark-only.brand-mark--lg .brand-mark__wordmark {
+  font-size: 28px;
+  font-weight: 400;
+  letter-spacing: -0.02em;
+}

package/dist/lit/components/brand-mark/index.d.ts

@@ -0,0 +1,24 @@
+import { LitElement } from "lit";
+import type { TemplateResult } from "lit";
+type BrandSize = "sm" | "md" | "lg";
+declare class LightElement extends LitElement {
+    createRenderRoot(): HTMLElement | DocumentFragment;
+}
+declare class XmBrandGlyph extends LightElement {
+    render(): TemplateResult;
+}
+declare class XmBrandMark extends LightElement {
+    size: BrandSize;
+    showGlyph: boolean;
+    showWordmark: boolean;
+    showTagline: boolean;
+    tagline: string;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        "xm-brand-glyph": XmBrandGlyph;
+        "xm-brand-mark": XmBrandMark;
+    }
+}
+export {};

package/dist/lit/components/brand-mark/index.js

@@ -0,0 +1,116 @@
+/*
+  brand-mark/index.ts — Lit port of components/brand-mark/index.jsx.
+
+  <xm-brand-mark> — xmesh logo lockup.
+  <xm-brand-glyph> — just the SVG glyph (three routed paths meeting at a hub).
+
+  Properties on <xm-brand-mark>:
+    size           "sm" | "md" | "lg"            (default "md")
+    showGlyph      boolean                       (default true)
+    showWordmark   boolean                       (default true)
+    showTagline    boolean                       (default false)
+    tagline        string                        (default — see DEFAULT_TAGLINE)
+
+  Light DOM. Existing components/brand-mark/index.css owns all visuals.
+  The glyph SVG references --c-card-soft for the outer node fill, which
+  resolves at the host (light DOM) so theme switching works.
+*/
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { LitElement, html, nothing } from "lit";
+import { customElement, property } from "lit/decorators.js";
+const DEFAULT_TAGLINE = "Smart-routing AI chat. The mark is an X-mesh — four nodes routing to a single hub through the letterform itself.";
+class LightElement extends LitElement {
+    createRenderRoot() {
+        return this;
+    }
+}
+let XmBrandGlyph = class XmBrandGlyph extends LightElement {
+    render() {
+        // X-mesh: two crossing strokes meet at a central hub, four outer
+        // nodes at the X endpoints. Reads as the letter X at a glance and
+        // a routed mesh on inspection — couples the brand name to the
+        // smart-routing metaphor in a single symmetric mark.
+        return html `
+      <svg viewBox="0 0 32 32" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
+        <g
+          fill="none"
+          stroke="currentColor"
+          stroke-width="1.7"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+        >
+          <path d="M8 8 L16 16 L24 24" />
+          <path d="M24 8 L16 16 L8 24" />
+          <circle cx="8"  cy="8"  r="2.2" fill="transparent" />
+          <circle cx="24" cy="8"  r="2.2" fill="transparent" />
+          <circle cx="8"  cy="24" r="2.2" fill="transparent" />
+          <circle cx="24" cy="24" r="2.2" fill="transparent" />
+          <circle cx="16" cy="16" r="2.4" fill="currentColor" stroke="none" />
+        </g>
+      </svg>
+    `;
+    }
+};
+XmBrandGlyph = __decorate([
+    customElement("xm-brand-glyph")
+], XmBrandGlyph);
+let XmBrandMark = class XmBrandMark extends LightElement {
+    constructor() {
+        super(...arguments);
+        this.size = "md";
+        this.showGlyph = true;
+        this.showWordmark = true;
+        this.showTagline = false;
+        this.tagline = DEFAULT_TAGLINE;
+    }
+    render() {
+        const wordmarkOnly = !this.showGlyph && this.showWordmark;
+        const cls = [
+            "brand-mark",
+            `brand-mark--${this.size}`,
+            wordmarkOnly && "brand-mark--wordmark-only",
+        ].filter(Boolean).join(" ");
+        return html `
+      <span class="${cls}" title="xmesh">
+        ${this.showGlyph
+            ? html `<span class="brand-mark__chip"><xm-brand-glyph></xm-brand-glyph></span>`
+            : nothing}
+        ${(this.showWordmark || this.showTagline)
+            ? html `
+              <span class="brand-mark__info">
+                ${this.showWordmark
+                ? html `<span class="brand-mark__wordmark">mesh</span>`
+                : nothing}
+                ${this.showTagline
+                ? html `<span class="brand-mark__tagline">${this.tagline}</span>`
+                : nothing}
+              </span>
+            `
+            : nothing}
+      </span>
+    `;
+    }
+};
+__decorate([
+    property({ type: String })
+], XmBrandMark.prototype, "size", void 0);
+__decorate([
+    property({ type: Boolean, attribute: "show-glyph" })
+], XmBrandMark.prototype, "showGlyph", void 0);
+__decorate([
+    property({ type: Boolean, attribute: "show-wordmark" })
+], XmBrandMark.prototype, "showWordmark", void 0);
+__decorate([
+    property({ type: Boolean, attribute: "show-tagline" })
+], XmBrandMark.prototype, "showTagline", void 0);
+__decorate([
+    property({ type: String })
+], XmBrandMark.prototype, "tagline", void 0);
+XmBrandMark = __decorate([
+    customElement("xm-brand-mark")
+], XmBrandMark);