Origami Frontend Components & Services

Readme: o-brand

o-brand is experimental. This component is not guaranteed to be ready for production use, and the API should be considered unstable.

Tools to tailor Origami components for distinct use cases.

⚠️ Non-Origami projects must not depend on o-brand directly.

Terms

Brand

A brand represents an environment which requires components to offer a distinct appearance or unique functionality.

Brands include:

Variant

A variant is an addition or modification to a component within a given brand. A variant may also alter the appearance and/or functionality of a component. Variants must be optional and build upon a fully functional component.

E.g. A button component may have an "inverse" variant, a "big" variant, etc. A header component may have a "subnav" variant, a "sticky" variant, etc.

Motivation

As of March 2018 Origami components provide master brand specific styles inconsistently. Some components aim to provide a generic foundation for visually distinct clients to build upon, e.g. o-table, but include CSS classes which unpredictably introduce heavy "master" brand specific styles. This means some clients need to manually override "master" brand styles with extra CSS. It also means a non-masterbrand client cannot be confident that new "master" brand styles will not creep in over time.

Branded components aim to provide styles for "master" and "internal" branded products which are immediately usable with little or no modification. For products where those do not apply a "whitelabel" brand provides a reliable foundation with little visual styling to build upon.

Sass

The default brand is master. Projects which consume branded Origami components may choose a different brand. To do so set the SCSS variable $o-brand.

Mixins within o-brand help configure components to support brands. There is no configuration in o-brand. It provides the mechanisms for components to apply their own brand support.

The following mixins and functions help brand a component.

oBrandGetCurrentBrand

This function will return the brand defined at a product level, or can be used to define a brand to be used within a component for conditional logic.

If $o-brand has been previously defined, it can be used like this:

$o-brand: internal //defined in the product using the component

$chosen-brand: oBrandGetCurrentBrand(); //returns 'internal'

If it has not yet been defined, it will provide a default brand: master.

//$o-brand is undefined

$chosen-brand: oBrandGetCurrentBrand(); //returns 'master'

oBrandDefine

Components are individually responsible for defining the configuration for each brand they support. In order to add configuration for a new brand, use the mixin oBrandDefine.

Brand configuration comprises of variables and supported variants. As explained below.

@include oBrandDefine($component: 'o-example', $brand: 'master', (
    'variables': $variables,
    'supports-variants': $supports-variants
));

This can also be used in conjunction with oBrandGetCurrentBrand to define a component conditionally:

$chosen-brand: oBrandGetCurrentBrand();

@if $chosen-brand == 'master' {
    @include oBrandDefine($component: 'o-example', $brand: $chosen-brand, (
        'variables': $variables,
        'supports-variants': $supports-variants
    ));
}

Brand Variables

Brand variables configure a component for a brand. E.g. a component o-example might define a variable example-background to configure its background colour.

$variables: (
    example-background: 'paper'
);

A nested map configures a variant, which may provide new variables or a different value for an existing variable. E.g. for an inverse variant which has a different value for the variable example-background:

$variables: (
    example-background: 'paper',
    'inverse': (
        example-background: 'slate'
    )
);

Supported Variants

To indicate a brand should support a variant, add the variant name to the supports-variants list.

E.g. To configure support for "inverse" and "b2b" variants:

$supports-variants: (
    'inverse',
    'b2b'
);

These ensures support for a variant which sets no variables can be determined.

A Complete oBrandDefine Example

The below example defines a master brand for the component o-example. We define four variables including example-background, but we provide a different example-background value for the inverse and b2b variants. Using the supports-variants list we explicitly state the master brand supports both of these variants.

@include oBrandDefine('o-example', 'master', (
    'variables': (
        example-background: 'paper',
        example-border-width: 1px,
        example-border-type: solid,
        example-border-type: grey,
        'inverse': (
            example-background: 'slate'
        )
        'b2b': (
            example-background: 'lightblue'
        )
    ),
    'supports-variants': (
        'inverse',
        'b2b'
    )
));

oBrandGet

Use oBrandGet to retrieve a brand variable.

E.g. building on the oBrandDefine example:

.o-example {
    background: oBrandGet($component: 'o-example', $variables: 'example-background'); // background: paper;
}

It is possible to request multiple variables:

.o-example {
    border: oBrandGet($component: 'o-example', $variables: ('example-border-width', 'example-border-type', 'example-border-color')); // border: 1px solid grey;
}

To retrieve a variable for a variant use the $from argument of oBrandGet.

.o-example--inverse {
    background: oBrandGet($component: 'o-example', $variables: 'example-background', $from: 'inverse'); // background: slate;
}

The $from argument oBrandGet also accepts a custom variant:

$custom-variant: (
    'example-background': 'hotpink',
    'example-border-width', '2px'
);

.o-example--custom {
    background: oBrandGet($component: 'o-example', $variables: 'example-background', $from: $custom-variant); // background: hotpink;
    border-width: oBrandGet($component: 'o-example', $variables: 'example-border-width', $from: $custom-variant); // border-width: 2px;
}

oBrandSupportsVariant

To check if a brand supports a variant call oBrandSupportsVariant.

E.g. only output the inverse variant if the brand supports it:

@if oBrandSupportsVariant($component: 'o-example', $variant: 'inverse') {
    .o-example--inverse {
        background: oBrandGet($component: 'o-example', $variables: 'example-background', $from: 'inverse'); // background: slate;
    }
}

oBrandCustomize

oBrandCustomize allows existing brand variables to be modified, so long as those variables have been defined with oBrandDefine. This customisation is component-specific, so a branded component must wrap oBrandCustomize within a mixin of its own, as o-brand must not be used directly outside Origami components.

Currently only the whitelabel brand is allowed to be customised in this way.

Example Component (o-example):

/// Create a component-specific mixin to wrap `oBrandCustomize`.
@mixin oExampleCustomize($variables) {
    @include oBrandCustomize('o-example', $variables);
}

// Define the whitelabel brand for the component.
@include oBrandDefine('o-example', 'whitelabel', (
    'variables': (
        example-background: white,
        example-color: black,
    ),
    'supports-variants': ()
));

Example Project:

$o-brand: 'whitelabel';
@import 'o-table/main';

// Customise the example component.
// Here we change the variable "example-background" from "white" to "lightblue".
// The "example-color" variable has not been customised so remains "black".
@include oExampleCustomize((
    example-background: lightblue
));

// Output the example component CSS.
@include oExample();

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.

Switch component view

GitHub Repository

Install o-brand

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

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

Help & Support

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

Slack: #ft-origami
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: #ft-origami
Email: origami.support@ft.com