Loquent · Design System Evolution Mode B · brainstorm + roadmap · 2026-06-14
Design system · brainstorm + roadmap

Loquent's design system is two layers — and we only ever wrote down one.

Aurora (the visual language) is documented and current. The thing that actually makes Loquent different — an agent-first, human-in-the-loop interaction paradigm — is half-built in code and written down nowhere a coding agent can load. This doc maps both layers, folds in the two features landing this week (Calls Enhancements + Agent AutoEvolve) and three cross-cutting mandates (realtime everywhere, inline-feedback over toasts, new components incl. the Command palette), and lays out exactly which skills and rules to write so future agents have exact knowledge.

Audience · future coding agents (+ humans) Scope · src/ui, .claude/skills, .claude/rules, tailwind.css Status · brainstorm — iterate before writing docs/code
↳ What this doc decides:
  • Where each piece of design knowledge lives (which skill / rule / token file owns it).
  • What's new: an agent-interaction-model rule, an agent-ux skill, a realtime rule, an inline-feedback rule, and a batch of UI primitives.
  • What's an update: the app-design skill, ui-permissions.md, and the scaffolding skills.

00TL;DR — six workstreams

The verdict on the original question (does the design skill follow Aurora?) is yes for the visual layer — but "exact knowledge" needs five more things, four of which don't exist yet.

01 · PARADIGM

Write down the agent-era model. Operators + agents, human-in-the-loop via escalation→push, learn-then-earn-autonomy. Zero docs today. → new rule + new agent-ux skill.

02 · SURFACES

Catalog the agent surfaces. Escalation cards, draft picker, activity feed, memory blocks, live-supervision (Calls), trust-and-learning (AutoEvolve). Many already in code — undocumented.

03 · REALTIME

Realtime everywhere. The infra is proven (messaging, calls). Task/contact/insights/sales/settings still poll. → reusable use_realtime_entities + a rule + scaffolding steps.

04 · FEEDBACK

Inline over toasts. 318 toast calls; ~90% are errors, only ~9% are confirmations that should be inline. Redesign the toast (Aurora glass), revise the mandate rule.

05 · COMPONENTS

Port what's missing. Command palette (⌘K), Dialog, DropdownMenu, Popover, Table, RadioGroup, redesigned Toast — the real gaps vs shadcn.

06 · AURORA

Close the Aurora drift. The "coral = honey = persimmon" naming landmine, missing recipe classes, and a component index covering only 8 of 45 primitives.

i

One sentence to anchor everything below

Loquent is not a CRM you operate — it's an operator backed by agents that mimic a human (persona + goals), do anything (dynamic skills + tools + MCP), and keep the human in the loop (escalate → push → answer → learn → gain autonomy). The UI exists to review, approve, and supervise, not to do manual data entry.

01The design system is two layers

A coding agent that loads app-design today learns how to make a card coral and frosted. It learns nothing about what a Loquent screen is for. Both are "the design system."

LayerGovernsWhere it livesStatus
Aurora
visual language
Tokens, Liquid Glass, serif-for-display, soft shadows, organic radii, pill controls, coral accent, entity/status colors, mobile headers, type scale. tailwind.css (source of truth) · docs/design-system.html (rendered) · ux-principles.md (principles) · app-design skill (code). Current minor drift only
Agent-era paradigm
interaction model
Review/approve/supervise over manual CRUD; escalation as a first-class surface; autonomy controls; plain-language outcomes; push as a channel; realtime by default. Nowhere a coding agent loads. Scattered across ~15 memory entries, two published artifacts, and built components with no doc. Undocumented
!

Why this is the real gap

The two features shipping this week — Calls Enhancements and Agent AutoEvolve — specify zero visual tokens. They are pure interaction-pattern features. The layer they need is exactly the one we never wrote down. Build them with only the Aurora layer documented and a fresh agent will produce 2010-era CRM screens (manual fields, save buttons) — the model Loquent kills.

02The agent-era interaction paradigm

The mental model, stated so an agent could build to it — plus the hard UI principles it implies. This becomes a new always-on rule.

OPERATOR ── handles the whole org, effortlessly │ ├─ AGENT (persona + goals → mimics a human) │ ├─ DYNAMIC SKILLS → learns how to do anything │ ├─ TOOLS → a way to actually do it │ └─ MCP CONNECTORS → reach any external platform ⇒ unlimited scope │ └─ HUMAN-IN-THE-LOOP agent hits an unknown it can't derive → escalates a question ──→ PUSH NOTIFICATION → owner answers → answer becomes a lesson (memory) → next time the agent has autonomy

The principles this forces on every UI

PrincipleWhat it means when you build a screen
Review > data entryDefault surface is "here's what the agent did / proposes — approve, edit, or undo," not an empty form. Manual CRUD is the fallback, not the front door.
Escalation is first-classAn agent asking the owner a question (yes/no · ≤3 options · custom) is a primary surface, thread-anchored, and push-delivered — not a buried notification.
Expose autonomyEvery agent capability has a visible trust dial: suggest vs. autonomous (send_mode), auto-apply vs. approval (learning_apply_mode). The owner controls how much rope.
Plain-language, outcomes-firstAudience = non-technical business owners (per user_target_audience memory). "Your agent learned to check hours before booking" — never a JSON diff. Technical logs are a demoted tier.
Calm, not naggingHITL must feel like a helpful colleague. Batch where possible (escalation queue), respect terse warm copy, no exclamation marks, no alarm.
Live by defaultBecause an agent acts while you watch, every surface updates in realtime (see §4). Supervision is meaningless if the screen is stale.

03The agent-surface catalog

The recurring surfaces the paradigm produces. Many already exist in code (reuse, don't reinvent); the two features add two new families. This catalog becomes the agent-ux skill.

Built today reuse these

SurfaceComponent / entry pointParadigm role
Escalation / "agent asks" cardai_agent/components/escalation_question_card_component.rs + escalate_to_user_tool / resolve_escalation_toolhuman-in-the-loop, push-driven
Escalation queue card (stepper)recent commit dc7c3053 (messaging)batched HITL
Draft picker (suggest-mode)messaging/components/agent_draft_picker_component.rsthe "gold signal" — edit → learn
Agent activity feedagent_activity_feed_component.rs, views/agent_activity_view.rsoutcomes-first log
Memory / Skills / Schedules / Capabilities panelsagent_memory_section_*, agent_skills_section_*, agent_schedules_section_*, agent_capabilities_section_*persona · dynamic skills · tools
Thread observability ("technical logs")debug_timeline_component.rs, prompt_capture_panel_component.rs, tool_call_card_component.rs (#1493)demoted debug tier
Autonomy toggle (send mode)agent detail view (#1478 / #1454 send_mode)trust dial
Staff presenceschemas/staff_presence.rslive-supervision foundation

Coming this week — two new families set the pattern

Calls Enhancements → live supervision

  • Live calls dashboard — active calls w/ AI·human badges, transfers-in-flight, waiting-callers queue, staff availability strip, daily counters.
  • Streaming live transcript of an in-progress AI call.
  • Whisper-to-AI box — inject an instruction mid-call.
  • "Take Over" button — join the conference, displace the AI.
  • Incoming-call overlay (Apple-Calls feel) + pre-answer context card (caller, intent, 2-line AI summary).
  • Persistent in-call pill (reuses OutboundCallProvider).

Agent AutoEvolve → trust & learning

  • "What your agent learned" feed entry + one-click undo (version rollback).
  • Change summary + provenance ("learned from 3 chats on Jun 10–13").
  • Shadow-replay preview — before/after on the last N real threads.
  • Typed, editable memory blocks with read_only pins (replaces the markdown blob).
  • Autonomy controlslearning_apply_mode = auto | approval.
  • "Improve my agent now" + "Topics your agent struggled with" report.
i

The point of the catalog

The first engineer to build "live calls dashboard" or "what your agent learned" sets the pattern every later one copies. The agent-ux skill names these surfaces, points at the canonical component, and states the paradigm role — so the pattern is set deliberately, not by whoever happens to build it first.

04Realtime everywhere

Mandate: all server data, in all areas, updates live — like messaging does today. The infrastructure already exists and is proven; the gap is coverage and a reusable pattern.

The infra (already shipped)

  • Server hub: bases/realtime/event_hub.rspublish_org() / publish_user() / publish_session(), RAII subscription guard, presence tracking.
  • Wire: bases/realtime/ws_route.rs (/api/realtime) merges org + user streams; 10s ping / 15s dead-timeout.
  • Client: shared/context/realtime_context.rsRealtimeContext { events, status, reconnect_count, visibility_wake }, 500-event buffer, exponential-backoff reconnect, tab-visibility wake, Capacitor foreground reconnect.
  • Canonical consumer: messaging — hooks/use_realtime_messages.rs (last-seen cursor, reset-on-reconnect, idempotent merge by id) + services/publish_message_service.rs.

Coverage map — who's live today

ModuleRealtime?Evidence
messagingFULLuse_realtime_messages, EVT_MESSAGE_NEW/STATUS
callFULLuse_realtime_calls, EVT_CALL_* + presence
notificationFULLuse_unread_notification_count, EVT_NOTIFICATION_NEW
assistant (bulk ops)FULLuse_realtime_operation, EVT_OPERATION_PROGRESS
planPARTIALdetail merges logs/state; list polls
ai_agentPARTIALthread live (EVT_THREAD_UPDATED); listing not
contactPARTIALonly bulk-enrich progress; list/detail poll
twilio / settings syncPARTIALsync-progress only
taskNONEuse_resource + manual refetch
insights · sales/products · billing · settings (entity)NONEno events defined

The reusable pattern to standardize

A generic use_realtime_entities<T>(event_types, filter_fn) hook in shared/hooks/ (encapsulates the last-seen cursor + reset-on-reconnect + idempotent merge that messaging hand-rolls), paired with a per-module publish_<entity>_event_service.rs called from every create/update/delete API.

PER MODULE → realtime in 6 steps 1. types/<entity>_event_type.rs EVT_X_CREATED / _UPDATED / _DELETED 2. services/publish_<entity>_event_service.rs publish_org(org_id, AppEvent{..}) 3. call publish_* in create / update / delete APIs (3 sites) 4. hooks/use_realtime_<entity>.rs = use_realtime_entities(EVTS, filter) 5. list view: merge by id · detail view: replace current 6. reset-on-reconnect handled by the shared hook (reconnect_count dep)

Lands as

A new realtime rule (paths: src/mods/**) stating "all server data is realtime — here's the canonical pattern + the shared hook," and added steps in the add-api / add-view / add-module scaffolding skills so new code is born realtime.

05Inline feedback over toasts

Stop using toasts the way we do. Action confirmations should be inline; toasts only when genuinely necessary; the toast itself redesigned to Aurora glass.

318
total toast call sites
~90%
are error feedback (rule-mandated)
~28
success confirmations → make inline
3–5
async/background → keep as toast

Today: shared/context/toaster_context.rs + shared/components/toast_container_component.rs — 3 variants, bottom-right, 5s auto-dismiss for all. The ~28 success toasts are redundant: the UI change (form closes, row removed, modal dismissed) already confirms the action.

Today

  • "Contact updated" toast fires after the sheet already closed.
  • "Phone added" toast fires as the row already appears.
  • ui-permissions.md mandates mutation_error for every mutation.
  • One 5s timer, bottom-right, for success and error alike.

Proposed

  • Inline confirmations: expand SaveStatusButton (Saving→Saved✓) for forms; a row/field "saved ✓" fade for inline edits; modal-header status chips for bulk ops.
  • Toast only for: background/async jobs ("Enrichment started") and errors away from the triggering view.
  • Redesigned toast: Aurora .ds-glass-panel, top-right, max ~2 stacked, error 8s / info 5s / success 3s, explicit close.
  • Validation shows inline at the field, never a toast.
!

Rule conflict to resolve

.claude/rules/ui-permissions.md currently mandates toaster.mutation_error() for all failures. The revision: keep it for network/500/403/unexpected failures; switch confirmations to inline; route validation to field-level errors. This rule edit must ship with the pattern, or the two will contradict.

Existing inline primitives to build on: SaveStatus enum + SaveStatusButton + run_save() helper, ConfirmDialog, optimistic list removal. Gaps: row/field success indicators, modal-local operation state.

06Command palette (⌘K)

A single ⌘K entry that unifies navigation, cross-entity search, quick actions, and "ask the assistant" — high value for non-technical owners who can't hunt menus, and the natural front door to an agent-first app.

┌─────────────────────────────────────────────────┐ │ ⌘K Search or jump to… [Esc] │ ├─────────────────────────────────────────────────┤ │ NAVIGATE Dashboard · Contacts · Calls · │ │ Messaging · Tasks · AI Agents · … │ │ CREATE Contact · Task · Agent · Offer · … │ │ DO Send SMS · Click-to-Call │ │ SEARCH Find contact / call / agent by name │ │ ASK 💡 Ask the assistant: "…" │ └─────────────────────────────────────────────────┘ permission-gated · grouped · keyboard-driven
GroupContentsWires to
Navigate~20 top-level routes, permission-gated, mirroring the sidebarroutes.rs Route enum · sidebar.rs · use_navigator()
CreateContact, Task, Agent, Text Agent, Analyzer, Offer, Product, Widgetcreate routes + permission checks
DoSend SMS, Click-to-Call (hidden if no number provisioned)quick_actions_component.rs · dial pad
SearchCross-entity lookup → navigate w/ ?search= prefilledcontact_filter_query_type.rs · SearchableSelect
AskHand the raw query to the assistant, open sidebar, focus inputAssistantContext::prefill_input() · assistant_provider_component.rs

Mount point: global ⌘K/Ctrl K listener in shared/layouts/app_layout.rs (sibling to ToastContainer), guarded so it doesn't fire while typing in an input. Mobile: secondary entry via the avatar pill or assistant orb (no hardware ⌘). Built as a new command_ui.rs primitive (the cmdk pattern: filtered list + keyboard nav + groups) wrapped by a CommandPalette shared component that owns the app-specific items.

07Component audit vs shadcn

We have a strong 45-primitive foundation (Dioxus-native, mobile-first, Aurora-integrated). These are the real gaps and the thin spots — ordered by value to an agent-first CRM.

Missing — port these new primitives

ComponentPriorityWhy Loquent needs it / likely use site
Command (cmdk)HighThe ⌘K palette (§6). No discoverable action entry today.
Dialog / ModalHighWe only have ConfirmDialog (destructive). No general modal for forms/wizards/content (e.g. shadow-replay preview, memory-block editor).
DropdownMenuHighRow/card action menus (edit · delete · archive · promote-lesson). Today: custom button groups only.
Popover (generic)MedOnly a desktop FilterPopover exists; date/picker popovers re-hand-roll floating logic. Extract one primitive.
Table / DataTableMedListRow is row-anatomy only — no header/sort/select/footer. Live calls dashboard + activity tables want this.
RadioGroupMed3–5 exclusive options (escalation answer · autonomy mode · filters) currently misuse Select.
ToggleGroupMedSegmented controls — view list/grid/board, time range 7d/30d/90d (dashboards).
Toast (redesign)MedNative Aurora-glass redesign per §5.
Alert · HoverCard · Breadcrumb · Separator · Slider · CarouselLowNice-to-have; build on demand.

Improve — thin spots in what we have

PrimitiveGap
confirm_dialog_ui.rsMake it a variant of a general Dialog, not the only modal.
scroll_area_ui.rsPure Tailwind wrapper — no Aurora scrollbar theming.
tabs_ui.rsNo TabsContent — consumers hand-roll show/hide.
select / multi_select / calendarIncomplete keyboard nav (typeahead, arrow keys, Home/End).
input + labelNo FormField wrapper (label + control + error/hint + a11y aria-describedby).
floating layers (dialog/sheet/tooltip)Scattered hardcoded z-[70]/z-[999] — needs a z-index scale.
i

Where to find it

The full 45-row HAVE inventory lives in the audit thread; it doesn't need to live in a doc — it lives in src/ui/. What belongs in the app-design skill is a complete one-line index of all 45 (today it lists 8), so agents stop reinventing EmptyState, ListRow, Avatar, Tabs, etc.

08Aurora completeness pass

The visual layer is current, but the app-design skill has drifted behind tailwind.css. Three fixes.

A · NAMING LANDMINE

One hue, three names — #f4724f

The accent is called coral in the design language (skill, ux-principles, design-system.html), honey in tailwind.css internals (.btn-honey, --shadow-honey, .honey-soft), and Persimmon in the ramp (--persimmon-*). All the same value. tailwind.css:96 literally warns "Do NOT restore honey hex." A future agent reading the CSS will think these are different colors. Fix: a 3-line callout in the skill reconciling the names — highest-value single edit.

B · Missing recipe classes & tokens (in tailwind.css, absent from the skill)

Class / tokenWhat
bg-scrimDialog/sheet/overlay backdrop — replaces ad-hoc bg-black/40
.btn-honey · .chat-bubble-outPrimary-button + outbound-bubble honey gradient (the skill says "gradient" but never names them)
.ds-orb · .assistant-trigger-ringAssistant orb sphere + trigger glow
.ds-aurora-bg · .brand-glyph · .honey-soft · .avatar-gradient-contactPage wash, wordmark, accent surface, contact-avatar gradient
shadow-honey · shadow-sheet · .skeletonAvatar/sheet elevation + loading skeleton (skill only shows Spinner)
ease-spring · ease-outNamed easings — skill hardcodes the raw cubic-bezier(…) everywhere
h-header · w-sidebar · max-w-content · pt-floating-navShell layout dims
.ds-glass-titleReferenced in the skill's mobile section but missing from its glass recipe table

C · Component index

The skill's quick-reference table covers ~8 of 45 primitives — and omits EmptyState, which its own prose references. Expand to a complete one-line index.

09The knowledge map — what to write where

This answers the original question directly: where each piece of design knowledge lives so a future coding agent has exact knowledge. NEW = create · UPD = update.

KnowledgeHomeAction
Agent-era paradigm principles (always-on).claude/rules/agent-interaction-model.mdNEW
Agent-surface catalog + component pointers (on-demand).claude/skills/agent-ux/SKILL.mdNEW
Realtime-everywhere pattern + coverage (paths: src/mods/**).claude/rules/realtime.md + shared use_realtime_entities hookNEW
Inline-feedback patterns + when-a-toast-is-warranted.claude/rules/ui-permissions.md (revise mandate) + a feedback section/ruleUPD
Aurora completeness (naming, recipes, index).claude/skills/app-design/SKILL.mdUPD
"New code is born realtime + inline-feedback"add-api · add-view · add-module skillsUPD
New primitives (Command, Dialog, DropdownMenu, Popover, Table, RadioGroup, Toast)src/ui/*.rs via add-ui-element skill → then index in app-design + render in design-system.htmlNEW
Visual source-of-truth (tokens/recipes)tailwind.css · docs/design-system.html · ux-principles.mdNo change (add new components once built)
i

Division of labor that keeps it maintainable

Rules = always-on principles (paradigm, realtime, feedback). Skills = on-demand reference + workflows (agent-ux catalog, app-design code). Token files = the single visual source of truth. No knowledge duplicated across two homes — each fact has one owner, the others link to it.

10Suggested build sequence

Docs-first where they unblock builders; primitives before the features that consume them.

  1. STEP 1Write the paradigm rule + agent-ux skilldocs · fast

    Unblocks correct UI for both features immediately. Cheap, high-leverage, no code risk.

  2. STEP 2Aurora completeness pass on app-designdocs · fast

    Naming callout + recipe section + full component index. Verify every class against tailwind.css/src/ui/.

  3. STEP 3Realtime: shared hook + rule + scaffoldinginfra

    Build use_realtime_entities, write the rule, update scaffolding skills. Then roll module-by-module (task → contact → insights → sales → settings).

  4. STEP 4Feedback: toast redesign + inline pattern + rule revisioninfra

    Redesign the toast (Aurora glass), ship the inline confirmation pattern, revise ui-permissions.md in the same change, migrate the ~28 confirmation sites.

  5. STEP 5Core primitivesbuild

    Dialog → DropdownMenu → Popover → Command palette → Table → RadioGroup. Each via add-ui-element, indexed in app-design, rendered in design-system.html.

  6. STEP 6The two features, on the now-documented foundationfeature

    Calls Enhancements (live-supervision family) and AutoEvolve (trust-and-learning family) — built against the paradigm rule, the agent-ux catalog, realtime, inline feedback, and the new primitives.

11Open questions

Decisions to lock before I write the docs/code. My recommendations are pre-selected.

Q1

Paradigm knowledge: one always-on rule, or fold into ux-principles.md?

  • Append a section to ux-principles.md — fewer files, but mixes visual and interaction concerns
Q2

Realtime rollout — how aggressive?

  • Big-bang: convert all non-realtime modules in one sweep
  • Rule only for now; convert lazily with no dedicated effort
Q3

Toast mandate — how hard a switch?

  • Remove the toast mandate entirely, leave it to per-case judgment
  • Keep the mandate, only redesign the toast visually (smallest change)
Q4

Scope of this follow-through — docs only, or docs + first primitives?

  • Everything in sequence, end to end
  • Just the artifact for now — you'll assign the build separately