refactor: updating deprecated components and updating docs

MetaMask · Jan 20, 2024 · 28944fe · 28944fe
1 parent 6e74c59
commit 28944fe
Show file tree

Hide file tree

Showing 9 changed files with 182 additions and 106 deletions.
diff --git a/docs/BrandColors.mdx b/docs/BrandColors.mdx
@@ -1,17 +1,19 @@
-import { Meta, Canvas, Story } from '@storybook/addon-docs';
-import LinkTo from '@storybook/addon-links/react';
+import { Canvas, Meta } from '@storybook/blocks';
+import * as BrandColorStories from './BrandColors.stories';
 
-<Meta title="Design Tokens/Brand Colors" />
+<Meta of={BrandColorStories} />
 
-# Brand Colors (first tier)
+# Brand Colors (First Tier)
 
-Brand specific colors used in the first tier of design token abstraction. They **should not** be used in the code directly but referenced by [**Theme Colors**](/docs/colors-themecolors--light-theme-colors) used in second tier tokens. Most brand color progressions were generated using [0to255](https://0to255.com/037dd6)
+The first tier of our design token abstraction consists of brand-specific colors. These colors uses literal color names (like red, green, etc.) and a numeric scale (where 000 is light and 900 is dark) by default.They form the foundation of our design system and are essential to maintaining visual consistency across our products.
 
-<Canvas>
-  <Story id="colors-brandcolors--default-story" />
-</Canvas>
+While these colors are fundamental to our design system, they **should not** be used directly in most cases. The exception is when a color needs to remain the same regardless of the theme (light or dark mode). Instead, these brand colors should be referenced via [**theme colors**](/docs/colors-themecolors--light-theme-colors), which form the second tier of our design tokens.
+
+The majority of our brand color progressions were generated using the [0to255](https://0to255.com/037dd6) tool, which helps ensure smooth and consistent color transitions.
+
+<Canvas of={BrandColorStories.DefaultStory} />
 
 ## References
 
-- [Tool used to generate colors](http://www.0to255.com/037DD6)
-- [Figma Brand Colors Library](https://www.figma.com/file/cBAUPFMnbv6tHR1J8KvBI2/Brand-Colors?node-id=0%3A1)(internal use only)
+- [0to255](http://www.0to255.com/037DD6): The tool we used to generate our color progressions.
+- [Figma Brand Colors Library](https://www.figma.com/file/cBAUPFMnbv6tHR1J8KvBI2/Brand-Colors?node-id=0%3A1): Our internal Figma library for brand colors. Please note that this is for internal use only.
diff --git a/docs/BrandColors.stories.tsx b/docs/BrandColors.stories.tsx
@@ -1,27 +1,24 @@
-import { ComponentStory, ComponentMeta } from '@storybook/react';
+import React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
 import tokens from '../src/figma/tokens.json';
-
 import { ColorSwatchGroup } from './components';
-
 import README from './BrandColors.mdx';
 
-export default {
+const meta: Meta<typeof ColorSwatchGroup> = {
   title: 'Colors/BrandColors',
+  component: ColorSwatchGroup,
   parameters: {
     docs: {
       page: README,
     },
   },
-} as ComponentMeta<typeof ColorSwatchGroup>;
+};
 
-const Template: ComponentStory<typeof ColorSwatchGroup> = (args) => (
-  <ColorSwatchGroup {...args} />
-);
+export default meta;
 
-export const DefaultStory = Template.bind({});
+type Story = StoryObj<typeof ColorSwatchGroup>;
 
-DefaultStory.args = {
-  swatchData: tokens.global.brandColors,
+export const DefaultStory: Story = {
+  render: () => <ColorSwatchGroup swatchData={tokens.global.brandColors} />,
+  name: 'Default',
 };
-
-DefaultStory.storyName = 'Default';
diff --git a/docs/IntroductionColor.stories.mdx b/docs/IntroductionColor.stories.mdx
@@ -7,11 +7,7 @@ import { lightTheme } from '../src/index.ts';
 
 # Color
 
-Color is used to express style and communicate meaning.
-
-## Token Tiers
-
-We follow a 3 tiered system for color design tokens.
+Color is a powerful tool in design. It can express style, convey meaning, and establish visual hierarchy. In our design system, we manage colors through a three-tiered system of design tokens.
 
 <div
   style={{
@@ -26,26 +22,109 @@ We follow a 3 tiered system for color design tokens.
 <br />
 <br />
 
-### **Brand colors** (first tier)
+## Token tiers
 
-These colors **SHOULD NOT** be used in your component styles directly. They are used as a reference for the [Theme Colors](/docs/colors-themecolors--light-theme-colors). Brand colors are used to keep track of all colors used in our app. See [Brand Colors](/docs/colors-brandcolors--default-story)
+### **Brand colors (first tier)**
 
-### **Theme Colors** (second tier)
+Brand colors form the foundation of our color system. However, in most cases they **SHOULD NOT** be used directly in component styles. Instead, they serve as a reference for the [Theme Colors](/docs/colors-themecolors--light-theme-colors). You can view our brand colors in the [Brand Colors](/docs/colors-brandcolors--default-story) section.
 
-These colors are color agnostic, semantically neutral and theme compatible design tokens that you can use in your code and styles. Please refer to the description of each token for it's intended purpose. See [Theme Colors](/docs/colors-themecolors--light-theme-colors)
+### **Theme colors (second tier)**
 
-### **Component colors** (third tier)
+Theme colors are semantically neutral, theme-compatible design tokens that you can use directly in your code and styles. Each token has a specific purpose, which is described in its documentation. You can view our theme colors in the [Theme Colors](/docs/colors-themecolors--light-theme-colors) section.
 
-Another level of abstraction is component colors that you can use at a component specific level. We do not currently provide any component tier colors but that may change in future.
+### **Component colors (third tier)**
 
-## Takeaways
+Component colors provide another level of abstraction for component-specific colors. We currently do not provide any component tier colors, but this may change in the future.
 
-- Do not use static HEX values in your code. Use the [Theme Colors](/docs/colors-themecolors--light-theme-colors). If one does not exist for your use case [create an issue](https://github.com/MetaMask/design-tokens/issues/new) and tag it with a `color` label.
-- Make sure the design token you are using is for it's intended purpose. Please refer to the description of each token.
+## Best practices
 
-### Next 👉 [Theme Colors](/docs/colors-themecolors--light-theme-colors)
+### **Prioritize theme colors**
 
-<br />
+Theme colors should be your go-to choice for 99% of use cases. Using theme tokens ensures that the UI works across all themes and modes. We have built-in accessibility and functionality into the theme colors to ensure this. By using theme colors, you're leveraging these benefits and ensuring a consistent and accessible color scheme across your project.
+
+#### ✅ **DO**: Use theme colors in your components
+
+```
+background-color: theme.colors.background.default;
+background-color: var(--color-background-default);
+```
+
+#### ❌ **DON'T**: Use static color values or brand colors in your components
+
+```
+background-color: #ffffff; // Static color value
+background-color: brandColors.white.white000; // Brand color
+background-color: var(--brand-colors-white-white000); // Brand color
+```
+
+### **Use brand colors for theme-independent colors**
+
+In the rare case where a color should remain the same regardless of the theme (for instance, if white should always be white, regardless of whether light or dark mode is active), use the corresponding brand color. However, always check first to ensure that there isn't an existing theme token that suits your needs.
+
+#### ✅ **DO**: Use brand colors when the color should remain the same across all themes
+
+```
+fill: brandColors.white.white000;
+fill: var(--brand-colors-white-white000);
+```
+
+#### ❌ **DON'T**: Use brand colors without checking for an existing theme token first
+
+```
+background-color: brandColors.blue.blue500; // Brand color instead of theme.color.primary.default
+background-color: var(--brand-colors-blue-blue500); // Brand color instead of var(--color-primary-default)
+```
+
+### **Avoid static color values**
+
+As a general rule, avoid applying static color values at the component level. This helps maintain consistency and makes it easier to update colors in the future.
+
+#### ✅ **DO**: Use theme colors in your components
+
+```
+background-color: theme.colors.background.default;
+background-color: var(--color-background-default);
+```
+
+#### ❌ **DON'T**: Use static color values in your components
+
+```jsx
+background-color: #ffffff; // Static color value
+```
+
+### **Centralize non-token colors**
+
+If you need to use colors that are not included in the design tokens, store these colors in a global file in your project. This makes it easier to keep track of these colors and update them as needed. Always consider this as a last resort, and strive to use design tokens wherever possible.
+
+#### ✅ **DO**: Store non-token colors in a global file
+
+```
+// colors.js
+export const customColors = {
+  myCustomColor: '#abc123',
+};
+
+// colors.css
+--custom-colors-my-custom-color: #abc123;
+
+// component.js
+import { customColors } from './colors.js';
+
+background-color: customColors.myCustomColor;
+background-color: var(--custom-colors-my-custom-color);
+```
+
+#### ❌ **DON'T**: Use non-token colors directly in your components
+
+```jsx
+background-color: #abc123; // Custom color not in design tokens or global file
+```
+
+Remember, the goal of these practices is to maintain consistency across your project, make your code easier to maintain, and ensure that your project's colors align with the overall design system and MetaMask brand 🦊
+
+## Next steps
+
+Learn more about our [brand colors](/docs/colors-brandcolors--docs) or [theme colors](/docs/colors-themecolors--light-theme-colors) section
 
 ## References
 

diff --git a/docs/Shadows.mdx b/docs/Shadows.mdx
@@ -1,23 +1,19 @@
 import { Meta, Canvas, Story } from '@storybook/addon-docs';
-import LinkTo from '@storybook/addon-links/react';
+import * as ShadowStories from './Shadows.stories';
 
 <Meta title="Design Tokens/Shadows" />
 
 # Shadows
 
-Shadows convey elevation of elements on a surface
+Shadows in design are used to create depth and hierarchy. They can be used to differentiate between different elements, and to highlight interactive elements.
 
-<Canvas>
-  <Story id="shadows-shadows--shadow" />
-</Canvas>
+<Canvas of={ShadowStories.DefaultStory} />
 
 ## Size
 
-There are 4 different sizes of shadow in MetaMask.
+Shadows come in four different sizes: XS, SM, MD, and LG. The size of the shadow can be used to indicate the relative importance or prominence of an element.
 
-<Canvas>
-  <Story id="shadows-shadows--size" />
-</Canvas>
+<Canvas of={ShadowStories.Size} />
 
 | Size   | JS                | CSS                     |
 | ------ | ----------------- | ----------------------- |
@@ -28,25 +24,21 @@ There are 4 different sizes of shadow in MetaMask.
 
 ## Color
 
-As well as the neutral colors for shadow 2 other colors exist that are used for the primary and error/danger button hover states
+Shadows can have three different colors: default (neutral), primary, and error/danger. The color of the shadow can be used to indicate the state or functionality of an element.
 
-<Canvas>
-  <Story id="shadows-shadows--color" />
-</Canvas>
+<Canvas of={ShadowStories.Color} />
 
 | Color       | JS                      | CSS                           |
 | ----------- | ----------------------- | ----------------------------- |
 | **neutral** | `colors.shadow.default` | `var(--color-shadow-default)` |
 | **primary** | `colors.primary.shadow` | `var(--color-primary-shadow)` |
 | **danger**  | `colors.error.shadow`   | `var(--color-error-shadow)`   |
 
-## Example usage
+## Usage
 
-Using both size and color tokens, different shadows can be applied to components.
+Shadows can be applied to various components to create depth and hierarchy. Here are some examples of how shadows can be used in different components:
 
-<Canvas>
-  <Story id="shadows-shadows--example-usage" />
-</Canvas>
+<Canvas of={ShadowStories.ExampleUsage} />
 
 | Component                | JS                                                                              | CSS                                                              |
 | ------------------------ | ------------------------------------------------------------------------------- | ---------------------------------------------------------------- |

diff --git a/docs/Shadows.stories.tsx b/docs/Shadows.stories.tsx
@@ -1,33 +1,8 @@
 import React from 'react';
 import { lightTheme } from '../src/js';
-
 import { Text } from './components';
-
 import README from './Shadows.mdx';
 
-export default {
-  title: 'Shadows/Shadows',
-  parameters: {
-    docs: {
-      page: README,
-    },
-  },
-  argTypes: {
-    size: {
-      control: 'select',
-      options: Object.keys(lightTheme.shadows.size),
-    },
-    color: {
-      control: 'select',
-      options: ['default', 'primary', 'error'],
-    },
-  },
-  args: {
-    color: 'default',
-    size: 'xs',
-  },
-};
-
 interface ShadowSwatchProps {
   children: any;
   style?: object;
@@ -61,8 +36,29 @@ const ShadowSwatch = ({
   </div>
 );
 
-export const Shadow = (args) => {
-  return (
+export default {
+  title: 'Shadows/Shadows',
+  component: ShadowSwatch,
+  parameters: {
+    docs: {
+      page: README,
+    },
+  },
+  argTypes: {
+    size: {
+      control: 'select',
+      options: Object.keys(lightTheme.shadows.size),
+    },
+    color: {
+      control: 'select',
+      options: ['default', 'primary', 'error'],
+    },
+  },
+};
+
+export const DefaultStory = {
+  name: 'Default',
+  render: (args) => (
     <div
       style={{
         display: 'grid',
@@ -76,11 +72,15 @@ export const Shadow = (args) => {
         </Text>
       </ShadowSwatch>
     </div>
-  );
+  ),
+  args: {
+    color: 'default',
+    size: 'xs',
+  },
 };
 
-export const Size = (args) => {
-  return (
+export const Size = {
+  render: (args) => (
     <div
       style={{
         display: 'grid',
@@ -109,11 +109,15 @@ export const Size = (args) => {
         </Text>
       </ShadowSwatch>
     </div>
-  );
+  ),
+  args: {
+    color: 'default',
+    size: 'xs',
+  },
 };
 
-export const Color = (args) => {
-  return (
+export const Color = {
+  render: (args) => (
     <div
       style={{
         display: 'grid',
@@ -151,11 +155,15 @@ export const Color = (args) => {
         </Text>
       </ShadowSwatch>
     </div>
-  );
+  ),
+  args: {
+    color: 'default',
+    size: 'xs',
+  },
 };
 
-export const ExampleUsage = () => {
-  return (
+export const ExampleUsage = {
+  render: () => (
     <div>
       <div
         style={{
@@ -233,5 +241,5 @@ export const ExampleUsage = () => {
         </ShadowSwatch>
       </div>
     </div>
-  );
+  ),
 };
diff --git a/docs/ThemeColors.mdx b/docs/ThemeColors.mdx
@@ -1,7 +1,5 @@
 import { Meta, Canvas, Story } from '@storybook/addon-docs';
 
-import tokens from '../src/figma/tokens.json';
-
 <Meta title="Design Tokens/Theme Colors" />
 
 # Theme Colors (second tier)