Generated by /plan-design-review on 2026-03-23 Branch: main Repo: epsilla-enterprise/clawtrace

ClawTrace is a standalone product surface in this repository that uses the Atelier language and extends it for workflow reliability operations.

The product should feel like:

• an Atelier Operator workspace at rest
• an editorial operations room under investigation
• a careful control surface when risk appears

It should not feel like:

• a generic AI dashboard
• a chat app with some trace widgets attached
• a dense SOC terminal by default
• a premium executive dashboard that hides operational truth behind polish

ClawTrace should align with these in-repo sources whenever possible:

• packages/clawtrace-ui/src/lib/clawtrace.tokens.css
• packages/clawtrace-ui/src/components/clawtrace/ClawTraceStandalone.tsx
• packages/clawtrace-ui/src/components/clawtrace/ClawTraceStandalone.module.css
• packages/clawtrace-ui/src/components/clawtrace/portfolio/WorkflowPortfolio.tsx
• packages/clawtrace-ui/src/components/clawtrace/onboarding/OnboardingGuidedConversation.tsx
• docs/design-specs/clawtrace.tokens.css
• docs/design-specs/clawtrace.interfaces.ts

1. ClawTrace is a workflow reliability control room, not a metrics dashboard.
2. Evidence is the center of gravity. Metrics support the story, not the other way around.
3. Chat is a partner surface, not the home screen.
4. Calm earns trust better than alarmism.
5. The workspace should feel operationally legible in 5 seconds.
6. The product should remain visually coherent as we expand ClawTrace surfaces over time.

Start from Atelier Operator.

Reuse from Operator:

• page background logic
• panel layering and contrast rhythm
• left rail behavior and expanded/collapsed patterns
• border, radius, and shadow language
• button, tab, badge, and drawer interaction patterns
• restrained use of blue as an action accent
• clean sans-serif typography and spacing cadence

Add ClawTrace-specific semantics on top of Operator:

• workflow trust states
• evidence callouts
• verification breakdowns
• state-diff surfaces
• control-point timelines
• incident memos
• primary-next-action modules

Do not create a separate ClawTrace-only theme family in Phase 0.

ClawTrace uses a workspace shell, not a single full-screen one-off page.

The shell has 4 functional zones:

1. Global app rail
2. Workflow portfolio column
3. Selected workflow cockpit
4. Collapsible right-side investigation drawer

The portfolio can show all discovered workflows, but only one workflow gets the full command-center treatment at a time.

Order of importance:

1. Selected workflow trust state and primary next action
2. Run story, verification breakdown, and recent incidents
3. Portfolio health across other workflows
4. Investigation chat and artifact generation

The portfolio is for triage, not deep inspection.

Each workflow card should show only:

• workflow name
• current trust state
• latest run outcome
• one-line issue summary or calm status summary
• most recent relevant timestamp
• one affordance to open the full cockpit

Do not give every workflow equal cockpit depth on the overview screen.

The selected workflow cockpit is the product heart.

It should always expose:

• workflow identity and contract version
• trust state
• primary recommended action
• latest run state
• verification breakdown
• control-point timeline / run story
• state change / drift markers
• incident memo entry point

The cockpit is where users act. It should not look like a pile of interchangeable analytics cards.

Chat is first-class during onboarding.

The onboarding chat should feel like a guided systems audit:

• connect to OpenClaw
• inspect existing execution history
• discover configured workflows
• explain what ClawTrace inferred
• warm up a first reliability map
• ask for confirmation only where control or trust truly matters

This is not a generic assistant asking open-ended questions. It is an evidence-led setup flow.

After setup, chat becomes a collapsible right-side investigation drawer.

The drawer is for:

• asking questions about the selected workflow
• generating incident artifacts
• explaining evidence already collected
• helping author or revise workflow contracts
• navigating to the right artifact or run quickly

It is not the home screen. It should stay out of the way when the workflow is healthy.

ClawTrace is calm by default.

Healthy days should feel:

• quiet
• controlled
• legible
• lightly editorial

Unhealthy days should feel:

• more focused
• more contrast-rich
• more directive
• never frantic

States like Awaiting Confirmation, Partially Verified, Replay Pending, and Revalidating must be presented as calm operational states with:

• one strong next action
• an explicit known vs unknown breakdown
• one short primary explanation
• visible evidence, not vague reassurance

Do not treat uncertainty like a generic red error banner.

The visual direction is editorial operations room built on top of Atelier Operator.

Desired traits:

• strong type hierarchy
• annotated evidence feel
• a briefing-desk rhythm rather than dashboard-card soup
• restrained but intentional status color
• fewer, larger surfaces with clear jobs
• obvious reading order

Avoid:

• neon control-center tropes
• graph wallpaper and gratuitous gradients
• overuse of mini-cards
• “AI assistant bubble” visual dominance
• excessive icon noise

Use the existing ClawTrace / Atelier sans-serif foundation as the base.

Typography rules:

• headings are compact, high-contrast, and structurally important
• trust states and decisions use short, direct language
• supporting evidence uses smaller, quieter text
• memos should read like an annotated incident brief, not like chat transcript prose

Recommended hierarchy:

• Display / page title: used sparingly at workspace level
• Section title: cockpit zones and portfolio groups
• Operational label: state bands, verifier labels, timeline markers
• Evidence note: secondary text, timestamps, provenance

Do not introduce a serif display system for ClawTrace in Phase 0. That would pull it away from the ClawTrace design family.

Reuse Operator's neutral and blue structure, then add a narrow ClawTrace evidence palette.

• Backgrounds and panels come from Operator tokens.
• Blue remains the primary action and focus color.
• Neutral surfaces remain the default resting state.

Recommended semantic token families:

• trust.healthy
• trust.at_risk
• trust.drifting
• trust.blocked
• trust.awaiting_confirmation
• trust.partially_verified
• trust.control_plane_issue
• verify.success
• verify.fail
• verify.unknown
• evidence.callout
• decision.allow
• decision.defer
• decision.block

Status color rules:

• healthy: green family already close to Operator event
• at-risk / awaiting confirmation / partially verified: warm amber family
• drifting: cool accent family distinct from healthy and blocked
• blocked: explicit danger/red family
• control-plane incident: darker neutral-danger treatment so workflow problems and ClawTrace problems are distinguishable

Do not let color carry meaning alone. Every state needs text + icon + label.

The following Atelier patterns should be reused or adapted first:

• AtelierAppRail
• shell panel rhythm from AtelierChatsApp and AtelierWorkspacesApp
• sidebar list behavior from AtelierChatSidebar
• right-side detail panel behavior from AtelierCustomerPanel
• composer / drawer interaction patterns from AtelierChatComposer

These should be designed as first-class ClawTrace extensions to the Atelier system:

• ClawTraceWorkflowPortfolio
• ClawTraceWorkflowCard
• ClawTraceWorkflowCockpit
• ClawTraceTrustStateBand
• ClawTracePrimaryActionCard
• ClawTraceRunStoryTimeline
• ClawTraceVerificationBreakdown
• ClawTraceStateDiffPanel
• ClawTraceIncidentMemoPanel
• ClawTraceEvidenceCallout
• ClawTraceWarmupAuditChat
• ClawTraceInvestigationDrawer
• ClawTraceControlDecisionAudit
• ClawTraceWorkflowFilterBar

Component rule: Prefer extending the Atelier system with domain-specific components over forcing irrelevant reuse.

Recommended structure:

• left rail: app/global navigation
• left workspace column: workflow portfolio and filters
• center: selected workflow cockpit with primary action and run story
• right drawer: collapsible investigation chat / artifacts

The center column must visually dominate.

• rail can collapse sooner
• portfolio may narrow but remains available
• drawer becomes an overlay rather than fixed third column

Mobile is triage-first.

Show in order:

1. workflow portfolio
2. selected workflow summary
3. primary next action
4. trust state and latest issue summary
5. drill-down routes for run story, evidence, memo, and drawer chat

Do not just stack the desktop columns vertically.

Motion should be purposeful and restrained.

Use motion for:

• drawer open/close
• workflow selection focus shift
• trust-state change emphasis
• onboarding warm-up progression

Do not use decorative ambient motion.

Recommended motion tone:

• short, crisp transitions
• subtle easing
• no “AI magic” flourishes

Minimum rules:

• keyboard reachability across rail, portfolio, cockpit actions, and drawer
• visible focus states using the shared focus token family
• state labels announced in plain language
• color is never the only signal
• tap targets remain comfortable on tablet/mobile
• primary next action is always discoverable without hover
• uncertainty states clearly say what is known, unknown, and what action is available

This should happen inside the onboarding chat.

The product should say, in effect:

• we are reading your existing workflow history
• we are identifying the workflows you already run
• we are building an initial reliability map
• we will ask for confirmation where it matters

If nothing needs attention, the workspace should not feel blank. It should show:

• a calm portfolio
• the selected workflow summary
• one “worth your attention” note or reassurance

Every meaningful state should answer:

• what happened
• what is known
• what is unknown
• what action is recommended

The product voice should be:

• direct
• operational
• low-drama
• evidence-based

Prefer:

• “Awaiting confirmation before deploy.”
• “Image generation did not verify successfully.”
• “State changed during run. Revalidation required at next control point.”

Avoid:

• “Something went wrong.”
• “The AI seems confused.”
• “We noticed an issue and are looking into it.”

• equal-depth cockpit treatment for every workflow in the overview
• chat as the default daily home
• a separate ClawTrace-only visual theme family
• dense terminal-style UI as the default experience
• alarm-heavy SOC presentation for every uncertain state
• direct desktop-to-mobile stacking as the primary responsive strategy

• Detailed build-ready token and component guidance now lives in docs/design-specs/CLAWTRACE_ATELIER_COMPONENT_SPEC.md.
• Use DESIGN.md for the product-level design thesis and this companion spec for implementation-level UI contracts.

When ClawTrace is implemented and expanded in this repo:

• preserve Atelier Operator shell compatibility first
• add ClawTrace components as a narrow extension layer
• keep the selected workflow cockpit visually central
• keep onboarding chat evidence-led
• keep the investigation drawer collapsible and secondary
• validate mobile as triage-first, not desktop-shrunk