Skip to main content

Design System

Bilko Design System

Source: Extracted from apps/web/tailwind.config.ts + brand identity spec Design Language: Modern Balkan accounting SaaS — clean, professional, accessible

Color Palette

Primary Brand Colors

Primary:        #00E5A0  (Vibrant teal-green — primary CTA, links, active states)
Primary Dark:   #00B380  (Darker variant for hover states)
Primary Light:  #33EBB3  (Lighter variant for backgrounds)

Status Colors

Success:        #22C55E  (Green — success states, paid invoices, positive metrics)
Warning:        #F59E0B  (Amber — warnings, pending items, aging invoices)
Error:          #EF4444  (Red — errors, overdue invoices, negative actions)
Info:           #3B82F6  (Blue — informational messages, neutral data)

Text Colors

Text Primary:   #111113  (Near-black — body text, headings)
Text Secondary: #6B7280  (Gray-600 — secondary text, labels)
Text Muted:     #888888  (Gray-500 — muted text, placeholders)

Background Colors

Background Light:   #FAFAFA  (Off-white — main content area background)
Background Surface: #FFFFFF  (White — card backgrounds, modals)

Border Color

Border:         #E5E7EB  (Gray-200 — borders, dividers)

Chart Colors

Chart Revenue:  #22C55E  (Green — revenue bars/lines)
Chart Expense:  #EF4444  (Red — expense bars/lines)
Chart Profit:   #3B82F6  (Blue — profit bars/lines)
Chart Neutral:  #6B7280  (Gray — neutral data points)

Sidebar Colors (Dark Theme)

Sidebar BG:         #111113  (Near-black — sidebar background)
Sidebar Text:       #FAFAFA  (Off-white — sidebar text)
Sidebar Text Muted: #888888  (Gray — inactive menu items)
Sidebar Active:     #00E5A0  (Primary green — active menu item)
Sidebar Hover:      #1F1F23  (Slightly lighter black — hover state)

Usage:

  • Sidebar = dark (#111113) with light text
  • Content area = light (#FAFAFA) with dark text
  • Cards = white (#FFFFFF) surface on light background

Typography

Font Family

Sans Serif: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif

Source: Google Fonts Inter (variable font) Fallback: System UI fonts for performance

Font Sizes

xs:   12px  (Small badges, captions)
sm:   14px  (Table cells, secondary text, form labels)
base: 16px  (Body text, default)
lg:   18px  (Subheadings, emphasized text)
xl:   20px  (Section titles)
2xl:  24px  (Card titles, small headings)
3xl:  32px  (Page headings)
4xl:  40px  (Hero text, large numbers)

Font Weights

normal:    400  (Body text)
medium:    500  (Emphasis, table headers)
semibold:  600  (Subheadings, button text)
bold:      700  (Headings, metric numbers)

Type Scale Usage

  • Headings:
    • Page title: text-3xl font-bold (32px, 700)
    • Section title: text-2xl font-bold (24px, 700)
    • Card title: text-base font-semibold (16px, 600)
  • Body:
    • Default: text-base font-normal (16px, 400)
    • Table cells: text-sm font-medium (14px, 500)
    • Muted text: text-sm text-text-muted (14px, #888888)
  • Numbers:
    • Metrics: text-3xl font-bold (32px, 700)
    • Totals: text-2xl font-bold (24px, 700)
    • Amounts: text-base font-medium (16px, 500)

Spacing System (8px Grid)

xs:  4px   (Tight spacing, icon gaps)
sm:  8px   (Input padding, small gaps)
md:  16px  (Default spacing, card padding)
lg:  24px  (Section spacing)
xl:  32px  (Large section spacing)
2xl: 48px  (Major section breaks)
3xl: 64px  (Hero spacing)

Usage:

  • Card padding: p-6 (24px)
  • Form field gap: space-y-4 (16px)
  • Section spacing: space-y-6 (24px)
  • Grid gap: gap-6 (24px)

Consistency: All spacing uses 8px increments (4px, 8px, 16px, 24px, 32px, 48px, 64px)

Border Radius

sm:   6px   (Small elements, badges)
md:   8px   (Buttons, inputs, cards)
lg:   12px  (Modals, large cards)
full: 9999px (Circular elements, pills)

Usage:

  • Cards: rounded-md (8px)
  • Buttons: rounded-md (8px)
  • Inputs: rounded-md (8px)
  • Badges: rounded-sm (6px)
  • User avatar: rounded-full (circular)

Shadows

Card Shadow:     0 2px 8px rgba(0, 0, 0, 0.08)   (Subtle card elevation)
Modal Shadow:    0 8px 24px rgba(0, 0, 0, 0.12)  (Dialog/modal elevation)
Dropdown Shadow: 0 4px 16px rgba(0, 0, 0, 0.10)  (Dropdown menu elevation)

Usage:

  • Cards: shadow-card
  • Modals/dialogs: shadow-modal
  • Dropdown menus: shadow-dropdown

Philosophy: Subtle shadows for depth, avoid heavy shadows (material design style)

Breakpoints

sm:  640px   (Small tablets, large phones)
md:  768px   (Tablets)
lg:  1024px  (Small desktops, large tablets)
xl:  1280px  (Desktops)

Mobile-First Strategy:

  • Base styles = mobile (< 640px)
  • sm: = small tablet (640px+)
  • md: = tablet/desktop toggle (768px+)
  • lg: = desktop layout (1024px+)
  • xl: = wide desktop (1280px+)

Responsive Patterns:

  • Grid: grid-cols-1 md:grid-cols-2 lg:grid-cols-3
  • Sidebar: hidden md:block (hide on mobile)
  • Filters: flex-col sm:flex-row (stack on mobile, row on tablet+)

Component Tokens

Button

  • Height: 40px (default), 32px (sm), 48px (lg), 40px (icon)
  • Padding: 16px horizontal (default), 12px (sm), 20px (lg)
  • Border Radius: 8px (md)
  • Font: 14px medium (default), 12px (sm), 16px (lg)
  • Variants:
    • Default: Primary green background, white text
    • Outline: Border only, transparent background
    • Ghost: No border, no background, hover shows background
    • Destructive: Error red background, white text

Input

  • Height: 40px
  • Padding: 12px horizontal
  • Border: 1px solid #E5E7EB (border color)
  • Border Radius: 8px (md)
  • Font: 14px normal
  • Focus: Primary color ring (2px)

Card

  • Background: #FFFFFF (surface)
  • Border: 1px solid #E5E7EB
  • Border Radius: 8px (md)
  • Shadow: 0 2px 8px rgba(0, 0, 0, 0.08)
  • Padding: 24px (default content padding)

Badge

  • Padding: 4px 8px
  • Border Radius: 6px (sm)
  • Font: 12px medium
  • Variants:
    • Default: Gray background
    • Success: Green background
    • Warning: Amber background
    • Destructive: Red background
    • Secondary: Light gray

Table

  • Row Height: 48px (default)
  • Cell Padding: 12px horizontal, 16px vertical
  • Border: 1px solid #E5E7EB (between rows)
  • Hover: Light gray background (#FAFAFA)
  • Header: Medium font weight, secondary text color

Icon System

Library: Lucide React (v0.469.0) Size: Consistent 16px (w-4 h-4) or 20px (w-5 h-5) Usage:

  • Buttons: 16px icon + 8px gap from text
  • Menu items: 20px icon + 12px gap from text
  • Standalone: 24px or larger

Common Icons:

  • Plus (add actions)
  • Search (search inputs)
  • Menu (mobile sidebar toggle)
  • User (user menu)
  • Bell (notifications)
  • ChevronDown/Right (expandable sections)
  • Check (success, reconciliation)
  • X (close, delete)
  • Download (export actions)
  • Send (send email)

Chart Design Tokens

Chart Colors (Recharts)

Revenue:  #22C55E  (Green bars)
Expense:  #EF4444  (Red bars)
Profit:   #3B82F6  (Blue bars)
Neutral:  #6B7280  (Gray — when no semantic meaning)

Chart Typography

  • Axis Labels: 12px normal
  • Tooltip: 14px medium
  • Legend: 12px normal

Chart Layout

  • Responsive Container: 100% width, fixed height (250px default)
  • Cartesian Grid: Dashed, #E5E7EB stroke
  • Tooltip Background: White with border
  • Border Radius: 8px (md)

Accessibility

Color Contrast

  • All text colors meet WCAG AA standards
  • Primary text (#111113) on white = 16.17:1 (AAA)
  • Secondary text (#6B7280) on white = 4.69:1 (AA)
  • Primary green (#00E5A0) on white = 2.92:1 (fails — used for accents only, not body text)

Focus Indicators

  • All interactive elements have visible focus ring
  • Focus ring color: Primary green (#00E5A0)
  • Focus ring width: 2px

Semantic HTML

  • Proper heading hierarchy (h1 → h2 → h3)
  • Form labels properly associated with inputs
  • ARIA labels on icon-only buttons
  • Table headers properly scoped

Design Principles

  1. Clarity over Decoration — Data-first, minimal ornamentation
  2. Consistent Spacing — 8px grid, predictable rhythm
  3. Accessible by Default — WCAG AA minimum, Radix UI primitives
  4. Mobile-First — Responsive from 375px+ (iPhone SE)
  5. Dark Sidebar + Light Content — Clear visual separation
  6. Primary Color as Accent — Green (#00E5A0) for actions, not backgrounds
  7. Subtle Shadows — Elevation without heaviness
  8. Data-Dense UI — Tables, charts, metrics — optimized for information density

Brand Identity Alignment

From ~/system/specs/bilko-brand-identity.md:

  • Primary Color: #00E5A0 (implemented)
  • Typography: Inter (implemented)
  • Tone: Modern, professional, Balkan-focused (implemented)
  • Dark Sidebar: #111113 (implemented)
  • Logo Placement: Top left sidebar (implemented)

Future Tokens (Phase 2)

When implementing API integration:

  • Loading States: Skeleton component colors
  • Error States: Error message backgrounds (#FEF2F2, light red)
  • Success States: Success message backgrounds (#F0FDF4, light green)
  • Toast Notifications: Background, text, border colors
  • Dark Mode: Full dark theme variant (optional)
Back to top