@mindvalley/design-system 3.1.1 → 3.2.0

package/docs/USAGE.md

@@ -1,41 +1,37 @@
-## Installation
+# Installation
 
-#### Using npm or yarn
+### Using npm or yarn
 
 We recommend using either npm or yarn to install, as per your own preference.
 
-```
+```bash
 npm install @mindvalley/design-system
 ```
 
-```
+```bash
 yarn add @mindvalley/design-system
 ```
 
-## Usage
-
-### Figma Design Documentation
+The package supports both ES module syntax and commonJS syntax
 
-You can use this [link](https://www.figma.com/file/Gmdp0kAAYsmBgCthFjGkpY/MV-Core?node-id=5593%3A26473) to check out Mindvalley's core design system project. All the colors, icons, and typography, and design tokens follow it as the source of truth.
+#### *ES module syntax*
 
-###### *ES module syntax*
-
-```
+```js
   import { colors } from '@mindvalley/design-system'
 ```
 
-###### *commonJS syntax*
+#### *commonJS syntax*
 
-```
+```js
   const { colors } = require('@mindvalley/design-system')
 
 ```
 
-#### 🎨 colors
+## 🎨 colors
 
 To use the colors from the design system there are two options.
 
-###### 1. TailwindCSS
+### 1. TailwindCSS
 
 If you use TailwindCSS in your project, using the colors is a simple two-step process:
 
@@ -44,7 +40,7 @@ If you use TailwindCSS in your project, using the colors is a simple two-step pr
 
 *Example tailwind.config.js*
 
-```JavaScript
+```js
   const { colors } = require('@mindvalley/design-system')
 
   module.exports = {
@@ -56,7 +52,29 @@ If you use TailwindCSS in your project, using the colors is a simple two-step pr
   }
 ```
 
-##### Gradients
+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.
+
+```js
+  const { colors } = require('@mindvalley/design-system');
+  const { colors: b2bColors } = require('@mindvalley/design-system/b2b');
+
+  module.exports = {
+    theme: {
+      colors: {
+        ...color,
+        ...b2bColors
+      }
+    }
+  }
+```
+
+## 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.
+
+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)
+
+#### Gradients
 
 For gradient you can use the following tailwindCSS gradients:
 
@@ -68,7 +86,10 @@ For gradient you can use the following tailwindCSS gradients:
 - Gray wave (600 - 700): `from-cool-gray-600 to-cool-gray-700`
 
 Example use:
-`<div class="bg-gradient-to-b from-brand-accent to-purple-600 ..."></div>`
+
+```html
+  <div class="bg-gradient-to-b from-brand-accent to-purple-600 ..."></div>
+```
 
 Will give you purple wave gradient.
 
@@ -76,14 +97,14 @@ Will give you purple wave gradient.
 
 If you'd like other custom names, you can make [tailwindcss color customizations](https://tailwindcss.com/docs/customizing-colors#using-the-default-colors) to the provided values and use them in your code.
 
-###### 2. Using CSS-in-JS
+#### 2. Using CSS-in-JS
 
 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*
 
-```Javascript
+```js
   import React from 'react'
   import { color } from '@mindvalley/design-system'
 
@@ -102,13 +123,13 @@ If you'd like other custom names, you can make [tailwindcss color customizations
   export default App;
 ```
 
-#### 🖋️ Typography
+## 🖋️ Typography
 
-#### Typography plugin (Tailwindcss)
+### Typography plugin (Tailwindcss)
 
-Mindvalley's design eco-system is highly opinionated with most repos utilizing TailwindCSS. 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
+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
 
-##### How to use it?
+#### 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.
 
@@ -164,7 +185,7 @@ Let's say that you are trying to codify a button from a Figma design, and you wa
 
 - The typography plugin by default, generates Kebab cased class names, such as `title-bold-1`.  However, you can customize the class name casing by passing a `casing` option to the plugin. Supported casing options include `snakeCase`, `camelCase`, and `pascalCase.`
 
-Usage:
+Here is how to pass the casing:
 
   ```js
   module.exports = {
@@ -183,20 +204,22 @@ Usage:
   .TitleBold8 {
     ...
   }
-
   ```
 
-- The resulting typography classes are responsive for two screen sizes: desktop and mobile/tablet.
-
 ##### Best Practices
 
-###### Don't Do
+The resulting typography classes are responsive for two screen sizes: desktop and mobile/tablet.
+You don't need to add screen prefixes to the CSS classes.
+
+For example, the `title-bold-5` class includes media queries for both desktop and mobile/tablet, so there's no need to add custom media queries in the markup. Here's an example of the CSS for `title-bold-5`:
+
+###### Bad ❌
 
 ```html
 <h1 class="title-bold-5 md:title-bold-3">Hello World!</h1>
 ```
 
-###### Do
+###### Good ✅
 
 ```html
 <h1 class="title-bold-5">Hello World!</h1>
@@ -220,6 +243,53 @@ Since the typography classes are responsive, you don't need to add media queries
 }
 ```
 
+#### Configuring the brand
+The Mindvalley design system also supports multiple brands, including the core Mindvalley brand and a B2B (business-to-business) brand. Each brand has its own set of typography tokens that can be used to ensure consistency across different projects and platforms.
+
+To configure the typography for a specific brand within your TailwindCSS setup, you will need to adjust your `tailwind.config.js` file to include the brand-specific typography tokens.
+
+Here's how you can configure the brand:
+1. In your `tailwind.config.js` file, require and configure the typography plugin with the brand option.
+
+For the core Mindvalley brand:
+
+```js
+module.exports = {
+// ...
+  plugins: [
+    require('@mindvalley/design-system/dist/tailwind/plugins/typography.js')({
+      brands: ['mindvalley']
+    }),
+  ],
+  // ...
+}
+```
+This is the same as the default config and ends up rendering typography classes for Mindvalley's core
+design. You can omit this if you are working with just the normal Mindvalley brand.
+
+For the B2B brand:
+
+```js
+module.exports = {
+// ...
+  plugins: [
+    require('@mindvalley/design-system/dist/tailwind/plugins/typography.js')({
+      brands: ['mindvalley', 'b2b']
+    }),
+  ],
+  // ...
+}
+```
+
+This configuration will generate the necessary CSS classes for typography based on the tokens defined for each brand. 
+You can then use these classes in your HTML or JSX files to apply the correct typography styles for the brand 
+you are working on.
+
+Note: B2b brand builds on top of the core brand typography with an additional specific typography style. As such we have to have both options added to the brands config list for both to be included.
+
+Browse [B2B foundations figma file](https://www.figma.com/file/1EPj7v5H5JhP2d0v2h8QeC/B2B-Foundations?type=design&node-id=139-11&mode=design&t=SY5HTy1zbFO5p80n-0) to see the specific typography.
+
+
 #### Configuring the breakpoint
 
 By default, the plugin uses the `lg` breakpoint from the [screen size configuration](https://tailwindcss.com/docs/screens) in your Tailwind configuration. If you have a different configuration or naming convention for your Tailwind breakpoints, you can specify the identifier of the desired breakpoint using the `breakingPoint` option in the plugin configuration.
@@ -265,12 +335,11 @@ 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.
 
-<img src="getting-class-name.png" width="1000" height="auto">
+![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 -->
@@ -278,3 +347,283 @@ You'll need to make the plugin aware of the `breakingPoint` boundary between the
 ```
 
 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
+
+This guide provides detailed instructions on how to integrate and use icons within your applications.
+
+Our icon collection is meticulously organized into three distinct categories, each serving a unique purpose within your applications. Here's a breakdown of these categories:
+
+1. **Brand Icons**: These icons are specific to branding and include logos, trademarks, etc.
+2. **UI Icons**: Designed to enhance user interface aesthetics and usability.
+3. **Category Icons**: These icons represent different categories or topics covered in the content.
+
+All icons are available as single icons or as combined sets in an svg sprite.
+
+> A sprite is a single image file which contains multiple graphics. By using sprites, you can load multiple icons with a single HTTP request.
+
+> See the [Working Figma file for icons](https://www.figma.com/file/0b2swzflgtIMoELPgj4TVI/MV-Icons?node-id=203:3)
+
+Accessing the icons for your project is a straightforward process. We provide a single npm package with different ways of accessing icons.
+
+#### Installing the icons
+
+You will have to have the mindvalley design system npm package installed to access the icons. See the [installation guide](#using-npm-or-yarn).
+
+#### Accessing the icons
+
+With the package installed you can now access the icons with these access methods.
+
+a) **Recommended method (category-specific directories)**
+
+This is the updated and recommended method. It involves accessing icons and sprites from category-specific organized directories.
+
+Below is the organized file tree, showcasing the intuitive structuring of icons in category-specific folders and sprites:
+
+```txt
+dist
+├── icons
+│   └── categories 
+│   │   ├── icon-body.svg                 // single category icon
+│   │   ├── icons-career.svg
+│   │   ├── ...
+│   │   └── wordmark-soul-spanish.svg
+│   │
+│   └── brand-icons 
+│   │   ├── aging-filled.svg              // single brand icon
+│   │   ├── aging-outlined.svg
+│   │   ├── ...
+│   │   └── vision-outlined.svg
+│   │
+│   └── ui-icons  
+│   │   ├── activity-filled.svg           // single ui icon
+│   │   ├── activity-outline.svg
+│   │   ├── ...
+│   │   └── zoom-out-outline.svg
+│   │
+│   ├── sprites
+│   │   ├── ui-icons.svg                  // sprites by category
+│   │   ├── brand-icons.svg
+│   │   ├── categories.svg
+```
+
+And here are the path conventions to follow:
+
+- Path to an individual icon: `@mindvalley/design-system/dist/icons/<category>/<icon-name>.svg`
+- Path to combined sprite icons: `@mindvalley/design-system/dist/icons/<sprites>/<category-sprite>.svg`
+
+For a detailed overview of the available icons in each category, refer to the following:
+
+1. [Brand Icons](icons/brand-icons.md)
+2. [UI Icons](icons/ui-icons.md)
+3. [Categories](icons/categories.md)
+
+b) **Legacy Method (To be deprecated) - combined directory/sprite**
+
+This initial method involves using the combined `svg-defs.svg` sprite file or from the `svg` folder which is combination of UI icons and category icons.
+
+Here’s the tree path for a clearer view:
+
+```text
+dist
+├── svg
+│   ├── activity-filled.svg
+│   ├── activity-outline.svg
+│   ├── airplay-filled.svg
+│   ├── airplay-official-audio.svg       // single icon file
+│   ├── airplay-official-video.svg
+│   ├── ...
+│   └── zoom-out-outline.svg
+├── svg-sprite
+│   └── svg-defs.svg                     // sprite file
+```
+
+And here are the path conventions to follow:
+
+- Path to individual icons: `@mindvalley/design-system/dist/svg/<icon-name>.svg`
+- Path to combined sprite icons: `@mindvalley/design-system/dist/svg-sprite/svg-defs.svg`
+
+Visit the Legacy [combined icons view](icons/legacy-combined.md) for the full list of icons accessed this way.
+
+> Important: This legacy method of accessing icons is slated for deprecation. We encourage users to adopt the updated, category-specific approach to ensure compatibility and receive the latest icon updates.
+
+#### Using icons in your project?
+
+Below are instructions for integrating icons in different types of projects including Vue and Elixir Phoenix applications.
+
+##### With Vue.js
+
+There are plenty of JS libries to use here but the recommended one is [vue-svg-sprite](https://github.com/thierrymichel/vue-svg-sprite).
+
+##### Using vue-svg-sprite
+
+Start by installing it:
+
+```
+npm i vue-svg-sprite
+```
+
+or
+
+```
+yarn add vue-svg-sprite
+```
+
+And then, in your code, you can import and configure the library to work with the provided sprites.
+
+```js
+import Vue from 'vue';
+import { svgSpritePlugin } from 'vue-svg-sprite';
+
+/** See all the paths to import from in the Accessing icons from the npm package section */
+import svgSpriteUrl from '@mindvalley/design-system/dist/svg-sprite/svg-defs.svg'
+
+Vue.use(SvgSprite, {
+  url: svgSpriteUrl
+})
+
+/** On a component */ 
+<template>
+  <div class="container">  
+    <svg v-svg symbol="activity-filled" size="24" class="some-class" ></svg>
+  </div>
+</template>
+```
+
+Checkout vue-svg-sprite documentation for more configuration and usage in vue.
+
+ Be sure to checkout [Accessing icons from the npm package](#accessing-the-icons) for all paths to icon / sprites.
+
+#### 2. Usage in Elixir phoenix
+
+**1. Import the sprite in your js file(s)**
+
+*in your `**/app.js`*
+
+```js
+  import "@mindvalley/design-system/dist/svg-sprite/svg-defs.svg";
+  ...
+```
+
+**2. Update your bundler to load the svg sprite**
+
+*webpack.config.js*
+
+```js
+  module.exports = {
+    ...
+    module: {
+      rules: [
+       ...,
+        {
+          test: /\.(svg)$/i,
+          loader: "file-loader",
+          options: {
+            name: '[name].[ext]',
+            outputPath: "../images",
+          },
+        }
+      ]
+    }
+  }
+```
+
+This configuration is set up to process .svg files through [file-loader](https://v4.webpack.js.org/loaders/file-loader/) or [asset modules](https://webpack.js.org/guides/asset-modules/), keeping their original names and placing them in a directory named images one level above the Webpack output directory. In this example the images folder here is the one in `assets/` in a phoenix project.
+
+By doing this the svg sprite is available during development and will be copied over and be available in priv/static in production.
+
+**3. Use a helper module to help import the sprite**
+
+Next, define a helper module to consume the sprite:
+
+```elixir
+defmodule SampleApp.SvgHelpers do
+  @moduledoc """
+  Svg helpers for rendering svg icons
+  """
+  import Phoenix.HTML.Tag
+
+  @base_path "/images"
+
+  @doc """
+  Creates an SVG tag which references a SVG sprite from an external SVG sprite
+  file and returns it as a safe HTML string.
+
+  ** How to use it **
+  <%= svg_icon "activity-filled", class: "w-5 h-5 fill-current inline-block" %>
+
+  ** The html output
+  <svg class="inline-block w-5 h-5 fill-current">
+    <use href="/images/svg-defs.svg#activity-filled"></use>
+  </svg>
+  """
+  def svg_icon(icon_id, opts \\ [])
+
+  def svg_icon(icon_id, opts) do
+    content_tag(:svg, use_tag(icon_id), opts)
+  end
+
+  defp use_tag(icon_id) do
+    content_tag(:use, "", href: @base_path <> "/svg-defs.svg#" <> icon_id)
+  end
+end
+```
+
+**4. Use the module**
+
+Next import the helper globally to make the svg_icon/2 available:
+
+```elixir
+# import the helper in /lib/sample_app_web.ex
+import SampleApp.SvgHelpers 
+```
+
+And finally use the sprite using the icon id.
+
+```elixir
+<%= svg_icon "chevron-right-filled", class: "w-5 h-5 fill-current inline-block" %>
+```
+
+> Note: You can alternatively utilize the [SvgSprite](https://hexdocs.pm/svg_sprite/SvgSprite.html) library which might be a suitable method when you are accessing the svg files via category-specific directories recommended style the icons from the package.
+
+💡 Tip
+
+Icon name/id and previews of the svg file you want to use are linked in the [Accessing the icons](#accessing-the-icons) sections. Here is is sample preview of brand icons:
+
+![icons previews](./icon-preview-names-ids.png)
+
+## 🔜 Wordmarks
+
+Just like icons, wordmarks are also conveniently organized into specific directories and also include a common sprites folder.
+
+```text
+dist
+├── wordmarks
+│   ├── trainers 
+│   │   ├── agapi-stassinopoulos.svg    // Example of a single trainer wordmark
+│   │   ├── ajit-nawalkha-left.svg
+│   │   ├── ...
+│   │   └── vykintas-glodenis.svg
+│   │
+│   ├── topics 
+│   │   ├── certs-10-x-fitness-left.svg  // Example of a single topic wordmark
+│   │   ├── certs-10-x-fitness.svg
+│   │   ├── ...
+│   │   └── coming-soon-reclaim-your-happiness.svg
+│   │
+│   └── sprites
+│       ├── trainers.svg             // Trainers wordmarks sprite
+│       └── topics.svg               // Topics wordmarks sprite
+```
+
+Here are the path conventions to follow to access wordmarks:
+
+- Path to an individual wordmark: `@mindvalley/design-system/dist/wordmarks/<category>/<wordmark-name>.svg`
+- Path to a combined wordmarks sprite: `@mindvalley/design-system/dist/wordmarks/sprites/<category-sprite>.svg`
+
+Explore the detailed list of wordmarks available for each category
+
+1. [Topics](wordmarks/topics.md)
+2. [Trainers](wordmarks/trainers.md)
+
+Since they are svgs under the hood, you can use the methods defined in the [icons](#©️-icons) section to access and utilize them in your app.