Design System & Theming

Relevant source files

The following files were used as context for generating this wiki page:

• app/src/main/java/io/github/mojri/hesabyar/ui/theme/Theme.kt
• app/src/main/java/io/github/mojri/hesabyar/ui/theme/Color.kt
• app/src/main/java/io/github/mojri/hesabyar/ui/designsystem/SpacingTokens.kt
• app/src/test/java/io/github/mojri/hesabyar/ui/ThemeTest.kt
• app/src/main/java/io/github/mojri/hesabyar/ui/screens/CategoryManagementScreen.kt
• README.md

Introduction

The Hesabyar design system is built upon Material 3 (M3) using Jetpack Compose, providing a modern, responsive, and Persian-first user interface. It emphasizes clear financial data visualization through a strict color palette, consistent spacing tokens, and support for both light and dark modes, including Android 12+ dynamic color capabilities.

The system is designed to handle Persian (Farsi) typography and RTL (Right-to-Left) layouts natively, ensuring that financial information remains legible and accessible. It integrates core design tokens for colors, spacing, and shapes to maintain consistency across complex screens such as the Analytical Dashboard and Smart Assistant.

Sources: README.md:120-130, app/src/main/java/io/github/mojri/hesabyar/ui/theme/Theme.kt:82-105

Color System

The color system is divided into standard Material 3 color schemes and specialized "Financial Colors" used for indicating transaction types (income vs. expense).

Theme Palettes

Hesabyar defines explicit LightColorScheme and DarkColorScheme using a custom selection of hex values. The dark theme is designed with high-contrast surfaces to ensure readability in low-light environments.

Theme Attribute	Light Value	Dark Value
Primary	#0061A4	#A1C9FF
Background	#FDFBFF	#111315
Surface	#FFFFFF	#1E2123
Error	#BA1A1A	#FFB4AB
Outline	#74777F	#8E9099

Sources: app/src/main/java/io/github/mojri/hesabyar/ui/theme/Color.kt:6-80

Financial Semantic Colors

Beyond standard UI colors, the application uses semantic colors to represent financial states. These are centralized in FinancialColors (referenced in the codebase as preferred over deprecated legacy constants).

• Income/Success: Represented by Green (#2ECC71).
• Expense/Error: Represented by Red (#E74C3C).
• Warning/Pending: Represented by Orange (#F39C12).

Sources: app/src/main/java/io/github/mojri/hesabyar/ui/theme/Color.kt:82-101

Theming Logic and Implementation

The HesabyarTheme composable manages the application's visual state. It utilizes a logic flow to determine whether to use system-wide dynamic colors (on Android 12/API 31+) or the internal static color schemes.

Theme Resolution Flow

The following diagram illustrates how the theme is applied based on system settings and device capabilities:

The theme provider injects the colorScheme and Typography into the Compose hierarchy.

Sources: app/src/main/java/io/github/mojri/hesabyar/ui/theme/Theme.kt:82-105

Design Tokens

Design tokens are used to decouple visual values from UI components, ensuring consistency in spacing and layout.

Spacing Tokens

Hesabyar uses a standardized spacing scale for margins, padding, and arrangement:

Token	Value	Usage
xs	4.dp	Fine-tuned internal padding
sm	8.dp	Small gaps between related elements
md	12.dp	Standard component internal padding
lg	16.dp	Standard screen margins and list spacing
xl	24.dp	Large section breaks
xxl	32.dp	Hero section padding

Sources: app/src/main/java/io/github/mojri/hesabyar/ui/designsystem/SpacingTokens.kt:6-14

Component-Specific Styles

The design system includes predefined maps for icons and specific colors used in features like Category Management. This ensures that even user-created content (like custom categories) adheres to the app's aesthetic.

private val CATEGORY_COLORS = listOf(
    0xFF4CAF50L, // Green
    0xFFFF9800L, // Orange
    0xFF2196F3L, // Blue
    0xFFF44336L  // Red
    // ... total 16 colors
)

Sources: app/src/main/java/io/github/mojri/hesabyar/ui/screens/CategoryManagementScreen.kt:59-77

Quality Assurance & Verification

The design system is validated through unit tests in ThemeTest.kt. These tests ensure that contrast ratios meet accessibility standards and that theme transitions are visually distinct.

Verified Constraints

• Contrast: DarkOnSurface and LightOnSurface must maintain a WCAG contrast ratio of at least 4.5:1 against their respective backgrounds.
• Luminance: The dark background must have a luminance < 0.1f, while the light background must be > 0.9f.
• Color Roles: Verification that Inverse Surface roles correctly flip foreground/background luminance.

Sources: app/src/test/java/io/github/mojri/hesabyar/ui/ThemeTest.kt:38-140

Summary

The Hesabyar Design System provides a robust foundation for a financial application by combining Material 3 principles with domain-specific semantic tokens. By centralizing spacing, colors, and theming logic, the project ensures a consistent experience across its AI-driven features and standard financial management modules.