o-brand
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. A brand may be thought of as a theme, but branded components may provide unique features as well as a distinct appearance.
Brands include:
- master: FT branding for public ft.com sites and affiliates.
- internal: Style suitable for internal products, tools, and documentation.
- whitelabel: Base, structural styles only.
Variant
A variant is an addition or modification to a component within a given brand. 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.
Sass
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. Projects which consume branded Origami components may choose a brand by setting the $o-brand
variable.
The following mixins and functions help brand a component.
oBrandGetCurrentBrand
This function will return the brand defined at a product level.
If $o-brand
has been defined by a project oBrandGetCurrentBrand
will return that value.
$o-brand: internal // Defined in the product using branded Origami components.
$chosen-brand: oBrandGetCurrentBrand();
If it has not yet been defined, it will provide a default brand (master).
$chosen-brand: oBrandGetCurrentBrand();
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
.
Where $component
is the component's name; $brand
is one of "master", "internal", or "whitelabel"; and $config
is a map which comprises of variables and supported variants:
@if oBrandGetCurrentBrand() == 'master' {
@include oBrandDefine($component, $brand, $config);
}
Note: oBrandDefine
should be used in conjunction with oBrandGetCurrentBrand
, to define only the requested brand.
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'
)
);
- Variable names must be a string and should be alphanumeric, including dashes e.g.
example-background
. - Variable names should not match css properties exactly e.g.
example-background
over background
. - A variant must be an alphanumeric string e.g.
inverse
, b2b-inverse
.
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'
);
Variant support can then be checked using oBrandSupportsVariant.
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.
@if oBrandGetCurrentBrand() == 'master' {
@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. First create a private, component-specifc function which calls oBrandGet
, e.g. for a component o-example
, create _oExampleGet
:
@function _oExampleGet($variables, $from: null) {
@return oBrandGet($component: 'o-example', $variables: $variables, $from: $from);
}
Your new component specifc function _oExampleGet
can then be used to fetch variables. E.g. building on the oBrandDefine
example:
.o-example {
background: _oExampleGet($variables: 'example-background');
}
It is possible to request multiple variables:
.o-example {
border: _oExampleGet($variables: ('example-border-width', 'example-border-type', 'example-border-color'));
}
To retrieve a variable for a variant use the $from
argument:
.o-example--inverse {
background: _oExampleGet($variables: 'example-background', $from: 'inverse');
}
The $from
argument also accepts a custom variant:
$custom-variant: (
'example-background': 'hotpink',
'example-border-width', '2px'
);
.o-example--custom {
background: _oExampleGet($variables: 'example-background', $from: $custom-variant);
border-width: _oExampleGet($variables: 'example-border-width', $from: $custom-variant);
}
oBrandGet
returns null
if a variable is undefined. Sass removes css properties which are set to null
. This is a useful feature to conditionally output css properties for different variants.
oBrandSupportsVariant
To check if a brand supports a variant call oBrandSupportsVariant
. First create a private, component-specifc function which wraps oBrandSupportsVariant
, e.g. for a component o-example
, create _oExampleSupports
:
@function _oExampleSupports($variant) {
@return oBrandSupportsVariant($component: 'o-example', $variant: $variant);
}
Then call your new function _oExampleSupports
to determine whether to output CSS for a variant or not. E.g. to only output the inverse
variant if the brand supports it:
@if _oExampleSupports($variant: 'inverse') {
.o-example--inverse {
background: _oExampleGet($variables: 'example-background', $from: 'inverse');
}
}
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.
Example Component (o-example):
@mixin oExampleCustomize($variables) {
@include oBrandCustomize('o-example', $variables);
}
@if oBrandGetCurrentBrand() == 'whitelabel' {
@include oBrandDefine('o-example', 'whitelabel', (
'variables': (
example-background: white,
example-color: black,
),
'supports-variants': ()
));
}
Example Project:
$o-brand: 'whitelabel';
@import 'o-table/main';
@include oExampleCustomize((
example-background: lightblue
));
@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.