From 1842e596cbe89f83ef960100f1be9cc59a3b4225 Mon Sep 17 00:00:00 2001 From: mark-tate <143323+mark-tate@users.noreply.github.com> Date: Wed, 4 Sep 2024 21:30:44 +0100 Subject: [PATCH] - renamed reusable-design to best-practices as this creates more of a shared responsibility - provided an overview of the options to theming, which is intended to link out to other docs - re-formatted as a set of do's and don't --- site/docs/theming/best-practices.mdx | 124 ++++++++++++++++++++++++++ site/docs/theming/reusable-design.mdx | 41 --------- 2 files changed, 124 insertions(+), 41 deletions(-) create mode 100644 site/docs/theming/best-practices.mdx delete mode 100644 site/docs/theming/reusable-design.mdx diff --git a/site/docs/theming/best-practices.mdx b/site/docs/theming/best-practices.mdx new file mode 100644 index 0000000000..c13ce4727d --- /dev/null +++ b/site/docs/theming/best-practices.mdx @@ -0,0 +1,124 @@ +--- +title: Best Practices +layout: DetailTechnical +--- + +# Best practices for theming +Salt offers a comprehensive suite of [components](/salt/components) and [patterns](/salt/patterns) designed to streamline both the design and development process. While these resources cover a wide range of use cases, there will inevitably be times when you need to create custom components to meet specific product requirements. + +This guide will explore best practices for theming within the Salt design language, highlighting key considerations and best-practice. + +By adhering to these guidelines +- you will make consuming future Salt updates easier +- make your components more reusable and composable with other Salt components +- make your design easier to maintain and understood by others. +- provide your end user with a cohesive user experience. + +## Theming options + +Salt theming has [3 layers](/salt/theming/index#design-tokens) each with their own responsibility. + +Design tokens in the Salt Design language take the form of CSS/Figma variables that enable you to customise the presentation of Salt components. + +Changing a layer or token, without understanding how it's used, could solve your requirements but when you receive your next Salt update, it could also break? + +So, given theming is both powerful and also subject to change, what are your options and what are the associated best practices? + +### 1. Adopt the standard, pre-built, theme + +#### Don'ts +- Don't own any styling and use the Salt theme "out of the box". + +#### Dos +- Do recognize that adopting Salt provides an opportunity cost that would align your current UX to a maintained standard that conforms to accessible rules. + +### 2. Opt into pre-made design choices + +Salt provides pre-made, system-wide [styling options](/salt/theming/index#styling-options) that Salt maintains stable support for, between releases. + +**Do** opt into these features to provide a no-code styling solution. + +Salt will continue to expand this offering but it offers the easiest/cheapest/stablest way to customise your UI. + +### 2. Opt into Pre-Made Design Choices + +Salt provides pre-made, system-wide [styling options](/salt/theming/index#styling-options) that users can opt into through the SaltProvider. + +**Do** opt into these features to compose pre-made styling options. + +Salt will continue to expand this offering, but it currently offers the easiest, cheapest, and most stable way to customize your UI. + +### 3. Create Your Own Theme + +Each Salt theme consists of 3 layers that work together to offer a consistent theming solution across all components: + +- **Foundation Layer**: The foundation layer is the lowest layer, consisting of primitive values that should remain stable between releases. It should not be referenced directly but through the palette and characteristics layers. +- **Palette Layer**: The palette layer defines semantic groupings derived from the foundation layer. These groupings can be referenced by multiple characteristics. +- **Characteristics Layer**: The characteristics layer is the top layer, using values from the palette layer to define theming attributes for specific aspects of the design. + +#### Don'ts +- Don't change the foundation layer unless you fully understand the impact it will have on all components. +- Don't reference the foundation layer directly but through either the palette or characteristics layer. + +#### Dos +- Do create your own theme that references the Salt characteristics and palette layers to provide a holistic theming solution. +- Do document your design language so others understand the design intent and how to use it. This avoids future duplication and eases updates. +- Do change the palette layer but federate the solution to a central theme, ensuring that deviations from the Salt standard are known and can be easily updated if required. +- Do change the characteristics layer but federate the solution to a central theme, ensuring that deviations from the Salt standard are known and can be easily updated if required. + +We've documented all our [design tokens](/salt/theming/index#design-tokens), but let's start with some basic tokens that have the biggest effect: + +| Token | Pro tip | +| --------------------------------------- | ------------------------------ | +| `--salt-container-primary-background` | **Salt's primary background color**

Ideal for most background changes, this token adapts seamlessly between light and dark modes with the appropriate color. It is commonly used by container components like [Panel](/salt/components/panel) and [Card](/salt/components/card). | +| `--salt-content-primary-foreground` | **Salt's default foreground color**

This token serves as the [default foreground color](https://github.com/jpmorganchase/salt-ds/blob/e76e5b92dcb6cfae02813137098393b91f54e501/packages/theme/css/global.css#L6) for text and icons, ensuring consistency across your UI. | +| `--salt-status-info-foreground-informative` | **Salt info status foreground**

The `informative` suffix ensures this token meets the minimal contrast ratio when used against Salt container background colors, making it suitable for informative text (as opposed to `decorative`). | +| `--salt-accent-borderColor` | **Salt's accent styling option**

Use this token for border colors to reflect the accent styling option choice – `teal` or `blue`. The `borderColor` naming convention helps maintain clarity and consistency. | + +
+These four variables represent key aspects of theming controls: background, foreground, typography, and border color. Exploring these variables will demonstrate the power of theming and guide you to discover the rest of our documentation. + +#### Dos +- Do consider how much change can be achieved with the smallest number of theme adjustments. With just these four variables, you can create significant visual impact. + +Be mindful that unless you are using the 'styling options', any overrides may be subject to breaking changes. Creators of Salt themes should pay careful attention to updates in the @salt-ds/theme package and manage any dependencies within their own themes. +## Best Practices for making changes from default values +
+- **Don't** replace token values with hex, rgb, or other hard-coded values, as this can lead to unmaintainable changes. Hard-coded values break theming and decouple you from future updates. +- **Do** use Salt's foundational palette and design tokens for colors. Using these tokens instead of hex values ensures that changes map to Salt's foundations or characteristics layers. If the characteristics or foundations change in the future, your component will update accordingly. +
+- **Don't** see your UI as a collection of individual components and override specific use-cases based on personal preferences. +- **Do** understand the value of consistent, accessible styling for your end-users. While changes can be made, consider the cost of not only making a change but also maintaining it. Theming is a holistic solution to styling your product. Corner cases often indicate either a new feature you need to design/build/maintain yourself or an opportunity cost. +
+- **Don't** define colors on individual components. +- **Do** use Salt components that define their color settings through palette tokens with semantic meanings. This allows your application to adapt to [accent or mode](/salt/theming/index#accent--mode) settings. Refer to [characteristics tokens](/salt/theming/accordionview) for a full list of tokens. +
+- **Don't** hardcode sizes of components, such as pixel-based sizing. +- **Do** ensure that Salt components are responsive and uniformly sized. Use the size and spacing tokens to maintain density support and responsiveness. Salt's [size](/salt/foundations/size) and [spacing](/salt/foundations/spacing) foundation tokens will adapt to the [density](/salt/foundations/density) settings. + +## What does good look like ? + +The good practices outlined on this page are being used across Salt components and patterns. Studying how tokens are utilized by Salt can be very helpful. + +- **Button**: Uses the actionable characteristic, size token for height, and spacing token for inline padding. +- **List Box**: Uses the selectable characteristic, size, and spacing tokens for height. +- **Banner**: Uses various status characteristic tokens to indicate its status. + +## What Other Options Do I Have to Avoid Overriding Styles? + +In addition to using design tokens, you can leverage Salt components to help build your own patterns without the need for additional styling. + +### Layout Components +Layout components provide a declarative way to layout content without additional styling. They also adjust their spacing according to the current `density`. + +- [Stack Layout](/salt/components/stack-layout) +- [Split Layout](/salt/components/split-layout) +- [Grid Layout](/salt/components/grid-layout) + +### Typography Components +Typography components offer declarative typographic styles that do not require additional styles. + +- [Text](/salt/components/text) components encapsulate [typography](/salt/foundations/typography) + +### Glyph-Based Components +Glyph-based components provide visual cues without additional styling. diff --git a/site/docs/theming/reusable-design.mdx b/site/docs/theming/reusable-design.mdx deleted file mode 100644 index 554459d51c..0000000000 --- a/site/docs/theming/reusable-design.mdx +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Reusable design -layout: DetailTechnical ---- - -Salt offers many [components](/salt/components) and [patterns](/salt/patterns) you can use and build on top of. There will still be times where you want to build a custom component to suit specific product need. We will talk about what to consider and what is available for you to reuse. - -## Design to be reusable - -A good component should be reusable across multiple places. When building on top of Salt, it would be ideal if your component can be used across all [styling options](/salt/theming/index#styling-options) just like all Salt components. To achieve that, you will need to use the right [design tokens](/salt/theming/index#design-tokens). - -### Color tokens - -Instead of using hex or RGB values of color, [characteristics tokens](/salt/theming/accordionview) are designed with semantic meanings and to adapt application's [accent or mode](/salt/theming/index#accent--mode) settings through palette tokens. - -Here are some example tokens for you to take a look first: - -- `--salt-container-primary-background` is a good starting point for most background, which will switch nicely between light and dark mode with the right color. It is used by container components like [Panel](/salt/components/panel) and [Card](/salt/components/card). -- `--salt-content-primary-foreground` is the [default color](https://github.com/jpmorganchase/salt-ds/blob/e76e5b92dcb6cfae02813137098393b91f54e501/packages/theme/css/global.css#L6) for text and icons. -- `--salt-status-info-foreground-informative` represents informational status. The `informative` suffix indicates it will meet minimal contrast ratio when used against Salt container background colors (oppose to `decorative`). -- `--salt-accent-borderColor` can be used for border color (notice `borderColor` naming convension), which will reflect accent styling option choice – teal or blue. - -### Size and spacing tokens - -Instead of using fixed pixel values, Salt [size](/salt/foundations/size) and [spacing](/salt/foundations/spacing) foundation tokens will adapt to [density](/salt/foundations/density) option. - -For example, `--salt-spacing-100` scales from 4px in high density to 16px in low density. Similarly, `--salt-size-base` scales from 20px in high density to 44px in touch density. Combining both results the height defination for [app header](/salt/patterns/app-header) pattern, which would work across all densities. - -## Salt examples - -Good practices shown above are being used across Salt components and patterns. You may find it helpful to study how tokens are used by Salt. - -- [Button](/salt/components/button) uses actionable characteritic, size token for height and spacing token for inline padding. -- [List box](/salt/components/list-box) uses seletable characteritic, size and spacing tokens for height. -- [Banner](/salt/components/banner) uses various status characteritic tokens to inform its status. - -On top of using design tokens, you can utilize as many as Salt components to help build your own pattern. - -- Layout components (e.g. [stack layout](/salt/components/stack-layout), [split layout](/salt/components/split-layout), [grid layout](/salt/components/grid-layout)) will adjust its spacing according to the density it sits it. -- [Text](/salt/components/text) components encapusate [typography](/salt/foundations/typography) design choices to be readily available. -- [Icon](/salt/components/icon) and [status indicator](/salt/components/status-indicator) can be used for common recognizable UIs.