Implement $darken1, $darken2, and $darken3 utilities

MisRob commented 1 month ago

🌱 Are you new to the codebase? Welcome! Please see the contributing guidelines.

Blocks

Summary

$darken1, $darken2, and $darken3 will be new utilities that will allow us to darken palette colors to achieve new colors that are still derived from a palette, but without the need to add them to the palette.

When Kolibri Design System is initialized in a consumer via Vue.use(KThemePlugin) , these three $darken_ helpers should be installed to all Vue instances, similarly how it’s currently done for $themeTokens, $themePalette, and other helpers.

Then, every Vue component can use them without the need to import. Examples:

computed: {
  styles() {
    return {
      backgroundColor: this.$darken1(this.$themePalette.red.v_1100)
    }
  }
}

<div
  :style="{ backgroundColor: $darken3($themePalette.red.v_1100) }"
 />

As for the actual color darkness shifts, we will use the following guidance from designers as a starting point. Note that (1) the algorithm used for $darken_ helpers should always be the same (no need to distinguish on which color it is being applied), (2) the expected hex values below are just estimates. So, the resulting hex values don't need to be exactly the same, but rather be as close as possible.

$darken1($themePalette.red.v_1100) to produce #A81700
$darken2($themePalette.red.v_1100) to produce #7E1200
$darken3($themePalette.red.v_1100) to produce #540C00
$darken1($themePalette.lightblue.v_1100) to produce #00619B
$darken2($themePalette.lightblue.v_1100) to produce #004974
$darken3($themePalette.lightblue.v_1100) to produce #00304E

References

Slack thread

Guidance

See the "Colors" docs
You can use the playground page for development
https://www.npmjs.com/package/color can be used under the hood (see color.darken())
Search for $themeTokens or $themePalette in KThemePlugin.js to understand how to define new helpers in a similar manner

The Value Add

Flexibility, efficiency, and ease when a need arises to use a color that's not in the palette, while still remaining within the palette's limits, as new colors can only be derived from existing colors.
Limited pre-defined darken steps ensure consistency

Background

Motivated by a Kolibri’s red button that needs to use palette.red.v_1100 as its background color. This is our darkest red and for the button’s hover state, we needed even darker color that is currently hardcoded here Additionally, designers had some work in progress figuring out adding more flexibility to our palette that is aligned with this approach.

Acceptance Criteria

[ ] Implemented as specified above
[ ] There is a new section on the Colors documentation page that contains
- A note that it is available in every Vue component after KDS installed
- Examples of usage in code
- Guidance on when to use it and when not, such as
  - Not to be overused. It is meant for rare cases for colors that are not ‘worth’ adding to the palette.
  - First look whether you can find a suitable color in the palette.
- Visual examples for how darkening looks like when applied to red.v_1100

MisRob commented 4 weeks ago

The proposal confirmed with the team. Ready to be worked on.

shivam-daksh commented 4 weeks ago

Hi @MisRob, The issue is now pretty clear to me. We've to replace the previous hard coded colors with new utility $darken_ . For example, If we have to achieve a shade of a color darker than darkest shade (already available) then $darken_ helps to achieve this without hardcoding. I'm ready to work on this.

MisRob commented 4 weeks ago

Sounds we're on the same page @shivam-daksh! Please follow the guidance as close as possible and message me in case of any doubts. I will assign you now. Thank you.

shivam-daksh commented 3 weeks ago

Hi @MisRob , I've added new file in darkenColors.js in lib/styles/darkenColors.js , also added to KThemePlugin.js to make it globally. It is working fine in playground.vue. Here is the code of darkenColors.js :

import Color from 'color';

export function darken1(color) {
  return Color(color)
    .darken(0.15)
    .hex();
}

export function darken2(color) {
  return Color(color)
    .darken(0.3)
    .hex();
}

export function darken3(color) {
  return Color(color)
    .darken(0.45)
    .hex();
}

Need your suggestions before making a PR!

MisRob commented 3 weeks ago

Hi @shivam-daksh, thanks! This particular file looks fine to me. To be able to say more, I will need to briefly preview other changes. You're welcome to open a draft pull request to demonstrate your work in progress - then we can chat there.

MisRob commented 3 weeks ago

Closed by https://github.com/learningequality/kolibri-design-system/pull/728

learningequality / kolibri-design-system