npm - @mindvalley/design-system - Versions diffs - 3.4.2 → 4.0.1 - Mend

@mindvalley/design-system 3.4.2 → 4.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (32) hide show

package/CHANGELOG.md +90 -2
package/dist/b2b.d.ts +45 -45
package/dist/b2b.d.ts.map +1 -1
package/dist/b2b.js +1 -1
package/dist/b2b.js.map +1 -1
package/dist/helpers/casing.d.ts.map +1 -1
package/dist/helpers/casing.js +21 -23
package/dist/helpers/dimens.d.ts +1 -0
package/dist/helpers/dimens.d.ts.map +1 -1
package/dist/helpers/dimens.js +11 -2
package/dist/helpers/regex.d.ts.map +1 -1
package/dist/index.d.ts +98 -83
package/dist/index.d.ts.map +1 -1
package/dist/index.js +1 -1
package/dist/index.js.map +1 -1
package/dist/tailwind/plugins/tokens/b2b/typography.d.ts.map +1 -1
package/dist/tailwind/plugins/tokens/b2b/typography.js +25 -26
package/dist/tailwind/plugins/tokens/mindvalley/typography.d.ts.map +1 -1
package/dist/tailwind/plugins/tokens/mindvalley/typography.js +60 -67
package/dist/tailwind/plugins/typography.d.ts.map +1 -1
package/dist/tailwind/plugins/typography.js +25 -15
package/dist/typography/b2b/fonts.css +19 -0
package/dist/typography/b2b/fonts.d.ts +8 -0
package/dist/typography/b2b/fonts.js +30 -0
package/dist/typography/mindvalley/fonts.css +43 -0
package/dist/typography/mindvalley/fonts.d.ts +8 -0
package/dist/typography/mindvalley/fonts.js +54 -0
package/docs/USAGE.md +121 -76
package/docs/typography-fonts.md +552 -0
package/docs/typography-token-pipeline-b2b.md +156 -0
package/package.json +17 -3
package/docs/token-validation.md +0 -298

package/docs/typography-fonts.md ADDED Viewed

@@ -0,0 +1,552 @@
+# Typography font loading
+This guide provides comprehensive instructions on how to load Mindvalley Design System typography fonts in your application across different frameworks and scenarios.
+## Overview
+The Mindvalley Design System provides pre-generated `@font-face` CSS declarations that you can easily import into your project. The fonts are hosted on Fastly CDN and optimized for performance with `font-display: swap`.
+## Available fonts
+The design system includes fonts for two brands:
+- **Mindvalley** (`@mindvalley/design-system/typography/mindvalley/fonts.css`)
+- **B2B** (`@mindvalley/design-system/typography/b2b/fonts.css`)
+Each brand includes the following font families:
+- Sharp Grotesk Cyr Book 19
+- Sharp Grotesk Cyr Book Itl 19
+- Sharp Grotesk Cyr Medium 19
+- Sharp Grotesk Cyr Medium 20
+- Sharp Grotesk Cyr Medium 22
+- Sharp Grotesk Cyr Semibold 20
+## Installation
+First, ensure you have the design system package installed:
+```bash
+npm install @mindvalley/design-system
+```
+or
+```bash
+yarn add @mindvalley/design-system
+```
+---
+## Basic usage
+### Direct CSS import
+> ⚠️ **Important for PostCSS users**: If you're using `@import` in SCSS/CSS files with `postcss-import`, make sure to configure it to resolve from `node_modules` and use the full `dist/` path. See [PostCSS configuration](#using-with-postcss-and-scss-import-phoenix-webpack--scss) for details.
+#### Mindvalley brand only
+```css
+@import '@mindvalley/design-system/typography/mindvalley/fonts.css';
+```
+#### B2B brand only
+```css
+@import '@mindvalley/design-system/typography/b2b/fonts.css';
+```
+#### Both brands
+If your application uses both Mindvalley and B2B typography:
+```css
+@import '@mindvalley/design-system/typography/mindvalley/fonts.css';
+@import '@mindvalley/design-system/typography/b2b/fonts.css';
+```
+### Using without a bundler
+If you're working on a static HTML project without a bundler (Webpack, Vite, etc.), you'll need to copy the CSS file to your public assets directory:
+**Build script example:**
+```json
+{
+  "scripts": {
+    "copy-fonts": "cp node_modules/@mindvalley/design-system/dist/typography/mindvalley/fonts.css public/assets/css/"
+  }
+}
+```
+Then reference it in your HTML:
+```html
+<link rel="stylesheet" href="/assets/css/fonts.css">
+```
+**Note:** For modern JavaScript projects, use the import method instead (see above), which is handled automatically by your bundler.
+---
+## Framework-specific integration
+### Next.js
+#### App Router (Next.js 13+)
+**Using in Root Layout (`app/layout.tsx`):**
+```tsx
+import '@mindvalley/design-system/typography/mindvalley/fonts.css'
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  )
+}
+```
+#### Pages Router (Next.js 12 and below)
+**Using in custom app (`pages/_app.tsx`):**
+```tsx
+import '@mindvalley/design-system/typography/mindvalley/fonts.css'
+import type { AppProps } from 'next/app'
+export default function App({ Component, pageProps }: AppProps) {
+  return <Component {...pageProps} />
+}
+```
+#### Loading fonts in a component
+If you only need fonts in specific pages or components:
+```tsx
+import '@mindvalley/design-system/typography/b2b/fonts.css'
+export default function B2BPage() {
+  return (
+    <div className="title-bold-5">
+      B2B Page Content
+    </div>
+  )
+}
+```
+---
+### Vite + React
+**In your main entry point (`src/main.tsx` or `src/index.tsx`):**
+```tsx
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import '@mindvalley/design-system/typography/mindvalley/fonts.css'
+import App from './App'
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+)
+```
+**Or in your global CSS file (`src/index.css`):**
+```css
+@import '@mindvalley/design-system/typography/mindvalley/fonts.css';
+/* Your other global styles */
+```
+---
+### Vue.js (Vite or Vue CLI)
+#### Using in main entry point
+**In your main entry file (`src/main.ts` or `src/main.js`):**
+```ts
+import { createApp } from 'vue'
+import '@mindvalley/design-system/typography/mindvalley/fonts.css'
+import App from './App.vue'
+createApp(App).mount('#app')
+```
+#### Using in a component
+**In a single file component:**
+```vue
+<template>
+  <div>
+    <h1 class="title-bold-5">Welcome to Mindvalley</h1>
+    <p class="body">This uses design system typography.</p>
+  </div>
+</template>
+<style>
+@import '@mindvalley/design-system/typography/mindvalley/fonts.css';
+</style>
+```
+#### Using in global CSS
+**In your global CSS file (`src/assets/main.css`):**
+```css
+@import '@mindvalley/design-system/typography/mindvalley/fonts.css';
+/* Your other global styles */
+```
+Then import it in your main entry:
+```ts
+import { createApp } from 'vue'
+import './assets/main.css'
+import App from './App.vue'
+createApp(App).mount('#app')
+```
+#### Composition API with programmatic usage
+If you need to access font CSS programmatically:
+```vue
+<script setup>
+import { fontFaceCSS } from '@mindvalley/design-system/typography/mindvalley/fonts'
+// Inject into head if needed
+const injectFonts = () => {
+  const style = document.createElement('style')
+  style.textContent = fontFaceCSS
+  document.head.appendChild(style)
+}
+</script>
+```
+---
+### Webpack
+#### Using in entry point
+**In your main JavaScript/TypeScript file:**
+```js
+import '@mindvalley/design-system/typography/mindvalley/fonts.css'
+```
+#### Webpack configuration
+Ensure your webpack config has CSS loading capability:
+```js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.css$/i,
+        use: ['style-loader', 'css-loader'],
+      },
+    ],
+  },
+}
+```
+---
+### Phoenix (Elixir)
+#### Using with esbuild (Phoenix 1.6+)
+**1. Import in your app.js:**
+```js
+// assets/js/app.js
+import '@mindvalley/design-system/typography/mindvalley/fonts.css'
+```
+**2. Ensure CSS is configured in `config/config.exs`:**
+```elixir
+config :esbuild,
+  version: "0.17.11",
+  default: [
+    args: ~w(js/app.js --bundle --target=es2017 --outdir=../priv/static/assets --external:/fonts/* --external:/images/*),
+    cd: Path.expand("../assets", __DIR__),
+    env: %{"NODE_PATH" => Path.expand("../deps", __DIR__)}
+  ]
+```
+#### Using with Webpack (Phoenix 1.5 and below)
+**1. Import in your app.js:**
+```js
+// assets/js/app.js
+import '@mindvalley/design-system/typography/mindvalley/fonts.css'
+```
+**2. Ensure webpack config has CSS loader:**
+```js
+// assets/webpack.config.js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.css$/,
+        use: ['style-loader', 'css-loader']
+      }
+    ]
+  }
+}
+```
+#### Using with PostCSS and SCSS @import (Phoenix Webpack + SCSS)
+If you're using SCSS files with `@import` statements instead of JavaScript imports, you'll need to configure `postcss-import` to resolve from `node_modules`:
+**1. Configure PostCSS (`assets/postcss.config.js`):**
+```js
+module.exports = {
+  plugins: [
+    require('postcss-import')({
+      path: ['node_modules']
+    }),
+    require('tailwindcss'),
+    require('autoprefixer')
+  ],
+}
+```
+**2. Import in your SCSS file (`assets/css/app.scss`):**
+```scss
+@import '@mindvalley/design-system/dist/typography/mindvalley/fonts.css';
+```
+> **Note:** When using `@import` with `postcss-import`, you must use the full `dist/` path since postcss-import doesn't use package export resolution like modern JavaScript bundlers do.
+---
+## CSS-in-JS solutions
+### Styled Components
+**Using global styles:**
+```tsx
+import { createGlobalStyle } from 'styled-components'
+import { fontFaceCSS } from '@mindvalley/design-system/typography/mindvalley/fonts'
+const GlobalStyles = createGlobalStyle`
+  ${fontFaceCSS}
+  /* Your other global styles */
+  body {
+    font-family: 'Sharp Grotesk Cyr Book 19', sans-serif;
+  }
+`
+export default function App() {
+  return (
+    <>
+      <GlobalStyles />
+      {/* Your app content */}
+    </>
+  )
+}
+```
+---
+## JavaScript/TypeScript module usage
+For programmatic use cases where you need the CSS as a string:
+### ES modules
+```typescript
+import { fontFaceCSS } from '@mindvalley/design-system/typography/mindvalley/fonts'
+// Inject into a style tag
+const styleElement = document.createElement('style')
+styleElement.textContent = fontFaceCSS
+document.head.appendChild(styleElement)
+```
+### CommonJS
+```javascript
+const { fontFaceCSS } = require('@mindvalley/design-system/typography/mindvalley/fonts')
+// Use the CSS string as needed
+console.log(fontFaceCSS)
+```
+---
+## Brand-specific examples
+### Mindvalley brand project
+```tsx
+// src/main.tsx
+import '@mindvalley/design-system/typography/mindvalley/fonts.css'
+import { colors } from '@mindvalley/design-system'
+// Now use Mindvalley typography classes
+function Hero() {
+  return (
+    <h1 className="title-bold-1" style={{ color: colors.brandAccent }}>
+      Welcome to Mindvalley
+    </h1>
+  )
+}
+```
+### B2B brand project
+```tsx
+// src/main.tsx
+import '@mindvalley/design-system/typography/b2b/fonts.css'
+import { colors } from '@mindvalley/design-system/b2b'
+// Now use B2B typography classes
+function Hero() {
+  return (
+    <h1 className="title-bold-1" style={{ color: colors.brandAccent }}>
+      Welcome to Mindvalley B2B
+    </h1>
+  )
+}
+```
+### Multi-brand project
+If your application needs to support both brands (e.g., a platform that serves both consumer and B2B users):
+```tsx
+// src/main.tsx
+import '@mindvalley/design-system/typography/mindvalley/fonts.css'
+import '@mindvalley/design-system/typography/b2b/fonts.css'
+// Now both brand fonts are available
+function App() {
+  const isBB2User = checkUserType() // Your logic
+  return (
+    <div className={isBB2User ? 'b2b-theme' : 'mindvalley-theme'}>
+      {/* Your app content */}
+    </div>
+  )
+}
+```
+---
+## Best practices
+### Performance optimization
+1. **Only Import What You Need**: If you only use one brand, only import that brand's fonts.
+2. **Use `font-display: swap`**: All generated font files use `font-display: swap` by default, which shows fallback text immediately and swaps to custom fonts when loaded.
+3. **Preload Critical Fonts** (Optional): For even better performance, you can preload the most critical font files:
+```html
+<link rel="preload" href="https://assets.mindvalley.com/api/v1/assets/b61f86ec-3dbd-4674-907a-f3f26f5101ce.woff2" as="font" type="font/woff2" crossorigin>
+```
+### Font loading strategy
+The fonts are loaded with `font-display: swap`, which means:
+1. Text is immediately visible using fallback fonts (Helvetica, Arial, sans-serif)
+2. Custom fonts load in the background
+3. Text swaps to custom fonts once loaded
+4. No layout shift since line heights are optimized
+### Fallback fonts
+All typography classes include proper fallback fonts:
+```css
+font-family: 'Sharp Grotesk Cyr Book 19', Helvetica, Arial, sans-serif;
+```
+---
+## Troubleshooting
+### Fonts not loading
+1. **Check Import Path**: Ensure you're using the correct import path with `/typography/` in the path.
+2. **Build Configuration**: Verify your bundler is configured to handle CSS imports from node_modules.
+3. **PostCSS Import**: If using `@import` in SCSS/CSS files, ensure `postcss-import` is configured with `path: ['node_modules']`. See [PostCSS configuration](#using-with-postcss-and-scss-import-phoenix-webpack--scss).
+4. **CDN Access**: Ensure your application can access the Fastly CDN URLs.
+### TypeScript errors
+If you get TypeScript errors when importing CSS:
+```typescript
+// Add to your tsconfig.json or create a declaration file
+declare module '*.css' {
+  const content: string
+  export default content
+}
+```
+Or specifically for the design system:
+```typescript
+// src/types/design-system.d.ts
+declare module '@mindvalley/design-system/typography/*/fonts' {
+  export const fontFaceCSS: string
+  export default fontFaceCSS
+}
+```
+### Webpack/bundler issues
+Ensure you have the appropriate loaders installed:
+```bash
+npm install --save-dev style-loader css-loader
+```
+---
+## Related documentation
+- [Typography Plugin Usage](./USAGE.md#%EF%B8%8F-typography) - How to use typography classes
+- [Color System](./USAGE.md#-colors) - Working with design system colors
+- [Icon System](./USAGE.md#%EF%B8%8F-icons) - Using design system icons
+---
+## Support
+For issues or questions:
+- [GitHub Issues](https://github.com/mindvalley/mv-design-system/issues)
+- [Design System Documentation](../README.md)

package/docs/typography-token-pipeline-b2b.md ADDED Viewed

@@ -0,0 +1,156 @@
+****# Typography Token Pipeline (B2B)
+This document explains, end‑to‑end, how B2B typography tokens are processed in this repository: where they start, which hooks/transforms/filters run, and what the final output is. It also highlights the current gap around using group‑level `description` during transforms and options to fix it.
+## Problem Statement
+We want to use the typography group’s `description` (e.g., "Sharp Grotesk … 20/21/22") to build the final `fontFamily` string. However, leaf tokens (base/mobile/tablet/desktop) do not surface that parent `description` in transforms, so `getFontFamily` cannot read it directly.
+## Initial State (Source Tokens)
+- Location: `src/tokens/brands/b2b/typography.json`
+- Origin: Exported by Supernova.
+- Shape:
+  - Nested groups under `typography` (e.g., `deprecated-mobile`, `header`, `display`, `heading‑1`, …)
+  - Leaf tokens look like `{ value: { fontFamily, fontSize, lineHeight, letterSpacing, ... }, type: 'typography' }`
+  - The group’s human‑readable descriptor lives on the group as `description` (e.g., on `display‑1`, `heading‑6`, etc.), not on the leaf tokens.
+Example (condensed):
+```json
+{
+  "typography": {
+    "header": {
+      "heading-6": {
+        "base": { "value": { "fontFamily": "Sharp Grotesk Cyr Medium", "fontSize": "16px", ... }, "type": "typography" },
+        "mobile": { "value": { ... }, "type": "typography" },
+        "desktop": { "value": { ... }, "type": "typography" },
+        "description": "Sharp Grotesk Cyr Medium 20"
+      }
+    }
+  }
+}
+```
+## Build Entry
+- Command: `npm run build:styledictionary`
+- Script: `ts-node ./build.ts`
+- Brands built: currently `b2b` (see `build.ts`)
+## Registration (build.ts)
+- Transforms registered: from `src/utilities/style-dictonary/transforms` (color, typography, naming), plus SD built‑ins.
+- Transform groups (`src/utilities/style-dictonary/transformGroups/index.ts`):
+  - `js-object`: `['attribute/cti', 'font/object', 'name/ti/kebab', 'name/ts/kebab']`
+  - `js-ti`: `['attribute/cti', 'color/rgbaOrHex', 'name/ti/kebab']`
+- Filters: `b2b-typography` / `mindvalley-typography` from `src/utilities/style-dictonary/filters`.
+- Formats: `typescript/module-flat` from `src/utilities/style-dictonary/formats/typescript.ts`.
+Note: `typography/responsive` transform is registered but not referenced in `js-object`. Responsive consolidation currently happens in the formatter (`formatters/responsiveTypography.ts`).
+## Platform Config (build.ts → getStyleDictionaryConfig)
+- `source`: `src/tokens/brands/b2b/*.json`
+- Platforms:
+  - `js` platform
+    - `transformGroup`: `js-ti`
+    - Outputs color tokens to `src/build/js/b2b/colors.js`
+  - `typography` platform
+    - `transformGroup`: `js-object`
+    - `filter`: `b2b-typography`
+    - `format`: `typescript/module-flat`
+    - Output: `src/tailwind/plugins/tokens/b2b/typography.ts`
+## Processing Sequence (Typography)
+1) Source ingestion
+- Style Dictionary reads `src/tokens/brands/b2b/typography.json` into a token tree.
+- Built‑in `attribute/cti` later derives `token.attributes` (`category`, `type`, `item`, …) from `token.path`.
+2) Filter
+- The file entry for typography uses the `b2b-typography` filter to keep only typography tokens under the desired categories (`display`, `header`, `heading`) and exclude deprecated ones.
+3) Transform group: `js-object`
+- `attribute/cti` (built‑in): populates `token.attributes` used by subsequent transforms.
+- `font/object` (`src/utilities/style-dictonary/transforms/typography.ts`):
+  - Filter: only typography tokens (`token.attributes.category === 'typography'`).
+  - Builds a normalized value object:
+    - `fontFamily`: via `getFontFamily(token)`.
+    - `fontSize`, `lineHeight`, `letterSpacing`: normalized to strings; accepts both structured measure/unit and simple strings like `"80px"`.
+  - `getFontFamily(token)`
+    - Intended to prefer a Sharp Grotesk face derived from the group’s descriptor.
+    - Fallback to a mapping for known family names.
+    - Current limitation: transforms do not receive the group’s `description` on leaf tokens; neither `token.original.description` nor `token.comment` is populated by default for this source.
+- `name/ti/kebab` and `name/ts/kebab` (naming transforms): compute token names based on path/type.
+4) Format: `typescript/module-flat`
+- File: `src/utilities/style-dictonary/formats/typescript.ts`.
+- Uses `groupAndOptimizeTokens` (`formatters/responsiveTypography.ts`) to:
+  - Deduplicate path segments (e.g., remove category prefix redundancies).
+  - Decide whether to emit single tokens or `-mobile`/`-desktop` responsive variants by comparing values across breakpoints.
+  - Produce the final JS object with `fontFamily`, `fontSize`, `letterSpacing`, `lineHeight`, `fontWeight?`.
+- Output file: `src/tailwind/plugins/tokens/b2b/typography.ts` (TypeScript module with an interface + token object).
+## End State (Artifacts)
+- Colors: `src/build/js/b2b/colors.js` (if any)
+- Typography: `src/tailwind/plugins/tokens/b2b/typography.ts`
+  - Contains a flat object keyed by token names (some with `-mobile` and `-desktop`).
+  - Values are normalized strings; `fontFamily` uses mapping or description logic if available.
+## Sequence Diagram (Typography Flow)
+```mermaid
+flowchart TD
+  A[Source JSON\nsrc/tokens/brands/b2b/typography.json] --> B[Style Dictionary Config\n(build.ts)]
+  B --> C[Filter: b2b-typography]
+  C --> D[Transform Group: js-object]
+  D --> D1[attribute/cti]
+  D1 --> D2[font/object\n(getFontFamily, unit normalization)]
+  D2 --> D3[name/ti/kebab + name/ts/kebab]
+  D3 --> E[Format: typescript/module-flat\n(groupAndOptimizeTokens)]
+  E --> F[Output\nsrc/tailwind/plugins/tokens/b2b/typography.ts]
+```
+## Current Gap (Root Cause)
+- The typography group’s `description` is defined on the group (e.g., `heading-6`) and is not present on leaf tokens (`base`/`mobile`/`tablet`/`desktop`).
+- Style Dictionary does not, by default, surface that parent `description` on the leaf token objects available to transforms:
+  - `token.original.description` → empty
+  - `token.original.$description` → empty
+  - `token.comment` → empty
+- Attempts to inject description via parser or preprocessor did not appear in `token.comment` or `token.original` during transforms in this pipeline, so `getFontFamily` cannot use it directly.
+## Options to Resolve
+- Formatter‑based resolution (recommended, minimal)
+  - In the formatter, use `dictionary.tokens` and `token.path` to find the parent group node and read its `description`. Build the `fontFamily` string there.
+  - Pros: Full dictionary context; no reliance on transform‑time token shape.
+  - Cons: Couples font family logic to this formatter (acceptable given current architecture).
+- Preprocessor (central normalization)
+  - Use a preprocessor to copy the nearest group `description` onto leaf tokens as `comment` and/or `$description` before transforms.
+  - Ensure it operates on SD v5 `$value`/`$type` schema if needed.
+  - Pros: Keeps transforms simple; consistent across formats.
+  - Cons: Needs careful verification that the hook runs on our inputs; our initial attempt didn’t surface values during transforms.
+- Upstream token export change
+  - Adjust Supernova export to include the `description` on leaves (as `comment` or `$description`).
+  - Pros: Zero build‑time logic; most robust long‑term.
+  - Cons: Requires coordination/change to export settings.
+## Where the Issue Is
+- Stage: Transform (`font/object` → `getFontFamily`).
+- Symptom: No access to group‑level descriptor (`description`) on leaf tokens at transform time.
+- Impact: `fontFamily` can’t be built using the intended descriptor; fallback mapping is used instead.
+## Next Step (Proposed)
+- Implement formatter‑based descriptor lookup for `fontFamily` in `typescript/module-flat` (using `dictionary` + `path`).
+- Alternatively, finalize a preprocessor that provably runs on our inputs and sets `token.comment` for transforms.