@financial-times/o-colors

    6.4.0 • Public • Published

    o-colors MIT licensed

    A component to manage colours. Includes the FT colour palette.

    Usage

    Check out how to include Origami components in your project to get started with o-colors.

    Markup

    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">
    	<!-- default background colour set -->
    	<!-- e.g. for the core brand `background: #fff1e5;` -->
    </body>

    More colours are available for build service users as CSS Custom Properties.

    CSS Custom Properties

    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);
    }

    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 '@financial-times/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 core, internal, whitelabel
    white core, internal, whitelabel
    oxford core, internal
    teal core, internal
    slate core, internal,
    lemon core, internal,
    jade core, internal
    mandarin core, internal
    crimson core, internal
    paper core
    claret core
    wheat core
    sky core
    velvet core
    candy core
    wasabi core
    light-blue core
    graphics-dark-blue core
    ft-pink (previously brand-ft-pink) core
    ft-grey core
    org-b2c core
    org-b2c-dark core
    org-b2c-light core

    There are additional colours in the palette by default including tones and mixes. See the registry demos for a full list.

    ft-pink and ft-grey are brand colours which are used in some digital assets, such as the FT logo, but have a limited number of valid use-cases for digital UI. Instead consider paper and slate or a black/paper mix such as black-80. As an example of a usecase for ft-pink, it could be used to prevent a flash of the wrong colour as a logo image loads.

    Default Palette Colours

    Get a default colour from the palette using oColorsByName.

    .example {
    	// Get a default o-colors palette colour.
    	background: oColorsByName('paper');
    }

    Custom Palette Colours

    To set a custom palette colour to share with other components call oColorsSetColor. Colour names must be namespaced for the project or component using a forward slash.

    // Set a custom palette colour within a project `o-example`.
    @include oColorsSetColor(
    	$color-name: 'o-example/myhotpink',
    	$color-value: #ff69b4
    );
    
    .example {
    	// Get a custom palette colour from a project `o-example`.
    	background: oColorsByName('o-example/myhotpink');
    }

    By default custom colours do not allow tones to reduce the number of colours used within a project. To allow tones set the allow-tones option.

    // Set a custom palette colour within a project `o-example`,
    // which allows tones of the same colour.
    @include oColorsSetColor(
    	$color-name: 'o-example/myhotpink',
    	$color-value: #ff69b4,
    	$opts: ('allow-tones': true)
    );
    
    .example {
    	// Get a toned custom palette colour from a project `o-example`.
    	background-color: oColorsGetTone('o-example/myhotpink', 80);
    }

    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.

    // Deprecate a custom colour, which will be removed in a future major release.
    @include oColorsSetColor(
    	$color-name: 'o-example/myhotpink',
    	$color-value #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 core, internal, whitelabel
    focus outline core, internal
    box background core, internal
    link text core, internal
    link-hover text core, internal
    link-title text core, internal
    link-title-hover text core, internal
    title text core, internal
    body text core, internal
    muted text core, internal
    tag-link text core
    tag-link-hover text core
    opinion-tag-link text core
    opinion-tag-link-hover text core
    opinion background core
    hero background core
    hero-opinion background core
    hero-highlight background core
    Section colors
    section-life-arts all core
    section-life-arts-alt all core
    section-magazine all core
    section-magazine-alt all core
    section-house-home all core
    section-house-home-alt all core
    section-money all core
    section-money-alt all core

    Default Usecases

    To get a colour for a default usecase call oColorsByUsecase.

    	html {
    		// get the background colour for the page usecase
    		background: oColorsByUsecase('page', 'background');
    	}
    
    	.paragraph {
    		// get the text colour for the body usecase
    		color: oColorsByUsecase('body', 'text');
    	}

    Custom Usecase

    To create a new usecase call oColorsSetUseCase.

    • $usecase: The name of the usecase, e.g. 'page'. This must include a namespace for your component or project followed by a forward slash.
    • $colors: A map of properties ('text', 'background', 'border', or 'outline') to a palette color name.
    • $opts (optional):
      • deprecated: A deprecation message for the usecase.
    	// set colours for a "stripes" in o-example.
    	@include oColorsSetUseCase('o-example/stripes', (
    		'text': 'white',
    		'background': 'black',
    		'border': 'black-50'
    	));

    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:

    	// deprecate all usecase properties for the o-example custom usecase "stripes".
    	@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:

    	// deprecate only the background property for the o-example custom usecase "stripes".
    	@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');
    	// Get a text colour for a teal background
    	color: oColorsGetTextColor('teal');
    }
    .example {
    	background: oColorsByName('teal');
    	// Get a text colour for a teal background,
    	// with greater than usual opacity (80)
    	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');
    	// Get a text colour for a teal background,
    	// enforce a lower level of contrast "large text".
    	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); // same as black-30

    But two colours may be given. For example to mix claret over slate at 20%:

    $color: oColorsMix($color: 'claret', $background: 'slate', $percentage: 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. If your project has defined custom colours using oColorsSetColor, these may be toned by setting the allow-tones option.

    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

    State Major Version Last Minor Release Migration guide
    active 6 N/A migrate to v6
    maintained 5 N/A migrate to v5
    ╳ deprecated 4 4.10 migrate to v4
    ╳ deprecated 3 3.6 migrate to v3
    ╳ deprecated 2 2.5 migrate to v2
    ╳ deprecated 1 1.1 migrate to v1
    ╳ deprecated 0 0.2 N/A

    Contact

    If you have any questions or comments about this component, or need help using it, please either raise an issue, visit #origami-support or email Origami Support.


    Licence

    This software is published by the Financial Times under the MIT licence.

    Install

    npm i @financial-times/o-colors

    DownloadsWeekly Downloads

    2,461

    Version

    6.4.0

    License

    MIT

    Unpacked Size

    117 kB

    Total Files

    37

    Last publish

    Collaborators

    • emmalewis
    • aendra
    • briggsc
    • the-ft
    • quarterto
    • rowanmanning
    • mattandrews
    • jakedchampion
    • sdbernard
    • bobhaslett
    • joannaskao
    • robinmarr-ft
    • ft-internal-products
    • chee
    • notlee
    • tatiana.stantonian
    • conor-mullen
    • alexwilson