zeba_academy_color_utils 0.0.1

A lightweight Flutter utility package for color conversion, manipulation, contrast calculation, opacity, and interpolation.

Zeba Color Utils

A lightweight, type-safe, and production-ready color utility package for Flutter.

Zeba Color Utils provides convenient extensions and utility methods for working with Flutter Color objects, including hexadecimal conversion, RGB/ARGB conversion, color manipulation, opacity control, luminance calculation, WCAG contrast checking, and automatic contrasting-color selection.

---

✨ Features

• 🎨 Convert hexadecimal strings to Flutter Color
• 🔢 Convert Color to hexadecimal
• 🔴 Access RGB channel values
• 🟢 Access ARGB channel values
• ☀️ Lighten colors using HSL
• 🌑 Darken colors using HSL
• 💧 Set color opacity
• 🎚️ Adjust existing opacity
• 🌈 Calculate relative luminance
• ♿ Calculate WCAG contrast ratios
• ✅ Check WCAG contrast requirements
• 🌓 Automatically choose a contrasting color
• 🔀 Interpolate between two colors
• 🧱 Immutable RGB and ARGB value classes
• 🛡️ Input validation for channels and numeric ranges
• 📦 Simple API with no unnecessary dependencies

---

📦 Installation

Add zeba_color_utils to your pubspec.yaml:

dependencies:
  zeba_color_utils: ^1.0.0

Then run:

flutter pub get

Import the package:

import 'package:zeba_color_utils/zeba_color_utils.dart';

Replace ^1.0.0 with the latest version available on pub.dev.

---

🚀 Quick Start

Hexadecimal to Color

final red = ZebaColorUtils.fromHex('#FF0000');

final transparentRed = ZebaColorUtils.fromHex('#80FF0000');

Supported formats:

Format	Example	Description
#RGB	#F00	RGB shorthand
#ARGB	#8F00	ARGB shorthand
#RRGGBB	#FF0000	RGB
#AARRGGBB	#80FF0000	ARGB

---

🎨 Color to Hexadecimal

final color = Colors.blue;

final hex = color.toHex();

print(hex);
// #2196F3

Include alpha:

final hex = color.toHex(
  includeAlpha: true,
);

print(hex);
// #FF2196F3

Lowercase output:

final hex = color.toHex(
  uppercase: false,
);

print(hex);
// #2196f3

---

🔴 RGB Values

Use the rgb extension:

final color = Colors.blue;

final rgb = color.rgb;

print(rgb.red);
print(rgb.green);
print(rgb.blue);

You can also convert the values into a list:

final values = color.rgb.toList();

print(values);
// [33, 150, 243]

---

🟣 ARGB Values

Use the argb extension:

final color = Colors.blue;

final argb = color.argb;

print(argb.alpha);
print(argb.red);
print(argb.green);
print(argb.blue);

Convert ARGB values into a list:

final values = color.argb.toArgbList();

print(values);
// [255, 33, 150, 243]

---

🏗️ Create Colors from RGB

final color = ZebaColorUtils.fromRgb(
  red: 255,
  green: 0,
  blue: 0,
);

This creates an opaque color with an alpha value of 255.

---

🏗️ Create Colors from ARGB

final color = ZebaColorUtils.fromArgb(
  alpha: 128,
  red: 255,
  green: 0,
  blue: 0,
);

---

☀️ Lighten a Color

The lighten method adjusts the color's HSL lightness.

final lighterBlue = Colors.blue.lighten(0.2);

The amount must be between 0 and 1.

final color = Colors.blue.lighten(0.1);

---

🌑 Darken a Color

final darkerBlue = Colors.blue.darken(0.2);

The amount must be between 0 and 1.

---

💧 Set Opacity

Set an exact opacity value:

final color = Colors.blue.withOpacityValue(0.5);

opacity must be between 0 and 1.

For example:

Colors.black.withOpacityValue(0.25);
Colors.white.withOpacityValue(0.75);

---

🎚️ Adjust Existing Opacity

Multiply the existing opacity by a factor:

final color = Colors.blue.adjustOpacity(0.5);

For example, a color with 0.8 opacity adjusted by 0.5 will result in approximately 0.4 opacity.

final result = color.adjustOpacity(0.5);

---

🌈 Relative Luminance

Calculate the WCAG relative luminance of a color:

final luminance = Colors.blue.relativeLuminance;

print(luminance);

The result is between 0 and 1.

This can be useful for accessibility and contrast calculations.

---

♿ Contrast Ratio

Calculate the WCAG contrast ratio between two colors:

final ratio = Colors.black.contrastWith(
  Colors.white,
);

print(ratio);
// 21.0

The result ranges from:

1 → 21

A higher value indicates stronger contrast.

---

✅ Check Contrast Requirements

You can check whether a foreground and background color meet a required contrast ratio:

final isAccessible = ZebaColorUtils.meetsContrastRatio(
  Colors.black,
  Colors.white,
  4.5,
);

print(isAccessible);
// true

For common WCAG targets:

// Normal text
ZebaColorUtils.meetsContrastRatio(
  foreground,
  background,
  4.5,
);

// Large text
ZebaColorUtils.meetsContrastRatio(
  foreground,
  background,
  3.0,
);

---

🌓 Automatically Choose a Contrasting Color

Choose between black and white based on which provides better contrast:

final textColor = Colors.blue.contrastingColor();

By default:

• Light color → Colors.black
• Dark color → Colors.white

You can provide custom colors:

final textColor = Colors.blue.contrastingColor(
  light: Colors.white,
  dark: Colors.black,
);

This is especially useful for dynamic UI components.

Example

Container(
  color: backgroundColor,
  child: Text(
    'Hello',
    style: TextStyle(
      color: backgroundColor.contrastingColor(),
    ),
  ),
)

---

🔀 Color Interpolation

Interpolate between two colors:

final middleColor = ZebaColorUtils.interpolate(
  Colors.red,
  Colors.blue,
  0.5,
);

t must be between 0 and 1.

0.0 → first color
0.5 → midpoint
1.0 → second color

Example:

final color = ZebaColorUtils.interpolate(
  Colors.red,
  Colors.blue,
  0.25,
);

---

🧩 API Overview

ZebaColorExtensions

API	Description
toHex()	Converts a color to hexadecimal
rgb	Returns RGB channel values
argb	Returns ARGB channel values
lighten(amount)	Lightens a color
darken(amount)	Darkens a color
withOpacityValue(opacity)	Sets opacity
adjustOpacity(factor)	Adjusts existing opacity
relativeLuminance	Returns relative luminance
contrastWith(color)	Calculates contrast ratio
contrastingColor()	Returns the best contrasting color

ZebaColorUtils

API	Description
fromHex()	Creates a color from hexadecimal
toHex()	Converts a color to hexadecimal
fromRgb()	Creates a color from RGB
fromArgb()	Creates a color from ARGB
toRgb()	Converts a color to RGB
toArgb()	Converts a color to ARGB
lighten()	Lightens a color
darken()	Darkens a color
withOpacityValue()	Sets opacity
adjustOpacity()	Adjusts opacity
contrastRatio()	Calculates contrast ratio
relativeLuminance()	Calculates relative luminance
contrastingColor()	Selects a contrasting color
interpolate()	Interpolates between colors
meetsContrastRatio()	Validates contrast ratio

---

🧱 Value Classes

The package includes two immutable value classes.

RgbColor

const RgbColor(
  red: 255,
  green: 0,
  blue: 0,
);

Properties:

rgb.red
rgb.green
rgb.blue

Convert to a list:

rgb.toList();

ArgbColor

const ArgbColor(
  alpha: 255,
  red: 255,
  green: 0,
  blue: 0,
);

Properties:

argb.alpha
argb.red
argb.green
argb.blue

Convert to a list:

argb.toArgbList();

Both classes implement value equality and provide useful hashCode and toString() implementations.

---

🛡️ Validation

The package validates channel values and numeric parameters.

RGB/ARGB channels must be between:

0 - 255

Amounts such as opacity, interpolation values, lightening, and darkening must be between:

0.0 - 1.0

Invalid values throw appropriate Dart exceptions such as:

RangeError

Invalid hexadecimal strings throw:

FormatException

For example:

ZebaColorUtils.fromHex('#12345');

will throw a FormatException.

---

♿ Accessibility

The contrast-related APIs are based on WCAG relative luminance and contrast ratio calculations.

Example:

final ratio = ZebaColorUtils.contrastRatio(
  Colors.white,
  Colors.black,
);

Result:

21.0

You can use meetsContrastRatio() to build accessibility-aware UI components:

final foreground = background.contrastingColor();

final accessible = ZebaColorUtils.meetsContrastRatio(
  foreground,
  background,
  4.5,
);

Always validate accessibility requirements against the version of WCAG and product requirements applicable to your application.

---

💡 Practical Example

A complete example using several APIs:

import 'package:flutter/material.dart';
import 'package:zeba_color_utils/zeba_color_utils.dart';

void main() {
  const background = Color(0xFF40E0D0);

  final hex = background.toHex();

  final rgb = background.rgb;

  final textColor = background.contrastingColor();

  final darker = background.darken(0.15);

  final lighter = background.lighten(0.15);

  final contrast = background.contrastWith(textColor);

  debugPrint('Hex: $hex');
  debugPrint('RGB: ${rgb.toList()}');
  debugPrint('Contrast: $contrast');
  debugPrint('Text Color: $textColor');

  runApp(
    MaterialApp(
      home: Scaffold(
        backgroundColor: background,
        body: Center(
          child: Container(
            color: darker,
            padding: const EdgeInsets.all(24),
            child: Text(
              'Zeba Color Utils',
              style: TextStyle(
                color: textColor,
                fontSize: 24,
                fontWeight: FontWeight.bold,
              ),
            ),
          ),
        ),
      ),
    ),
  );
}

---

📁 Suggested Project Structure

lib/
├── zeba_color_utils.dart
├── color_utils.dart
├── color_value.dart
└── color_extensions.dart

test/
├── color_utils_test.dart
├── color_extensions_test.dart
└── color_value_test.dart

LICENSE
README.md
CHANGELOG.md
pubspec.yaml

---

🧪 Testing

Run all tests with:

flutter test

Run static analysis:

flutter analyze

Format the project:

dart format .

A production release should pass:

dart format --output=none --set-exit-if-changed .
flutter analyze
flutter test

---

📚 Documentation

API documentation is available through Dart's generated documentation and on pub.dev.

For the latest package information, visit:

https://pub.dev/packages/zeba_color_utils

---

🤝 Contributing

Contributions are welcome and appreciated.

Before submitting a pull request:

1. Fork the repository.
2. Create a feature branch.
3. Make your changes.
4. Add or update tests.
5. Run formatting.
6. Run static analysis.
7. Run the test suite.
8. Submit a pull request.

Example:

git checkout -b feature/my-feature

dart format .

flutter analyze

flutter test

git commit -m "feat: add my feature"

git push origin feature/my-feature

Please keep the public API focused, documented, and backwards compatible whenever possible.

---

🐛 Issues & Feature Requests

If you find a bug or have an idea for improving the package, please open an issue in the project's GitHub repository.

When reporting a bug, include:

• Flutter version
• Dart version
• Package version
• Operating system
• Minimal reproducible example
• Expected behavior
• Actual behavior

---

📄 License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0).

You should include the full GPL-3.0 license text in a file named:

LICENSE

The package is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version.

See the full license:

https://www.gnu.org/licenses/gpl-3.0.html

---

👨‍💻 About the Author

✨ Sufyan bin Uzayr is an open-source developer passionate about building and sharing meaningful projects.

🌐 Website: https://sufyanism.com/

💼 LinkedIn: https://www.linkedin.com/in/sufyanism

---

🎓 Zeba Academy

Zeba Academy is a learning platform dedicated to coding, technology, and development.

🚀 Explore courses, tutorials, real-world projects, and hands-on development resources.

🌐 Main website: https://zeba.academy

💻 Courses & resources: https://code.zeba.academy

▶️ YouTube: https://www.youtube.com/@zeba.academy

📸 Instagram: https://www.instagram.com/zeba.academy/

---

❤️ Support Open Source

If this package helps you:

⭐ Star the repository 🐛 Report issues 💡 Suggest improvements 🔀 Submit pull requests 📦 Share the package with other Flutter developers

Every contribution helps make the project better.

---

🙏 Thank You

Thank you for using Zeba Color Utils and supporting open-source software.

Built with ❤️ for the Flutter community.

Zeba Academy • Open Source • Flutter