balady_design_system 0.0.3

Reusable Flutter design system with themes and request card widgets for Balady apps.

🎨 Balady Design System

A centralized Flutter design system package that provides the core UI foundations for Balady applications. It ensures visual consistency, scalability, and easy theming across all apps by unifying themes, colors, and typography.

---

✨ Key Features

• 🌗 App Themes Pre-configured ThemeData for both Light and Dark modes.

• 🎨 Color Palette Centralized brand colors mapped to Material ColorScheme.

• 🅰️ Typography Standardized text styles fully compatible with Material Design.

---

📦 Installation

Add the package to your main application’s pubspec.yaml.

🧪 Local Installation (During Development)

dependencies:
  flutter:
    sdk: flutter

  balady_design_system:
    path: ../balady_design_system

---

🚀 Git Installation (Production)

dependencies:
  balady_design_system:
    git:
      url: https://github.com/YourOrg/balady_design_system.git
      ref: main

---

💻 Usage

1️⃣ Application Setup

Import the design system and apply the themes to MaterialApp.

import 'package:flutter/material.dart';
import 'package:balady_design_system/theme/app_theme.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Balady App',
      debugShowCheckedModeBanner: false,

      // Light Theme
      theme: myLightTheme,

      // Dark Theme
      darkTheme: myDarkTheme,

      // System-based theme switching
      themeMode: ThemeMode.system,

      home: const HomeScreen(),
    );
  }
}

---

2️⃣ Accessing Colors & Typography (Best Practice)

❗ Do not access colors directly from static classes. Always rely on Theme.of(context) to ensure support for Light / Dark modes and dynamic theme updates.

🎨 Using Colors

Container(
  // ✅ Uses active theme color
  color: Theme.of(context).colorScheme.primary,
  child: Icon(
    Icons.check,
    // ✅ Correct contrast color
    color: Theme.of(context).colorScheme.onPrimary,
  ),
);

🅰️ Using Text Styles

Text(
  'Hello Balady',
  style: Theme.of(context).textTheme.headlineLarge,
);

---

3️⃣ Advanced Usage – Dynamic Theme Overrides (API Driven)

If your backend provides dynamic theme values (e.g. via CommonProperties), you can override specific properties using .copyWith().

⚠️ Important: API colors are usually returned as int. Always wrap them with Color().

import 'package:flutter/material.dart';
import 'package:balady_design_system/theme/app_theme.dart';

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    final themeConfig = CommonProperties.appThemeConfig;

    return MaterialApp(
      title: 'Balady App',

      // Light Theme Overrides
      theme: myLightTheme.copyWith(
        cardColor: themeConfig?.colorSchemeLight?.cardColor != null
            ? Color(themeConfig!.colorSchemeLight!.cardColor)
            : null,
        scaffoldBackgroundColor:
            themeConfig?.colorSchemeLight?.scaffoldBackgroundColor != null
                ? Color(themeConfig!.colorSchemeLight!.scaffoldBackgroundColor)
                : null,
        colorScheme: myLightTheme.colorScheme.copyWith(
          primary: themeConfig?.colorSchemeLight?.primary != null
              ? Color(themeConfig!.colorSchemeLight!.primary)
              : null,
        ),
      ),

      // Dark Theme Overrides
      darkTheme: myDarkTheme.copyWith(
        cardColor: themeConfig?.colorSchemeDark?.cardColor != null
            ? Color(themeConfig!.colorSchemeDark!.cardColor)
            : null,
        scaffoldBackgroundColor:
            themeConfig?.colorSchemeDark?.scaffoldBackgroundColor != null
                ? Color(themeConfig!.colorSchemeDark!.scaffoldBackgroundColor)
                : null,
        colorScheme: myDarkTheme.colorScheme.copyWith(
          primary: themeConfig?.colorSchemeDark?.primary != null
              ? Color(themeConfig!.colorSchemeDark!.primary)
              : null,
        ),
      ),

      themeMode: ThemeMode.system,
      home: const HomeScreen(),
    );
  }
}

---

📁 Project Structure

balady_design_system/
├── lib/
│   └── theme/
│       └── app_theme.dart   # Main entry for themes & color schemes
├── test/
│   └── balady_design_system_test.dart
├── pubspec.yaml
└── README.md

---

✅ Summary

• Centralized theming for all Balady apps
• Supports Light & Dark modes out of the box
• Fully Material Design compliant
• Easy to extend and override dynamically

🚀 Use this design system to keep your apps consistent, scalable, and future-proof.