Proofing amends

Change-type: patch

src/docs/10_introduction/10_welcome.mdx

@@ -4,9 +4,9 @@ import { Meta } from '@storybook/blocks';
 
 # Welcome
 
-Welcome to the Balena Design System, a single source of truth for the UI of Balena products, aimed at enhancing collaboration between designers and engineers. 
+Welcome to the balena design system, a single source of truth for the UI of balena products, aimed at enhancing collaboration between designers and engineers. 
 
-Here, you will find design foundations such as color and typography, UI components and patterns, as well as elements specific to BalenaCloud. 
+Here, you will find design foundations such as color and typography, UI components and patterns, as well as elements specific to balenaCloud. 
 
 This system is dynamic and will continue to grow and evolve over time. If you have any feedback or any questions, please
 [get in touch](?path=/docs/introduction-get-in-touch--docs).
@@ -22,6 +22,4 @@ The power of having a design system at balena is that it allows our whole team,
 
 Our engineers can all work from the same set of design tokens, components, and patterns, not only building consistency within the product but also saving time by reusing elements wherever possible.
 
-For product designers, the guidelines that sit beside each element will provide a clear description of when it should be used and how it should work. Becoming familiar with the contents of this system will give you a box full of tools and knowledge of how to use them.
-
-This is the only place the balena design system lives. By maintaining a single source of truth, we reduce the likelihood of deviation, enabling us to build a product that looks and behaves consistently regardless of where you are within it and which team worked on it.
+For product designers, the guidelines that sit beside each element will provide a clear description of when it should be used and how it should work. Becoming familiar with the contents of this system will give you a box full of tools and knowledge of how to use them.

src/docs/10_introduction/30_get-in-touch.mdx

@@ -14,7 +14,7 @@ Or you can message us in the [DS - Feedback](https://balena.zulipchat.com/#narro
 
 ## Feature Request process
 
-We are well aware that this system isn't complete right now. In fact, one could argue that a design system is never truly complete; it's certainly never finished.
+We are well aware that this system isn't complete right now. In fact, you could say that a design system is never truly complete; it's certainly never finished.
 
 With this knowledge, we actively welcome feature requests. Working a new UI element into the design system rather than letting it stand rogue somewhere in the product, not only ensures it's consistent with the rest of the UI but enables other teams to use it.
 

src/docs/10_introduction/40_contribute.mdx

@@ -2,15 +2,15 @@ import { Meta } from '@storybook/blocks';
 
 <Meta title="Introduction / Contribute" />
 
-# Getting started
+# Contribute
 
 ## Develop locally
 
 ### Requirements
 
-- A basic knowledge of git. For an overview on how git works, check out this guide by Atlassian: [https://www.atlassian.com/git](https://www.atlassian.com/git).
-- If you are not familiar with git or the command line, you can use Github Desktop: https://desktop.github.com/](https://desktop.github.com/). It provides an easy-to-use interface on top of git.
-- A code editor. You can use VS Code: [https://code.visualstudio.com/](https://code.visualstudio.com/).
+- A basic knowledge of git. For an overview on how git works, check out this [guide by Atlassian](https://www.atlassian.com/git).
+- If you are not familiar with git or the command line, you can use [Github Desktop](https://desktop.github.com/). It provides an easy-to-use interface on top of git.
+- A code editor. You could use [VS Code](https://code.visualstudio.com/).
 
 ### Run
 
@@ -19,7 +19,7 @@ import { Meta } from '@storybook/blocks';
 - Move into the directory: `cd ui-shared-components`
 - Install dependencies: `npm install`
 - Run the Storybook instance: `npm start`
-- Storybook should open in your browser. Any change you make in the codebase will automatically reload the
+- Storybook should open in your browser. Any change you make in the codebase will automatically reload the page.
 
 ### Publishing your changes
 

src/docs/20_foundations/00_introduction.mdx → src/docs/20_foundations/00_explained.mdx

@@ -1,10 +1,10 @@
 import { Meta } from '@storybook/blocks';
 
-<Meta title="Foundations / Introduction" />
+<Meta title="Foundations / Explained" />
 
-# Foundations
+#Foundations Explained
 
-At the core of our Design System are the foundations, which help keep everyone on the same page, speaking the same language, and working as a team. These foundation elements of color, typography, spacing, grids, and iconography will form the base of all subsequent UI designs. 
+At the core of our Design System are the foundations, these help keep everyone on the same page, speaking the same language, and working as a team. Our foundation elements of color, typography, spacing, grids, and iconography will form the base of all subsequent UI designs. 
 
 In the future, they will also go further and become the foundation for not just UI designs, but all visual elements of balena. Whether it's the marketing website, a digital product like balenaCloud, or a slide deck presented by Customer Success they should all look and feel like they come from the same company.
 

src/docs/20_foundations/20_colors.mdx

@@ -24,7 +24,7 @@ Our color system has been divided into two groups Foundations and Roles.
 
 **Foundations** provide the underlying structure of the UI, design a feature using just these would give you a perfectly functional design but lacking the context and hierarchy that color can bring. This group consists of text, icons, backgrounds, and borders that make up most of a product interface.
 
-**Roles** add visual order and give meaning to the product, these colors will help guide the user through their experience and provide context to the content. In this group, you will find tokens for content-specific roles such as ```text.success``` as well as more branded ones like ```text.accent```.That's where we've put Primary blue in old terms.
+**Roles** add visual order and give meaning to the product, these colors will help guide the user through their experience and provide context to the content. In this group, you will find tokens for content-specific roles such as ```text.success``` as well as more branded ones like ```text.accent```. That's where we've put Primary blue in old terms.
 
 ### Design token anatomy
 
@@ -46,7 +46,7 @@ Attribute applies a quality to the property, for color these come in two groups,
 
 **Variants**
 
-Variants help distinguish between elements with the same property whilst not adding any semantic context. These are best used to create a subtle visual hierarchy between elements in the UI.  
+Variants help distinguish between elements with the same property whilst not adding any semantic context. These are best used to create a subtle visual hierarchy between elements in the UI, this is where branded UI elements live with ```.accent```, what we'd call our ```primary``` color in the old lingo.
 
 <table style={{ width: '100%', borderCollapse: 'collapse' }}>
 	<tbody>
@@ -75,7 +75,7 @@ Variants help distinguish between elements with the same property whilst not add
 
 **Roles**
 
-These add visual order and give meaning to the product, these colors will help guide the user through their experience and provide context to the content. In this group, you will find tokens for content-specific roles such as ```text.success``` as well as more branded ones like ```text.accent```. That's where we've put Primary blue in old terms.
+These add visual order and give meaning to the product, these colors will help guide the user through their experience and provide context to the content. In this group, you will find tokens for content-specific roles such as ```text.success```.
 
 <table style={{ width: '100%', borderCollapse: 'collapse' }}>
 	<tbody>
@@ -125,7 +125,7 @@ These roles have no specific context, they are used **ONLY** for the status colo
 
 #### Modifiers
 
-These levels take the existing element and modify it to give it an additional quality, currently, the only modifier we use is ```strong``` which gives extra emphasis to a property.
+These levels take the existing element and modify it to give it an additional quality, currently, the only modifier we use is ```.strong``` which gives extra emphasis to a property.
 
 ## The Colors
 
@@ -137,17 +137,17 @@ These colors are used exclusively for all text.
 
 <ColorTable>
 	<ColorRow token={color.text} description="The default color for all text." />
-	<ColorRow token={color.text.subtle} description="ext that needs to be less prominent, such as labels." />
-	<ColorRow token={color.text.subtlest} description="ext that needs to be far less prominent, such as placerholders." />
-	<ColorRow token={color.text.inverse} description="se when text is on an inverted background." />
-	<ColorRow token={color.text.accent} description="he brand accent color is to be used to make text stand out in the UI. To be used sparingly." />
+	<ColorRow token={color.text.subtle} description="Text that needs to be less prominent, such as labels." />
+	<ColorRow token={color.text.subtlest} description="Text that needs to be far less prominent, such as placerholders." />
+	<ColorRow token={color.text.inverse} description="Use when text is on an inverted background." />
+	<ColorRow token={color.text.accent} description="The brand accent color is to be used to make text stand out in the UI. To be used sparingly." />
 </ColorTable>
 
 #### Roles
 
 <ColorTable>
-	<ColorRow token={color.text.info} description="se to highlight a primary, stable state or for a message providing additional details." />
-	<ColorRow token={color.text.success} description="se to highlight a positive, successful message." />
+	<ColorRow token={color.text.info} description="Use to highlight a primary, stable state or for a message providing additional details." />
+	<ColorRow token={color.text.success} description="Use to highlight a positive, successful message." />
 	<ColorRow token={color.text.warning} description="Use to highlight a message that requires the user's attention." />
 	<ColorRow token={color.text.danger} description="Use to emphasize an error, blocked status, or permanent change." />
 </ColorTable>
@@ -161,9 +161,9 @@ Background colors apply to surfaces of all elements and components, such as page
 <ColorTable>
 	<ColorRow token={color.bg} description="The default background color for the product." />
 	<ColorRow token={color.bg.subtle} description="Use for providing contrast against the default background with little emphasis." />
-	<ColorRow token={color.bg.subtlest} description="Use for when an element needs to have additional focus without standing out from the UI." />
-	<ColorRow token={color.bg.strong} description="Use for when an element needs to have additional focus and to stand out against the UI." />
-	<ColorRow token={color.bg.strongest} description="Use for when an element needs to have additional focus and stand out strongly against the UI." />
+	<ColorRow token={color.bg.subtlest} description="Use for elements that need to have additional focus without standing out from the UI." />
+	<ColorRow token={color.bg.strong} description="Use for UI elements that have a dark background, such as the sidebar." />
+	<ColorRow token={color.bg.strongest} description="Use to emphasize UI elements that have a dark background, such as the sidebar menu." />
 	<ColorRow token={color.bg.accent} description="Use to highlight an element to stand out in the UI with no additional context." />
 	<ColorRow token={color.bg.accent.strong} description="Use to emphasize an element to stand out in the UI with no additional context." />
 </ColorTable>