Design System
title: Design System
owner: vizu
last-updated: 2026-05-16
supersedes: docs/frontend/DESIGN-SYSTEM.md (2026-02-25 — teal palette, retired)
status: canonical
Bilko Design System
Source:
RETIRED:ExtractedThefrompreviousapps/web/tailwind.config.tsDESIGN-SYSTEM.md documented a teal (#00E5A0) palette. That document is wrong and archived. The canonical+ brandisidentityplumspec(#8B6BBF).DesignSeeLanguage:Moderndocs/branding/branding/bilko-brand-guidelines.mdforBalkantheaccountingauthoritativeSaaSbrand—source.clean, professional, accessible
1. Color Palette — Canonical Plum
Source
Primary ofBrand truth: bilko-brand-guidelines.md (2026-05-16). Tokens below are the Tailwind 4 @theme mapping.
CSS Custom Properties (@theme block in globals.css)Colors
@themePrimary: {#00E5A0 /*(Vibrant teal-green — primary CTA, links, active states)
Primary plumDark: scale#00B380 */(Darker --color-primary:variant #8b6bbf;for /*hover Plumstates)
Primary Light: #33EBB3 (Lighter variant for backgrounds)
Status Colors
Success: #22C55E (Green — CTAs, activesuccess states, linkspaid */invoices, --color-primary-hover:positive #5b3e8a;metrics)
/*Warning: Deep#F59E0B Plum(Amber — hoverwarnings, onpending primaryitems, elementsaging */invoices)
--color-primary-light:Error: #c4a8e0;#EF4444 /* Light Plum(Red — subtleerrors, backgrounds,overdue chipsinvoices, */negative --color-primary-subtle:actions)
#ede5f8;Info: /*#3B82F6 Plum tint(Blue — focusinformational rings,messages, hoverneutral surfacesdata)
*/
/*Text AccentColors
*/Text --color-accent:Primary: #f2c87a;#111113 /* Gold(Near-black — highlights,body accenttext, dots,headings)
iconsText */Secondary: --color-accent-hover:#6B7280 #e8ae4a; /* Gold dark(Gray-600 — hoversecondary ontext, accentlabels)
elementsText */Muted: /*#888888 Surface(Gray-500 /— muted text, placeholders)
Background Colors
Background Light: #FAFAFA (Off-white — main content area background)
Background */Surface: --color-surface:#FFFFFF #f9f7fc; /* Light Lavender — preferred background */
--color-surface-dark: #14111f; /* Dark mode background */
--color-bg: #ffffff; /* Pure white(White — card backgrounds, modalsmodals)
*/
/*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: --color-text-primary:#888888 #231c33;(Gray /*— Darkinactive plum-tonedmenu items)
Sidebar Active: #00E5A0 (Primary green — active menu item)
Sidebar Hover: #1F1F23 (Slightly lighter black — hover state)
@themeglobals.css@themePrimary: {#00E5A0 /*(Vibrant teal-green — primary CTA, links, active states)
Primary plumDark: scale#00B380 */(Darker --color-primary:variant #8b6bbf;for /*hover Plumstates)
Primary Light: #33EBB3 (Lighter variant for backgrounds)
Success: #22C55E (Green — CTAs, activesuccess states, linkspaid */invoices, --color-primary-hover:positive #5b3e8a;metrics)
/*Warning: Deep#F59E0B Plum(Amber — hoverwarnings, onpending primaryitems, elementsaging */invoices)
--color-primary-light:Error: #c4a8e0;#EF4444 /* Light Plum(Red — subtleerrors, backgrounds,overdue chipsinvoices, */negative --color-primary-subtle:actions)
#ede5f8;Info: /*#3B82F6 Plum tint(Blue — focusinformational rings,messages, hoverneutral surfacesdata)
*/Text --color-accent:Primary: #f2c87a;#111113 /* Gold(Near-black — highlights,body accenttext, dots,headings)
iconsText */Secondary: --color-accent-hover:#6B7280 #e8ae4a; /* Gold dark(Gray-600 — hoversecondary ontext, accentlabels)
elementsText */Muted: /*#888888 Surface(Gray-500 /— muted text, placeholders)
Background Light: #FAFAFA (Off-white — main content area background)
Background */Surface: --color-surface:#FFFFFF #f9f7fc; /* Light Lavender — preferred background */
--color-surface-dark: #14111f; /* Dark mode background */
--color-bg: #ffffff; /* Pure white(White — card backgrounds, modalsmodals)
*/Border: #E5E7EB (Gray-200 — borders, dividers)
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 BG: #111113 (Near-black — sidebar background)
Sidebar Text: #FAFAFA (Off-white — sidebar text)
Sidebar Text */Muted: --color-text-primary:#888888 #231c33;(Gray /*— Darkinactive plum-tonedmenu items)
Sidebar Active: #00E5A0 (Primary green — active menu item)
Sidebar Hover: #1F1F23 (Slightly lighter black — hover state)
Usage:
7.Component shadcn/uiTokens
Button
- Height:
cva - 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
AllLibrary: shadcn/uiLucide componentsReact use(v0.469.0)
class-variance-authoritycvaw-4 h-4foror variant20px composition.(w-5 )
Theh-5cn() utility merges Tailwind classes with conflict resolution via tailwind-merge.Usage:
Button
Common Icons:
- Plus (
fromaddcomponents/ui/button.tsx)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)
importRevenue: {#22C55E cva,(Green typebars)
VariantPropsExpense: }#EF4444 from(Red 'class-variance-authority'bars)
importProfit: {#3B82F6 cn(Blue }bars)
fromNeutral: '@/lib/utils'#6B7280 const buttonVariants = cva(
// Base styles(Gray — alwayswhen appliedno 'inline-flexsemantic items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50',
{
variants: {
variant: {
default: 'bg-primary text-primary-foreground hover:bg-primary/90',
destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
outline: 'border border-input bg-background hover:bg-accent hover:text-accent-foreground',
secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
ghost: 'hover:bg-accent hover:text-accent-foreground',
link: 'text-primary underline-offset-4 hover:underline',
},
size: {
default: 'h-10 px-4 py-2',
sm: 'h-11 rounded-md px-3',
lg: 'h-11 rounded-md px-8',
icon: 'h-11 w-11',
},
},
defaultVariants: { variant: 'default', size: 'default' },
},
)meaning)
AddingChart a Custom VariantTypography
//
Extend- Axis
buttonVariantsLabels: 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
aaccents "plum-outline"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
- Clarity over Decoration — Data-first, minimal ornamentation
- Consistent Spacing — 8px grid, predictable rhythm
- Accessible by Default — WCAG AA minimum, Radix UI primitives
- Mobile-First — Responsive from 375px+ (iPhone SE)
- Dark Sidebar + Light Content — Clear visual separation
- Primary Color as Accent — Green (#00E5A0) for actions, not backgrounds
- Subtle Shadows — Elevation without heaviness
- 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
const(optional)
buttonVariants
= cva(/* base */, {
variants: {
variant: {
// ... existing variants
'plum-outline': 'border-2 border-primary text-primary hover:bg-primary-subtle',
},
},
})
cn() Usage Rule
Always compose class lists with cn() — never with template literals or string concatenation:
// Correct
<div className={cn('base-class', condition && 'conditional-class', className)} />
// Wrong
<div className={`base-class ${condition ? 'conditional-class' : ''} ${className}`} />