- 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

@@ -0,0 +1,118 @@
+---
+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 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. Ideally, 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**<br/><br/>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**<br/><br/>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**<br/><br/>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**<br/><br/>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. | 
+
+<br/>
+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
+<br/>
+- **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.
+<br/>
+- **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.
+<br/>
+- **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.
+<br/>
+- **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)
+
+### Icon Components
+Icon components provide visual cues without additional styling.
+- [Icon](/salt/components/icon)
+- [Status Indicator](/salt/components/status-indicator)