@salesforce-ux/wes-styling-hooks

v0.0.2

Published

a year ago

Global Styling hooks for WES use CSS custom properties which make it easy to customize application-wide styling.

Downloads

1,418

0High
0Medium
0Low

salesforce-ux

`@salesforce-ux/wes-styling-hooks`

About

Global Styling hooks for WES use CSS custom properties which make it easy to customize application-wide styling.

Getting Started

Let's start by installing wes-styling-hooks as a dependency of your project with npm.

npm i @salesforce-ux/wes-styling-hooks

Distributable

Integration

There are different ways to include wes-styling-hooks to a web application depending on the requirement. If you are using the Salesforce Experience Cloud platform, WES is supported through an Unlocked Package, see the Confluence page for the WES Unlocked Package. It can be used in both light DOM and shadow DOM Below are the styles to include the package -

Add WES Styling Hooks in HTML

You can use the HTML <link> to link to WES Styling Hooks as an external resource.

<html>
  <head>
    <link rel="stylesheet" href="/node_modules/@salesforce-ux/wes-styling-hooks/dist/hooks.custom-props.css">
    <!-- Your application's stylesheets go below -->
    <link rel="stylesheet" href="...">
  </head>
  <body>
    <!-- Your application -->
  </body>
</html>

Add WES Styling Hooks in CSS

You can use CSS @imports to pull in WES Styling Hooks.

:root {
  @import "@salesforce-ux/wes-styling-hooks/dist/hooks.custom-props.css";
}

body {
  /* Directly reference WES Styling Hook */
  background: var(--wes-g-color-neutral-base-1);
}

Add WES Styling Hooks in JS

You can use JS import to pull in WES Styling Hooks directly in the JS file.

import "@salesforce-ux/wes-styling-hooks/dist/hooks.custom-props.css";

Interactive Demo

To see more examples with interactive demo, please visit wes Subsytem's Storybook Environment

File Formats

WES Styling Hooks have 6 different file formats for consumption. All files are located in /dist/.

JSON (`*.json`)

{
  "PROP_NAME": "PROP_VALUE"
}

Raw JSON (`*.raw.json`)

{
  "props": {
    "PROP_NAME": {
      "value": "PROP_VALUE",
      "type": "PROP_TYPE",
      "category": "PROP_CATEGORY",
      /* additional metadata */
    }
  }
}

Common JS (`*.js`)

module.exports = {
  propName: "PROP_VALUE"
};

ES Module (`*.js`)

export const propName = "PROP_VALUE";

Custom Properties scoped to `:root` (`*.css`)

:root {
  --prop-name: PROP_VALUE;
}

Custom Property Registration using CSS Properties and Values API (`*.js`)

Experimental
This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

For more information, see CSS Properties and Values API Level 1.

if (CSS.registerProperty) {
  CSS.registerProperty({
    name: "--prop-name",
    syntax: "PROP_SYNTAX",
    inherits: false,
    initialValue: "PROP_VALUE",
  });
}

Usage Guidelines

Color

The WES Design System comes with a robust color system and relationships to ensure our UIs meet WCAG 2.1 contrast ratios of 4.5:1. The semantic relationships allow for easy theme switching to handle features such as dark mode or high contrast mode.

Additionally, we generate sets of vibrant color palettes to use as accents in your designs. These values are generated in the HCL color space, which are designed to accord with human perception of color.

Using Color Relationships for UIs

View UI color relationships →

The WES Design System offers a set of neutral and brand color relationships. These two sets are intended to be used on your UI elements to define properties such as backgrounds, borders and text.

Each set, neutral and brand, have two groupings called base and inverse. The base group defaults to "light" UI elements. The inverse color group are the opposite values of the base group, these default to "dark" UI elements.

Neutral

--wes-g-color-neutral-base-1
--wes-g-color-neutral-base-2
--wes-g-color-neutral-base-3
--wes-g-color-neutral-base-4

--wes-g-color-neutral-base-contrast-1
--wes-g-color-neutral-base-contrast-2
--wes-g-color-neutral-base-contrast-3
--wes-g-color-neutral-base-contrast-4

Brand

--wes-g-color-brand-base-1
--wes-g-color-brand-base-2
--wes-g-color-brand-base-3
--wes-g-color-brand-base-4

--wes-g-color-brand-base-contrast-1
--wes-g-color-brand-base-contrast-2
--wes-g-color-brand-base-contrast-3
--wes-g-color-brand-base-contrast-4

Each group contains 8 color values; 4 of which are the default color values for that group and 4 are the contrast variants. These hold the color relationships in the set.

An image showing the color mappings for UI color relationships

Golden Rule for Relationships

Regardless of the set, neutral or brand, there is a golden rule to ensure the color relationships are retained;

When you use a base or inverse value as your background color, a contrast value in that group is required to be used on top of that background, i.e., if base-2 is the background, then base-contrast-2 is your text color. If inverse-1 is the background, then inverse-contrast-1 is your text color.
The second requirement is to use the correct number value. You can only use a contrast value where the number is equal to or greater than the background color number value, i.e. if base-2 is the background, then base-contrast-2, base-contrast-3, base-contrast-4 as your text will always ensure a 4.5:1 contrast ratio.

An image showing the neutral color UI relationships

Generic Palettes

View all color palettes →

The WES Design System provide generic color palettes to use in your designs. These values are generated in the HCL color space, which are designed to accord with human perception of color.

Important usage note
If you use a color from these palettes on a UI element, you are responsible to ensure proper contrast ratio between the background and text. Additionally, the color cannot be programmatically alter if your application requires different themes such as dark mode or high contrast mode.

An image showing the indigo color UI relationships

Typography

Font Family

View Font Families →

The WES Design System uses different font-families based on the design context. We provide three styling hooks for font families.

Font Family Styling hooks and Font Stack

--wes-g-font-family-display: 'ITC Avant Garde', system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, 'Noto Sans', sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji';

--wes-g-font-family-sans: 'Salesforce Sans', system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, 'Noto Sans', sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji';

--wes-g-font-family-monospace: Consolas, Menio, Monaco, Courier, monospace;

Font Sizes

View Font Sizes →

The WES Design System offers a robust palette of font sizes. Our font sizes are independent of semantics so they are intended to be used for visual hierarchy. The sizes are based off a major second scale, 8:9 scale ratio with the base font size starting at 0.75rem or 12px. The scale offers 10 font sizes.

An image showing the font scale

Font Styles

Spacing

The WES Design System offers spacings to control the amount of space for details within a component.

View Spacing Code →

An image showing the spacing scale

Shadows

The WES Design System offers shadows to highlight difference in elevations between components

View Shadows Code →

An image showing the shadow scale

Radius

The WES Design System offers border radius that can be applied on the element.

View Radius Code →

An image showing the radius scale

Sizing

The WES Design System offers border sizing that can be applied on the element.

View Sizing Code →

An image showing the sizing scale

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme