Skip to content

DESIGN.md

Latest commit

 

History

History
112 lines (102 loc) · 7.08 KB

DESIGN.md

File metadata and controls

112 lines (102 loc) · 7.08 KB

Design System - ExpensesBot

Product Context

  • What this is: Personal expense tracking app with AI-powered entry (text + receipt OCR), budgets, recurring expenses, analytics, and exports
  • Who it's for: Personal finance users who want simplicity - people who track spending but don't want a banking app
  • Space/industry: Personal finance, expense tracking. Peers: Monefy, Monarch Money, Expensify, Cashew
  • Project type: Mobile app (iOS + Android via React Native/Expo) - migrating from Telegram bot
  • AI backend: Groq (moonshotai/kimi-k2-instruct) for natural language queries, categorization, and receipt parsing

Aesthetic Direction

  • Direction: Brutally Minimal - type and whitespace do all the work. Feels like a Braun calculator: precise, calm, beautiful.
  • Decoration level: Minimal - no gradients, no illustrations, no patterns. Emoji category icons provide all the color and personality.
  • Mood: Calm, focused, trustworthy. The app disappears so your data can speak. Light enough to feel fast, structured enough to feel reliable.
  • Reference sites: Ramotion expense tracker concept, Monarch Money (warm editorial), Expensify (corporate baseline). ExpensesBot breaks from all three by going near-monochrome.

Typography

  • Display/Hero: Satoshi (Variable, 700-900) - geometric with personality, gives the app a "designed object" quality without being playful. Not overused in fintech.
  • Body: DM Sans (400, 500, 600, 700) - excellent readability, clean geometric forms, native tabular figures support.
  • UI/Labels: DM Sans 500-600 - same as body for consistency.
  • Data/Tables: DM Sans 700 (font-variant-numeric: tabular-nums) - perfect alignment for monetary values, columns of numbers stay vertically aligned.
  • Code/Mono: JetBrains Mono 400-500 - for API keys, technical display, section labels.
  • Loading: Satoshi via Fontshare CDN (api.fontshare.com), DM Sans + JetBrains Mono via Google Fonts.
  • Scale:
    • xs: 11px / 0.6875rem - timestamps, tertiary labels
    • sm: 13px / 0.8125rem - secondary text, metadata
    • base: 14px / 0.875rem - body text, list items (mobile)
    • md: 16px / 1rem - body text (emphasis), input text
    • lg: 18px / 1.125rem - large input, amount entry
    • xl: 24px / 1.5rem - section titles
    • 2xl: 28px / 1.75rem - page headings
    • 3xl: 32px / 2rem - large data display (amounts)
    • 4xl: 36px / 2.25rem - hero amounts
    • 5xl: 48px / 3rem - display / hero text

Color

  • Approach: Restrained - near-monochrome with a single teal accent. Color is rare and meaningful. Emoji icons carry category identity.
  • Primary/Accent: #0D9488 (teal) - says "clarity" and "fresh," not "bank." Used for active states, CTAs, progress bars, links.
  • Accent hover: #0F766E (darker teal)
  • Accent light: #CCFBF1 (pale teal) - chip backgrounds, subtle highlights, ghost button hover
  • Accent text: #FFFFFF on accent backgrounds
  • Neutrals (light mode):
    • Background: #FFFFFF
    • Surface: #F8FAFB (barely-there cool gray - cards, inputs, sections)
    • Surface hover: #F1F3F5
    • Border: #E5E7EB
    • Text primary: #111827 (ink black)
    • Text secondary: #6B7280 (cool gray)
    • Text tertiary: #9CA3AF (muted)
  • Semantic:
    • Success: #059669 / light: #D1FAE5
    • Warning: #D97706 / light: #FEF3C7
    • Error: #DC2626 / light: #FEE2E2
    • Info: #0284C7 / light: #E0F2FE
  • Dark mode strategy: Redesign surfaces (not invert). Reduce accent saturation 10-20%. Use #2DD4BF as dark-mode accent.
    • Background: #0F1114
    • Surface: #1A1D23
    • Surface hover: #22262E
    • Border: #2D3139
    • Text primary: #F0F1F3
    • Text secondary: #9CA3AF
    • Text tertiary: #6B7280

Spacing

  • Base unit: 4px
  • Density: Comfortable - generous whitespace makes the app feel fresh, not cramped
  • Scale: 2xs(2px) xs(4px) sm(8px) md(16px) lg(24px) xl(32px) 2xl(48px) 3xl(64px)
  • Standard gaps: 16px between list items, 24px between sections, 32px between major blocks, 48-64px between page sections

Layout

  • Approach: Grid-disciplined - strict alignment, predictable structure, consistent gutters
  • Grid: Single column on mobile (320-428px), content padding 16px
  • Max content width: 428px (largest phone width)
  • Gutters: 16px horizontal padding
  • Thumb zones: Primary actions in bottom third, navigation fixed at bottom
  • Border radius:
    • sm: 6px - inputs, small buttons, expense icons
    • md: 12px - cards, modals, alert banners
    • lg: 16px - bottom sheets, large cards, total card
    • full: 9999px - pills, chips, avatars, round buttons

Motion

  • Approach: Intentional - spring animations for touch feedback, subtle fades for transitions. Motion aids comprehension, never decorates.
  • Easing: enter(ease-out) exit(ease-in) move(cubic-bezier(0.4, 0, 0.2, 1))
  • Duration: micro(50-100ms) short(150-250ms) medium(250-400ms) long(400-700ms)
  • Principles:
    • Touch feedback: immediate (< 100ms), spring physics for press/release
    • Screen transitions: 250-350ms slide or fade
    • Data loading: skeleton screens with subtle pulse (1.5s loop)
    • Success states: 200ms scale + fade for checkmarks
    • No bounce, no overshoot, no playful animations. Precise and calm.

Navigation

  • Pattern: Bottom tab bar (4 tabs: Home, Add, Stats, Settings)
  • Add action: Center tab opens quick-entry (text input). Long-press or menu for receipt camera.
  • Stats sub-navigation: Budgets / Analytics / Recurring via horizontal tabs
  • Settings: Flat list - Timezone, Currency, AI, Export, Reset

Key UI Patterns

  • Quick entry: Large text input at top. Type "20 coffee" → AI parses amount + category. Confirmation card below with edit option.
  • Receipt flow: Camera → processing indicator → parsed result card → confirm/edit → saved.
  • Budget bars: Horizontal progress bars. Teal < 70%, warning 70-90%, error > 90%.
  • Expense list: Icon (emoji) + name/category + amount/date. Simple rows, no swipe actions on first version.
  • AI chat: Bubble UI. User messages in accent color (right-aligned), bot responses in surface color (left-aligned).

Decisions Log

Date Decision Rationale
2026-03-18 Initial design system created Created by /design-consultation based on competitive research (Expensify, Monarch Money, Cino) and product context. Brutally minimal aesthetic chosen to differentiate from corporate-clean and lifestyle-magazine patterns in the space.
2026-03-18 Satoshi + DM Sans typography Satoshi gives "designed object" quality vs generic SF Pro/Inter. DM Sans has superior tabular figures for financial data.
2026-03-18 Single teal accent (#0D9488) Deliberately not blue (too corporate) or green (too banking). Teal says "clarity" - appropriate for a personal tool about understanding your money.
2026-03-18 Groq (kimi-k2-instruct) for AI Replacing DeepSeek from Telegram bot. Free tier, async streaming, tool calling. Matches .Asqav project setup.
2026-03-18 Near-monochrome color strategy Emoji category icons provide all color/personality. UI stays calm. Radical in fintech space where everyone uses multiple bright colors.