@mindvalley/design-system 4.0.0 → 4.1.0
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.
- package/CHANGELOG.md +74 -235
- package/README.md +11 -17
- package/dist/b2b.d.ts +31 -95
- package/dist/b2b.d.ts.map +1 -1
- package/dist/b2b.js +1 -1
- package/dist/b2b.js.map +1 -1
- package/dist/tailwind/plugins/tokens/b2b/typography.d.ts +4 -1
- package/dist/tailwind/plugins/tokens/b2b/typography.d.ts.map +1 -1
- package/dist/tailwind/plugins/tokens/b2b/typography.js +25 -25
- package/dist/tailwind/plugins/tokens/mindvalley/typography-gsf.d.ts +15 -0
- package/dist/tailwind/plugins/tokens/mindvalley/typography-gsf.d.ts.map +1 -0
- package/dist/tailwind/plugins/tokens/mindvalley/typography-gsf.js +77 -0
- package/dist/tailwind/plugins/tokens/mindvalley/typography.d.ts.map +1 -1
- package/dist/tailwind/plugins/tokens/mindvalley/typography.js +420 -60
- package/dist/tailwind/plugins/typography-gsf.d.ts +31 -0
- package/dist/tailwind/plugins/typography-gsf.d.ts.map +1 -0
- package/dist/tailwind/plugins/typography-gsf.js +130 -0
- package/docs/README.md +25 -0
- package/docs/RELEASING.md +9 -9
- package/docs/USAGE.md +129 -131
- package/docs/token-validation.md +298 -0
- package/docs/typography/README.md +58 -0
- package/docs/typography/migration.md +166 -0
- package/docs/typography/setup.md +366 -0
- package/package.json +10 -3
- package/docs/CONTRIBUTION.md +0 -262
- package/docs/typography-fonts.md +0 -552
- package/docs/typography-token-pipeline-b2b.md +0 -156
|
@@ -0,0 +1,366 @@
|
|
|
1
|
+
# Typography setup
|
|
2
|
+
|
|
3
|
+
This guide covers how to set up typography in your application, including font loading and Tailwind plugin configuration.
|
|
4
|
+
|
|
5
|
+
## Google Sans Flex (recommended)
|
|
6
|
+
|
|
7
|
+
Google Sans Flex is a variable font that provides multiple weights and widths in a single file.
|
|
8
|
+
|
|
9
|
+
### 1. Load the font
|
|
10
|
+
|
|
11
|
+
Choose one of the following methods:
|
|
12
|
+
|
|
13
|
+
#### Option A: HTML link tags
|
|
14
|
+
|
|
15
|
+
Add to your HTML `<head>`:
|
|
16
|
+
|
|
17
|
+
```html
|
|
18
|
+
<link rel="preconnect" href="https://fonts.googleapis.com">
|
|
19
|
+
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
|
20
|
+
<link href="https://fonts.googleapis.com/css2?family=Google+Sans+Flex:wdth,wght@75..125,100..900&display=swap" rel="stylesheet">
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
#### Option B: CSS @import (Tailwind v4)
|
|
24
|
+
|
|
25
|
+
Import directly in your CSS file - ideal for Tailwind v4's CSS-first approach:
|
|
26
|
+
|
|
27
|
+
```css
|
|
28
|
+
/* Font import must come FIRST */
|
|
29
|
+
@import "https://fonts.googleapis.com/css2?family=Google+Sans+Flex:wdth,wght@75..125,100..900&display=swap";
|
|
30
|
+
|
|
31
|
+
@import "tailwindcss";
|
|
32
|
+
|
|
33
|
+
@config "./tailwind.config.js";
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
> **Important:** The Google Fonts `@import` must be the first statement in your CSS file. CSS requires `@import` rules to precede all other rules.
|
|
37
|
+
>
|
|
38
|
+
> **Note:** Google Sans Flex requires the variable font version to support width variations (`font-variation-settings: "wdth"`). Fontsource currently only offers static font weights, which won't work with this typography system.
|
|
39
|
+
|
|
40
|
+
### 2. Configure Tailwind plugin
|
|
41
|
+
|
|
42
|
+
```typescript
|
|
43
|
+
// tailwind.config.ts
|
|
44
|
+
import typography from '@mindvalley/design-system/tailwind/plugins/typography-gsf'
|
|
45
|
+
|
|
46
|
+
export default {
|
|
47
|
+
plugins: [
|
|
48
|
+
typography({
|
|
49
|
+
brands: ['mindvalley'], // or ['b2b'] for B2B projects
|
|
50
|
+
}),
|
|
51
|
+
],
|
|
52
|
+
}
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
### Plugin options
|
|
56
|
+
|
|
57
|
+
```typescript
|
|
58
|
+
typography({
|
|
59
|
+
// Class name casing (default: 'kebabCase')
|
|
60
|
+
casing: 'kebabCase' | 'camelCase' | 'snakeCase' | 'pascalCase' | 'noCase',
|
|
61
|
+
|
|
62
|
+
// Responsive breakpoints
|
|
63
|
+
breakpoints: {
|
|
64
|
+
tablet: '768px', // default: theme('screens.md')
|
|
65
|
+
desktop: '1024px', // default: theme('screens.lg')
|
|
66
|
+
},
|
|
67
|
+
|
|
68
|
+
// Optional class prefix
|
|
69
|
+
prefix: 'mv-',
|
|
70
|
+
|
|
71
|
+
// Brands to include
|
|
72
|
+
brands: ['mindvalley', 'b2b'],
|
|
73
|
+
})
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
### Tailwind v4 Setup
|
|
77
|
+
|
|
78
|
+
Tailwind v4 uses a CSS-first approach and doesn't require a config file by default. However, to use the typography plugin, you'll need to create a config file and load it with the `@config` directive.
|
|
79
|
+
|
|
80
|
+
**Step 1: Create `tailwind.config.js`**
|
|
81
|
+
|
|
82
|
+
```js
|
|
83
|
+
// tailwind.config.js
|
|
84
|
+
import typography from '@mindvalley/design-system/tailwind/plugins/typography-gsf'
|
|
85
|
+
|
|
86
|
+
export default {
|
|
87
|
+
plugins: [
|
|
88
|
+
typography({
|
|
89
|
+
brands: ['mindvalley'],
|
|
90
|
+
}),
|
|
91
|
+
],
|
|
92
|
+
}
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
**Step 2: Load the config in your CSS**
|
|
96
|
+
|
|
97
|
+
```css
|
|
98
|
+
/* app.css */
|
|
99
|
+
@import "tailwindcss";
|
|
100
|
+
@config "./tailwind.config.js";
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
**Step 3: Use typography classes as normal**
|
|
104
|
+
|
|
105
|
+
```html
|
|
106
|
+
<h1 class="title-bold-1">Welcome</h1>
|
|
107
|
+
<p class="body">Body text</p>
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
This same process works for the Sharp Grotesk plugin.
|
|
111
|
+
|
|
112
|
+
### 3. Use typography classes
|
|
113
|
+
|
|
114
|
+
```html
|
|
115
|
+
<h1 class="title-bold-1">Welcome to Mindvalley</h1>
|
|
116
|
+
<p class="body">This is body text using Google Sans Flex.</p>
|
|
117
|
+
<button class="button-text">Click Me</button>
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
> **Important:** Typography classes are already responsive - don't add screen prefixes!
|
|
121
|
+
>
|
|
122
|
+
> ```html
|
|
123
|
+
> <!-- Bad -->
|
|
124
|
+
> <h1 class="title-bold-5 md:title-bold-3">Hello</h1>
|
|
125
|
+
>
|
|
126
|
+
> <!-- Good -->
|
|
127
|
+
> <h1 class="title-bold-5">Hello</h1>
|
|
128
|
+
> ```
|
|
129
|
+
|
|
130
|
+
---
|
|
131
|
+
|
|
132
|
+
## Sharp Grotesk (legacy)
|
|
133
|
+
|
|
134
|
+
Sharp Grotesk is the legacy typography system using static font files hosted on Fastly CDN.
|
|
135
|
+
|
|
136
|
+
### 1. Load the font
|
|
137
|
+
|
|
138
|
+
#### Direct CSS import
|
|
139
|
+
|
|
140
|
+
```css
|
|
141
|
+
/* Mindvalley brand */
|
|
142
|
+
@import '@mindvalley/design-system/typography/mindvalley/fonts.css';
|
|
143
|
+
|
|
144
|
+
/* B2B brand */
|
|
145
|
+
@import '@mindvalley/design-system/typography/b2b/fonts.css';
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
#### JavaScript import
|
|
149
|
+
|
|
150
|
+
```typescript
|
|
151
|
+
import '@mindvalley/design-system/typography/mindvalley/fonts.css'
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
### 2. Configure Tailwind plugin
|
|
155
|
+
|
|
156
|
+
```typescript
|
|
157
|
+
// tailwind.config.ts
|
|
158
|
+
import typography from '@mindvalley/design-system/tailwind/plugins/typography'
|
|
159
|
+
|
|
160
|
+
export default {
|
|
161
|
+
plugins: [
|
|
162
|
+
typography({
|
|
163
|
+
brands: ['mindvalley'],
|
|
164
|
+
}),
|
|
165
|
+
],
|
|
166
|
+
}
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
---
|
|
170
|
+
|
|
171
|
+
## Framework examples
|
|
172
|
+
|
|
173
|
+
### React (Vite)
|
|
174
|
+
|
|
175
|
+
```tsx
|
|
176
|
+
// src/main.tsx
|
|
177
|
+
import './index.css'
|
|
178
|
+
|
|
179
|
+
import React from 'react'
|
|
180
|
+
import ReactDOM from 'react-dom/client'
|
|
181
|
+
import App from './App'
|
|
182
|
+
|
|
183
|
+
ReactDOM.createRoot(document.getElementById('root')!).render(
|
|
184
|
+
<React.StrictMode>
|
|
185
|
+
<App />
|
|
186
|
+
</React.StrictMode>,
|
|
187
|
+
)
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
```html
|
|
191
|
+
<!-- index.html -->
|
|
192
|
+
<head>
|
|
193
|
+
<link rel="preconnect" href="https://fonts.googleapis.com">
|
|
194
|
+
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
|
195
|
+
<link href="https://fonts.googleapis.com/css2?family=Google+Sans+Flex:wdth,wght@75..125,100..900&display=swap" rel="stylesheet">
|
|
196
|
+
</head>
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
### Next.js (App Router)
|
|
200
|
+
|
|
201
|
+
```tsx
|
|
202
|
+
// app/layout.tsx
|
|
203
|
+
import './globals.css'
|
|
204
|
+
|
|
205
|
+
export default function RootLayout({
|
|
206
|
+
children,
|
|
207
|
+
}: {
|
|
208
|
+
children: React.ReactNode
|
|
209
|
+
}) {
|
|
210
|
+
return (
|
|
211
|
+
<html lang="en">
|
|
212
|
+
<head>
|
|
213
|
+
<link rel="preconnect" href="https://fonts.googleapis.com" />
|
|
214
|
+
<link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="anonymous" />
|
|
215
|
+
<link href="https://fonts.googleapis.com/css2?family=Google+Sans+Flex:wdth,wght@75..125,100..900&display=swap" rel="stylesheet" />
|
|
216
|
+
</head>
|
|
217
|
+
<body>{children}</body>
|
|
218
|
+
</html>
|
|
219
|
+
)
|
|
220
|
+
}
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
### Next.js (Pages Router)
|
|
224
|
+
|
|
225
|
+
```tsx
|
|
226
|
+
// pages/_document.tsx
|
|
227
|
+
import { Html, Head, Main, NextScript } from 'next/document'
|
|
228
|
+
|
|
229
|
+
export default function Document() {
|
|
230
|
+
return (
|
|
231
|
+
<Html lang="en">
|
|
232
|
+
<Head>
|
|
233
|
+
<link rel="preconnect" href="https://fonts.googleapis.com" />
|
|
234
|
+
<link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="anonymous" />
|
|
235
|
+
<link href="https://fonts.googleapis.com/css2?family=Google+Sans+Flex:wdth,wght@75..125,100..900&display=swap" rel="stylesheet" />
|
|
236
|
+
</Head>
|
|
237
|
+
<body>
|
|
238
|
+
<Main />
|
|
239
|
+
<NextScript />
|
|
240
|
+
</body>
|
|
241
|
+
</Html>
|
|
242
|
+
)
|
|
243
|
+
}
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
### Vue 3
|
|
247
|
+
|
|
248
|
+
```typescript
|
|
249
|
+
// src/main.ts
|
|
250
|
+
import { createApp } from 'vue'
|
|
251
|
+
import './assets/main.css'
|
|
252
|
+
import App from './App.vue'
|
|
253
|
+
|
|
254
|
+
createApp(App).mount('#app')
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
```html
|
|
258
|
+
<!-- index.html -->
|
|
259
|
+
<head>
|
|
260
|
+
<link rel="preconnect" href="https://fonts.googleapis.com">
|
|
261
|
+
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
|
262
|
+
<link href="https://fonts.googleapis.com/css2?family=Google+Sans+Flex:wdth,wght@75..125,100..900&display=swap" rel="stylesheet">
|
|
263
|
+
</head>
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
### Phoenix (Elixir)
|
|
267
|
+
|
|
268
|
+
Add to your layout template (`lib/your_app_web/components/layouts/root.html.heex`):
|
|
269
|
+
|
|
270
|
+
```html
|
|
271
|
+
<head>
|
|
272
|
+
<link rel="preconnect" href="https://fonts.googleapis.com">
|
|
273
|
+
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
|
274
|
+
<link href="https://fonts.googleapis.com/css2?family=Google+Sans+Flex:wdth,wght@75..125,100..900&display=swap" rel="stylesheet">
|
|
275
|
+
</head>
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
**For Sharp Grotesk with PostCSS/SCSS:**
|
|
279
|
+
|
|
280
|
+
Configure `postcss-import` to resolve from `node_modules`:
|
|
281
|
+
|
|
282
|
+
```javascript
|
|
283
|
+
// assets/postcss.config.js
|
|
284
|
+
module.exports = {
|
|
285
|
+
plugins: [
|
|
286
|
+
require('postcss-import')({
|
|
287
|
+
path: ['node_modules']
|
|
288
|
+
}),
|
|
289
|
+
require('tailwindcss'),
|
|
290
|
+
require('autoprefixer')
|
|
291
|
+
],
|
|
292
|
+
}
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
Then import in SCSS:
|
|
296
|
+
|
|
297
|
+
```scss
|
|
298
|
+
// assets/css/app.scss
|
|
299
|
+
@import '@mindvalley/design-system/dist/typography/mindvalley/fonts.css';
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
> **Note:** When using `@import` with `postcss-import`, use the full `dist/` path.
|
|
303
|
+
|
|
304
|
+
### CSS-in-JS (Styled Components)
|
|
305
|
+
|
|
306
|
+
```tsx
|
|
307
|
+
import { createGlobalStyle } from 'styled-components'
|
|
308
|
+
|
|
309
|
+
// Add the Google Fonts link tag to your HTML head
|
|
310
|
+
|
|
311
|
+
const GlobalStyles = createGlobalStyle`
|
|
312
|
+
body {
|
|
313
|
+
font-family: 'Google Sans Flex', Helvetica, Arial, sans-serif;
|
|
314
|
+
}
|
|
315
|
+
`
|
|
316
|
+
|
|
317
|
+
export default function App() {
|
|
318
|
+
return (
|
|
319
|
+
<>
|
|
320
|
+
<GlobalStyles />
|
|
321
|
+
{/* Your app content */}
|
|
322
|
+
</>
|
|
323
|
+
)
|
|
324
|
+
}
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
---
|
|
328
|
+
|
|
329
|
+
## Troubleshooting
|
|
330
|
+
|
|
331
|
+
### Fonts not loading
|
|
332
|
+
|
|
333
|
+
1. **Check link tags**: Ensure the Google Fonts link is in your HTML `<head>`
|
|
334
|
+
2. **CDN access**: Ensure your app can reach `fonts.googleapis.com`
|
|
335
|
+
3. **Variable font support**: Verify your browser supports variable fonts
|
|
336
|
+
|
|
337
|
+
### TypeScript errors
|
|
338
|
+
|
|
339
|
+
If you get TypeScript errors when importing CSS:
|
|
340
|
+
|
|
341
|
+
```typescript
|
|
342
|
+
// src/types/css.d.ts
|
|
343
|
+
declare module '*.css' {
|
|
344
|
+
const content: string
|
|
345
|
+
export default content
|
|
346
|
+
}
|
|
347
|
+
```
|
|
348
|
+
|
|
349
|
+
### PostCSS import issues
|
|
350
|
+
|
|
351
|
+
When using `@import` in SCSS/CSS with `postcss-import`, use the full `dist/` path:
|
|
352
|
+
|
|
353
|
+
```scss
|
|
354
|
+
/* Works */
|
|
355
|
+
@import '@mindvalley/design-system/dist/typography/mindvalley/fonts.css';
|
|
356
|
+
|
|
357
|
+
/* May not work */
|
|
358
|
+
@import '@mindvalley/design-system/typography/mindvalley/fonts.css';
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
---
|
|
362
|
+
|
|
363
|
+
## Related
|
|
364
|
+
|
|
365
|
+
- [Migration Guide](migration.md) - Migrate from Sharp Grotesk to Google Sans Flex
|
|
366
|
+
- [Typography Overview](README.md) - Class reference and overview
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mindvalley/design-system",
|
|
3
|
-
"version": "4.
|
|
3
|
+
"version": "4.1.0",
|
|
4
4
|
"description": "Resources, components, design guidelines and tooling for Mindvalley's design system",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"design-system",
|
|
@@ -42,6 +42,10 @@
|
|
|
42
42
|
"types": "./dist/tailwind/*.d.ts",
|
|
43
43
|
"default": "./dist/tailwind/*.js"
|
|
44
44
|
},
|
|
45
|
+
"./tailwind/plugins/typography-gsf": {
|
|
46
|
+
"types": "./dist/tailwind/plugins/typography-gsf.d.ts",
|
|
47
|
+
"default": "./dist/tailwind/plugins/typography-gsf.js"
|
|
48
|
+
},
|
|
45
49
|
"./typography/*": {
|
|
46
50
|
"types": "./dist/typography/*.d.ts",
|
|
47
51
|
"default": "./dist/typography/*"
|
|
@@ -49,7 +53,7 @@
|
|
|
49
53
|
"./dist/*": "./dist/*"
|
|
50
54
|
},
|
|
51
55
|
"peerDependencies": {
|
|
52
|
-
"tailwindcss": "^3.4.17"
|
|
56
|
+
"tailwindcss": "^3.4.17 || ^4.0.0"
|
|
53
57
|
},
|
|
54
58
|
"scripts": {
|
|
55
59
|
"validate-tokens": "ts-node src/scripts/validate-tokens.ts",
|
|
@@ -77,7 +81,9 @@
|
|
|
77
81
|
"check": "biome check --write ./src",
|
|
78
82
|
"check:ci": "biome ci ./src",
|
|
79
83
|
"check:staged": "biome check --staged",
|
|
80
|
-
"check:changed": "biome check --changed"
|
|
84
|
+
"check:changed": "biome check --changed",
|
|
85
|
+
"lint:md": "markdownlint-cli2 \"**/*.md\"",
|
|
86
|
+
"lint:md:fix": "markdownlint-cli2 --fix \"**/*.md\""
|
|
81
87
|
},
|
|
82
88
|
"devDependencies": {
|
|
83
89
|
"@babel/core": "^7.22.9",
|
|
@@ -107,6 +113,7 @@
|
|
|
107
113
|
"husky": "^8.0.3",
|
|
108
114
|
"jest": "^30.1.3",
|
|
109
115
|
"lodash.kebabcase": "^4.1.1",
|
|
116
|
+
"markdownlint-cli2": "^0.20.0",
|
|
110
117
|
"npm-run-all": "^4.1.5",
|
|
111
118
|
"plugin": "^0.0.15",
|
|
112
119
|
"resolve-tspaths": "^0.8.23",
|
package/docs/CONTRIBUTION.md
DELETED
|
@@ -1,262 +0,0 @@
|
|
|
1
|
-
## 🤝 Contributing [](http://makeapullrequest.com)
|
|
2
|
-
|
|
3
|
-
Before you get your hands dirty, let's first understand how the repo works and its structure. We are going to look at:
|
|
4
|
-
|
|
5
|
-
* What happens in the repo and its inputs and outputs: Jump to [Token transformation](#-token-transformation-process)
|
|
6
|
-
* How the repo is structured and its core parts: See [Directory structure](#-directory-structure)
|
|
7
|
-
|
|
8
|
-
#### 🏭 Token transformation process
|
|
9
|
-
|
|
10
|
-
Token transformation on a high level involves the following steps:
|
|
11
|
-
|
|
12
|
-
```mermaid
|
|
13
|
-
sequenceDiagram
|
|
14
|
-
participant Figma
|
|
15
|
-
participant Supernova
|
|
16
|
-
participant Tokens as src/tokens/brands
|
|
17
|
-
participant SD as style-dictionary build
|
|
18
|
-
participant JS as src/build/js & src/tailwind/plugins/tokens
|
|
19
|
-
participant Webpack
|
|
20
|
-
participant Dist as dist
|
|
21
|
-
participant NPM as Publish (NPM)
|
|
22
|
-
|
|
23
|
-
Figma->>Supernova: Designer publishes changes
|
|
24
|
-
Supernova->>Tokens: Supernova raises PR to update tokens
|
|
25
|
-
Tokens->>SD: style-dictionary parses & transforms
|
|
26
|
-
SD->>JS: Outputs JS modules (colors, typography)
|
|
27
|
-
JS->>Webpack: Bundling for distribution
|
|
28
|
-
Webpack->>Dist: Outputs bundled files
|
|
29
|
-
Dist->>NPM: CI publishes package
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
**1. The design tokens**
|
|
35
|
-
This is the starting point of the design token transformation process. When there are changes in the Figma design system (such as a color update), an automated workflow powered by Supernova detects these changes and creates a pull request in the repository to update the relevant token files in `src/tokens/brands/{brand}/` (e.g., `src/tokens/brands/mindvalley/colors.json`). This ensures that the tokens in the codebase stay in sync with the design system, reducing manual effort and the risk of inconsistencies.
|
|
36
|
-
|
|
37
|
-
**2. Parsing and transformation**
|
|
38
|
-
Using [style-dictionary](https://styledictionary.com/getting-started/), the design tokens are parsed, merged, and transformed into the desired formats. The main outputs are JavaScript modules for colors and typography, but the output is configurable and can be extended to other formats (CSS, SCSS, etc.) in the future.
|
|
39
|
-
Run:
|
|
40
|
-
|
|
41
|
-
```bash
|
|
42
|
-
npm run build:styledictionary
|
|
43
|
-
```
|
|
44
|
-
|
|
45
|
-
**3. Bundling**
|
|
46
|
-
Bundling is done using [webpack](https://webpack.js.org/concepts) to ensure the resultant files work across browser and server environments. The files from the previous step are bundled and output to the `dist/` directory, which is not checked in for versioning.
|
|
47
|
-
Run:
|
|
48
|
-
|
|
49
|
-
```bash
|
|
50
|
-
npm run build
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
**4. Publishing**
|
|
54
|
-
The last step is releasing and publishing the bundled files. This is automated and runs on CI, ensuring that changes are tested, versioned, and documented. Publishing is handled by [semantic release](https://semantic-release.gitbook.io/semantic-release/).
|
|
55
|
-
See more in the [release guide](RELEASING.md#releasing-🚀).
|
|
56
|
-
|
|
57
|
-
#### 🗂 Directory structure
|
|
58
|
-
|
|
59
|
-
Here is a simplified directory structure highlighting key areas for contributors:
|
|
60
|
-
|
|
61
|
-
```bash
|
|
62
|
-
├── LICENSE
|
|
63
|
-
├── README.md
|
|
64
|
-
├── __tests__
|
|
65
|
-
├── babel.config.js
|
|
66
|
-
├── build.ts
|
|
67
|
-
├── dist/
|
|
68
|
-
│ └── ...
|
|
69
|
-
├── docs/
|
|
70
|
-
│ ├── CONTRIBUTION.md
|
|
71
|
-
│ ├── RELEASING.md
|
|
72
|
-
│ └── USAGE.md
|
|
73
|
-
├── package-lock.json
|
|
74
|
-
├── package.json
|
|
75
|
-
├── src/
|
|
76
|
-
│ ├── assets/
|
|
77
|
-
│ │ ├── brands/
|
|
78
|
-
│ │ │ ├── mindvalley/
|
|
79
|
-
│ │ │ │ └── icons/
|
|
80
|
-
│ │ │ └── b2b/
|
|
81
|
-
│ │ │ └── icons/
|
|
82
|
-
│ │ ├── icons/
|
|
83
|
-
│ │ └── wordmarks/
|
|
84
|
-
│ ├── build/
|
|
85
|
-
│ │ └── js/
|
|
86
|
-
│ ├── helpers/
|
|
87
|
-
│ ├── tailwind/
|
|
88
|
-
│ │ └── plugins/
|
|
89
|
-
│ │ └── tokens/
|
|
90
|
-
│ ├── tokens/
|
|
91
|
-
│ │ └── brands/
|
|
92
|
-
│ │ ├── mindvalley/
|
|
93
|
-
│ │ └── b2b/
|
|
94
|
-
│ └── utilities/
|
|
95
|
-
│ └── svg-import/
|
|
96
|
-
│ ├── .figma_icons.js
|
|
97
|
-
│ └── .figma_wordmarks.js
|
|
98
|
-
├── webpack.config.js
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
#### Test Directory
|
|
102
|
-
|
|
103
|
-
* All tests are under `__tests__/` (not `test/`).
|
|
104
|
-
|
|
105
|
-
* Subfolders include `utilities/`, `src/tailwind/plugins/`, etc.
|
|
106
|
-
|
|
107
|
-
#### Configuration Files
|
|
108
|
-
|
|
109
|
-
* There is **no** root `config.json`.
|
|
110
|
-
|
|
111
|
-
* Main configuration is in `build.ts`, `webpack.config.js`, and scripts in `package.json`.
|
|
112
|
-
|
|
113
|
-
#### Important npm scripts
|
|
114
|
-
|
|
115
|
-
* `build`: Runs both the style-dictionary build and webpack bundle.
|
|
116
|
-
|
|
117
|
-
* `build:styledictionary`: Generates token outputs (see above for output locations).
|
|
118
|
-
* `build:bundle`: Runs webpack for production.
|
|
119
|
-
* `build:figma`: Runs both icon and wordmark export scripts.
|
|
120
|
-
* `build:figma:icons`: Uses `src/utilities/svg-import/.figma_icons.js`.
|
|
121
|
-
* `build:figma:wordmarks`: Uses `src/utilities/svg-import/.figma_wordmarks.js`.
|
|
122
|
-
* `test`: Runs all tests with jest.
|
|
123
|
-
* `commit`: Uses Commitizen CLI for conventional commits.
|
|
124
|
-
|
|
125
|
-
#### ⌨️ Start development
|
|
126
|
-
|
|
127
|
-
To get started with development, start by cloning the mv-design-system repo:
|
|
128
|
-
|
|
129
|
-
```bash
|
|
130
|
-
git clone git@github.com:mindvalley/mv-design-system.git
|
|
131
|
-
```
|
|
132
|
-
|
|
133
|
-
Change your current directory to the folder you just cloned and install the dependencies:
|
|
134
|
-
|
|
135
|
-
```bash
|
|
136
|
-
cd mv-design-system && npm install
|
|
137
|
-
```
|
|
138
|
-
|
|
139
|
-
###### 💡 Note
|
|
140
|
-
|
|
141
|
-
This repo uses `npm` as the package manager.
|
|
142
|
-
|
|
143
|
-
##### Making commits
|
|
144
|
-
|
|
145
|
-
After making changes, stage your changes by issuing the standard `git add <filename>`, or however you stage your files.
|
|
146
|
-
For commits, we leverage the power of conventional commits using [Commitizen](https://github.com/commitizen/cz-cli).
|
|
147
|
-
|
|
148
|
-
**Why use conventional commits?** To enable automation of releases, semantic versioning, and release notes auto-generation.
|
|
149
|
-
|
|
150
|
-
To make a commit, run the command below:
|
|
151
|
-
|
|
152
|
-
```
|
|
153
|
-
npm run commit
|
|
154
|
-
```
|
|
155
|
-
|
|
156
|
-
This will trigger a command line interface and all you have to do is answer the prompted questions which includes a Jira ticket ID number.
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
If your branch name has a Jira ticket ID already included, then the prompt automatically extracts it.
|
|
161
|
-
|
|
162
|
-
Though using `npm run commit` is highly recommended for this repo, you can alternatively write your commit without the Commitizen helper by ensuring you follow the conventional commits conventions.
|
|
163
|
-
|
|
164
|
-
```bash
|
|
165
|
-
type(scope): commit-message
|
|
166
|
-
|
|
167
|
-
Jira-Issue-ID
|
|
168
|
-
```
|
|
169
|
-
|
|
170
|
-
The commit type has to be one of:
|
|
171
|
-
|
|
172
|
-
* `feat`: A new feature
|
|
173
|
-
* `fix`: A bug fix
|
|
174
|
-
* `docs`: Documentation only changes
|
|
175
|
-
* `style`: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
|
|
176
|
-
* `refactor`: A code change that neither fixes a bug nor adds a feature
|
|
177
|
-
* `perf`: A code change that improves performance
|
|
178
|
-
* `test`: Adding missing tests or correcting existing tests
|
|
179
|
-
* `build`: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
|
|
180
|
-
* `ci`: Changes to our CI configuration files and scripts (example - scopes: Travis, Circle, BrowserStack, SauceLabs)
|
|
181
|
-
* `chore`: Other changes that don't modify src or test files
|
|
182
|
-
* `revert`: Reverts a previous commit
|
|
183
|
-
|
|
184
|
-
Here is an example commit message:
|
|
185
|
-
|
|
186
|
-
```
|
|
187
|
-
chore(asdf): Add .tool-versions file with current supported node version
|
|
188
|
-
|
|
189
|
-
MVHOME-765
|
|
190
|
-
```
|
|
191
|
-
|
|
192
|
-
Once your commits are done, you can do a normal push to remote.
|
|
193
|
-
|
|
194
|
-
Read more on [commit conventions](https://www.conventionalcommits.org/en/v1.0.0-beta.4/).
|
|
195
|
-
|
|
196
|
-
##### Branch naming
|
|
197
|
-
|
|
198
|
-
Branch names start with the Jira ticket ID eg.
|
|
199
|
-
|
|
200
|
-
`MVHOME-765-branch-description-here`
|
|
201
|
-
|
|
202
|
-
##### Important commands
|
|
203
|
-
|
|
204
|
-
###### Tests
|
|
205
|
-
|
|
206
|
-
To run all the tests:
|
|
207
|
-
|
|
208
|
-
```
|
|
209
|
-
npm run test
|
|
210
|
-
```
|
|
211
|
-
|
|
212
|
-
###### Transform design tokens
|
|
213
|
-
|
|
214
|
-
Whenever there are changes that affect our design tokens, we need to regenerate the build assets using the command below and commit the results:
|
|
215
|
-
|
|
216
|
-
```
|
|
217
|
-
npm run build:styledictionary
|
|
218
|
-
```
|
|
219
|
-
|
|
220
|
-
This is the command that transforms our design tokens to the different desired formats we have defined.
|
|
221
|
-
|
|
222
|
-
###### Bundle assets for release
|
|
223
|
-
|
|
224
|
-
In the release step of the CI pipeline, we bundle the assets into a UMD module with the help of webpack to ensure that our package runs on both the server (Node.js) and the client side (browser).
|
|
225
|
-
|
|
226
|
-
```bash
|
|
227
|
-
npm run build
|
|
228
|
-
```
|
|
229
|
-
|
|
230
|
-
You can test it out on your development environment to see the output.
|
|
231
|
-
|
|
232
|
-
Once your changes are made and merged, they'll need to be published. See how that is done in the [release guide](RELEASING.md#releasing-🚀).
|
|
233
|
-
|
|
234
|
-
## How to update icons and wordmarks
|
|
235
|
-
|
|
236
|
-
Icons and wordmarks are directly fetched from the respective Figma files where they are composed and updated by the designer.
|
|
237
|
-
|
|
238
|
-
To update them, follow the steps below:
|
|
239
|
-
|
|
240
|
-
1. Get your [Figma personal token](https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens)
|
|
241
|
-
2. Clone the `.env.example` file on your root and rename it to `.env`
|
|
242
|
-
3. Add your Figma token in the file `FIGMA_TOKEN=Y0urF1gM@T0k3n` and save the changes
|
|
243
|
-
4. Then run `npm run build:figma`
|
|
244
|
-
|
|
245
|
-
Running `npm run build:figma` triggers the workflows to fetch, generate sprites and generate documentation for sprites and wordmarks. `npm run build:figma` is an aggregate script that:
|
|
246
|
-
|
|
247
|
-
1. Pulls and processes icons, using the script `npm run build:figma:icons`
|
|
248
|
-
2. Pulls and processes wordmarks, using the script: `npm run build:figma:wordmarks`
|
|
249
|
-
3. Clears the duplicate docs in the src/assets folder: `npm run clean:docs`
|
|
250
|
-
|
|
251
|
-
Step 1 and 2 are run in parallel using the [npm-run-all](https://github.com/mysticatea/npm-run-all/blob/HEAD/docs/npm-run-all.md) package.
|
|
252
|
-
|
|
253
|
-
The outputs go to `/src/assets/icons` for icons and `/src/assets/wordmarks` for wordmarks with additional generated markdown preview files added in `/docs/icons` and `/docs/wordmarks` directories respectively.
|
|
254
|
-
|
|
255
|
-
Here is an image illustrating the process:
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
If there is a newly added Figma page, remember to adjust the scripts with the new pages:
|
|
260
|
-
|
|
261
|
-
* [wordmarks](../src/utilities/svg-import/.figma_wordmarks.js)
|
|
262
|
-
* [Icons](../src/utilities/svg-import/.figma_icons.js)
|