@runtypelabs/persona 3.34.1 → 3.35.0

package/src/theme-editor/sections.ts

@@ -1,4 +1,4 @@
-/** Declarative section/field definitions for the theme editor (pure data — no DOM, no render logic) */
+/** Declarative section/field definitions for the theme editor (pure data: no DOM, no render logic) */
 
 import type { SectionDef, TabDef, SubGroupDef, FieldDef } from './types';
 import {
@@ -19,7 +19,7 @@ import {
 } from './role-mappings';
 
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-// STYLE TAB — brand colors, chat colors, typography, shape, etc.
+// STYLE TAB: brand colors, chat colors, typography, shape, etc.
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 const themeModeSectionDef: SectionDef = {
@@ -209,7 +209,7 @@ export const STYLE_SECTIONS: SectionDef[] = [
 ];
 
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-// COLORS & STYLE TAB — palette scales, semantic tokens
+// COLORS & STYLE TAB: palette scales, semantic tokens
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 function buildPaletteSectionDef(): SectionDef {
@@ -269,7 +269,7 @@ export const COLORS_SECTIONS: SectionDef[] = [
 ];
 
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-// DESIGN SYSTEM TAB — component shapes, colors, layout
+// DESIGN SYSTEM TAB: component shapes, colors, layout
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 const panelLayoutSectionDef: SectionDef = {
@@ -510,7 +510,7 @@ export const COMPONENTS_SECTIONS: SectionDef[] = [
 ];
 
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-// CONFIGURE TAB — content, layout, widget, features, developer
+// CONFIGURE TAB: content, layout, widget, features, developer
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 const MB = 1024 * 1024;
@@ -613,6 +613,7 @@ const messageActionsSectionDef: SectionDef = {
     { id: 'msg-actions-copy', label: 'Show Copy', type: 'toggle', path: 'messageActions.showCopy', defaultValue: true },
     { id: 'msg-actions-upvote', label: 'Show Upvote', type: 'toggle', path: 'messageActions.showUpvote', defaultValue: true },
     { id: 'msg-actions-downvote', label: 'Show Downvote', type: 'toggle', path: 'messageActions.showDownvote', defaultValue: true },
+    { id: 'msg-actions-read-aloud', label: 'Show Read Aloud', type: 'toggle', path: 'messageActions.showReadAloud', defaultValue: false },
     { id: 'msg-actions-visibility', label: 'Visibility', type: 'select', path: 'messageActions.visibility', defaultValue: 'hover', options: [{ value: 'hover', label: 'On Hover' }, { value: 'always', label: 'Always Visible' }] },
     { id: 'msg-actions-align', label: 'Alignment', type: 'select', path: 'messageActions.align', defaultValue: 'right', options: [{ value: 'left', label: 'Left' }, { value: 'right', label: 'Right' }] },
     { id: 'msg-actions-layout', label: 'Layout', type: 'select', path: 'messageActions.layout', defaultValue: 'pill-inside', options: [{ value: 'pill-inside', label: 'Pill' }, { value: 'row-inside', label: 'Row' }] },
@@ -768,9 +769,9 @@ const streamAnimationSectionDef: SectionDef = {
       path: 'features.streamAnimation.buffer',
       defaultValue: 'none',
       options: [
-        { value: 'none', label: 'None — stream every character' },
-        { value: 'word', label: 'Word — hold until whitespace' },
-        { value: 'line', label: 'Line — hold until newline' },
+        { value: 'none', label: 'None: stream every character' },
+        { value: 'word', label: 'Word: hold until whitespace' },
+        { value: 'line', label: 'Line: hold until newline' },
       ],
     },
     {
@@ -781,12 +782,12 @@ const streamAnimationSectionDef: SectionDef = {
       path: 'features.streamAnimation.speed',
       defaultValue: 120,
       options: [
-        { value: '40', label: '40ms — snappy' },
+        { value: '40', label: '40ms: snappy' },
         { value: '80', label: '80ms' },
         { value: '120', label: '120ms (default)' },
         { value: '200', label: '200ms' },
         { value: '320', label: '320ms' },
-        { value: '480', label: '480ms — slow' },
+        { value: '480', label: '480ms: slow' },
       ],
       formatValue: (v: unknown) => String(v ?? 120),
       parseValue: (v: unknown) => Number(v),
@@ -803,7 +804,7 @@ const streamAnimationSectionDef: SectionDef = {
         { value: '1200', label: '1200ms' },
         { value: '1800', label: '1800ms (default)' },
         { value: '2400', label: '2400ms' },
-        { value: '3600', label: '3600ms — slow' },
+        { value: '3600', label: '3600ms: slow' },
       ],
       formatValue: (v: unknown) => String(v ?? 1800),
       parseValue: (v: unknown) => Number(v),
@@ -894,10 +895,10 @@ export const CONFIGURE_SUB_GROUPS: SubGroupDef[] = [
 export const CONFIGURE_SECTIONS: SectionDef[] = CONFIGURE_SUB_GROUPS.flatMap(g => g.sections);
 
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-// STYLE TAB V2 — outcome-oriented editor structure
+// STYLE TAB V2: outcome-oriented editor structure
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-/** Section 1: Theme — color mode selection */
+/** Section 1: Theme: color mode selection */
 export const THEME_SECTION: SectionDef = {
   id: 'theme-mode-v2',
   title: 'Theme',
@@ -919,7 +920,7 @@ export const THEME_SECTION: SectionDef = {
   ],
 };
 
-/** Section 2: Brand Palette — primary colors + collapsed status colors */
+/** Section 2: Brand Palette: primary colors + collapsed status colors */
 export const BRAND_PALETTE_SECTION: SectionDef = {
   id: 'brand-palette-v2',
   title: 'Brand Palette',
@@ -933,7 +934,7 @@ export const BRAND_PALETTE_SECTION: SectionDef = {
   ],
 };
 
-/** Section 2b: Status palette — collapsed under Brand Palette */
+/** Section 2b: Status palette: collapsed under Brand Palette */
 export const STATUS_PALETTE_SECTION: SectionDef = {
   id: 'status-palette',
   title: 'Status Palette',
@@ -947,7 +948,7 @@ export const STATUS_PALETTE_SECTION: SectionDef = {
   ],
 };
 
-/** Section 3: Interface Roles — the main theming surface */
+/** Section 3: Interface Roles: the main theming surface */
 export const INTERFACE_ROLES_SECTION: SectionDef = {
   id: 'interface-roles',
   title: 'Interface Roles',
@@ -1020,7 +1021,7 @@ export const INTERFACE_ROLES_SECTION: SectionDef = {
   ],
 };
 
-/** Section 4: Status Colors — feedback semantic tokens */
+/** Section 4: Status Colors: feedback semantic tokens */
 export const STATUS_COLORS_SECTION: SectionDef = {
   id: 'status-colors',
   title: 'Status Colors',
@@ -1034,7 +1035,7 @@ export const STATUS_COLORS_SECTION: SectionDef = {
   ],
 };
 
-/** Section 5: Advanced Tokens — entry point for drill-downs (no fields) */
+/** Section 5: Advanced Tokens: entry point for drill-downs (no fields) */
 export const ADVANCED_TOKENS_SECTION: SectionDef = {
   id: 'advanced-tokens',
   title: 'Advanced Tokens',
@@ -1043,7 +1044,7 @@ export const ADVANCED_TOKENS_SECTION: SectionDef = {
   fields: [],
 };
 
-/** V2 Style tab sections — outcome-oriented editor */
+/** V2 Style tab sections: outcome-oriented editor */
 export const STYLE_SECTIONS_V2: SectionDef[] = [
   THEME_SECTION,
   BRAND_PALETTE_SECTION,
@@ -1064,7 +1065,7 @@ export const ALL_TABS: TabDef[] = [
 ];
 
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-// HELPERS — light/dark scoping for dual-mode editing
+// HELPERS: light/dark scoping for dual-mode editing
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 type ThemeScope = 'theme' | 'darkTheme';

package/src/theme-editor/types.ts

@@ -1,4 +1,4 @@
-/** Field definition types for the declarative configurator system (headless — no DOM) */
+/** Field definition types for the declarative configurator system (headless: no DOM) */
 
 import type { DeepPartial, PersonaTheme } from '../types/theme';
 import type { AgentWidgetConfig } from '../types';

package/src/theme-editor/webmcp/index.ts

@@ -4,7 +4,7 @@
  * Transport-agnostic: `createThemeEditorTools(state)` returns plain tool
  * definitions. Host code (e.g. an example app or a self-styling widget) is
  * responsible for obtaining a `document.modelContext` and calling
- * `registerTool` for each — this module has no polyfill dependency.
+ * `registerTool` for each: this module has no polyfill dependency.
  */
 
 export { createThemeEditorTools } from './tools';

package/src/theme-editor/webmcp/summary.ts

@@ -49,8 +49,7 @@ const RADIUS_KEYS = ['sm', 'md', 'lg', 'xl', 'full'] as const;
 /**
  * Resolve a theme token path to a concrete color, following `palette.*`,
  * `semantic.*`, and `components.*` references. When resolving the `darkTheme`
- * variant, tokens the dark theme doesn't define fall back to the light theme —
- * mirroring the widget's runtime merge behavior.
+ * variant, tokens the dark theme doesn't define fall back to the light theme: * mirroring the widget's runtime merge behavior.
  */
 export function resolveColor(
   state: ThemeEditorLike,

package/src/theme-editor/webmcp/tools.ts

@@ -4,8 +4,8 @@
  * `createThemeEditorTools(state)` returns transport-agnostic tool definitions
  * designed for Agent Experience: intent-level operations (set brand colors,
  * assign a color role, set roundness…) rather than a 1:1 mapping of the ~150
- * editor fields. Two altitudes — high-level semantic tools plus a low-level
- * escape hatch (`set_theme_fields`) — keep the catalog small without losing
+ * editor fields. Two altitudes: high-level semantic tools plus a low-level
+ * escape hatch (`set_theme_fields`): keep the catalog small without losing
  * coverage. Every mutation returns a compact summary + contrast warnings.
  */
 
@@ -176,7 +176,7 @@ export function createThemeEditorTools(
     name: 'get_theme_overview',
     title: 'Get current theme & what is editable',
     description:
-      'Read the current widget theme (brand colors, per-role color assignments, typography, roundness, color scheme, undo/redo state), the available presets, and the high-level levers you can change. Call this FIRST before editing.',
+      'Read theme summary, presets, and editable levers. Call before editing.',
     annotations: { readOnlyHint: true },
     inputSchema: {
       type: 'object',
@@ -184,7 +184,7 @@ export function createThemeEditorTools(
         verbosity: {
           type: 'string',
           enum: ['summary', 'full'],
-          description: "Use 'full' to also include the field-id index for set_theme_fields.",
+          description: "'full' includes the field-id index.",
         },
       },
       additionalProperties: false,
@@ -205,16 +205,16 @@ export function createThemeEditorTools(
           tags: p.tags ?? [],
         })),
         tools: [
-          { tool: 'set_brand_colors', hint: 'Recolor the palette (primary/secondary/accent) — auto-generates shade scales.' },
-          { tool: 'assign_color_role', hint: 'Recolor a region (header, user/assistant messages, actions, input, links, borders, surfaces, scroll) with a family + intensity.' },
+          { tool: 'set_brand_colors', hint: 'Recolor primary/secondary/accent and generate shade scales.' },
+          { tool: 'assign_color_role', hint: 'Recolor a widget region with family + intensity.' },
           { tool: 'set_typography', hint: 'Set font family, size, weight, line height.' },
-          { tool: 'set_roundness', hint: 'Set corner roundness (sharp/default/rounded/pill) or granular radii.' },
-          { tool: 'set_color_scheme', hint: 'Set light/dark/auto and which variant edits target.' },
-          { tool: 'apply_preset', hint: 'Apply a complete built-in preset.' },
+          { tool: 'set_roundness', hint: 'Set corner roundness or granular radii.' },
+          { tool: 'set_color_scheme', hint: 'Set light/dark/auto and edit target.' },
+          { tool: 'apply_preset', hint: 'Apply a built-in preset.' },
           { tool: 'configure_widget', hint: 'Toggle launcher position, features, and layout.' },
           { tool: 'set_copy_and_suggestions', hint: 'Set welcome copy, placeholder, and suggestion chips.' },
-          { tool: 'set_theme_fields', hint: 'Advanced escape hatch: set any field by id or dot-path.' },
-          { tool: 'check_contrast', hint: 'Audit WCAG contrast across key text/background pairs.' },
+          { tool: 'set_theme_fields', hint: 'Set any field by id or dot-path.' },
+          { tool: 'check_contrast', hint: 'Audit WCAG contrast.' },
           { tool: 'manage_session', hint: 'Undo, redo, reset, or export the theme.' },
         ],
       };
@@ -236,13 +236,13 @@ export function createThemeEditorTools(
     name: 'set_brand_colors',
     title: 'Set brand colors',
     description:
-      'Set one or more brand colors (primary, secondary, accent). Each color auto-generates a full 50–950 shade scale and applies to the light and dark themes (per the current edit target). Accepts hex ("#2563eb", "2563eb", "#18f"), rgb()/rgba() ("rgb(37, 99, 235)"), or CSS color names ("blue", "slateblue").',
+      'Set primary, secondary, and/or accent colors. Generates shade scales and accepts hex, rgb/rgba, or CSS names.',
     inputSchema: {
       type: 'object',
       properties: {
-        primary: { type: 'string', description: 'Hex, rgb()/rgba(), or CSS color name.' },
-        secondary: { type: 'string', description: 'Hex, rgb()/rgba(), or CSS color name.' },
-        accent: { type: 'string', description: 'Hex, rgb()/rgba(), or CSS color name.' },
+        primary: { type: 'string', description: 'Hex, rgb/rgba, or CSS name.' },
+        secondary: { type: 'string', description: 'Hex, rgb/rgba, or CSS name.' },
+        accent: { type: 'string', description: 'Hex, rgb/rgba, or CSS name.' },
       },
       additionalProperties: false,
     },
@@ -282,13 +282,13 @@ export function createThemeEditorTools(
     name: 'assign_color_role',
     title: 'Assign a color family to an interface role',
     description:
-      'Recolor a semantic region of the widget by choosing a palette family and intensity. One call writes all related tokens (background, text, border, icon) consistently. Roles: header, user-messages, assistant-messages, primary-actions, input, links, borders, surfaces, scroll-to-bottom. Families: primary, secondary, accent, neutral. Intensity: solid (bold) or soft (tinted).',
+      'Recolor a widget region by role, palette family, and intensity.',
     inputSchema: {
       type: 'object',
       properties: {
-        role: { type: 'string', description: 'Interface role, e.g. "header" or "user-messages".' },
+        role: { type: 'string', description: 'Role, e.g. header or user-messages.' },
         family: { type: 'string', enum: ROLE_FAMILY_NAMES },
-        intensity: { type: 'string', enum: ['solid', 'soft'], description: "Defaults to 'solid'." },
+        intensity: { type: 'string', enum: ['solid', 'soft'], description: 'Default: solid.' },
       },
       required: ['role', 'family'],
       additionalProperties: false,
@@ -315,7 +315,7 @@ export function createThemeEditorTools(
     name: 'set_typography',
     title: 'Set typography',
     description:
-      'Set font family, base size, weight, and line height in one call. fontFamily: sans|serif|mono. fontSize: xs|sm|base|lg|xl. fontWeight: normal|medium|semibold|bold (or 400–700). lineHeight: tight|normal|relaxed (or 1.25/1.5/1.625).',
+      'Set font family, size, weight, and line height.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -358,14 +358,14 @@ export function createThemeEditorTools(
     name: 'set_roundness',
     title: 'Set corner roundness',
     description:
-      'Set overall corner roundness with a keyword (sharp, default, rounded, pill) which maps the full radius scale, OR pass granular radius values. Provide at least one of `style` or `radius`.',
+      'Set roundness by style or granular radius values.',
     inputSchema: {
       type: 'object',
       properties: {
         style: { type: 'string', enum: ['sharp', 'default', 'rounded', 'pill'] },
         radius: {
           type: 'object',
-          description: 'Granular overrides (px number or CSS length).',
+          description: 'Granular px or CSS length overrides.',
           properties: {
             sm: { type: ['string', 'number'] },
             md: { type: ['string', 'number'] },
@@ -415,7 +415,7 @@ export function createThemeEditorTools(
     name: 'set_color_scheme',
     title: 'Set color scheme',
     description:
-      'Set the shipped widget color scheme (light, dark, or auto/follow-system). Optionally set `editTarget` to choose which theme variant subsequent styling edits write to (light, dark, or both — default both).',
+      'Set light/dark/auto color scheme and optional edit target.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -481,7 +481,7 @@ export function createThemeEditorTools(
     name: 'configure_widget',
     title: 'Configure launcher, features, and layout',
     description:
-      'Toggle non-theme widget configuration. launcherPosition: bottom-right|bottom-left|top-right|top-left. features: { voice, artifacts, attachments, toolCalls, reasoning, feedback } booleans. layout: { avatars, timestamps, showHeader } booleans and messageStyle: bubble|flat|minimal.',
+      'Toggle launcher position, feature flags, and message layout.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -563,7 +563,7 @@ export function createThemeEditorTools(
     name: 'set_copy_and_suggestions',
     title: 'Set welcome copy and suggestion chips',
     description:
-      'Set the widget welcome copy and suggestion chips. title/subtitle are the welcome card text; placeholder is the input placeholder; sendLabel is the send button label; suggestions is an array of suggestion-chip strings (replaces the existing list).',
+      'Set welcome copy, input placeholder, send label, and suggestion chips.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -607,7 +607,7 @@ export function createThemeEditorTools(
     name: 'set_theme_fields',
     title: 'Set theme fields by id or path (advanced)',
     description:
-      'Advanced escape hatch: set individual editor fields by field id (see get_theme_overview verbosity:"full") — theme field ids follow the current edit target (light/dark/both) — or by raw dot-path (theme.* / darkTheme.* / a config path), which is written as-is. Use only when a higher-level tool does not cover the need. Values are validated against the field metadata.',
+      'Advanced escape hatch: set fields by id or raw dot-path. Values are validated when metadata exists.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -616,7 +616,7 @@ export function createThemeEditorTools(
           items: {
             type: 'object',
             properties: {
-              field: { type: 'string', description: 'Field id or dot-path.' },
+              field: { type: 'string', description: 'Field id or path.' },
               value: { type: ['string', 'number', 'boolean'] },
             },
             required: ['field', 'value'],
@@ -686,13 +686,13 @@ export function createThemeEditorTools(
     name: 'check_contrast',
     title: 'Check accessibility contrast',
     description:
-      'Run WCAG contrast checks over the key text/background pairs (message text, header title, input/body text, primary button). Returns each ratio, whether it passes, and a suggested foreground shade for failures.',
+      'Run WCAG checks over key text/background pairs.',
     annotations: { readOnlyHint: true },
     inputSchema: {
       type: 'object',
       properties: {
-        level: { type: 'string', enum: ['AA', 'AAA'], description: "Defaults to 'AA'." },
-        variant: { type: 'string', enum: ['light', 'dark', 'both'], description: "Defaults to 'both'." },
+        level: { type: 'string', enum: ['AA', 'AAA'], description: 'Default: AA.' },
+        variant: { type: 'string', enum: ['light', 'dark', 'both'], description: 'Default: both.' },
       },
       additionalProperties: false,
     },
@@ -716,7 +716,7 @@ export function createThemeEditorTools(
     name: 'manage_session',
     title: 'Undo, redo, reset, or export the theme',
     description:
-      'Session action. "undo"/"redo" step through edit history; "reset" restores defaults; "export" returns the embeddable theme snapshot (config + theme JSON) with no side effects.',
+      'Undo, redo, reset defaults, or export the theme snapshot.',
     inputSchema: {
       type: 'object',
       properties: { action: { type: 'string', enum: ['undo', 'redo', 'reset', 'export'] } },

package/src/theme-editor/webmcp/types.ts

@@ -56,7 +56,7 @@ export interface WebMcpTool {
 
 /**
  * Wrap a JSON-serializable payload in the MCP tool-result envelope. Compact
- * JSON (no indentation) — the text is consumed by a model, where pretty-print
+ * JSON (no indentation): the text is consumed by a model, where pretty-print
  * whitespace is pure token overhead.
  */
 export function toolResult(payload: unknown): ToolResult {
@@ -71,7 +71,7 @@ export function toolResult(payload: unknown): ToolResult {
 /**
  * Structural subset of `ThemeEditorState` (and the example app's `state`
  * module) that the tools require. Anything satisfying this shape can be wired
- * to the tools — the headless `ThemeEditorState`, or a host's stateful wrapper
+ * to the tools: the headless `ThemeEditorState`, or a host's stateful wrapper
  * that also drives a live preview (e.g. a Persona widget styling itself).
  */
 export interface ThemeEditorLike {

package/src/theme-editor-preview.ts

@@ -0,0 +1,10 @@
+/** Entry point for @runtypelabs/persona/theme-editor/preview */
+export { createThemePreview } from './theme-editor/preview';
+export type {
+  ThemePreviewOptions,
+  ThemePreviewHandle,
+  PreviewLifecycleContext,
+  PreviewDevice,
+  PreviewShellMode,
+  CompareMode,
+} from './theme-editor/preview';

package/src/theme-reference.ts

@@ -1,5 +1,5 @@
 /**
- * Theme Reference — Structured documentation and examples for the Persona v2 theme system.
+ * Theme Reference: Structured documentation and examples for the Persona v2 theme system.
  *
  * Exported via the `@runtypelabs/persona/theme-reference` entry point so it stays
  * out of the IIFE widget bundle. Intended for AI/MCP tool consumption.
@@ -14,7 +14,7 @@ import type { DeepPartial, PersonaTheme } from './types/theme'
 
 export const THEME_TOKEN_DOCS = {
   overview:
-    'Persona uses a three-layer design token system: palette → semantic → components. Most themes only need palette.colors overrides — semantic and component layers auto-derive from palette values. Config also accepts non-theme appearance options (launcher, sendButton, toolCall, etc.).',
+    'Persona uses a three-layer design token system: palette → semantic → components. Most themes only need palette.colors overrides: semantic and component layers auto-derive from palette values. Config also accepts non-theme appearance options (launcher, sendButton, toolCall, etc.).',
 
   layers: {
     palette: {
@@ -24,9 +24,9 @@ export const THEME_TOKEN_DOCS = {
         description:
           '7 color scales, each with shades 50 (lightest) to 950 (darkest). Override only the shades you need.',
         scales: {
-          gray: 'Neutrals — backgrounds, text, borders. Key shades: 50 (lightest bg), 100 (secondary bg), 200 (borders), 500 (muted text), 900 (primary text).',
+          gray: 'Neutrals: backgrounds, text, borders. Key shades: 50 (lightest bg), 100 (secondary bg), 200 (borders), 500 (muted text), 900 (primary text).',
           primary:
-            'Brand color — buttons, links, interactive elements. Key shades: 500 (default), 600 (hover).',
+            'Brand color: buttons, links, interactive elements. Key shades: 500 (default), 600 (hover).',
           accent: 'Secondary highlight. Key shades: 500 (default), 600 (hover).',
           secondary: 'Tertiary color scale.',
           success: 'Positive feedback (default: green).',
@@ -65,17 +65,17 @@ export const THEME_TOKEN_DOCS = {
       description:
         'Design intent tokens. Auto-derived from palette by default. Override to redirect token resolution. Values are token reference strings like "palette.colors.primary.500".',
       colors: {
-        primary: 'palette.colors.primary.500 — Primary brand color.',
-        secondary: 'palette.colors.gray.500 — Secondary color.',
-        accent: 'palette.colors.primary.600 — Accent/interactive color.',
-        surface: 'palette.colors.gray.50 — Panel/card backgrounds.',
-        background: 'palette.colors.gray.50 — Page background.',
-        container: 'palette.colors.gray.100 — Container backgrounds.',
-        text: 'palette.colors.gray.900 — Primary text.',
-        textMuted: 'palette.colors.gray.500 — Muted/secondary text.',
-        textInverse: 'palette.colors.gray.50 — Text on dark backgrounds.',
-        border: 'palette.colors.gray.200 — Default border color.',
-        divider: 'palette.colors.gray.200 — Divider lines.',
+        primary: 'palette.colors.primary.500: Primary brand color.',
+        secondary: 'palette.colors.gray.500: Secondary color.',
+        accent: 'palette.colors.primary.600: Accent/interactive color.',
+        surface: 'palette.colors.gray.50: Panel/card backgrounds.',
+        background: 'palette.colors.gray.50: Page background.',
+        container: 'palette.colors.gray.100: Container backgrounds.',
+        text: 'palette.colors.gray.900: Primary text.',
+        textMuted: 'palette.colors.gray.500: Muted/secondary text.',
+        textInverse: 'palette.colors.gray.50: Text on dark backgrounds.',
+        border: 'palette.colors.gray.200: Default border color.',
+        divider: 'palette.colors.gray.200: Divider lines.',
         interactive: {
           default: 'palette.colors.primary.500',
           hover: 'palette.colors.primary.600',
@@ -93,7 +93,7 @@ export const THEME_TOKEN_DOCS = {
       spacing:
         'xs (0.25rem), sm (0.5rem), md (1rem), lg (1.5rem), xl (2rem), 2xl (2.5rem).',
       typography:
-        'fontFamily, fontSize, fontWeight, lineHeight — reference palette typography tokens.',
+        'fontFamily, fontSize, fontWeight, lineHeight: reference palette typography tokens.',
     },
 
     components: {
@@ -140,16 +140,16 @@ export const THEME_TOKEN_DOCS = {
       attachment: 'image (background, border).',
       scrollToBottom:
         'Floating scroll-to-bottom affordance shared by transcript and event stream: background, foreground, border, size, borderRadius, shadow, padding, gap, fontSize, iconSize.',
-      toolBubble: 'shadow — tool call row box-shadow.',
-      reasoningBubble: 'shadow — reasoning/thinking row box-shadow.',
-      composer: 'shadow — message input form box-shadow.',
+      toolBubble: 'shadow: tool call row box-shadow.',
+      reasoningBubble: 'shadow: reasoning/thinking row box-shadow.',
+      composer: 'shadow: message input form box-shadow.',
       artifact:
         'toolbar (icon styling, copy menu), tab (background, active states), pane (background, toolbarBackground).',
     },
   },
 
   colorScheme:
-    '"dark" merges darkTheme overrides on top of theme. "auto" detects system preference or <html class="dark">. "light" is default. colorScheme does NOT auto-invert colors — provide dark palette and semantic overrides yourself.',
+    '"dark" merges darkTheme overrides on top of theme. "auto" detects system preference or <html class="dark">. "light" is default. colorScheme does NOT auto-invert colors: provide dark palette and semantic overrides yourself.',
 
   plugins: {
     description:
@@ -246,7 +246,7 @@ export const THEME_TOKEN_DOCS = {
         'enabled, provider ("browser" | "runtype"), browserFallback, voice, rate, pitch.',
     },
     suggestionChips:
-      'string[] — Suggested prompts shown to the user.',
+      'string[]: Suggested prompts shown to the user.',
     messageActions: {
       description: 'Message action buttons (copy, upvote, downvote).',
       properties:
@@ -264,8 +264,8 @@ export const THEME_TOKEN_DOCS = {
     },
     layout: {
       description: 'Layout configuration.',
-      showHeader: 'boolean — show/hide the header section entirely.',
-      showFooter: 'boolean — show/hide the footer/composer section entirely.',
+      showHeader: 'boolean: show/hide the header section entirely.',
+      showFooter: 'boolean: show/hide the footer/composer section entirely.',
       contentMaxWidth:
         'CSS width value for centering content (e.g. "720px", "90ch").',
       header:
@@ -277,7 +277,7 @@ export const THEME_TOKEN_DOCS = {
       description: 'Status text shown below the composer.',
       properties: {
         visible: 'Show/hide the status indicator.',
-        align: '"left" | "center" | "right" — text alignment (default: "right").',
+        align: '"left" | "center" | "right": text alignment (default: "right").',
         idleText: 'Text shown when idle (default: "Online").',
         idleLink: 'URL to open when idle text is clicked (wraps text in a link).',
         connectingText: 'Text shown while connecting (default: "Connecting…").',
@@ -306,7 +306,7 @@ export interface ThemeExample {
 export const THEME_EXAMPLES: Record<string, ThemeExample> = {
   darkIndigo: {
     description:
-      'Dark mode with indigo accent — override grays for dark backgrounds and semantic tokens for inverted text/surface',
+      'Dark mode with indigo accent: override grays for dark backgrounds and semantic tokens for inverted text/surface',
     theme: {
       palette: {
         colors: {
@@ -359,7 +359,7 @@ export const THEME_EXAMPLES: Record<string, ThemeExample> = {
   },
   neonCyberpunk: {
     description:
-      'Neon on dark with monospace font — full semantic override for dark background',
+      'Neon on dark with monospace font: full semantic override for dark background',
     theme: {
       palette: {
         colors: {