@aphrody/m3-ai

Material Design 3 components for agent interfaces: tool-call cards, markdown, chat bubbles, the chat composer, model selector, worker and branch cards, and the task board. They are the SpaceUI @spacedrive/ai set, rebuilt on @aphrody/m3-primitives, the M3 color roles, typescale, shapes and motion of Aphrody OS, and Material Symbols icons.

Install

bun add @aphrody/m3-ai @aphrody/m3-primitives @aphrody/m3-motion

Peers: react and react-dom 18 or 19, tailwindcss 4.1+.

CSS setup

The components ship Tailwind class names that use the M3 utilities of @aphrody/m3-theme. Import the tokens, a palette sheet and the M3 utilities, then let Tailwind scan the package output. The full recipe is in docs/design/SPACEUI-M3-FUSION.md, section "Integration":

@import "tailwindcss";
@import "@aphrody/m3-tokens/m3-tokens.css";
@import "@aphrody/m3-theme/spaceui.css";
@import "@aphrody/m3-theme/tailwind.css";

@source "../node_modules/@aphrody/m3-primitives/dist";
@source "../node_modules/@aphrody/m3-ai/dist";

Register the Material Symbols font once, for example with ensureMaterialSymbols() from @aphrody/material-web/icon/material-symbols.js.

Usage

import { ChatComposer, MessageBubble, ToolCall } from "@aphrody/m3-ai";
import type { ToolCallPair } from "@aphrody/m3-ai";

const pair: ToolCallPair = {
  id: "1",
  name: "file_read",
  argsRaw: '{"path":"README.md"}',
  args: { path: "README.md" },
  resultRaw: '{"text":"# Aphrody"}',
  result: { text: "# Aphrody" },
  status: "completed",
};

export function Conversation({ draft, setDraft, send }: Props) {
  return (
    <>
      <MessageBubble content="List the files" isUser />
      <ToolCall pair={pair} />
      <MessageBubble content="There is one file: `README.md`." isUser={false} />
      <ChatComposer draft={draft} onDraftChange={setDraft} onSend={send} />
    </>
  );
}

Components

| Component | M3 anatomy | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | ToolCall | Outlined card (surface-container-low, medium shape): status icon or circular indicator, text-label-large tool name, expandable arguments and result blocks in font-code on surface-container-highest, error results on error-container. | | Markdown | Prose on the M3 typescale (headline / title / body), font-code code blocks, primary links, outline-variant quotes and tables. size picks the body scale; allowHtml enables raw HTML for trusted content. | | MessageBubble | User turn as a secondary-container bubble (large shape), assistant turn as markdown on the surface with a standard copy icon button. | | ChatComposer | Search-bar anatomy: surface-container-high, extra-large shape, text-body-large input, project pill, model chip, standard mic icon button, filled send / stop icon button. | | ModelSelector | Pill trigger opening an M3 menu (surface-container, extra-small shape, level 2): search field, provider section headers, 48 dp items, selection on secondary-container, capability chips. ModelOptionList and groupModelsByProvider expose the list alone. | | InlineWorkerCard | Filled card (surface-container, medium shape), text-title-small header, status chip, circular indicator while running, expandable transcript of ToolCalls and markdown. | | InlineBranchCard | Filled card for a thinking branch: indicator or branch icon, status chip, expandable conclusion. | | TaskStatusIcon | Material Symbol per status: done success, in progress and ready primary, pending approval warning, backlog outline. | | TaskPriorityIcon | Material Symbol per priority: critical error, high warning, medium primary, low outline. | | TaskRow | Dense M3 list item (48 dp): text-body-large headline, text-body-small supporting columns, 8 % hover state layer, secondary-container selection, overflow menu. | | TaskList | Tasks grouped by status: collapsible text-title-small section headers, outline-variant dividers. | | TaskDetail | Task on an M3 surface: text-headline-small title, property grid, subtasks as a checkbox list, markdown description, filled and text buttons. | | TaskCreateForm | Title and description text fields, priority select, filled Create and text Cancel buttons. |

Helpers from types.ts: pairTranscriptSteps, tryParseJson, isErrorResult, TASK_STATUS_ORDER, TASK_STATUS_LABEL, TASK_PRIORITY_LABEL, and the transcript, task and model types.

Local chat

Everything a chat over an OpenAI-compatible server (llama-server, vLLM, the Aphrody gateway) needs, with no visible string hard-coded:

| Export | Role | | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ChatLabels, chatLabelsFr / chatLabelsEn / chatLabelsJa, resolveChatLabels, formatLabel | One dictionary for every visible string and aria-label. Every chat component takes labels?: Partial<ChatLabels>; missing keys fall back on English. | | streamChatCompletion, createSseParser, parseChatCompletionChunk, chatReducer, ChatStreamError | Pure streaming client of POST <baseUrl>/chat/completions (stream: true): SSE framing, content / reasoning_content / tool-call deltas, finish_reason, top-level citations and refusal. Network failures and 404/502/503/504 are unavailable. | | useOpenAIChat({ baseUrl, model, fetch?, headers?, initialMessages?, preamble?, body? }) | React hook: { messages, send, stop, status, error, reset, setMessages }, status is idle, streaming, error or unavailable. | | ConversationList | Navigation-drawer list: new conversation, optional search, rename / delete callbacks, empty state, localized dates. | | ModelUnavailable | Downloading / loading / unavailable state with a determinate linear indicator and a retry button. | | CitedMarkdown, CitationChip, CitationList, RefusalNotice | Grounded answers: [n] markers as chips, the numbered sources, the "not established in the sources" notice. MessageBubble takes citations and refusal directly. | | MemoryPanel | Saved memories with per-item deletion and a confirmed "clear all" (confirmClear injects your own dialog). | | ChatIcon | The chat icons as inline Material Symbols SVG: no icon font is needed by the chat components. |

Markdown (and MessageBubble, CitedMarkdown) open external links with target="_blank" rel="noopener noreferrer" and take onLinkClick(href, event) (call event.preventDefault() to open the system browser from a Tauri webview) or renderLink. ChatComposer takes disabled (the model is unavailable: input, send, voice and selectors are inert), distinct from isSending.

Tests

bun test

test/preload.ts resolves @aphrody/m3-primitives to its sources, so the tests do not need a built dist.

Credits

Derived from SpaceUI @spacedrive/ai (MIT, see LICENSE.spaceui), rebuilt on Material Design 3. New code is Apache-2.0.