@pantheon-systems/pds-design-tokens 2.0.0-alpha.55 → 2.0.0-alpha.56

package/build/css/variables.global.css

@@ -73,7 +73,6 @@
   --pds-spacing-button-gap-inline-l: var(--pds-spacing-xs);
   --pds-spacing-input-height-s: var(--pds-spacing-2xl);
   --pds-spacing-input-height-m: var(--pds-spacing-3xl);
-  --pds-spacing-input-height-l: var(--pds-spacing-4xl);
   --pds-z-index-navigation: 100;
   --pds-z-index-dropdown: 300;
   --pds-z-index-notifications: 500;

package/build/figma/tokens.json

@@ -896,23 +896,6 @@
                   }
                 }
               }
-            },
-            "l": {
-              "value": "{spacing.4XL}",
-              "type": "dimension",
-              "$extensions": {
-                "public": true,
-                "defaultUnit": "rem",
-                "com.figma": {
-                  "scopes": [
-                    "WIDTH_HEIGHT"
-                  ],
-                  "exportAs": "variable",
-                  "codeSyntax": {
-                    "WEB": "--pds-spacing-input-height-l"
-                  }
-                }
-              }
             }
           }
         }

package/build/js/variables.global.d.ts

@@ -80,7 +80,6 @@ export const SPACING_BUTTON_GAP_INLINE_M: string;
 export const SPACING_BUTTON_GAP_INLINE_L: string;
 export const SPACING_INPUT_HEIGHT_S: string;
 export const SPACING_INPUT_HEIGHT_M: string;
-export const SPACING_INPUT_HEIGHT_L: string;
 export const TYPOGRAPHY_FONT_CSS_IMPORT: string;
 export const Z_INDEX_NAVIGATION: number;
 export const Z_INDEX_DROPDOWN: number;

package/build/js/variables.global.js

@@ -80,7 +80,6 @@ export const SPACING_BUTTON_GAP_INLINE_M = "0.625rem";
 export const SPACING_BUTTON_GAP_INLINE_L = "0.625rem";
 export const SPACING_INPUT_HEIGHT_S = "2rem";
 export const SPACING_INPUT_HEIGHT_M = "2.5rem";
-export const SPACING_INPUT_HEIGHT_L = "3rem";
 export const TYPOGRAPHY_FONT_CSS_IMPORT = "'https://fonts.googleapis.com/css2?family=IBM+Plex+Serif:ital,wght@0,100;0,200;0,300;0,400;0,500;0,600;0,700;1,100;1,200;1,300;1,400;1,500;1,600;1,700&family=Inter+Tight:ital,wght@0,100..900;1,100..900&family=Inter:ital,opsz,wght@0,14..32,100..900;1,14..32,100..900&family=Source+Code+Pro:ital,wght@0,200..900;1,200..900&display=swap'";
 export const Z_INDEX_NAVIGATION = 100;
 export const Z_INDEX_DROPDOWN = 300;

package/build/json/tokens.json

@@ -1715,29 +1715,6 @@
             "m"
           ],
           "public": true
-        },
-        "l": {
-          "value": "3",
-          "filePath": "tokens/spacing/semantic/input.json",
-          "isSource": true,
-          "original": {
-            "value": "{spacing.4XL}",
-            "public": true
-          },
-          "name": "SpacingInputHeightL",
-          "attributes": {
-            "category": "spacing",
-            "type": "input",
-            "item": "height",
-            "subitem": "l"
-          },
-          "path": [
-            "spacing",
-            "input",
-            "height",
-            "l"
-          ],
-          "public": true
         }
       }
     }

package/codemods/v1-to-v2/README.md

@@ -0,0 +1,203 @@
+# v1 to v2 Migration Codemod
+
+This directory contains the data and tooling for the automated migration from v1.x to v2.x of PDS Design Tokens.
+
+**Status:** 📝 Data collection phase (Alpha)
+
+The codemod itself will be built during the beta phase when the API is frozen.
+
+## Contents
+
+### `mappings.json`
+
+**Purpose:** Machine-readable source of truth for all breaking changes
+
+This file tracks:
+- File path renames (CSS, JS)
+- Token renames (direct 1:1 mappings)
+- Token patterns (wildcards like `--pds-color-gradient-avatar-*`)
+- Token removals (with optional replacement notes)
+- Value format changes (e.g., decimal → percentage)
+- Categories for grouping related changes
+
+**When to update:**
+- Every time you make a breaking change during alpha/beta
+- Update this file FIRST, then auto-generate the migration guide
+- This ensures consistency and makes codemod development easier
+
+### `validate.js`
+
+**Purpose:** Validates `mappings.json` for consistency
+
+Checks for:
+- Valid JSON structure
+- No duplicate "from" tokens
+- No duplicate removals
+- All category references exist
+- No conflicts (token in both renames and removals)
+
+**Usage:**
+```bash
+# Direct
+node codemods/v1-to-v2/validate.js
+
+# Or via npm script
+npm run validate:mappings
+```
+
+Run this before committing changes to ensure data integrity.
+
+### `generate-migration-guide.js`
+
+**Purpose:** Auto-generates the Breaking Changes section of `guides/MIGRATION-v2.md` from `mappings.json`
+
+Generates:
+- Summary-style Breaking Changes with counts and categories
+- Links to detailed Step-by-Step Migration sections
+- Organized by: File Structure, Token Removals, Token Renames, Category Changes, Format Changes, New Features
+
+**Usage:**
+```bash
+# Direct
+node codemods/v1-to-v2/generate-migration-guide.js
+
+# Or via npm script
+npm run generate:migration
+```
+
+Run this after updating `mappings.json` to keep the migration guide in sync.
+
+## Workflow for Adding Breaking Changes
+
+When you make a breaking change during alpha/beta:
+
+### 1. Update `mappings.json`
+
+**For a token rename:**
+```json
+{
+  "from": "--pds-old-token",
+  "to": "--pds-new-token",
+  "category": "animation"
+}
+```
+
+Add to `tokens.renames` array.
+
+**For a token removal:**
+```json
+{
+  "token": "--pds-removed-token",
+  "category": "color",
+  "replacement": null,
+  "note": "Optional note about why it was removed"
+}
+```
+
+Add to `tokens.removals` array.
+
+**For a file rename:**
+```json
+{
+  "from": "build/css/old-file.css",
+  "to": "build/css/new-file.css",
+  "description": "Brief description"
+}
+```
+
+Add to `files.renames` array.
+
+### 2. Validate the changes
+
+```bash
+npm run validate:mappings
+```
+
+### 3. Generate migration guide
+
+```bash
+npm run generate:migration
+```
+
+This auto-generates a summary-style Breaking Changes section in `guides/MIGRATION-v2.md` from `mappings.json`. The summary includes counts, categories, and links to detailed step-by-step instructions.
+
+### 4. Update CHANGELOG
+
+Add entry to `CHANGELOG.mdx` with "BREAKING:" prefix.
+
+### 5. Commit together
+
+```bash
+git add tokens/ codemods/v1-to-v2/mappings.json guides/MIGRATION-v2.md CHANGELOG.mdx
+git commit -m "BREAKING: Description
+
+- Specific change
+- Updated mappings.json and auto-generated migration guide"
+```
+
+## Future: Codemod Implementation
+
+**Timeline:** Build during beta phase (when API is frozen)
+
+**Implementation plan:**
+- Use [jscodeshift](https://github.com/facebook/jscodeshift) for JS/TS transformations
+- Use [postcss](https://postcss.org/) for CSS/SCSS transformations
+- Read from `mappings.json` for all transformation rules
+- Provide dry-run mode to preview changes
+- Generate report of:
+  - Automated changes (file renames, token renames)
+  - Manual review needed (removed tokens, value changes)
+
+**Usage (future):**
+```bash
+npx @pantheon-systems/pds-design-tokens migrate v1-to-v2
+```
+
+## Categories
+
+Current categories defined in `mappings.json`:
+
+- **animation** - Animation and transition tokens
+- **status-colors** - Status color tokens (info, success, warning, critical, discovery)
+- **text-colors** - Text and foreground color tokens
+- **typography** - Typography tokens (font families, sizes, etc.)
+- **gradients** - Gradient tokens (moved from color category)
+- **border** - Border width and offset tokens
+- **color** - General color tokens
+- **component** - Component-specific tokens
+
+Add new categories as needed to keep changes organized.
+
+## Validation Script Output
+
+Example successful validation:
+
+```
+✅ mappings.json is valid JSON
+✅ No duplicate 'from' tokens in renames (19 unique)
+✅ No duplicate removal tokens (21 unique)
+ℹ️  Valid categories: animation, status-colors, text-colors, typography, gradients, border, color, component
+✅ All token categories are valid
+✅ No conflicts between renames and removals
+
+📊 Summary:
+   File renames: 3
+   Token renames: 19
+   Token patterns: 1
+   Token removals: 21
+   Value changes: 1
+   Categories: 8
+
+✅ All validations passed!
+```
+
+## Notes
+
+- **Patterns:** Use `isPattern: true` for wildcard tokens like `--pds-color-gradient-avatar-*`
+- **Removals:** Set `replacement: null` for tokens removed without direct replacement
+- **Value changes:** Document transformation logic (e.g., "multiply by 100, add %")
+- **Keep synced:** `mappings.json` is the source of truth - migration guide reflects this data
+
+---
+
+For migration guide, see: `guides/MIGRATION-v2.md`

package/codemods/v1-to-v2/generate-migration-guide.js

@@ -0,0 +1,384 @@
+#!/usr/bin/env node
+
+/**
+ * Generates the Breaking Changes section of MIGRATION-v2.md from mappings.json
+ *
+ * Usage: npm run generate:migration
+ *
+ * This script:
+ * 1. Reads codemods/v1-to-v2/mappings.json
+ * 2. Generates markdown for the Breaking Changes section
+ * 3. Updates guides/MIGRATION-v2.md between auto-generated markers
+ */
+
+import { readFileSync, writeFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const mappingsPath = join(__dirname, 'mappings.json');
+const migrationGuidePath = join(__dirname, '../../guides/MIGRATION-v2.md');
+
+// Load mappings.json
+let mappings;
+try {
+  const content = readFileSync(mappingsPath, 'utf8');
+  mappings = JSON.parse(content);
+  console.log('✅ Loaded mappings.json');
+} catch (error) {
+  console.error('❌ Failed to load mappings.json:', error.message);
+  process.exit(1);
+}
+
+// Helper to get category name
+const categoryMap = {};
+if (mappings.categories) {
+  mappings.categories.forEach(cat => {
+    categoryMap[cat.id] = cat.name;
+  });
+}
+
+// Generate markdown sections - SUMMARY VERSION
+function generateBreakingChanges() {
+  let markdown = '';
+
+  // File Structure Changes
+  if (mappings.files.renames && mappings.files.renames.length > 0) {
+    markdown += '### File Structure Changes\n\n';
+    markdown += `${mappings.files.renames.length} CSS files have been renamed with clearer naming:\n`;
+    markdown += '- `pds-design-tokens.css` → `variables.global.css`\n';
+    markdown += '- `pds-design-tokens-light-mode.css` → `variables.light.css`\n';
+    markdown += '- `pds-design-tokens-dark-mode.css` → `variables.dark.css`\n\n';
+    markdown += 'See [Step 2: Update CSS Imports](#step-2-update-css-imports) for details.\n\n';
+  }
+
+  // Token Removals
+  if (mappings.tokens.removals && mappings.tokens.removals.length > 0) {
+    const regularRemovals = mappings.tokens.removals.filter(r => !r.isPattern);
+    const patternRemovals = mappings.tokens.removals.filter(r => r.isPattern);
+
+    markdown += '### Token Removals\n\n';
+    markdown += `${regularRemovals.length} individual tokens and ${patternRemovals.length} token patterns have been removed:\n\n`;
+
+    // Group by category
+    const removalsByCategory = {};
+    regularRemovals.forEach(removal => {
+      const cat = removal.category || 'other';
+      if (!removalsByCategory[cat]) removalsByCategory[cat] = [];
+      removalsByCategory[cat].push(removal.token);
+    });
+
+    Object.keys(removalsByCategory).sort().forEach(categoryId => {
+      const categoryName = categoryMap[categoryId] || categoryId;
+      markdown += `- **${categoryName}**: ${removalsByCategory[categoryId].length} tokens\n`;
+    });
+
+    if (patternRemovals.length > 0) {
+      markdown += '\n**Patterns removed:**\n';
+      patternRemovals.forEach(removal => {
+        markdown += `- \`${removal.token}\``;
+        if (removal.note) {
+          markdown += ` (${removal.note})`;
+        }
+        markdown += '\n';
+      });
+    }
+
+    markdown += '\nSee [Step 4: Handle Removed Tokens](#step-4-handle-removed-tokens) for the complete list.\n\n';
+  }
+
+  // Token Renames
+  if (mappings.tokens.renames && mappings.tokens.renames.length > 0) {
+    markdown += '### Token Renames\n\n';
+    markdown += `${mappings.tokens.renames.length} tokens have been renamed for better consistency and clarity:\n\n`;
+
+    // Group by category
+    const byCategory = {};
+    mappings.tokens.renames.forEach(rename => {
+      const category = rename.category || 'other';
+      if (!byCategory[category]) {
+        byCategory[category] = [];
+      }
+      byCategory[category].push(rename);
+    });
+
+    // Output counts by category
+    Object.keys(byCategory).sort().forEach(categoryId => {
+      const categoryName = categoryMap[categoryId] || categoryId;
+      markdown += `- **${categoryName}**: ${byCategory[categoryId].length} tokens\n`;
+    });
+
+    markdown += '\nSee [Step 3: Update Token References](#step-3-update-token-references-direct-replacements) for the complete list with before/after mappings.\n\n';
+  }
+
+  // Token Patterns
+  if (mappings.tokens.patterns && mappings.tokens.patterns.length > 0) {
+    markdown += '### Category Changes\n\n';
+    mappings.tokens.patterns.forEach(pattern => {
+      const categoryName = pattern.category ? (categoryMap[pattern.category] || pattern.category) : 'Tokens';
+      markdown += `- **${categoryName}**: \`${pattern.from}\` → \`${pattern.to}\``;
+      if (pattern.description) {
+        markdown += ` (${pattern.description})`;
+      }
+      markdown += '\n';
+    });
+    markdown += '\n';
+  }
+
+  // Format Changes
+  if (mappings.tokens.valueChanges && mappings.tokens.valueChanges.length > 0) {
+    markdown += '### Format Changes\n\n';
+    mappings.tokens.valueChanges.forEach(change => {
+      markdown += `- **${change.property}**: Changed from ${change.from} to ${change.to}`;
+      if (change.transformation) {
+        markdown += ` (${change.transformation})`;
+      }
+      markdown += '\n';
+    });
+    markdown += '\nSee [Step 5: Update Letter Spacing Values](#step-5-update-letter-spacing-values) for details.\n\n';
+  }
+
+  // New Features
+  if (mappings.files.additions && mappings.files.additions.length > 0) {
+    markdown += '### New Features\n\n';
+    markdown += `${mappings.files.additions.length} new JavaScript constant files for importing tokens as ES6 modules.\n\n`;
+    markdown += 'See [Step 8: Optional - Use JS Constants](#step-8-optional---use-js-constants) for usage examples.\n\n';
+  }
+
+  // Notes
+  if (mappings.notes) {
+    Object.keys(mappings.notes).forEach(key => {
+      const note = mappings.notes[key];
+      if (note && note !== 'TBD' && !note.includes('TBD')) {
+        markdown += `**${key.replace(/-/g, ' ')}:**\n`;
+        markdown += `- ${note}\n\n`;
+      }
+    });
+  }
+
+  return markdown;
+}
+
+// Generate detailed token renames section for Step 3
+function generateTokenRenames() {
+  let markdown = '';
+
+  if (!mappings.tokens.renames || mappings.tokens.renames.length === 0) {
+    return markdown;
+  }
+
+  // Group renames by category
+  const byCategory = {};
+  mappings.tokens.renames.forEach(rename => {
+    const category = rename.category || 'other';
+    if (!byCategory[category]) {
+      byCategory[category] = [];
+    }
+    byCategory[category].push(rename);
+  });
+
+  // Define category order and friendly names
+  const categoryOrder = [
+    'status-colors',
+    'text-colors',
+    'typography',
+    'animation',
+    'border',
+    'button',
+    'container',
+    'gradients',
+    'other'
+  ];
+
+  // Generate markdown for each category
+  categoryOrder.forEach(categoryId => {
+    if (!byCategory[categoryId] || byCategory[categoryId].length === 0) {
+      return;
+    }
+
+    const categoryName = categoryMap[categoryId] || categoryId;
+    const renames = byCategory[categoryId];
+
+    markdown += `**${categoryName}:**\n\n`;
+    markdown += '```css\n';
+
+    // Add comment groups for status colors
+    if (categoryId === 'status-colors') {
+      const backgrounds = renames.filter(r => r.to.includes('-background'));
+      const icons = renames.filter(r => r.to.includes('-icon'));
+      const borders = renames.filter(r => r.to.includes('-border'));
+
+      if (backgrounds.length > 0) {
+        markdown += '/* Background colors */\n';
+        backgrounds.forEach(r => {
+          markdown += `${r.from.padEnd(30)} → ${r.to}\n`;
+        });
+        markdown += '\n';
+      }
+
+      if (icons.length > 0) {
+        markdown += '/* Icon/Foreground colors */\n';
+        icons.forEach(r => {
+          markdown += `${r.from.padEnd(30)} → ${r.to}\n`;
+        });
+        markdown += '\n';
+      }
+
+      if (borders.length > 0) {
+        markdown += '/* Border colors */\n';
+        borders.forEach(r => {
+          markdown += `${r.from.padEnd(30)} → ${r.to}\n`;
+        });
+      }
+    }
+    // Add comment groups for animation tokens
+    else if (categoryId === 'animation') {
+      const transitions = renames.filter(r =>
+        r.to.includes('-transition-') &&
+        !r.to.includes('-delay') &&
+        !r.to.includes('-duration') &&
+        !r.to.includes('-timing')
+      );
+      const properties = renames.filter(r =>
+        r.to.includes('-delay') ||
+        r.to.includes('-duration') ||
+        r.to.includes('-timing')
+      );
+
+      if (transitions.length > 0) {
+        markdown += '/* Transition tokens */\n';
+        transitions.forEach(r => {
+          markdown += `${r.from.padEnd(40)} → ${r.to}\n`;
+        });
+        markdown += '\n';
+      }
+
+      if (properties.length > 0) {
+        markdown += '/* Duration/delay/timing tokens */\n';
+        properties.forEach(r => {
+          markdown += `${r.from.padEnd(50)} → ${r.to}\n`;
+        });
+      }
+    }
+    // Simple list for other categories
+    else {
+      renames.forEach(r => {
+        const padding = categoryId === 'typography' ? 34 : 30;
+        markdown += `${r.from.padEnd(padding)} → ${r.to}\n`;
+      });
+    }
+
+    markdown += '```\n\n';
+  });
+
+  // Add pattern-based renames (like gradients)
+  if (mappings.tokens.patterns && mappings.tokens.patterns.length > 0) {
+    mappings.tokens.patterns.forEach(pattern => {
+      const categoryName = pattern.category ?
+        (categoryMap[pattern.category] || pattern.category) :
+        'Pattern';
+
+      markdown += `**${categoryName}:**\n\n`;
+
+      if (pattern.description) {
+        markdown += `${pattern.description}:\n\n`;
+      }
+
+      markdown += '```css\n';
+      markdown += `${pattern.from} → ${pattern.to}\n`;
+
+      // Add example if it's a pattern
+      if (pattern.isPattern) {
+        markdown += '\n/* Example: */\n';
+        const exampleFrom = pattern.from.replace('*', 'midnight');
+        const exampleTo = pattern.to.replace('*', 'midnight');
+        markdown += `${exampleFrom} → ${exampleTo}\n`;
+      }
+
+      markdown += '```\n\n';
+    });
+  }
+
+  return markdown;
+}
+
+// Read current migration guide
+let migrationContent;
+try {
+  migrationContent = readFileSync(migrationGuidePath, 'utf8');
+  console.log('✅ Loaded MIGRATION-v2.md');
+} catch (error) {
+  console.error('❌ Failed to load MIGRATION-v2.md:', error.message);
+  process.exit(1);
+}
+
+// Generate new sections
+const newBreakingChanges = generateBreakingChanges();
+const newTokenRenames = generateTokenRenames();
+
+// Define markers for Breaking Changes section
+const breakingStartMarker = '<!-- BEGIN AUTO-GENERATED BREAKING CHANGES -->';
+const breakingEndMarker = '<!-- END AUTO-GENERATED BREAKING CHANGES -->';
+
+// Define markers for Token Renames section
+const renamesStartMarker = '<!-- BEGIN AUTO-GENERATED TOKEN RENAMES -->';
+const renamesEndMarker = '<!-- END AUTO-GENERATED TOKEN RENAMES -->';
+
+// Check if markers exist
+if (!migrationContent.includes(breakingStartMarker) || !migrationContent.includes(breakingEndMarker)) {
+  console.error('❌ Breaking Changes auto-generation markers not found in MIGRATION-v2.md');
+  console.error('Expected markers:');
+  console.error('  ' + breakingStartMarker);
+  console.error('  ' + breakingEndMarker);
+  console.error('\nPlease add these markers around the Breaking Changes section.');
+  process.exit(1);
+}
+
+if (!migrationContent.includes(renamesStartMarker) || !migrationContent.includes(renamesEndMarker)) {
+  console.error('❌ Token Renames auto-generation markers not found in MIGRATION-v2.md');
+  console.error('Expected markers:');
+  console.error('  ' + renamesStartMarker);
+  console.error('  ' + renamesEndMarker);
+  console.error('\nPlease add these markers around the Step 3 section.');
+  process.exit(1);
+}
+
+// Replace Breaking Changes section
+let updatedContent = migrationContent;
+
+const breakingStartIndex = updatedContent.indexOf(breakingStartMarker) + breakingStartMarker.length;
+const breakingEndIndex = updatedContent.indexOf(breakingEndMarker);
+
+updatedContent =
+  updatedContent.substring(0, breakingStartIndex) +
+  '\n\n' + newBreakingChanges +
+  updatedContent.substring(breakingEndIndex);
+
+// Replace Token Renames section
+const renamesStartIndex = updatedContent.indexOf(renamesStartMarker) + renamesStartMarker.length;
+const renamesEndIndex = updatedContent.indexOf(renamesEndMarker);
+
+updatedContent =
+  updatedContent.substring(0, renamesStartIndex) +
+  '\n\n' + newTokenRenames +
+  updatedContent.substring(renamesEndIndex);
+
+// Write updated content
+try {
+  writeFileSync(migrationGuidePath, updatedContent, 'utf8');
+  console.log('✅ Updated MIGRATION-v2.md');
+  console.log('\n📊 Generated:');
+  console.log(`   File renames: ${mappings.files.renames?.length || 0}`);
+  console.log(`   Token renames: ${mappings.tokens.renames?.length || 0}`);
+  console.log(`   Token patterns: ${mappings.tokens.patterns?.length || 0}`);
+  console.log(`   Token removals: ${mappings.tokens.removals?.length || 0}`);
+  console.log(`   Value changes: ${mappings.tokens.valueChanges?.length || 0}`);
+  console.log('\n✅ Auto-generated sections from mappings.json:');
+  console.log('   - Breaking Changes summary');
+  console.log('   - Step 3: Token Renames (detailed)');
+} catch (error) {
+  console.error('❌ Failed to write MIGRATION-v2.md:', error.message);
+  process.exit(1);
+}