@mindvalley/design-system 4.0.1 → 4.1.0

package/docs/token-validation.md

@@ -0,0 +1,298 @@
+# Design token validation with Zod
+
+This document describes the **internal** token validation system implemented using Zod for runtime validation and TypeScript type inference. These utilities are used during the build process and are not exported to package consumers.
+
+## Overview
+
+The Mindvalley Design System uses Supernova to manage design tokens, which are pushed to the repository as JSON. We use Zod for validation that:
+
+- Validates token structure at build time
+- Provides TypeScript types derived from the same schemas
+- Offers clear error messages when tokens don't match expected structure
+- Handles the complex, nested structures that Supernova generates
+
+## Architecture
+
+### Core files
+
+- `src/types/token-schemas.ts` - Zod schemas defining token structure
+- `src/types/token-validation.ts` - Validation utilities and functions
+- `src/types/index.d.ts` - TypeScript type exports
+
+### Token structure
+
+Supernova generates tokens with varying levels of nesting:
+
+```json
+{
+  "color": {
+    "primary": {
+      "500": {
+        "value": "#ff0000ff",
+        "type": "color"
+      }
+    },
+    "black": {
+      "value": "#000000ff",
+      "type": "color"
+    }
+  }
+}
+```
+
+## For package consumers
+
+If you're using the `@mindvalley/design-system` npm package, the validation happens at build time and you receive:
+
+- Type-safe `ColorTokens` interface for the colors object
+- `TypographyToken` and `TypographySet` types from the Tailwind plugin
+- Pre-validated, transformed tokens ready for use
+
+The examples below are for **contributors and maintainers** working on the design system itself.
+
+## Usage guide (internal development)
+
+### 1. Basic validation
+
+```typescript
+import { validateTokenFile } from './types/token-validation';
+
+const result = validateTokenFile('src/tokens/brands/mindvalley/colors.json');
+if (result.success) {
+  console.log('Tokens are valid!', result.data);
+} else {
+  console.error('Validation failed:', result.errors);
+}
+```
+
+### 2. Type-safe token access
+
+```typescript
+import { ColorToken } from './types/token-schemas';
+import { validateColorToken } from './types/token-validation';
+
+// Runtime validation with automatic type inference
+try {
+  const token: ColorToken = validateColorToken(unknownData);
+  // TypeScript knows token.value is a hex string
+  console.log(token.value);
+} catch (error) {
+  console.error('Invalid color token:', error);
+}
+```
+
+### 3. Batch validation
+
+```typescript
+import { validateAllTokens, getValidationSummary } from './types/token-validation';
+
+// Validate all tokens in the project
+const summary = getValidationSummary('./src/tokens');
+console.log(`Valid: ${summary.valid}, Invalid: ${summary.invalid}`);
+
+if (summary.invalid > 0) {
+  summary.errors.forEach(error => {
+    console.error(`❌ ${error.file}:`, error.errors);
+  });
+}
+```
+
+### 4. CI/CD integration
+
+Add to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "validate-tokens": "ts-node src/scripts/validate-tokens.ts",
+    "prebuild": "npm run validate-tokens"
+  }
+}
+```
+
+Create `src/scripts/validate-tokens.ts`:
+
+```typescript
+import { getValidationSummary } from '../types/token-validation';
+
+const summary = getValidationSummary('./src/tokens');
+
+if (summary.invalid > 0) {
+  console.error('Token validation failed!');
+  summary.errors.forEach(error => {
+    console.error(`❌ ${error.file}:`, error.errors.join('\n  '));
+  });
+  process.exit(1);
+}
+
+console.log('✅ All tokens validated successfully!');
+```
+
+### 5. Type guards
+
+```typescript
+import { isColorToken, isTypographyToken } from './types/token-validation';
+
+function processToken(token: unknown) {
+  if (isColorToken(token)) {
+    // TypeScript knows this is a ColorToken
+    return createColorVariable(token.value);
+  } else if (isTypographyToken(token)) {
+    // TypeScript knows this is a TypographyToken
+    return createTypographyStyles(token.value);
+  }
+}
+```
+
+### 6. Error handling
+
+```typescript
+import { safeValidate, ColorFileSchema, formatZodError } from './types/token-validation';
+
+function handleSupernovaWebhook(payload: unknown) {
+  const result = safeValidate(ColorFileSchema, payload);
+
+  if (!result.success) {
+    const errors = formatZodError(result.errors);
+
+    // Log structured errors
+    console.error('Token validation failed:', {
+      errors,
+      timestamp: new Date().toISOString(),
+      source: 'supernova-webhook'
+    });
+
+    // Alert team
+    notifySlack({
+      channel: '#design-system',
+      message: `Token validation failed: ${errors.join(', ')}`
+    });
+
+    return;
+  }
+
+  // Process valid tokens
+  updateTokens(result.data);
+}
+```
+
+## Testing
+
+### Unit tests
+
+```typescript
+import { ColorTokenSchema } from './types/token-schemas';
+
+describe('Color Token Validation', () => {
+  it('should accept valid color tokens', () => {
+    const validToken = {
+      value: '#ff0000ff',
+      type: 'color'
+    };
+
+    expect(() => ColorTokenSchema.parse(validToken)).not.toThrow();
+  });
+
+  it('should reject invalid hex values', () => {
+    const invalidToken = {
+      value: 'not-a-color',
+      type: 'color'
+    };
+
+    expect(() => ColorTokenSchema.parse(invalidToken)).toThrow();
+  });
+});
+```
+
+### Integration tests
+
+```typescript
+import { validateAllTokens } from './types/token-validation';
+
+describe('Token File Validation', () => {
+  it('should validate all production tokens', () => {
+    const results = validateAllTokens('./src/tokens');
+    const failures = results.filter(r => !r.success);
+
+    expect(failures).toHaveLength(0);
+  });
+});
+```
+
+## Schema flexibility
+
+The schemas are designed to handle Supernova's complex output:
+
+- **Nested structures**: Tokens can be nested at varying levels
+- **Optional properties**: Some tokens have optional fields like `comment`
+- **Mixed structures**: Different brands may have slightly different structures
+- **Type variations**: Properties like `textCase` can be strings or objects
+
+## Extending the system
+
+### Adding new token types
+
+1. Add the schema in `token-schemas.ts`:
+
+   ```typescript
+   export const NewTokenSchema = z.object({
+     value: z.string(),
+     type: z.literal('newtype'),
+     metadata: z.object({
+       // Define metadata structure
+     }).optional()
+   });
+   ```
+
+2. Add to file schema mapping in `token-validation.ts`:
+
+```typescript
+const FILE_SCHEMA_MAP = {
+  // existing mappings...
+  'newtokens.json': NewTokenFileSchema
+};
+```
+
+### Custom validation rules
+
+```typescript
+const CustomColorSchema = ColorTokenSchema.refine(
+  (token) => token.value.length === 9, // RGBA with alpha
+  { message: 'Colors must include alpha channel' }
+);
+```
+
+## Troubleshooting
+
+### Common issues
+
+1. **"Invalid input" errors**: Check if Supernova changed the token structure
+2. **Missing properties**: Some tokens may have optional fields
+3. **Type mismatches**: Use the flexible schemas that accept `z.any()` for complex nested structures
+
+### Debugging
+
+```typescript
+import { validateTokenFile, getErrorReport } from './types/token-validation';
+
+const result = validateTokenFile('path/to/tokens.json');
+if (!result.success) {
+  // Get detailed error report
+  console.log(getErrorReport(result.errors));
+}
+```
+
+## Best practices
+
+1. **Run validation in CI/CD**: Catch issues before they reach production
+2. **Validate after Supernova updates**: Add webhook handlers that validate incoming tokens
+3. **Use type guards**: Leverage TypeScript's type narrowing with `isColorToken()` etc.
+4. **Keep schemas updated**: When Supernova changes output format, update schemas accordingly
+5. **Test with real data**: Always test schemas against actual token files
+
+## Future improvements
+
+- Add schema versioning to handle Supernova format changes
+- Create a CLI tool for token validation
+- Add visual regression tests for token changes
+- Implement token transformation pipelines with validation

package/docs/typography/README.md

@@ -0,0 +1,58 @@
+# Typography
+
+Typography utilities ship as Tailwind CSS plugins. This documentation covers setup, configuration, and usage for both the current and legacy typography systems.
+
+## Quick links
+
+| Guide | Description |
+|-------|-------------|
+| [Setup Guide](setup.md) | Font loading and Tailwind plugin configuration |
+| [Migration Guide](migration.md) | Migrating from Sharp Grotesk to Google Sans Flex |
+
+## Typography systems
+
+### Google Sans Flex (recommended)
+
+The current typography system uses Google Sans Flex, a variable font that supports:
+
+- Multiple weights (400-700) in a single file
+- Width axis (`wdth`) for condensed/normal text
+- Slant axis (`slnt`) for italic variants
+- 3-tier responsive breakpoints (mobile, tablet, desktop)
+
+### Sharp Grotesk (legacy)
+
+The legacy typography system uses Sharp Grotesk static fonts. It remains available for backward compatibility but is frozen and will not receive updates.
+
+## Class reference
+
+### Body text
+
+| Class | Description |
+|-------|-------------|
+| `body` | Default body text |
+| `body-bold` | Bold body text |
+| `body-italic` | Italic body text (GSF only) |
+| `body-large`, `body-small`, `body-xs` | Size variants |
+
+### Titles (responsive)
+
+| Class | Description |
+|-------|-------------|
+| `title-1` through `title-6` | Responsive titles (scale across breakpoints) |
+| `title-7` through `title-11` | Non-responsive titles |
+| `title-bold-1` through `title-bold-5` | Bold responsive titles |
+
+### Component text
+
+| Class | Description |
+|-------|-------------|
+| `button-text`, `button-text-medium`, `button-text-small` | Button labels |
+| `caption-disclaimer` | Captions and disclaimers |
+| `overline-text` | Overline text |
+| `timer-text`, `timer-text-medium`, `timer-text-small` | Timer displays |
+
+## Related
+
+- [Usage Guide](../usage.md#-typography) - Typography section in main usage guide
+- [Colors](../usage.md#-colors) - Color system documentation

package/docs/typography/migration.md

@@ -0,0 +1,166 @@
+# Migrating to Google Sans Flex
+
+This guide helps you migrate from Sharp Grotesk typography to Google Sans Flex (GSF).
+
+## Overview
+
+Google Sans Flex is the new typography system. Sharp Grotesk remains available for backward compatibility but is frozen and will not receive updates.
+
+## Migration steps
+
+### 1. Update font loading
+
+**Before (Sharp Grotesk):**
+
+```typescript
+import '@mindvalley/design-system/typography/mindvalley/fonts.css'
+```
+
+**After (Google Sans Flex):**
+
+Option A - Add to your HTML `<head>`:
+
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Google+Sans+Flex:wdth,wght@75..125,100..900&display=swap" rel="stylesheet">
+```
+
+Option B - CSS @import (Tailwind v4):
+
+```css
+/* Font import must come FIRST */
+@import "https://fonts.googleapis.com/css2?family=Google+Sans+Flex:wdth,wght@75..125,100..900&display=swap";
+
+@import "tailwindcss";
+
+@config "./tailwind.config.js";
+```
+
+> See [Setup Guide](setup.md) for detailed framework examples.
+
+### 2. Update Tailwind plugin
+
+**Before:**
+
+```typescript
+import typography from '@mindvalley/design-system/tailwind/plugins/typography'
+```
+
+**After:**
+
+```typescript
+import typography from '@mindvalley/design-system/tailwind/plugins/typography-gsf'
+```
+
+### 3. Test your app
+
+Class names remain the same - your existing markup should work without modification:
+
+```html
+<!-- These classes work with both plugins -->
+<h1 class="title-bold-1">Heading</h1>
+<p class="body">Body text</p>
+<button class="button-text">Click me</button>
+```
+
+---
+
+## What changed
+
+### Font family
+
+| System | Font Family |
+|--------|-------------|
+| Sharp Grotesk | `'Sharp Grotesk Cyr Book 19', Helvetica, Arial, sans-serif` |
+| Google Sans Flex | `'Google Sans Flex', Helvetica, Arial, sans-serif` |
+
+### Responsive breakpoints
+
+| System | Breakpoints |
+|--------|-------------|
+| Sharp Grotesk | 2-tier: mobile, desktop |
+| Google Sans Flex | 3-tier: mobile, tablet (768px), desktop (1024px) |
+
+### Font weights
+
+GSF uses CSS `font-weight` values instead of multiple font family files:
+
+| Weight | Sharp Grotesk | Google Sans Flex |
+|--------|---------------|------------------|
+| Regular | `Sharp Grotesk Cyr Book 19` | `font-weight: 400` |
+| Medium | `Sharp Grotesk Cyr Medium 20` | `font-weight: 500` |
+| Semibold | `Sharp Grotesk Cyr Semibold 20` | `font-weight: 600` |
+| Bold | - | `font-weight: 700` |
+
+### Variable font axes
+
+GSF is a variable font with two axes:
+
+| Axis | CSS Property | Description |
+|------|--------------|-------------|
+| `wdth` | `font-variation-settings` | Width (92 for body, 100 for titles) |
+| `slnt` | `font-variation-settings` | Slant (-10 for italics) |
+
+### New italic variants (GSF only)
+
+GSF introduces italic variants:
+
+- `body-italic`, `body-bold-italic`
+- `body-large-italic`, `body-large-bold-italic`
+- `body-small-italic`, `body-small-bold-italic`
+- `body-xs-italic`
+
+---
+
+## Running both systems
+
+> **Note:** The recommended approach is to migrate fully from Sharp Grotesk to Google Sans Flex. Running both systems simultaneously is not recommended for production use, but is shown here as a technique for gradual migration or A/B testing.
+
+If needed, you can run both typography systems side-by-side using prefixes:
+
+```javascript
+// tailwind.config.js
+const sharpGrotesk = require('@mindvalley/design-system/tailwind/plugins/typography').default
+const googleSansFlex = require('@mindvalley/design-system/tailwind/plugins/typography-gsf').default
+
+module.exports = {
+  plugins: [
+    sharpGrotesk(), 
+    googleSansFlex({ prefix: 'gsf-' }), // or whatever prefix you need.
+  ],
+}
+```
+
+> **Warning:** Both plugins generate identical class names (`.body`, `.title-1`, etc.). Using prefixes is **required** when running both systems together to avoid conflicts. Without prefixes, the second plugin will override the first.
+
+```html
+<!-- Sharp Grotesk -->
+<h1 class="title-bold-1">Heading</h1>
+
+<!-- Google Sans Flex -->
+<h1 class="gsf-title-bold-1">Heading</h1>
+```
+
+---
+
+## Troubleshooting
+
+### Font not loading
+
+Ensure you've added the Google Fonts link to your HTML `<head>`.
+
+### Missing tablet breakpoint styles
+
+The GSF plugin supports 3-tier responsive. Ensure you're using the latest version of the design system.
+
+### Class names not generated
+
+Check that your Tailwind content paths include files using typography classes so the JIT compiler includes them.
+
+---
+
+## Related
+
+- [Setup Guide](setup.md) - Complete setup instructions
+- [Typography Overview](README.md) - Class reference