hsluv 1.0.4

  • Readme
  • Changelog
  • Example
  • Installing
  • 80

HSLuv for Dart & Flutter

Dart port of HSLuv (revision 4) with a Flutter sample. This was a direct conversion of the reference implementation.

HSLuv is a human-friendly alternative to HSL.

It is like HSL, but color only gets perceptually lighter or darker when the Lightness attribute changes. In HSL, if you go from a green hue to a red one, there will be big differences in the perceived lightness. In HSLuv, almost none.

If you want to see for yourself, check the sample app and open the Color Compare screen. Contrast "only" changes when Lightness changes. When Hue or Saturation attributes change, there might be minimal changes in contrast (in the 0.01 range), but nothing perceivable and certainly better than HSV/HSL.

This is specially useful when building acessible color systems. For more information, check: Designing Color Spaces / Wikipedia article

Usage #

In the pubspec.yaml of your flutter project, add the following dependency:

pub package

dependencies:
  hsluv: ^VERSION

In your project you can use it in two different ways, either low level (directly accessing values as a list<double>) or high level (similar to HSLColor). HSLuvColor is easier to use, but has less flexibility than a raw list.

import 'package:hsluv/hsluv.dart';

void main() {
  
  // Low level usage.
  final List<double> hsluvLow = Hsluv.rgbToHsluv([0.2,0.5,0.7]);
  print(Hsluv.hsluvToHex(hsluvLow));

  // High level usage.
  final hsluvFromColor = HSLuvColor.fromColor(Colors(0xffef3e4a));
  print(hsluvFromColor.toString());

  final hsluvFromHSL = HSLuvColor.fromHSL(300, 70, 60);
  print(hsluvFromHSL.toString());
}

Sample app showing HSV (top) vs HSLuv (bottom). See how the perceived lightness changes as the hue slider moves.

Color values ranges #

  • RGB values are ranging in [0...1]
  • HSLuv and HPLuv values have different ranging for their components
    • H : [0...360]
    • S and L : [0...100]
  • LUV has different ranging for their components
    • L* : [0...100]
    • u* and v* : [-100...100]
  • LCh has different ranging for their components
    • L* : [0...100]
    • C* : [0...?] Upper bound varies depending on L* and H*
    • H* : [0...360]
  • XYZ values are ranging in [0...1]

Important: Flutter's HSLColor has lightness and saturation ranging from 0 to 1.0. HSLuv uses 0 to 100. There is a class, called HSInterColor in the sample that tries to mitigate this.

API functions #

Note #

The passing/returning values, when not String are List<double> containing each component of the given color space/system in the name's order :

  • RGB : [red, blue, green]
  • XYZ : [X, Y, Z]
  • LCH : [L, C, H]
  • LUV : [L, u, v]
  • HSLuv/HPLuv : [H, S, L]

Function listing #

  • xyzToRgb(List<double> tuple)
  • rgbToXyz(List<double> tuple)
  • xyzToLuv(List<double> tuple)
  • luvToXyz(List<double> tuple)
  • luvToLch(List<double> tuple)
  • lchToLuv(List<double> tuple)
  • hsluvToLch(List<double> tuple)
  • lchToHsluv(List<double> tuple)
  • hpluvToLch(List<double> tuple)
  • lchToHpluv(List<double> tuple)
  • lchToRgb(List<double> tuple)
  • rgbToLch(List<double> tuple)
  • hsluvToRgb(List<double> tuple)
  • rgbToHsluv(List<double> tuple)
  • hpluvToRgb(List<double> tuple)
  • rgbToHpluv(List<double> tuple)
  • hsluvToHex(List<double> tuple)
  • hpluvToHex(List<double> tuple)
  • hexToHsluv(String s)
  • hexToHpluv(String s)
  • rgbToHex(List<double> tuple)
  • hexToRgb(String hex)

Reporting Issues #

Issues and Pull Requests are welcome. You can report here.

License #

Copyright 2019 Bernardo Ferrari

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

[1.0.4]

  • Initial port of HSLuv with a nice sample app.

example/README.md

HSLuv Sample

HSLuv Sample for Flutter #

SlidersMain ScreenColor BlindnessAbout
FirstSecThirdFourth

Most color pickers give you 16 million colors and ask you to choose one. I designed and developed this app to help developers and designers find the best color for them with the smallest amount of effort.

This app is actually part of another one, which is coming out hopefully soon and will also be open source. The project grew so large I thought it was better to split in two, test the public reception and collect feedback before moving forward. This is why this might be one of the most full-fledged over-engineered sample apps out there. It is hard to develop alone. If you have any good or bad feedback, want to be alerted when the bigger app is released or want to be more involved, please contact me!

Download the APK

This app contains the following screens:

  • Three sliders. RGB, HSV and HSLuv. You can see how they interact with each other.
  • HSLuv/HSV vertical picker. Shows a lot of colors without being overwhelming.
  • About. Contains a button to shuffle colors and a button open the compare colors screen.
  • Color Library. Colors from Color Claim, the color palette from Tobias van Schneider.
  • Compare Colors. Compare the WACG contrast between the first color and all the others.
  • Info. Check how the color attributes are changing from first color to others. Easy to see patterns (i.e. colors are similar but only Hue is changing!)

Color Blindness #

Color blindness involves difficulty in perceiving or distinguishing between colors, as well as sensitivity to color brightness. It affects approximately one in twelve men and one in two hundred women worldwide. Carbon Design System

TypeColor deficiency
ProtanopiaRed/green
TritanopiaBlue
DeuteranopiaGreen
MonochromacyAll colors

The app calculates color blindness by using the formulas from a Swift library named Colorblinds.

Contrast #

WCAG specifies:

  • 3.0:1 minimum contrast ratio for texts larger than 18pt (AA+).
  • 4.5:1 minimum contrast ratio for texts smaller than 18pt (AA).
  • 7.0:1 minimum contrast ratio is preferred, when possible (AAA).

The Compare Colors screen will help you check if your color palette is accessible enough.

For more information about those A letters, see this guide. IBM Checkpoint 1.4.3 Contrast (Minimum). Google also follows these guidelines in Material Design.

Color Claim #

The app uses Color Claim as the main palette, both in "Color Library" screen and when shuffling colors. Every time the method to shuffle the colors is called, it is actually retrieving Color Claim, shuffling it, and getting the first n elements. This pseudo-randomization strategy guarantees nice colors always.

To retrieve the colors, I opened the colorclaim.1.1.sketchpalette file in Visual Studio Code and took all the hex colors.

CompareInfoColor Library
FirstSecThird

HSV vs HSLuv #

HSV vs HSLuv

You can see in that image the difference between Hue values in HSV (or HSL, which has the same Hue values) and HSLuv. HSLuv only changes the apparent lightness when lightness changes. You can change both Hue and Saturation values that, when compared to another color, the resulting contrast value will be the same. This is one of the foundations for the "Contrast Compare" screen. You only need to update the lightness value and nothing else to modify the contrast ratio. Therefore, you only need one picker or slider, not three, if you are aiming at the contrast.

HSInterColor #

While developing this app, there was a need to interop HSLuvColor with HSVColor (or HSLColor). Given the similarities but differences between both (HSLuv's Saturation and Lightness range from 0 to 100, instead of 0 to 1.0), HSInterColor was born. You pass a kind parameter, which can be HSLuv or HSV and it automatically wraps them, so you can have unified toString, toColor and others. It is also extensible and modifying it to wrap other color structures should be easy.

Design Process #

Design Process

Many strategies were used to design this app. One of them was to draw in iPad using Paper by Wetransfer until a satisfiable design appeared. Another one was to sometimes test the app in iPad instead of phone. The large rectangular screen would make some designs immediately obsolete. And vice-versa. There was a previous iteration of the Color Compare screen that only compared two colors, but with a lot of details (like 3 selectors for each - H, S and V). This couldn't fit comfortably a phone's screen and, at the end, the 2 Color Compare screen was replaced by a multi Color Compare. It became more flexible and now works across all screens.

Why Flutter? #

I've been developing with Flutter for the past few months and has been a really enjoyable experience. There are a lot bugs, tooling for Dart is miles behind Kotlin, and there was even a feature in this app that had to be disabled because of mutable bugs. On the good side, it avoided me having to do the same work 3 times and this project even lead to a contribution in Flutter, the addition of onLongPress in Buttons.

Another fun thing: I needed to clone the Material Slider and modify it to fix this. While not something good (or even expected), it is great that Flutter doesn't use private internal fields in their own libraries. This could never happen in native Android with Material Components. Everything is tightly coupled.

While there were many frustrations, bugs, and some things that weren't possible (yet), I am really happy with the result and there would be few benefits if this app were native.

Reporting Issues #

Issues and Pull Requests are welcome. You can report here.

License #

Copyright 2019 Bernardo Ferrari

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  hsluv: ^1.0.4

2. Install it

You can install packages from the command line:

with Flutter:


$ flutter pub get

Alternatively, your editor might support flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:hsluv/hsluv.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
59
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
80
Learn more about scoring.

We analyzed this package on Jan 16, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.7.0
  • pana: 0.13.4
  • Flutter: 1.12.13+hotfix.5

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.5.0 <3.0.0
flutter 0.0.0
Transitive dependencies
collection 1.14.11 1.14.12
meta 1.1.8
sky_engine 0.0.99
typed_data 1.1.6
vector_math 2.0.8
Dev dependencies
flutter_test