Apply styling to the core components

How do I write styles?

There are two methods that we recommend to style our core components.

The simple method uses the global CSS variables for global styling across all core components. These variables are simple to change and are applied across all components. They are, however, more limited in what they can do. You can change basic colors and have limited control over the font and font sizes used. Styling your components using these variables has the advantage that newly released components will inherit these color configurations automatically when new components are released.

The advanced method is by overriding an individual component’s CSS. This allows finer control of what you can change but requires greater knowledge of web development and needs to be written for each component.

Simple method

We have configured our components CSS to allow overriding some basic styling via CSS variables These variable allow you to set a basic starting colours which all components will make use of in some way, not all components make use of all variables but most do in some way.

To find out what variables effect what in a component you can experiment by changing the values and observing what effect it has on the page or you can make use of your browsers development mode to inspect the elements of the page and determine if they are deriving a value from a specific CSS variable or not.

Fonts

You can control the basic font sizes used or the primary font for most components. The styles below values are the general defaults used across all components. These can be changed to allow you to set a smaller or larger font size, or an alternative font family to use.

--squiz-global-font-family: 'IBM Plex Sans', sans-serif;
--squiz-global-font-size-xss: 0.75rem;
--squiz-global-font-size-xs: 1rem;
--squiz-global-font-size-s: 1.25rem;
--squiz-global-font-size-m: 1.5rem;
--squiz-global-font-size-l: 2rem;
--squiz-global-font-size-xl: 3rem;
--squiz-global-font-size-xxl: 4rem;
--squiz-global-line-height-xss: 1rem;
--squiz-global-line-height-xs: 1.5rem;
--squiz-global-line-height-s: 1.625rem;
--squiz-global-line-height-m: 2rem;
--squiz-global-line-height-l: 2.75rem;
--squiz-global-line-height-xl: 4rem;
--squiz-global-line-height-xxl: 5.25rem;

Light / dark themes

Most components allow you to select a dark or light theme. The styling for these themes are controlled using the variables below, allowing you to specify the colours used by each of these themes. These variables must use a valid CSS colour name or a valid colour hex value. For example: * white; or * #ffffff.

/* Light theme */
--squiz-global-theme-light-color: <css colour code or name>;
--squiz-global-theme-light-background: <css colour code or name>;
--squiz-global-theme-light-button-color: <css colour code or name>;
--squiz-global-theme-light-button-background: <css colour code or name>;
--squiz-global-theme-light-button-hover-color: <css colour code or name>;
--squiz-global-theme-light-button-hover-background: <css colour code or name>;
/* Dark theme */
--squiz-global-theme-dark-color: <css colour code or name>;
--squiz-global-theme-dark-background: <css colour code or name>;
--squiz-global-theme-dark-button-color: <css colour code or name>;
--squiz-global-theme-dark-button-background: <css colour code or name>;
--squiz-global-theme-dark-button-hover-color: <css colour code or name>;
--squiz-global-theme-dark-button-hover-background: <css colour code or name>;

Non theme colours

Not all components use the themes, and some use additional styles. . For example, the color used for links. These variables must use a valid CSS colour name or a valid colour hex value. For example: * white; or * #ffffff.

--squiz-global-default-link-color: <css colour code or name>;
--squiz-global-default-color: <css colour code or name>;
--squiz-global-default-background: <css colour code or name>;
--squiz-global-default-background-hover: <css colour code or name>;
--squiz-global-default-border: <css colour code or name>;

--squiz-global-default-button-color: <css colour code or name>;
--squiz-global-default-button-background: <css colour code or name>;
--squiz-global-default-button-color-hover: <css colour code or name>;
--squiz-global-default-button-background-hover: <css colour code or name>;

Advanced method

How we style our components?

Squiz components use a CSS framework called CSS Modules to scope all the class names used locally for components. This prevents the styles from affecting other classes that are already applied to your website.

CSS Modules dynamically generates the class names based on the styling contents of the class, so the exact class names will change over time as changes are made to components. This means you should not override or attach styles directly to the classes as these are likely to change over time.

How do we recommend you style our components?

Dynamically generated class names do not prevent you from applying your own styling, it just requires a different way of making the changes.

Normally for a dropdown you would have a simple class (like dropdown) applied to it which you could use when defining your custom styling. The CSS classes for Squiz components are similar to _dropdown_ct70p_2, because they are generated. In new versions of the components, the ct70p_2 part of the class can change.

CSS has a useful feature called attribute selectors to allow styling of these dynamic class names. These selectors can include a special * character, which matches one occurrence of a value in an attribute allowing you to style an element which has a class that starts with a given pattern. This means we can style our dropdown element using the css selector [class*="_dropdown_"].

Example: recommended approach
[class*="_dropdown_"]{
    background-color: red;
}
Example: don’t do this
._dropdown_ct70p_2{
    background-color: red;
}

Shared classes in our components

Some CSS classes are shared between Squiz components . For example, _modal_1f8g2_1. This is because we have some shared code features that centralizes logic to make testing and updates easier for us. Since CSS Modules generates the hash portion of the class name from the contents of the styling these are safely shared.

However, it is possible that two of our components may use two different versions of the underlying functionality. This works as each has a self-contained copy of the logic but if there are styling differences between these two versions they may share some classes but others might differ in the hash value.

You can add styling to these classes as a shortcut to apply styling across these shared features but its possible due to version differences that there may be clashes in the CSS that will need updates.

How do I include these styles on the page with the component?

Add the styles created following the guidelines above to you Matrix site along with the rest of your site styles.