Skip to content

DESIGN.md

Latest commit

 

History

History
91 lines (83 loc) · 6.89 KB

DESIGN.md

File metadata and controls

91 lines (83 loc) · 6.89 KB
Raw

Design System: Ask Your Data

1. Visual Theme & Atmosphere

A calm, precise analyst's workbench. The interface feels like a well-kept ledger, not a chatbot: quiet zinc neutrals, one deep teal accent, numbers set in monospace, and lots of air around the single thing that matters on screen — the question and its answer. Density "Daily App Balanced" (5/10), variance "Offset Asymmetric" (5/10), motion "Fluid but restrained" (4/10). The signature moment is the clarification step: when a question is ambiguous, the interface pauses and lays out the possible meanings as clean, comparable choices before any query runs. It should feel careful and trustworthy — a colleague who asks "which do you mean?" instead of guessing.

2. Color Palette & Roles

  • Paper Canvas (#FAFAF9) — Page background
  • Pure Surface (#FFFFFF) — Answer panel, option tiles, input fill
  • Charcoal Ink (#18181B) — Primary text, headings, numbers
  • Muted Steel (#71717A) — Secondary text, definitions, assumptions, metadata
  • Whisper Border (#E4E4E7) — 1px structural lines, table row dividers, tile borders
  • Deep Ledger Teal (#0F766E) — The only accent: primary button, selected option, focus ring, active toggle
  • Teal Wash (#F0FDFA) — Background of the selected option tile and the clarification panel header strip
  • Caution Sand (#FEF3C7 fill, #92400E text) — "Guessed, not asked" warning chip in direct mode only
  • Error Clay (#FEF2F2 fill, #B91C1C text) — Inline error and "can't answer" messages
  • Code Slate (#27272A fill, #E4E4E7 text) — SQL block inside "View technical details"

No purple, no blue-violet gradients, no neon. Never pure black.

3. Typography Rules

  • Display / Headings: Geist, weight 600, tracking -0.02em. Page title clamp(1.75rem, 3vw, 2.25rem). Hierarchy by weight and color, not size jumps.
  • Body: Geist, weight 400, 1rem, line-height 1.6, max 65ch, Muted Steel for supporting copy.
  • Mono: Geist Mono — every number in the results table, customer and order IDs, dates, the SQL block, and the period chip ("2026-09-01 → 2026-09-30"). Numbers right-aligned with tabular figures.
  • Banned: Inter, any serif, all-caps body text. Small-caps labels allowed only for section eyebrows ("HOW I READ YOUR QUESTION") at 0.75rem, tracking 0.08em, Muted Steel.

4. Component Stylings

  • Question bar: One wide input (56px tall, radius 14px, Whisper Border, white fill) with the primary "Ask" button attached on the right. Focus: 2px Deep Ledger Teal ring. Label "Your question" above it. Below: a single row of 4–5 example questions as quiet text pills (Whisper Border, 32px tall, wrap on mobile).
  • Clarify toggle: A labeled switch under the bar — "Ask me when a question is ambiguous" — with helper text "Turn off to see what a guess-first system answers." Teal when on.
  • Clarification panel (hero component): Full-width surface with a Teal Wash header strip that reads "Before I answer — this question can mean more than one thing." Each ambiguous term gets its own group: the question in Charcoal Ink ("What does 'best customer' mean here?") and 2–3 option tiles side by side. Each tile: radio-style, radius 16px, label in weight 600 and a one-line plain-English definition in Muted Steel. Selected tile: 2px teal border, Teal Wash fill, small check mark top-right. The "Answer with this meaning" button stays disabled until every group has a selection. Nothing about SQL appears here.
  • Answer panel: White surface, radius 20px, a diffused zinc-tinted shadow (0 1px 2px, 0 8px 24px at 4%). Top: a one-sentence plain answer in large type ("C-MANY placed the most orders last month — 14."). Middle: the result table — no zebra stripes, 1px Whisper Border row dividers, monospace right-aligned numbers, column names in sentence case. Below: "How I read your question" — a short list of assumptions; choices the user made carry a teal "your choice" tag, company defaults carry a grey "default" tag. Bottom: a collapsed "View technical details" disclosure revealing the SQL in a Code Slate block with a copy button, plus "Generated by: offline planner".
  • Direct-mode answer: Same answer panel plus a Caution Sand chip at the top: "Guessed: 'best customer' read as highest spend." This makes the cost of guessing visible.
  • Buttons: Primary = teal fill, white text, radius 12px, 44px min height, translateY(1px) on press, no glow. Secondary = ghost with Whisper Border. One primary per view.
  • Loading: Skeleton shimmer shaped like the answer panel (title line, 4 table rows). No spinners.
  • Empty state: Before the first question — a left-aligned short explainer ("Ask about customers, orders, products and payments. If a question can mean more than one thing, you'll choose before any query runs.") next to a small static diagram of the flow: Question → Clarify → Answer.
  • Can't answer / error: Inline Error Clay box under the bar with what happened and one next step.

5. Layout Principles

  • Single main column, max-width 880px, left-aligned within a 1200px page container; a narrow right rail (280px) on desktop ≥1200px holds "Questions you can try" and a tiny "What I know about" list (customers, orders, order items, products, payments). Rail drops below the main column under 1200px.
  • Top bar: "Ask Your Data" wordmark left, links to the GitHub repo and the evaluation results on the right.
  • Vertical rhythm: 24px between related blocks, 48px between question area and answer.
  • Below 768px: everything one column, option tiles stack vertically, table scrolls inside its own panel (never the page), touch targets 44px minimum, no horizontal page scroll.
  • Full-height layouts use min-height 100dvh.

6. Motion & Interaction

  • Spring easing (stiffness 100, damping 20) for the clarification panel and answer panel entering: fade + 8px rise. Option tiles cascade in with a 40ms stagger.
  • Selecting a tile: border and fill cross-fade 150ms, check mark scales from 0.8 to 1.
  • Table rows reveal with a 30ms stagger, opacity only.
  • Only transform and opacity animate. No looping animations on idle data; the only perpetual motion is the skeleton shimmer while loading.

7. Anti-Patterns (Banned)

  • No chat-bubble UI, no avatars, no "AI is typing" dots — this is a query tool, not a chatbot.
  • No emojis. No Inter. No serif fonts. No pure black. No purple or neon. No glow shadows. No gradient text.
  • No 3-equal-card feature rows. No centered marketing hero.
  • No raw technical terms in the main view ("lift", "RFM 422", "churn_probability") — plain language first, technical details behind the disclosure.
  • No fake data like "John Doe", "Acme", "99.9%". Use the demo values: C-WHALE spent R$ 18,295.00, C-MANY placed 14 orders, C-FREQ ordered on 10 different days (September 2026).
  • No AI clichés in copy ("Unleash", "Seamless", "Elevate", "Next-gen", "Magic").
  • No "Scroll to explore", bouncing arrows, or custom cursors.