# `@salesforce-ux/sds-styling-hooks`
## About
Global Styling hooks use CSS custom properties which make it easy to customize application-wide styling.
### Table of Contents
- [Installation](#installation)
- [Add SDS Global Hooks in HTML](#add-sds-global-hooks-in-html)
- [Add SDS Global Hooks in CSS](#add-sds-global-hooks-in-css)
- [File Formats](#file-formats)
- [Usage Guidelines](#usage-guidelines)
- [Color](#color)
- [Using Color Relationships for UIs](#using-color-relationships-for-uis)
- [Generic Palettes](#generic-palettes)
- [Typography](#typography)
- [Font Family](#font-family)
- [Font Sizes](#font-sizes)
- [Font Styles](#font-styles)
### Relevant links (external)
- Non-normative Specifications
- [Global Styling Hooks](https://github.com/salesforce-ux/salesforce-design-system/blob/main/rfcs/text/0000-global-styling-hooks.md)
- [Component Styling Hooks](https://github.com/salesforce-ux/salesforce-design-system/blob/main/rfcs/text/0000-component-styling-hooks.md)
- Styling Hooks Documentation
- [Styling Hook Rules](https://github.com/salesforce-ux/salesforce-design-system/blob/main/docs/src/content/guide/styling-hooks.md#the-simple-rules)
- [Styling Hook Naming Conventions](https://github.com/salesforce-ux/salesforce-design-system/blob/main/docs/src/content/guide/styling-hooks.md#styling-hooks-naming-conventions)
- [How to use Styling Hooks in your Sub-system](https://github.com/salesforce-ux/salesforce-design-system/blob/main/docs/src/content/guide/customizations.md)
## Installation
Use [npm][npm] to install the [SDS Global Styling Hooks](https://www.npmjs.com/package/@salesforce-ux/sds-styling-hooks):
```bash
npm install --save-dev @salesforce-ux/sds-styling-hooks
```
### Add SDS Global Hooks in HTML
You can use the HTML `` to link to SDS Global Styling Hooks as an external resource.
```html
```
### Add SDS Global Hooks in CSS
You can use CSS `@imports` to pull in SDS Global Styling Hooks.
```css
:root {
@import "@salesforce-ux/sds-styling-hooks/dist/hooks.custom-props.css";
}
body {
/* Directly reference SDS Styling Hook */
background: var(--sds-g-color-neutral-base-50);
}
```
### File Formats
SDS Styling Hooks have 6 different file formats for consumption. All files are located in `/dist/`.
#### JSON (`*.json`)
```json
{
"PROP_NAME": "PROP_VALUE"
}
```
#### Raw JSON (`*.raw.json`)
```js
{
"props": {
"PROP_NAME": {
"value": "PROP_VALUE",
"type": "PROP_TYPE",
"category": "PROP_CATEGORY",
/* additional metadata */
}
}
}
```
#### Common JS (`*.js`)
```js
module.exports = {
propName: "PROP_VALUE"
};
```
#### ES Module (`*.js`)
```js
export const propName = "PROP_VALUE";
```
#### Custom Properties scoped to `:root` (`*.css`)
```css
:root {
--prop-name: PROP_VALUE;
}
```
#### Custom Property Registration using [CSS Properties and Values API](https://drafts.css-houdini.org/css-properties-values-api-1/) (`*.js`)
> **Experimental**
>
> This is an experimental technology
>
> Check the [Browser compatibility table](https://caniuse.com/mdn-api_css_registerproperty) carefully before using this in production.
For more information, see [CSS Properties and Values API Level 1](https://drafts.css-houdini.org/css-properties-values-api-1/).
```js
if (CSS.registerProperty) {
CSS.registerProperty({
name: "--prop-name",
syntax: "PROP_SYNTAX",
inherits: false,
initialValue: "PROP_VALUE",
});
}
```
## Usage Guidelines
### Color
The Salesforce Design System comes with a robust color system and relationships to ensure our UIs meet [WCAG 2.1 contrast ratios of 4.5:1](https://www.w3.org/TR/WCAG21/#contrast-minimum). 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](https://www.boronine.com/2012/03/26/Color-Spaces-for-Human-Beings/), which are designed to accord with human perception of color.
#### Using Color Relationships for UIs
The Salesforce 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 13 color values. The base group defaults to "light" UI elements.
[View all system colors →](https://design-system-services.herokuapp.com/?path=/story/salesforce-design-system-styling-hooks-global-colors--system-values)
**Neutral**
```css
--sds-g-color-neutral-base-100
--sds-g-color-neutral-base-95
--sds-g-color-neutral-base-90
--sds-g-color-neutral-base-80
--sds-g-color-neutral-base-70
--sds-g-color-neutral-base-65
--sds-g-color-neutral-base-60
--sds-g-color-neutral-base-50
--sds-g-color-neutral-base-40
--sds-g-color-neutral-base-30
--sds-g-color-neutral-base-20
--sds-g-color-neutral-base-15
--sds-g-color-neutral-base-10
```
**Brand**
```css
--sds-g-color-brand-base-100
--sds-g-color-brand-base-95
--sds-g-color-brand-base-90
--sds-g-color-brand-base-80
--sds-g-color-brand-base-70
--sds-g-color-brand-base-65
--sds-g-color-brand-base-60
--sds-g-color-brand-base-50
--sds-g-color-brand-base-40
--sds-g-color-brand-base-30
--sds-g-color-brand-base-20
--sds-g-color-brand-base-15
--sds-g-color-brand-base-10
```
**Golden Rule for Relationships**
Regardless of the set, neutral or brand, there is a golden rule to ensure the color relationships are retained;
Each palette contains a relationship of base and contrasting values. Whatever is the predominate color accent you are trying to achieve WCAG 2.1 color contrast for, you will start in that color palette.
The color system is meant to provide valid color relationships for background to foreground color values. This includes text and non-text glyphs.
The green lines highlight the relationships that pass AAA color contrast requirements and the yellow lines are designated for AA.
If a design crosses into another color palette, it is up to the designer to find the corresponding color value that passes color contrast requirements.
#### Reference Palettes
[View all reference colors →](https://design-system-services.herokuapp.com/?path=/story/salesforce-design-system-styling-hooks-global-colors--reference-values)
The Salesforce Design System provide reference color palettes to use in your designs. These values are generated in the [HCL color space](https://www.boronine.com/2012/03/26/Color-Spaces-for-Human-Beings/), 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 programmically alter if your application requires different themes such as dark mode or high contrast mode.
### Typography
#### Font Family
[View Font Families →](https://design-system-services.herokuapp.com/?path=/story/sds-styling-hooks-typography--font-family)
The Salesforce Design System defaults to use system fonts, this improves performance and legibility on the content based on the device being used. We provide two styling hooks for font families, one of the body text content and one for the heading text of your document.
**Body Text Content**
```css
--sds-g-font-family
```
**Heading Text Content**
```css
--sds-s-heading-font-family
```
**Font Stack**
```css
font-family: -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, 'Helvetica Neue', Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol';
```
#### Font Sizes
[View Font Sizes →](https://design-system-services.herokuapp.com/?path=/story/sds-styling-hooks-typography--font-size)
The Salesforce 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](https://www.modularscale.com/?1&rem&1.125), 8:9 scale ratio with the base font size starting at 1rem or 16px. The scale offers 10 font sizes larger than the base and 4 font sizes smaller than the base.
[npm]: https://www.npmjs.com/