Skip to content

.impeccable.md

Latest commit

 

History

History
71 lines (42 loc) · 8.37 KB

.impeccable.md

File metadata and controls

71 lines (42 loc) · 8.37 KB

DashClaw — Design Context

This file is the durable design context for DashClaw. Future Claude/AI sessions should read it before touching any UI, copy, marketing surface, or visual asset. It describes the people, the brand, the tone, and the non-negotiables so that every design decision can be made without re-interviewing the team.

Design Context

Users

DashClaw has two overlapping audiences who see the same surfaces but read them differently:

  • Primary: AI-agent developers and platform engineers. They're integrating DashClaw into Claude Code, Claude Managed Agents, LangChain, CrewAI, OpenAI Agents SDK, custom runtimes, or MCP hosts. They live in terminals, read code more naturally than prose, and judge a product in the first 60 seconds by the quality of its README, SDK ergonomics, and error messages. Their job-to-be-done: "Let my agent act in production without it doing something expensive, irreversible, or embarrassing."
  • Secondary: governance / compliance / security stakeholders. They rarely write code but need to audit agent behavior, approve risky actions, and produce evidence. Their job-to-be-done: "Show me, verifiably, what the agents did, why it was allowed, and who approved anything sensitive."

The context of use is almost always professional, focused, and consequential. Operators open Mission Control because an agent is running in prod. Developers open /connect because they're wiring up a live integration. No one is idly browsing. Every pixel should respect that — no decorative filler, no tutorials-for-their-own-sake, no "welcome to your new dashboard" fluff.

Brand Personality

Three words: Serious · Precise · Trustworthy.

DashClaw is a governance runtime. It sits on the critical path between an AI agent's intent and the real world. The visual and verbal tone must match the weight of that position:

  • Voice: direct, technical, declarative. Short sentences. Verbs like intercept, enforce, record, verify. No hype, no exclamation marks, no "unleash your agents."
  • Tone shift: slightly warmer on marketing pages (landing, /connect, docs intros), strictly neutral on operational surfaces (Mission Control, Approvals, Decisions, Policies).
  • Emotional target for operational surfaces: quiet confidence — "things are under control." When an operator opens Mission Control, the room should feel like a calm instrument panel, not an alarm board. Status should be obvious at a glance. Brand orange appears only when attention is actually required, not as decoration.
  • Emotional target for marketing surfaces: confident competence. We are the adults in the AI-safety room.

Aesthetic Direction

Theme: dark-mode only. Pitch-black canvas (--color-bg-primary: #0a0a0a), layered surfaces in near-black (#111, #1a1a1a, #222), with all interaction chrome built from translucent whites. No light-mode variants exist and none should be added without explicit product-level approval.

Brand color: #f97316 (Tailwind orange-500). Used as a signal, not a fill. Valid uses: the active brand mark, a focused state, a primary CTA, a "this decision needs you" cue, a live-stream pulse. Invalid uses: decorative backgrounds, gradients for their own sake, hero-washes, marketing glow-spam. Accompanying subtle variant rgba(249, 115, 22, 0.12) is reserved for hover surfaces and brand-ring glows.

Typography: Inter via next/font/google, exposed as var(--font-inter). Mono stack is ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace. Tabular numerals (.tabular-nums) on any data column. Tiny uppercase mono labels with wide tracking are a recurring motif for meta-labels ("DECISION INTERCEPTION DEMO") — keep this pattern.

Component language already established in app/globals.css and tailwind.config.js:

  • Cards: var(--color-bg-secondary) background, 1px var(--color-border) stroke, 12px radius, border-color lift on hover. This is the atom.
  • Semantic color tiers are already formalized — always use tokens, never hardcode hex. text-primary / secondary / tertiary / disabled, bg-primary / secondary / tertiary / elevated, border / border-hover / border-active, status-success / warning / error / info (plus -subtle variants).
  • Iconography: lucide-react only. Size 14–20px for inline, 24–28px for hero moments. Never mix icon libraries.
  • Elevation via border-color shifts and subtle shadow rings (shadow-[0_0_0_1px_rgba(255,255,255,0.05),0_30px_90px_rgba(0,0,0,0.55)] for hero cards). No chunky drop-shadows.

Reference direction (what we're aiming at): the restrained developer-brand register of Vercel, Linear, Resend, Supabase, Datadog, Grafana. Dense-but-readable, technical, calm, branded sparingly.

Anti-references (what we are explicitly NOT):

  • ❌ Generic SaaS dashboard — flat blue accents, Bootstrap-era cards, stock-photo marketing, "empower your team" copy. Undifferentiated and forgettable.
  • ❌ Consumer AI / playful LLM wrappers — gradients, emoji, chat bubbles, pastel, "AI sparkle" aesthetic. Undermines the governance posture.
  • ❌ Heavy enterprise compliance UI — dense gray-on-gray tables, mid-2000s corporate energy, no personality. Scares off the developer audience we need first.
  • ❌ Crypto / web3 dark theme — neon gradients, glassmorphism overload, glow spam. Signals hype over substance and is the most tempting failure mode given our dark + orange palette.

If a new design could be mistaken for any of the four above, it's wrong. The tell: if you removed the DashClaw logo, would someone still recognize this as a governance runtime, not a generic AI product? If not, push it further toward serious · precise · trustworthy.

Design Principles

These are the tiebreakers when a decision is unclear. Apply them in order.

  1. Evidence over decoration. Every element on operational surfaces must earn its pixels by communicating state, causality, or enabling action. Decorative flourishes belong on marketing pages only, and even there they should be restrained. If a visual element doesn't help the operator prove what happened or decide what to do next, cut it.

  2. Signal, not noise, with brand orange. #f97316 is reserved for things that mean something — active state, required attention, primary action, brand identity. The moment brand orange becomes ambient wallpaper, it stops signaling and the product loses a primary affordance. Default color for data is white/zinc; orange enters only when the UI has something to say.

  3. Calm under pressure. Operational surfaces should evoke quiet confidence, not vigilant alertness. An agent fleet running in prod is already stressful; the UI's job is to absorb complexity, not amplify it. Prefer typographic hierarchy, whitespace, and semantic color over motion, pulses, and alarm patterns. Reserve motion for truly live events (incoming decisions, approval arrivals).

  4. Token-first, never hardcoded. All color, spacing, and typography decisions flow through the CSS custom properties in app/globals.css and the Tailwind theme extension. If a needed token doesn't exist, add it to the token layer before using it in a component. Ad-hoc hex values in JSX are a regression and should be refactored on sight.

  5. Developer-reader before end-user-reader. The primary audience reads code, not marketing. Copy should be declarative and technical. Component affordances should favor keyboard users and density over cursor-friendly padding. When in doubt, imagine a senior platform engineer reading it at 1am while an incident is in progress — would it help them or annoy them?

  6. Accessibility: WCAG 2.1 AA is the floor, not the ceiling. 4.5:1 contrast on primary text, 3:1 on large text and meaningful UI components, full keyboard navigability, visible focus rings (use brand orange or border-active), prefers-reduced-motion honored on every animation, semantic HTML and ARIA labels on every data widget. Our current tertiary text (#71717a on #0a0a0a) is borderline — audit before reusing on critical information. Never lean on color alone to convey status; always pair with icon or text.

  7. Four anti-references are the guardrail. Before shipping any new surface, hold it against generic SaaS, consumer-AI, heavy-enterprise, and crypto/web3. If it drifts toward any of them, it's wrong. This check is cheap and catches 90% of drift.

Last updated: 2026-04-10 — initial capture via /teach-impeccable.