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.
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.
Catalog the agent surfaces. Escalation cards, draft picker, activity feed, memory blocks, live-supervision (Calls), trust-and-learning (AutoEvolve). Many already in code — undocumented.
Realtime everywhere. The infra is proven (messaging, calls). Task/contact/insights/sales/settings still poll. → reusable use_realtime_entities + a rule + scaffolding steps.
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.
Port what's missing. Command palette (⌘K), Dialog, DropdownMenu, Popover, Table, RadioGroup, redesigned Toast — the real gaps vs shadcn.
Close the Aurora drift. The "coral = honey = persimmon" naming landmine, missing recipe classes, and a component index covering only 8 of 45 primitives.
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."
| Layer | Governs | Where it lives | Status |
|---|---|---|---|
| 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.
The principles this forces on every UI
| Principle | What it means when you build a screen |
|---|---|
| Review > data entry | Default 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-class | An 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 autonomy | Every 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-first | Audience = 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 nagging | HITL must feel like a helpful colleague. Batch where possible (escalation queue), respect terse warm copy, no exclamation marks, no alarm. |
| Live by default | Because 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
| Surface | Component / entry point | Paradigm role |
|---|---|---|
| Escalation / "agent asks" card | ai_agent/components/escalation_question_card_component.rs + escalate_to_user_tool / resolve_escalation_tool | human-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.rs | the "gold signal" — edit → learn |
| Agent activity feed | agent_activity_feed_component.rs, views/agent_activity_view.rs | outcomes-first log |
| Memory / Skills / Schedules / Capabilities panels | agent_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 presence | schemas/staff_presence.rs | live-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_onlypins (replaces the markdown blob). - Autonomy controls —
learning_apply_mode = auto | approval. - "Improve my agent now" + "Topics your agent struggled with" report.
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.rs—publish_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.rs—RealtimeContext { 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
| Module | Realtime? | Evidence |
|---|---|---|
| messaging | FULL | use_realtime_messages, EVT_MESSAGE_NEW/STATUS |
| call | FULL | use_realtime_calls, EVT_CALL_* + presence |
| notification | FULL | use_unread_notification_count, EVT_NOTIFICATION_NEW |
| assistant (bulk ops) | FULL | use_realtime_operation, EVT_OPERATION_PROGRESS |
| plan | PARTIAL | detail merges logs/state; list polls |
| ai_agent | PARTIAL | thread live (EVT_THREAD_UPDATED); listing not |
| contact | PARTIAL | only bulk-enrich progress; list/detail poll |
| twilio / settings sync | PARTIAL | sync-progress only |
| task | NONE | use_resource + manual refetch |
| insights · sales/products · billing · settings (entity) | NONE | no 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.
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.
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.mdmandatesmutation_errorfor 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.
| Group | Contents | Wires to |
|---|---|---|
| Navigate | ~20 top-level routes, permission-gated, mirroring the sidebar | routes.rs Route enum · sidebar.rs · use_navigator() |
| Create | Contact, Task, Agent, Text Agent, Analyzer, Offer, Product, Widget | create routes + permission checks |
| Do | Send SMS, Click-to-Call (hidden if no number provisioned) | quick_actions_component.rs · dial pad |
| Search | Cross-entity lookup → navigate w/ ?search= prefilled | contact_filter_query_type.rs · SearchableSelect |
| Ask | Hand the raw query to the assistant, open sidebar, focus input | AssistantContext::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
| Component | Priority | Why Loquent needs it / likely use site |
|---|---|---|
| Command (cmdk) | High | The ⌘K palette (§6). No discoverable action entry today. |
| Dialog / Modal | High | We only have ConfirmDialog (destructive). No general modal for forms/wizards/content (e.g. shadow-replay preview, memory-block editor). |
| DropdownMenu | High | Row/card action menus (edit · delete · archive · promote-lesson). Today: custom button groups only. |
| Popover (generic) | Med | Only a desktop FilterPopover exists; date/picker popovers re-hand-roll floating logic. Extract one primitive. |
| Table / DataTable | Med | ListRow is row-anatomy only — no header/sort/select/footer. Live calls dashboard + activity tables want this. |
| RadioGroup | Med | 3–5 exclusive options (escalation answer · autonomy mode · filters) currently misuse Select. |
| ToggleGroup | Med | Segmented controls — view list/grid/board, time range 7d/30d/90d (dashboards). |
| Toast (redesign) | Med | Native Aurora-glass redesign per §5. |
| Alert · HoverCard · Breadcrumb · Separator · Slider · Carousel | Low | Nice-to-have; build on demand. |
Improve — thin spots in what we have
| Primitive | Gap |
|---|---|
confirm_dialog_ui.rs | Make it a variant of a general Dialog, not the only modal. |
scroll_area_ui.rs | Pure Tailwind wrapper — no Aurora scrollbar theming. |
tabs_ui.rs | No TabsContent — consumers hand-roll show/hide. |
select / multi_select / calendar | Incomplete keyboard nav (typeahead, arrow keys, Home/End). |
input + label | No 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. |
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.
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 / token | What |
|---|---|
bg-scrim | Dialog/sheet/overlay backdrop — replaces ad-hoc bg-black/40 |
.btn-honey · .chat-bubble-out | Primary-button + outbound-bubble honey gradient (the skill says "gradient" but never names them) |
.ds-orb · .assistant-trigger-ring | Assistant orb sphere + trigger glow |
.ds-aurora-bg · .brand-glyph · .honey-soft · .avatar-gradient-contact | Page wash, wordmark, accent surface, contact-avatar gradient |
shadow-honey · shadow-sheet · .skeleton | Avatar/sheet elevation + loading skeleton (skill only shows Spinner) |
ease-spring · ease-out | Named easings — skill hardcodes the raw cubic-bezier(…) everywhere |
h-header · w-sidebar · max-w-content · pt-floating-nav | Shell layout dims |
.ds-glass-title | Referenced 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.
| Knowledge | Home | Action |
|---|---|---|
| Agent-era paradigm principles (always-on) | .claude/rules/agent-interaction-model.md | NEW |
| Agent-surface catalog + component pointers (on-demand) | .claude/skills/agent-ux/SKILL.md | NEW |
Realtime-everywhere pattern + coverage (paths: src/mods/**) | .claude/rules/realtime.md + shared use_realtime_entities hook | NEW |
| Inline-feedback patterns + when-a-toast-is-warranted | .claude/rules/ui-permissions.md (revise mandate) + a feedback section/rule | UPD |
| Aurora completeness (naming, recipes, index) | .claude/skills/app-design/SKILL.md | UPD |
| "New code is born realtime + inline-feedback" | add-api · add-view · add-module skills | UPD |
| 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.html | NEW |
| Visual source-of-truth (tokens/recipes) | tailwind.css · docs/design-system.html · ux-principles.md | No change (add new components once built) |
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.
-
STEP 1Write the paradigm rule +
agent-uxskilldocs · fastUnblocks correct UI for both features immediately. Cheap, high-leverage, no code risk.
-
STEP 2Aurora completeness pass on
app-designdocs · fastNaming callout + recipe section + full component index. Verify every class against
tailwind.css/src/ui/. -
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). -
STEP 4Feedback: toast redesign + inline pattern + rule revisioninfra
Redesign the toast (Aurora glass), ship the inline confirmation pattern, revise
ui-permissions.mdin the same change, migrate the ~28 confirmation sites. -
STEP 5Core primitivesbuild
Dialog → DropdownMenu → Popover → Command palette → Table → RadioGroup. Each via
add-ui-element, indexed inapp-design, rendered indesign-system.html. -
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-uxcatalog, realtime, inline feedback, and the new primitives.
11Open questions
Decisions to lock before I write the docs/code. My recommendations are pre-selected.
Paradigm knowledge: one always-on rule, or fold into ux-principles.md?
- A dedicated
agent-interaction-model.mdrule + theagent-uxskill — keepsux-principles.mdvisual, gives the paradigm its own clear home - Append a section to
ux-principles.md— fewer files, but mixes visual and interaction concerns
Realtime rollout — how aggressive?
- Ship the shared hook + rule now; convert task & contact first (highest traffic), then the rest opportunistically as views are touched
- Big-bang: convert all non-realtime modules in one sweep
- Rule only for now; convert lazily with no dedicated effort
Toast mandate — how hard a switch?
- Inline-first for confirmations + validation; keep
mutation_errormandatory only for network/403/unexpected errors - Remove the toast mandate entirely, leave it to per-case judgment
- Keep the mandate, only redesign the toast visually (smallest change)
Scope of this follow-through — docs only, or docs + first primitives?
- Docs first (STEP 1–2), then I bring back the Command palette + Dialog as the first primitives
- Everything in sequence, end to end
- Just the artifact for now — you'll assign the build separately