Origami Frontend Components & Services

SassDoc: o-colors

oColors(opts)

Output o-colors CSS.

parameter type default description
opts The o-colors features to output. See the [readme](https://registry.origami.ft.com/components/o-colors) for a full list of options.

Examples

Example #1

all o-colors styles.

@include oColors();

Example #2

only o-colors CSS custom properties ("CSS variables") for palette colours and usecases.

@include oColors($opts: (
	'palette-custom-properties': true,
	'usecase-custom-properties': true
));

Example #3

only o-colors classes for usecases.

@include oColors($opts: (
	'usecase-classes': true
));

Links

oColorsByName(color-name)

Return the CSS color for a palette color name.

parameter type default description
color-name The name of the colour to get.

Returns

Links

oColorsByUsecase(...)

Return the defined palette color for a use case / property combination

parameter type default description
usecase The name of the usecase, e.g. 'page'.
property The usecase property e.g. 'text', 'background', 'border', 'outline'
fallback The fallback if the usecase is not found. Either a colour, palette colour string, or `null` (note: the default is `false` to indicate no fallback).

Returns

Color - The usecase colour.

Links

oColorsGetTone(color-name, brightness)

Returns a brighter or darker tone of a colour, where the hue remains the same but the saturation and luminance changes.

Not all our colours allow tones. If a colour cannot be toned an error is thrown. You may however mix the colour with another supported colour.

parameter type default description
color-name the name of the color to be shaded
brightness the brightness value of the new color, 0-100

Returns

Links

oColorsGetToneDetails(color)

Figure out if a given colour is a tone. If it is a tone return the original colour name and its tone brightness, otherwise return null.

parameter type default description
color the palette colour or color name e.g. 'claret-80'

Returns

Map | Null - the details of the given tone e.g. ('color-name': 'claret', 'brightness': 80) )

Example

the tone brightness of 'claret-80'

$tone-details: oColorsGetToneDetails('claret-80');
$color-name: map-get($tone-details, 'color-name'); // claret
$brightness: map-get($tone-details, 'brightness'); // 80

Links

oColorsMix(...)

Returns a color based on the background context and base color at the supplied percentage

parameter type default description
color (optional) black palette name of color
background (optional) paper palette name of background color
percentage (optional) 60 percentage opacity of the foreground color over the background

Returns

Links

oColorsGetTextColor(...)

Returns a text color based on the background and an opacity percentage the color should appear at

parameter type default description
background the color or palette color name of the background the text will appear on
opacity (optional) 100 the opacity percentage the text color should appear at
minimum-contrast (optional) 'aa-normal' the minimum contrast ratio standard between the background and the returned text color, one of: aa-normal, aa-large, aaa-normal, aaa-large. See [WCAG 2.1 guidelines](https://www.w3.org/TR/WCAG21/#contrast-minimum). If the contrast ratio is too low to meet the selected guideline an error is thrown. Set to `null` to remove contrast checking and never throw an error.

Returns

Links

oColorsColorBrightness(color)

Work out the brightness value in % of a color From: https://gist.github.com/jlong/f06f5843104ee10006fe

parameter type default description
color color value to get brightness from (either a CSS colour or o-colors palette colour name)

Returns

Links

oColorsColorLuminance(color)

Returns the luminance of $color as a float (between 0 and 1) 1 is pure white, 0 is pure black. From: https://css-tricks.com/snippets/sass/luminance-color-function/

parameter type default description
color The colour to return a luminance for (either a CSS colour or o-colors palette colour name)

Returns

Number - a number between 0 and 1

Links

oColorsGetContrastRatio(color-a, color-b)

Calculate the contrast ratio between two colours.

parameter type default description
color-a first colour to compare (either a CSS colour or o-colors palette colour name)
color-b second colour to compare (either a CSS colour or o-colors palette colour name) Based on the JS in https://github.com/LeaVerou/contrast-ratio/blob/gh-pages/contrast-ratio.js

Returns

Links

oColorsGetPaletteDetails

Get a list of palette colour details, including the colour name.

Returns

List - A list of maps with palette color details e.g. `(('name': 'paper'), ('name': 'o-example/storm')`

Links

oColorsSetColor(...)

Define a new palette color.

parameter type default description
color-name The name of the colour e.g. 'o-example/paper'.
color-value The colour to set e.g. #ff69b4.
opts (optional) () A map of options. Accepts a `deprecated` key with a message to deprecated a set colour e.g. `$opts: (deprecated: 'your deprecation message')`.

Examples

Example #1

Add a custom palette color

@include oColorsSetColor($color-name: 'o-example/pink', $color-value: #ff69b4);

Example #2

Deprecate a set colour (removing a color from the palette is considered a breaking change and requires a major release).

@include oColorsSetColor (
	$color-name: 'o-example/pink',
	$color-value #ff69b4,
	$opts: (
		'allow-tones': true,
		'deprecated': 'your deprecation message'
	)
);

Links

oColorsSetUseCase(...)

Add a custom use case property.

parameter type default description
usecase The name of the usecase, e.g. 'page'.
colors A map of properties ('text', 'background', 'border', or 'outline') to a color.
opts (optional) () A map of options. Accepts a `deprecated` key with a deprecation message for the usecase e.g. `$opts: (deprecated: 'your deprecation message')`, or a map to deprecate a specific property e.g. `(deprecated: (background: 'your deprecation message'))`.

Examples

Example #1

a 'stripe' usecase with background, text, and border colour within a component 'o-example'.

@include oColorsSetUseCase('o-example/stripe', (
	'text': 'white',
	'background': 'black',
	'border': 'black-50'
));

Example #2

a custom colour to a 'stripe' usecase with background.

@include oColorsSetColor('o-example/my-pink', #ff69b4);
@include oColorsSetUseCase('o-example/stripe', (
	'background': 'o-example/my-pink',
));

Example #3

all usecase properties (removing a colour usecase is a breaking change).

@include oColorsSetUseCase('o-example/stripe', (
	'text': 'white',
	'background': 'black',
	'border': 'black-50'
), (deprecated: 'o-example has no stripes anymore.'));

Example #4

particular usecase properties e.g. "border" (removing a usecase property is a breaking change).

  @include oColorsSetUseCase('o-example/stripe', (
   		'text': 'white',
   		'background': 'black',
   		'border': 'black-50',
), ('deprecated': ('border': 'o-example stripes have no border anymore.')));

Links

o-colors-is-silent

Silent mode

Links

oColors(opts)

Output o-colors CSS.

parameter type default description
opts The o-colors features to output. See the [readme](https://registry.origami.ft.com/components/o-colors) for a full list of options.

Examples

Example #1

all o-colors styles.

@include oColors();

Example #2

only o-colors CSS custom properties ("CSS variables") for palette colours and usecases.

@include oColors($opts: (
	'palette-custom-properties': true,
	'usecase-custom-properties': true
));

Example #3

only o-colors classes for usecases.

@include oColors($opts: (
	'usecase-classes': true
));

Links

Support Status
active
Switch component view

GitHub Repository

Install o-colors

If using the Build Service, add o-colors@^5.2.6 to your link tag.

If running a Manual Build, run bower install --save "o-colors@^5.2.6".

Help & Support

o-colors is maintained directly by the Origami team. If you have any questions about o-colors or Origami in general, we are happy to help. 😊

Slack: #origami-support
Email: origami.support@ft.com

Feedback / Issues

To report a bug or request features please create an issue on Github. For support or general feedback please get in touch 😊

Slack: #origami-support
Email: origami.support@ft.com