Skip to content

Claude-Design Package — frontend-core (Untool.ai)

What this is: a single, self-contained brief to paste/load into Claude design. It carries everything Claude needs to propose a visual identity + screen designs for the Untool.ai platform UI, on top of the already-chosen shadcn/ui foundation (do not re-pick a component library — that decision is made).

Your job, Claude design: propose the visual layer — color/typography/space identity, the look of key screens, and how the data-viz moments feel. Output should be expressible as shadcn design tokens (CSS variables, oklch) + Tailwind utility usage, so it drops straight into the codebase.

Compiled 2026-05-29. Companion files in this folder: ../DECISION-shadcn-vs-inhouse.md (why shadcn), ../STATUS.md (program state), ../../decisions/ARC-ADR-008-frontend-design-system.md.

1. The product (what you're designing)

Untool.ai / frontend-core — the web UI for an ArcadeDB semantic-search / RAG platform with an in-app AI copilot (CopilotKit generative UI). Tagline: "the tool that removes tools — turns a thicket of disconnected systems into one calm surface you can ask questions of."

Stack: Next.js App Router + React 19 (RSC), CopilotKit assistant sidebar, talks to backend services over typed contracts. It is an information-dense, analyst-facing product, not a consumer marketing site.

Screens to design (priority order)

  1. Search — semantic/RAG search; results render as citation cards (source, snippet, score, optional thumbnail).
  2. Cockpit — analytics dashboard: metric cards, trend charts, a graph/query console. The densest surface.
  3. Ingest — file upload + live job-progress cards (queued → processing → done/error).
  4. Sources — table of indexed sources + HITL destructive-delete confirmation dialog (role-gated).
  5. Objects — business-object ontology browser.
  6. Gallery — cross-modal image search results.
  7. Status — admin health aggregation. Assistant: a persistent CopilotKit sidebar overlays all screens.

2. Design direction (decider's stated taste)

The owner chose shadcn explicitly because it's an obvious common visual language other systems use — lean into that. Recognizable, calm, developer-grade. The earlier bespoke attempt was rejected for being visually subpar with a messy Figma; do not reinvent a quirky identity — refine a familiar, professional one.

Salvaged brand heritage (the ideas were liked; only execution was rejected — treat as inspiration, not constraint): - Edward Tufte — data-ink ratio, small multiples, sparklines, "above all else show the data." Metrics surfaces should feel like his books: quiet, typographic, high-resolution. - Dieter Rams — "as little design as possible"; unobtrusive. - Stripe — developer-grade polish; dense dashboards that stay legible. - Linear — keyboard-first, fast, dark-mode-native, opinionated minimalism. - Vercel / Geist — monochrome restraint, generous whitespace, mono for numbers.

Credo: Show the data (chrome recedes). Calm over clever (no animation that doesn't explain something). Keyboard-first. Density with dignity (dense ≠ cramped). One surface.

Won't do: gradients-as-decoration, glassmorphism, drop-shadow soup, mascots, playful illustration, rounded-everything, dark patterns / fake urgency.

3. Hard constraints (non-negotiable — design within these)

  • Output = shadcn tokens. Express the identity as the CSS-variable token set in §4 (oklch), consumed via Tailwind utilities (bg-primary, text-muted-foreground, …). No new CSS framework.
  • WCAG 2.2 AA. All text/bg pairs ≥ 4.5:1 (normal) / 3:1 (large), in both light and dark. The repo gates on axe in CI. (The current tokens already AA-tune muted-foreground & destructive.)
  • Light + dark, both first-class. Dark is driven by a [data-theme="dark"] attribute on <html> (a no-flash script sets it before paint). Provide both palettes.
  • RSC-native, low-runtime. Prefer CSS/tokens over JS. The app enforces a bundle budget (size-limit) + Lighthouse Core Web Vitals — keep it light. No heavy chart libs for sparklines.
  • Density. This is an analyst tool; default to compact, tabular, high-information layouts.

4. Current token set (your starting point — propose changes to THESE)

app/tailwind.css — shadcn "neutral" base, oklch. This is intentionally generic/stock; your identity pass should evolve these values (especially --primary, accent, and the data tones) while keeping the variable names and AA compliance.

:root {
  --radius: 0.625rem;
  --background: oklch(1 0 0);            --foreground: oklch(0.145 0 0);
  --card: oklch(1 0 0);                  --card-foreground: oklch(0.145 0 0);
  --popover: oklch(1 0 0);              --popover-foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);          --primary-foreground: oklch(0.985 0 0);
  --secondary: oklch(0.97 0 0);         --secondary-foreground: oklch(0.205 0 0);
  --muted: oklch(0.97 0 0);             --muted-foreground: oklch(0.44 0 0);  /* AA-tuned */
  --accent: oklch(0.97 0 0);            --accent-foreground: oklch(0.205 0 0);
  --destructive: oklch(0.577 0.245 27.325); --destructive-foreground: oklch(0.985 0 0);
  --border: oklch(0.922 0 0);           --input: oklch(0.922 0 0);  --ring: oklch(0.708 0 0);
}
[data-theme="dark"] {
  --background: oklch(0.145 0 0);        --foreground: oklch(0.985 0 0);
  --card: oklch(0.205 0 0);             --card-foreground: oklch(0.985 0 0);
  --primary: oklch(0.985 0 0);          --primary-foreground: oklch(0.205 0 0);
  --secondary: oklch(0.269 0 0);        --muted: oklch(0.269 0 0);  --muted-foreground: oklch(0.708 0 0);
  --destructive: oklch(0.52 0.2 25);    /* AA-tuned */
  --border: oklch(1 0 0 / 12%);         --input: oklch(1 0 0 / 15%); --ring: oklch(0.556 0 0);
}

Gaps to fill in your proposal: a real brand --primary (currently neutral black/white), plus data-visualization tones — --success, --warning, and chart series colors (--chart-1..n) — all AA-verified in both themes. Mono font for numbers (per the Tufte/Geist heritage) is encouraged.

5. Components in scope

Already vendored (shadcn — style them via tokens, don't redesign the API): Button (default/secondary/outline/ghost/destructive/link), Badge, Card, Dialog, Input, Table. Live gallery at route /design-system.

Data-viz primitives to design the look of (functional versions exist on a holding branch; they need your visual treatment — this is the differentiated Tufte layer): - Sparkline — inline word-scale line chart, no axes. - Numeric — tabular-figures metric display (eyebrow label + value + toned delta). - SmallMultiples — grid of identically-scaled sparklines for "compared to what?". - Annotation — quiet data-ink caption/footnote.

Assistant: the CopilotKit sidebar — design how it coexists with the dense content (docked rail, overlay, etc.).

6. What to hand back

  1. Token proposal — the §4 variables with your values (light + dark, AA-checked), plus the new brand/data tones.
  2. Type & space scale — font choices (incl. mono for numerics), sizes, spacing rhythm.
  3. Key screen mockups — at minimum Cockpit (dense dashboard) and Search (citation cards), in light + dark. Bonus: the HITL delete dialog, ingest progress card.
  4. Data-viz treatment — how Sparkline / Numeric / SmallMultiples / Annotation look and sit in Cockpit.
  5. A short rationale — tie choices back to the heritage (Tufte/Rams/Linear/Geist) and the "calm, common visual language" goal.

Anything expressible as shadcn tokens + Tailwind drops straight into the codebase.