docs: refactor docs

instructure · Jul 19, 2024 · d869ece · d869ece
1 parent 91cbc5f
commit d869ece
Showing 1 changed file with 60 additions and 72 deletions.
diff --git a/docs/contributor-docs/v10-upgrade-guide.md b/docs/contributor-docs/v10-upgrade-guide.md
@@ -10,14 +10,11 @@ order: 7
 
 Let's talk about the nature of the changes and the philosophy behind these decisions.
 
-You'll notice that some of the chages are straight up regressions from the old system. This may cause complications with the migration and in some cases it makes certain designs close to unachievable.
+InstUI v10 color system is very different from the earlier one. It has been simplified to uniformize our design language and bring us to sync with the design Figmas.
 
-The reasons we made it this way are:
+With the new system some old designs could be more challenging or close to impossible to implement. In these cases, make sure you talk with your designer and update the UI according to the new deisgn system.
 
-- to follow the new design system;
-- to make sure the tools we provide assist in achieving a uniform look-and-feel across all company products.
-
-The designers will make sure, every screen, every UI design is attainable using the base colors, without the complex overrides.
+The revised should result in better a11y, better code and more uniform look and feel.
 
 ## Let's start
 
@@ -28,102 +25,93 @@ We recommend upgrading your application for each major version gradually, e.g. i
 InstUI v10 is a major release which replaces the entire color system. The new color system is based on the [WCAG 2.1](https://www.w3.org/TR/WCAG21/) guidelines and is designed to be more accessible and easier to use.
 The places, where your code can break are related to theme overrides, color props and color utilities. Please check the how themes work guide to understand the new color system.
 
+If you override the theme colors, you must use the new colors provided in either the `canvas-high-contrast` or `canvas` theme object. The previous color system has been removed, and the old color names are no longer available.
+
 ### Instructure theme is removed
 
 Instructure theme is no longer part of the package. If you were using it, you need to switch to the `canvas` or the `canvas-high-contrast` theme.
 
-### Theme overrides, targeting variables in the theme object
+### Component level color overrides
 
-If you override the theme colors, you must use the new color options provided in either the `canvas-high-contrast` or `canvas` theme object. The previous color system has been removed, and the old color names are no longer available. Within these theme objects, you can customize contrast colors, as those are the building blocks for components. Let's take a look at how this works. This is an example with v9 color tokens:
+If you had component level overrides, using base colors e.g:
 
 ```js
 ---
-type: code
+  type: code
 ---
-<InstUISettingsProvider
-  theme={{
-    themeOverrides: {
-      canvas: {
-        colors: { backgroundLightest: 'orange' }
-      },
-      'canvas-high-contrast': {
-        colors: { backgroundLightest: 'red' }
-      },
-      instructure: {
-        colors: { backgroundLightest: 'green' }
-      }
-    }
-  }}
->
+<Heading level="h3" margin="small small" color="primary"
+         themeOverride={{primaryColor: canvas.colors.brand}}>
+    I should have monospace font family.
+</Heading>
 ```
 
-For this scenario, we don't have a straightforward way to migrate the color tokens as this is an edge case in the new design system. If you really have to achieve the same result, you have to override every components' background.
-
-What you can do is override the contrast colors in the `canvas` or `canvas-high-contrast` theme object. This will alter the theme at it's core, so if you override blue4570 to another shade of blue or even to another color, it will fundamentally change the color interactions within InstUI components. **Therefore this is highly discouraged!**
+you can migrate this, using the following table (codemods are coming soon):
+
+| Old              | New                         |
+| ---------------- | --------------------------- |
+| colors.Brand     | colors.contrasts.blue4570   |
+| colors.Link      | colors.contrasts.blue4570   |
+| colors.Electric  | colors.contrasts.blue4570   |
+| colors.Shamrock  | colors.contrasts.green4570  |
+| colors.Barney    | colors.contrasts.blue4570   |
+| colors.Crimson   | colors.contrasts.red4570    |
+| colors.Fire      | colors.contrasts.orange4570 |
+| colors.Licorice  | colors.contrasts.grey125125 |
+| colors.Oxford    | colors.contrasts.grey100100 |
+| colors.Ash       | colors.contrasts.grey4570   |
+| colors.Slate     | colors.contrasts.grey4570   |
+| colors.Tiara     | colors.contrasts.grey1214   |
+| colors.Porcelain | colors.contrasts.grey1111   |
+| colors.White     | colors.contrasts.white1010  |
 
 ```js
 ---
   type: code
 ---
+<Heading level="h3" margin="small small" color="primary"
+         themeOverride={{primaryColor: canvas.colors.contrasts.blue4570}}>
+    I should have monospace font family.
+</Heading>
+```
+
+Notice, that these are `colors.contrasts`. We don't recommend using the `colors.primitives` for anything.
+
+### Theme level color overrides
+
+Theme level properties, `border` `background` and `text` (for example `backgroundLightest` or `textDarkest`) have been removed. For these kind of overrides, you need to find and override component level theme variables for each component that used the replaced property.
+For example, if you had `backgroundLightest` overridden on the theme level, you need to find every component whose theme utilizes `backgroundLightest` and override them individually in each component. Some of these components are `Alert`, `Avatar`, `Billboard`, `View` and many many more.
+**This is heavily discouraged, upcoming designs should not necessiate theme overrides.**
+
+InstUI v9:
+
+```js
+---
+type: code
+---
 <InstUISettingsProvider
   theme={{
     themeOverrides: {
       canvas: {
-        colors: {
-          contrasts: {blue1212: 'blue'}
-        }
-      },
-      'canvas-high-contrast': {
-        colors: {
-          contrasts: {blue1212: 'blue'}
-        }
+        colors: { backgroundLightest: 'orange' }
       },
     }
   }}
 >
 ```
 
-### Theme overrides, targeting variables in components
-
-If you had component level overrides, using base colors e.g:
+InstUI v10:
 
 ```js
 ---
-  type: code
+type: code
 ---
-<Heading level="h3" margin="small small" color="primary"
-         themeOverride={{primaryColor: canvas.colors.brand}}>
-    I should have monospace font family.
-</Heading>
-```
+<Alert themeOverride={{background: 'orange'}}></Alert>
 
-you can migrate this, using the following table:
-
-| Old       | New        |
-| --------- | ---------- |
-| Brand     | blue4570   |
-| Link      | blue4570   |
-| Electric  | blue4570   |
-| Shamrock  | green4570  |
-| Barney    | blue4570   |
-| Crimson   | red4570    |
-| Fire      | orange4570 |
-| Licorice  | grey125125 |
-| Oxford    | grey100100 |
-| Ash       | grey4570   |
-| Slate     | grey4570   |
-| Tiara     | grey1214   |
-| Porcelain | grey1111   |
-| White     | white1010  |
 
-```js
----
-  type: code
----
-<Heading level="h3" margin="small small" color="primary"
-         themeOverride={{primaryColor: canvas.colors.contrasts.blue4570}}>
-    I should have monospace font family.
-</Heading>
-```
+<Avatar themeOverride={{background: 'orange'}}></Avatar>
 
-Notice, that these are `contrasts`. We don't recommend using the `primitives` for anything.
+
+<Billboard themeOverride={{background: 'orange'}}></Billboard>
+
+//...and all other components that use color.backgroundLightest
+```