@mindvalley/design-system 3.4.2 → 4.0.1

package/docs/USAGE.md

@@ -12,7 +12,7 @@ npm install @mindvalley/design-system
 yarn add @mindvalley/design-system
 ```
 
-The package supports both ES module syntax and commonJS syntax
+The package supports both ES module syntax and CommonJS syntax.
 
 #### *ES module syntax*
 
@@ -20,7 +20,7 @@ The package supports both ES module syntax and commonJS syntax
   import { colors } from '@mindvalley/design-system'
 ```
 
-#### *commonJS syntax*
+#### *CommonJS syntax*
 
 ```js
   const { colors } = require('@mindvalley/design-system')
@@ -36,7 +36,7 @@ To use the colors from the design system there are two options.
 If you use TailwindCSS in your project, using the colors is a simple two-step process:
 
 1. Install the design system. See [installation](#using-npm-or-yarn).
-2. Use the [commonJS syntax](#commonjs-syntax) to include the colors and extend your `tailwind.config.js`.
+2. Use the [CommonJS syntax](#commonjs-syntax) to include the colors and extend your `tailwind.config.js`.
 
 *Example tailwind.config.js*
 
@@ -52,8 +52,8 @@ If you use TailwindCSS in your project, using the colors is a simple two-step pr
   }
 ```
 
-For other brands eg B2B, you can access and combine colors from the core mindvalley brand
-and override the redefined colors using the b2b specific colors.
+For other brands (e.g., B2B), you can access and combine colors from the core Mindvalley brand
+and override the redefined colors using the B2B-specific colors.
 
 ```js
   const { colors } = require('@mindvalley/design-system');
@@ -62,7 +62,7 @@ and override the redefined colors using the b2b specific colors.
   module.exports = {
     theme: {
       colors: {
-        ...color,
+        ...colors,
         ...b2bColors
       }
     }
@@ -71,13 +71,13 @@ and override the redefined colors using the b2b specific colors.
 
 ## Why the override?
 
-Both brands share color names, but their hues and shades are distinct. For instance, the reds, blues, teals, and purples in b2b differ. Therefore, the override is necessary to guarantee that a developer working on b2b receives the specific shades of colors associated with b2b.
+Both brands share color names, but their hues and shades are distinct. For instance, the reds, blues, teals, and purples in B2B differ. Therefore, the override is necessary to guarantee that a developer working on B2B receives the specific shades associated with that brand.
 
-Here is full list of [b2b colors](https://www.figma.com/file/1EPj7v5H5JhP2d0v2h8QeC/B2B-Foundations?type=design&node-id=1-395&mode=design&t=SY5HTy1zbFO5p80n-0)
+Here is the full list of [B2B colors](https://www.figma.com/file/1EPj7v5H5JhP2d0v2h8QeC/B2B-Foundations?type=design&node-id=1-395&mode=design&t=SY5HTy1zbFO5p80n-0).
 
 #### Gradients
 
-For gradient you can use the following tailwindCSS gradients:
+For gradients you can use the following TailwindCSS presets:
 
 - Purple wave: `from-brand-accent to-purple-600`
 - Orange Wave: `from-orange-500 to-orange-600`
@@ -103,11 +103,11 @@ If you'd like other custom names, you can make [tailwindcss color customizations
 1. Install the design system. See [installation](#using-npm-or-yarn).
 2. Use the [ES module](#es-module-syntax) syntax to import your module and include it in your code.
 
- *Sample usage in a react app*
+ *Sample usage in a React app*
 
 ```js
   import React from 'react'
-  import { color } from '@mindvalley/design-system'
+  import { colors } from '@mindvalley/design-system'
 
   function App() {
     const isBackgroundRed = true;
@@ -115,7 +115,7 @@ If you'd like other custom names, you can make [tailwindcss color customizations
     return (
       <div
         style={{
-          backgroundColor: isBackgroundRed ? color.red : color.blue,
+          backgroundColor: isBackgroundRed ? colors.red : colors.blue,
         }}
       />
     );
@@ -126,76 +126,134 @@ If you'd like other custom names, you can make [tailwindcss color customizations
 
 ## 🖋️ Typography
 
-### Typography plugin (Tailwindcss)
+### Loading Typography Fonts
+
+Before using the typography plugin, you need to load the required fonts. The design system provides pre-generated `@font-face` declarations that you can easily import.
+
+#### Recommended Method: Package Import
+
+The easiest way to load fonts is to import them directly from the package:
+
+**For Mindvalley Brand:**
+
+```javascript
+import '@mindvalley/design-system/typography/mindvalley/fonts.css'
+```
+
+**For B2B Brand:**
+
+```javascript
+import '@mindvalley/design-system/typography/b2b/fonts.css'
+```
+
+**For projects using both brands:**
+
+```javascript
+import '@mindvalley/design-system/typography/mindvalley/fonts.css'
+import '@mindvalley/design-system/typography/b2b/fonts.css'
+```
+
+This works in all modern JavaScript frameworks including Next.js, Vite, Webpack, and Phoenix (Elixir).
+
+> 💡 **Note**: For detailed framework-specific examples (Next.js, Vite, Phoenix, CSS-in-JS solutions, etc.), see the comprehensive [Typography Font Loading Guide](typography-fonts.md).
+
+> ⚠️ **PostCSS Users**: If you're using `@import` in SCSS/CSS files with `postcss-import`, you need to configure it to resolve from `node_modules`. See the [PostCSS configuration example](typography-fonts.md#using-with-postcss-and-scss-import-phoenix-webpack--scss) for details.
+
+#### Alternative Method: Manual CSS
+
+If you prefer more control or need to customize the font loading, you can manually add the `@font-face` declarations to your CSS:
+
+```css
+/* Font files are served via Fastly CDN under Mindvalley assets and
+   managed via platform backoffice
+   
+   Note: Each font file has a single weight baked into the font name
+   (e.g., "Sharp Grotesk Cyr Medium 20" contains Medium, "Sharp Grotesk Cyr Semibold 20" weight of 600).
+   Using font-weight: auto allows the browser to use the font's intrinsic weight.
+*/
+
+@font-face {
+  font-family: "Sharp Grotesk Cyr Medium 22";
+  font-weight: auto;
+  font-display: swap;
+  src: url("https://assets.mindvalley.com/api/v1/assets/b61f86ec-3dbd-4674-907a-f3f26f5101ce.woff2") format("woff2");
+}
+
+@font-face {
+  font-family: "Sharp Grotesk Cyr Semibold 20";
+  font-weight: auto;
+  font-display: swap;
+  src: url("https://assets.mindvalley.com/api/v1/assets/85092275-d096-483e-a271-7d6094cafca1.woff2") format("woff2");
+}
+
+@font-face {
+  font-family: "Sharp Grotesk Cyr Medium 20";
+  font-weight: auto;
+  font-display: swap;
+  src: url("https://assets.mindvalley.com/api/v1/assets/faf3d1e3-d18c-461e-aafa-9e56f9f16ce0.woff2") format("woff2");
+}
+
+@font-face {
+  font-family: "Sharp Grotesk Cyr Medium 19";
+  font-weight: auto;
+  font-display: swap;
+  src: url("https://assets.mindvalley.com/api/v1/assets/9f7eea7d-ba59-4ee1-85a6-3ac45f23239c.woff2") format("woff2");
+}
+
+@font-face {
+  font-family: "Sharp Grotesk Cyr Book 19";
+  font-weight: auto;
+  font-display: swap;
+  src: url("https://assets.mindvalley.com/api/v1/assets/0982041e-3874-48dc-bba5-a15c6fb960d1.woff2") format("woff2");
+}
+
+@font-face {
+  font-family: "Sharp Grotesk Cyr Book Itl 19";
+  font-weight: auto;
+  font-display: swap;
+  src: url("https://assets.mindvalley.com/api/v1/assets/2ba064b8-f0d5-48e4-a790-d7b90d5d2db5.woff2") format("woff2");
+}
+```
+
+Both methods are valid, but the package import is easier to maintain and ensures you always have the latest font definitions.
 
-Mindvalley's engineers utilize TailwindCSS. So we provide a tailwind typography plugin to make life easy. This plugin enables developers to use typography class references from Figma and apply it to their code without worrying about all the underlying font sizes, line heights, font families, etc
+### Typography plugin (TailwindCSS)
+
+Mindvalley's engineers utilize TailwindCSS, so we provide a typography plugin to make life easier. This plugin lets developers use Figma typography class references without worrying about the underlying font sizes, line heights, font families, etc.
 
 #### How to use it?
 
-Let's say that you are trying to codify a button from a Figma design, and you want to apply the exact same typography values(line height, font family, font size, etc.) to your code. Here are the steps you will need to go through to utilize the plugin.
+Let's say that you are trying to codify a button from a Figma design, and you want to apply the exact same typography values (line height, font family, font size, etc.) to your code. Here are the steps you will need to go through to use the plugin.
+
+1. Install the design system as described in the [install section](#using-npm-or-yarn).
 
-1. Install the design system as descibed in the [install section](#using-npm-or-yarn)
+2. Load the typography fonts using one of the methods described in [Loading Typography Fonts](#loading-typography-fonts) above.
 
-2. Require and use the tailwind typography plugin in your `tailwind.config.js` file.
+3. Require and use the Tailwind typography plugin in your `tailwind.config.js` file.
 
       ```js
       module.exports = {
         ...
         plugins: [
-          require('@mindvalley/design-system/dist/tailwind/plugins/typography.js')();
+          require('@mindvalley/design-system/dist/tailwind/plugins/typography.js')()
         ],
         ...
       }
 
     ```
 
-3. Add font face definition for the font used in the plugin in your CSS.
-
-    ```css
-      @font-face {
-        font-family: "Sharp Grotesk Cyr Semibold 21";
-        font-weight: 500;
-        font-display: swap;
-        /* We load fonts from assets.mindvalley.com cdn but you can choose to host the files yourself */
-        src: url("https://assets.mindvalley.com/api/v1/assets/270944f2-bb71-4559-b461-aabb0b351d6b.woff2") format("woff2");
-      }
-
-      @font-face {
-        font-family: "Sharp Grotesk Cyr Semibold 20";
-        font-weight: 600;
-        font-display: swap;
-        /* We load fonts from assets.mindvalley.com cdn but you can choose to host the files yourself */
-        src: url("https://assets.mindvalley.com/api/v1/assets/85092275-d096-483e-a271-7d6094cafca1.woff2") format("woff2");
-      }
+4. Find the name to use by inspecting the selected text on the Figma design file.
 
-      @font-face {
-        font-family: "Sharp Grotesk Cyr Medium 22";
-        font-weight: 500;
-        font-display: swap;
-        src: url("https://assets.mindvalley.com/api/v1/assets/b61f86ec-3dbd-4674-907a-f3f26f5101ce.woff2") format("woff2");
-      }
+![Getting Class Name](getting-class-name.png)
 
-      @font-face {
-        font-family: "Sharp Grotesk Cyr Medium 20";
-        font-weight: 500;
-        font-display: swap;
-        src: url("https://assets.mindvalley.com/api/v1/assets/faf3d1e3-d18c-461e-aafa-9e56f9f16ce0.woff2") format("woff2");
-      }
+5. Use the class name as follows. Remember to adjust that according to the casing option if you are not using the default.
 
-      @font-face {
-        font-family: "Sharp Grotesk Cyr Book 19";
-        font-weight: 400;
-        font-display: swap;
-        src: url("https://assets.mindvalley.com/api/v1/assets/0982041e-3874-48dc-bba5-a15c6fb960d1.woff2") format("woff2");
-      }
+```html
+<p class="button-text">...</p>
 
-      @font-face {
-        font-family: "Sharp Grotesk Cyr Bold 16";
-        font-weight: 700;
-        font-display: swap;
-        src: url("https://assets.mindvalley.com/api/v1/assets/d0e0425c-3c29-4d67-b4d6-77567bec96ba.woff2") format("woff2");
-      }
-    ```
+<!-- This won't work as the button-text class generated is already responsive -->
+<p class="button-text lg:button-text">...</p>
+```
 
 *Note that*
 
@@ -245,9 +303,9 @@ Since the typography classes are responsive, you don't need to add media queries
 
 ```css
 .title-bold-5 {
-  font-family: 'Sharp Grotesk Semibold 21', 'Helvetica', 'Arial', 'sans-serif';
+  font-family: 'Sharp Grotesk Cyr Semibold 20', Helvetica, Arial, 'sans-serif';
   font-size: 1.5rem;
-  letter-spacing: 0rem;
+  letter-spacing: 0.015625rem;
   line-height: 1.875rem;
 }
 /* configured-breakpoint value is the value of the breakpoint identifier you pass in the plugin configuration. */
@@ -378,19 +436,6 @@ You'll need to make the plugin aware of the `breakingPoint` boundary between the
     }
   ```
 
-4. Find the name to use by inspecting the selected text on the Figma design file.
-
-![Getting Class Name](getting-class-name.png)
-
-5. Use the class name as follows. Remember to adjust that according to the casing option if you are not using the default.
-
-```html
-<p class="button-text">...</p>
-
-<!-- This won't work as the button-text class generated is already responsive -->
-<p class="button-text lg:button-text">...</p>
-```
-
 You can find the full list of typography definations here 👉 [Figma typography](https://www.figma.com/file/Gmdp0kAAYsmBgCthFjGkpY/MV-Core?node-id=5593%3A26473&t=3PPGng5xmhzaFyRe-0)
 
 ## ©️ Icons