Build on top of salt doc updates #4054
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
|
… 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
mark-tate
force-pushed
the
build-on-top-of-salt-doc-updates
branch
from
1842e59
to
416b380
Compare
| @@ -23,6 +29,18 @@ For a full list of foundational components, refer to the [component documentatio | |||
|
|
|||
| A design token is a visual attribute that represents a specific aspect of a design system. It is an abstract representation of a design property, such as colors, typography, spacing, or breakpoints, that can be used consistently across a product or design system. Design tokens provide a centralized and reusable way to define and manage design-related values, making it easier to maintain consistency and make global design changes. They act as a bridge between designers and developers, enabling a shared language and ensuring design consistency throughout the product or system. In Salt design tokens are represented as Figma variables and in code, they take the form of CSS variables. | |||
|
|
|||
| ## Foundation Layer | |||
|
|
|||
| The foundation layer is the lowest layer of the Salt theme, consisting of primitive values that should remain stable between releases. Ideally, it should not be referenced directly but through the palette and characteristics layers. | |||
There was a problem hiding this comment.
Spacing and size values will be referenced here. Remove last sentence
| @@ -35,6 +53,6 @@ Salt is the J.P. Morgan design system, an open-source solution for building exce | |||
|
|
|||
| ## Theming | |||
|
|
|||
| Salt is under active development. At this stage, we don't recommend theming unless absolutely necessary. | |||
| Refers to the process of customizing the visual appearance of a user interface (UI) by altering predefined design elements such as colors, typography, spacing, and other stylistic attributes. Theming allows for the creation of a cohesive and consistent look and feel across an application, ensuring that it aligns with brand guidelines and user experience (UX) standards. | |||
There was a problem hiding this comment.
Add only supported by salt next ?
| @@ -0,0 +1,140 @@ | |||
| --- | |||
| title: Best practices for theming | |||
There was a problem hiding this comment.
Building custom components and theming are 2 different areas, that's the reason why it's hard to get a good title
| - Do use the Salt theme "out of the box" and avoid owning any custom styles. | ||
| - Do recognize that adopting Salt aligns your current UX with a maintained standard that conforms to both design and accessibility guidelines. Whilst there is an opportunity cost, deviating from Salt can increase your costs and result in a disparate UI, ultimately affecting the end user's experience. | ||
|
|
||
| ### Option 2: Compose your theme from pre-made design options |
There was a problem hiding this comment.
1&2 shouldn't be split up, otherwise it could be seen as 2 different level of customization
|
|
||
| ### Option 3: Extend the Salt theme | ||
|
|
||
| Each Salt theme consists of 3 layers ([Foundation](/salt/about/glossary#foundation), [Palette](/salt/about/glossary#palette-layer) and [Characteristics](/salt/about/glossary#characteristics-layer) layers) that work together to offer a consistent theming solution across all components: |
There was a problem hiding this comment.
These 2 paragraphs are not defining what is "Extend the Salt theme"?
|
|
||
| Whilst this creates the highest level of flexibility it comes with an increased level of responsibility to maintain. If this is what you need , then here are our recommendations: | ||
|
|
||
| #### Don'ts |
There was a problem hiding this comment.
Dos and Don't tells a few different opinions from Salt, needs very careful team-wide review
| - 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. | ||
| - Do review the Salt backlog/roadmap before making a local change, to understand whether your change is tactical or strategic | ||
|
|
||
| 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: |
There was a problem hiding this comment.
let's start with some basic tokens that have the biggest effect
This feels the encouragement of changing these values?
|
|
||
| <br /> | ||
| These four variables represent key aspects of theming controls: background, | ||
| foreground, typography, and border color. Exploring these variables will |
There was a problem hiding this comment.
Exploring these variables
We shouldn't encourage change these
|
This adds too many new recommendations to the original intend of basic educational purpose, which means eating into product roadmap and #4004. I think we should close this entirely and rework piece by piece. My original page intentionally avoided overlapping with product roadmap or the main themes page, hoping to get easier review. With the current format, it's impossible to split and comment. |
|
Back to draft while working out #3847 |
Closes #3847