o-colors
![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)
A component to manage colours. Includes the FT colour palette.
Markup
Colour Palette Custom Properties
All palette colors, including default mixes and tones, are available as CSS Custom Properties (CSS Variables) in the format --o-colors-[NAME]
.
See all palette colours available in the registry.
.ft-pink {
background: var(--o-colors-paper);
color: var(--o-colors-black-80);
}
Colour Usecase Custom Properties
A limited number of colour usecases are also available as CSS Custom Properties (CSS Variables), including:
--o-colors-page-background
--o-colors-box-background
--o-colors-body-text
--o-colors-muted-text
--o-colors-link-text
--o-colors-link-hover-text
body {
background: var(--o-colors-page-background);
}
Colour Usecase Classes
A limited number of colour usecases are available as CSS classes, including:
.o-colors-page-background
.o-colors-box-background
.o-colors-body-text
.o-colors-muted-text
<body class="o-colors-page-background">
</body>
Sass
o-colors has a number of mixins and functions for you to access the color palette in your project. We recommend Sass projects use these mixins and functions directly. E.g. oColorsByName and oColorsByUsecase. However, it is also possible to output all o-colors CSS Custom Properties (CSS Variables) and classes using the oColors
mixin.
@import 'o-colors/main';
@include oColors($opts: (
'palette-custom-properties': true, // e.g. --o-colors-paper
'usecase-custom-properties': true, // e.g. --o-colors-page-background
'usecase-classes': true // e.g. .o-colors-page-background
));
Palette Colours
o-colors defines a colour palette (a set of named colours) which may be previewed in the registry. Custom palette colours may be added to the palette to share them with dependencies.
Color Name | Brand Support |
---|
black | master, internal, whitelabel |
white | master, internal, whitelabel |
oxford | master, internal |
teal | master, internal |
slate | master, internal, |
lemon | master, internal, |
jade | master, internal |
crimson | master, internal |
paper | master |
claret | master |
wheat | master |
sky | master |
velvet | master |
mandarin | master |
candy | master |
wasabi | master |
org-b2c | master |
org-b2c-dark | master |
org-b2c-light | master |
There are additional colours in the palette by default including tones and mixes. See the registry demos for a full list.
Default Palette Colours
Get a default colour from the palette using oColorsByName
.
.example {
background: oColorsByName('paper');
}
Custom Palette Colours
To set a custom palette colour to share with other components call oColorsSetColor
.
Colours are namespaced by the project/component name. To get a custom palette colour use the $from
argument.
@include oColorsSetColor(
$project-name: 'o-example',
$color-name: 'myhotpink',
$color-hex: #ff69b4
);
.example {
background: oColorsByName('myhotpink', $from: 'o-example');
}
Removing a colour is considered a breaking change and requires a major release. To inform users a colour should not be used deprecate it by passing an $opts
argument with a deprecation message.
@include oColorsSetColor(
$project-name: 'o-example',
$color-name: 'myhotpink',
$color-hex #ff69b4,
$opts: ('deprecated': 'Use the default colour claret instead.')
);
See o-colors SassDoc for more details and examples.
Usecases
A colour palette helps products use the same set of colours, but does not help them use the colours consistently. Therefore o-colors provides tools to return colours based on usecases. E.g. a colour for the page background or body text.
Usecase | Property | Brand Support |
---|
page | background | master, internal, whitelabel |
focus | outline | master, internal |
box | background | master, internal |
link | text | master, internal |
link-hover | text | master, internal |
link-title | text | master, internal |
link-title-hover | text | master, internal |
title | text | master, internal |
body | text | master, internal |
muted | text | master, internal |
tag-link | text | master |
tag-link-hover | text | master |
opinion-tag-link | text | master |
opinion-tag-link-hover | text | master |
opinion | background | master |
hero | background | master |
hero-opinion | background | master |
hero-highlight | background | master |
Section colors | | |
section-life-arts | all | master |
section-life-arts-alt | all | master |
section-magazine | all | master |
section-magazine-alt | all | master |
section-house-home | all | master |
section-house-home-alt | all | master |
section-money | all | master |
section-money-alt | all | master |
Default Usecases
To get a colour for a default usecase call oColorsByUsecase
.
html {
background: oColorsByUsecase('page', 'background');
}
.paragraph {
color: oColorsByUsecase('body', 'text');
}
Custom Usecase
To create a new usecase call oColorsSetUseCase
.
$project-name
: The name of the component or project setting this colour, e.g. 'o-example'.$usecase
: The name of the usecase, e.g. 'page'.$colors
: A map of properties ('text', 'background', 'border', or 'outline') to a palette color name.$opts
(optional):
deprecated
: A deprecation message for the usecase.
@include oColorsSetUseCase('o-example', 'stripes', (
'text': 'white',
'background': 'black',
'border': 'black-50'
));
Get custom usecases using the $from
argument:
.example {
color: oColorsByUsecase('stripes', 'text', $from: 'o-example');
background: oColorsByUsecase('stripes', 'background', $from: 'o-example');
border: 1px solid oColorsByUsecase('stripes', 'border', $from: 'o-example');
}
Removing a usecase is a breaking change and requires a major release. To inform users a usecase should not be used it should be deprecated. Deprecate a usecase by passing an $opts
argument with a deprecation message.
Deprecate all usecase properties:
@include oColorsSetUseCase('o-example', 'stripes', (
'text': 'white',
'background': 'black',
'border': 'black-50'
), ('deprecated': 'o-example has no stripes anymore, use a different colour'));
Deprecate individual usecase properties:
@include oColorsSetUseCase('o-example', 'stripes', (
'text': 'white',
'background': 'black',
'border': 'black-50'
), ('deprecated': ('background': 'o-example stripes has no background anymore, use a different colour')));
Generated Text Colors
oColorsGetTextColor
will return a light or dark text color based on the background and an opacity specified.
.example {
background: oColorsByName('teal');
color: oColorsGetTextColor('teal');
}
.example {
background: oColorsByName('teal');
color: oColorsGetTextColor('teal', 80);
}
The contrast of the background and resulting text colour is checked against WCAG 2.1 guidelines. If the contrast is too low an error is thrown. By default the contrast is checked for normal text at AA level. The contrast may be checked for large text or against stricter AAA recommendations (aa-normal, aa-large, aaa-normal, or aaa-large).
.example-large-text {
background: oColorsByName('teal');
color: oColorsGetTextColor('teal', $minimum-contrast: 'aa-large');
}
Set $minimum-contrast
to null
to remove contrast checking. Only ignore contrast for incidental or logo text, otherwise your project may be inaccessible.
Mix colors
oColorsMix
will mix two colors based on a percentage. This gives the impression of the base color appearing at the percentage opacity over the background color. oColorsMix
will accept either a color value or the name of an o-colors palette color as arguments.
By default oColorsMix
mixes with the page background colour usecase:
$color: oColorsMix($color: 'black', $percentage: 30);
But two colours may be given. For example to mix claret over slate at 20%:
$color: oColorsMix($color: 'claret', $background: 'slate', 20);
Tone Palette Colors
An o-colors tone is a palette colour with modified saturation and luminosity, to create a lighter or darker colour whilst retaining vibrancy.
Recommended tones are already in the colour palette, e.g. teal-80
(see default tones in the registry). However for cases where a new tone is required use oColorsGetTone
. It will return a new color based on a specified brightness.
.teal-tone-example {
background-color: oColorsGetTone('teal', 80);
}
For design consistency not all colours are allowed to be toned. Only colours with default tones in the palette (e.g. teal, oxford, and claret) may be used. Other colours may still be mixed.
Colour Tools
o-colors provides other useful functions for working with colours, including:
- oColorsGetContrastRatio
- oColorsColorBrightness
- oColorsColorLuminance
See o-colors SassDoc for more details and examples.
Migration
Contact
If you have any questions or comments about this component, or need help using it, please either raise an issue, visit #ft-origami or email Origami Support.
Licence
This software is published by the Financial Times under the MIT licence.