@ethlete/core 5.0.0-next.2 → 5.0.0-next.21

package/generators/generators.json

@@ -5,10 +5,15 @@
       "schema": "./migrate-to-v5/schema.json",
       "description": "Migrate to v5"
     },
-    "tailwind-4-theme": {
-      "factory": "./tailwind-4-theme/generator",
-      "schema": "./tailwind-4-theme/schema.json",
-      "description": "Generate theming for Tailwind CSS v4"
+    "tailwind-4-color-theme": {
+      "factory": "./tailwind-4-color-theme/generator",
+      "schema": "./tailwind-4-color-theme/schema.json",
+      "description": "Generate color theming for Tailwind CSS v4"
+    },
+    "tailwind-4-surface-theme": {
+      "factory": "./tailwind-4-surface-theme/generator",
+      "schema": "./tailwind-4-surface-theme/schema.json",
+      "description": "Generate surface theming for Tailwind CSS v4"
     }
   }
 }

package/generators/migrate-to-v5/color-naming.js

@@ -0,0 +1,175 @@
+import { logger } from '@nx/devkit';
+/**
+ * Symbol renames in TypeScript files (imports + usage).
+ */
+const TS_SYMBOL_RENAMES = {
+    ProvideThemeDirective: 'ProvideColorDirective',
+    THEME_PROVIDER: 'COLOR_PROVIDER',
+    ColorThemedDirective: 'ColoredDirective',
+    ColorThemedStylesComponent: 'ColoredStylesComponent',
+    SurfaceThemedDirective: 'SurfacedDirective',
+    SurfaceThemedStylesComponent: 'SurfacedStylesComponent',
+    injectThemesPrefix: 'injectColorThemesPrefix',
+    createCssThemeName: 'createCssColorThemeName',
+};
+/**
+ * String replacements applied to HTML templates and inline templates.
+ */
+const TEMPLATE_REPLACEMENTS = [
+    ['[etProvideTheme]', '[etProvideColor]'],
+    ['etProvideTheme', 'etProvideColor'],
+    ['[etProvideAltTheme]', '[etProvideAltColor]'],
+    ['etProvideAltTheme', 'etProvideAltColor'],
+    ['[etColorThemed]', '[etColored]'],
+    ['etColorThemed', 'etColored'],
+    ['[etSurfaceThemed]', '[etSurfaced]'],
+    ['etSurfaceThemed', 'etSurfaced'],
+    ['[theme]=', '[color]='],
+    ['[altTheme]=', '[altColor]='],
+    ['et-theme-alt--', 'et-color-alt--'],
+    ['et-theme--', 'et-color--'],
+];
+/**
+ * CSS class name replacements.
+ */
+const CSS_REPLACEMENTS = [
+    ['.et-color-themed', '.et-colored'],
+    ['.et-surface-themed', '.et-surfaced'],
+    ['.et-theme--', '.et-color--'],
+    ['.et-theme-alt--', '.et-color-alt--'],
+];
+/**
+ * Host directive input alias replacements in TypeScript files.
+ */
+const HOST_DIRECTIVE_REPLACEMENTS = [
+    ["'etProvideTheme:theme'", "'etProvideColor:color'"],
+    ["'etProvideAltTheme:altTheme'", "'etProvideAltColor:altColor'"],
+    ["'etProvideTheme:color'", "'etProvideColor:color'"],
+    ["'etProvideAltTheme:altColor'", "'etProvideAltColor:altColor'"],
+    ['"etProvideTheme:theme"', '"etProvideColor:color"'],
+    ['"etProvideAltTheme:altTheme"', '"etProvideAltColor:altColor"'],
+    ['"etProvideTheme"', '"etProvideColor"'],
+    ['"etProvideAltTheme"', '"etProvideAltColor"'],
+];
+export default async function migrateColorNaming(tree) {
+    logger.log('\n🔄 Migrating theme → color naming...\n');
+    const tsFiles = [];
+    const htmlFiles = [];
+    const cssFiles = [];
+    findFiles('.', tree, tsFiles, htmlFiles, cssFiles);
+    let filesModified = 0;
+    for (const filePath of tsFiles) {
+        const wasModified = migrateTypeScriptFile(tree, filePath);
+        if (wasModified) {
+            filesModified++;
+            logger.log(`  ✓ ${filePath}`);
+        }
+    }
+    for (const filePath of htmlFiles) {
+        const wasModified = migrateTemplateFile(tree, filePath);
+        if (wasModified) {
+            filesModified++;
+            logger.log(`  ✓ ${filePath}`);
+        }
+    }
+    for (const filePath of cssFiles) {
+        const wasModified = migrateCssFile(tree, filePath);
+        if (wasModified) {
+            filesModified++;
+            logger.log(`  ✓ ${filePath}`);
+        }
+    }
+    if (filesModified > 0) {
+        logger.log(`\n✅ Successfully migrated color naming in ${filesModified} file(s)\n`);
+    }
+    else {
+        logger.log('\nℹ️  No files needed migration\n');
+    }
+}
+function findFiles(dir, tree, tsFiles, htmlFiles, cssFiles) {
+    const children = tree.children(dir);
+    for (const child of children) {
+        const path = dir === '.' ? child : `${dir}/${child}`;
+        if (tree.isFile(path)) {
+            if (path.includes('node_modules'))
+                continue;
+            if (path.endsWith('.ts') && !path.endsWith('.spec.ts')) {
+                tsFiles.push(path);
+            }
+            else if (path.endsWith('.html')) {
+                htmlFiles.push(path);
+            }
+            else if (path.endsWith('.css') || path.endsWith('.scss')) {
+                cssFiles.push(path);
+            }
+        }
+        else {
+            if (child === 'node_modules')
+                continue;
+            findFiles(path, tree, tsFiles, htmlFiles, cssFiles);
+        }
+    }
+}
+function migrateTypeScriptFile(tree, filePath) {
+    let content = tree.read(filePath, 'utf-8');
+    if (!content)
+        return false;
+    const original = content;
+    // Rename symbols
+    for (const [oldName, newName] of Object.entries(TS_SYMBOL_RENAMES)) {
+        content = replaceWholeWord(content, oldName, newName);
+    }
+    // Rename host directive input aliases
+    for (const [oldStr, newStr] of HOST_DIRECTIVE_REPLACEMENTS) {
+        content = content.replaceAll(oldStr, newStr);
+    }
+    // Handle inline templates in TypeScript files
+    for (const [oldStr, newStr] of TEMPLATE_REPLACEMENTS) {
+        content = content.replaceAll(oldStr, newStr);
+    }
+    // Handle CSS in TypeScript files
+    for (const [oldStr, newStr] of CSS_REPLACEMENTS) {
+        content = content.replaceAll(oldStr, newStr);
+    }
+    if (content !== original) {
+        tree.write(filePath, content);
+        return true;
+    }
+    return false;
+}
+function migrateTemplateFile(tree, filePath) {
+    let content = tree.read(filePath, 'utf-8');
+    if (!content)
+        return false;
+    const original = content;
+    for (const [oldStr, newStr] of TEMPLATE_REPLACEMENTS) {
+        content = content.replaceAll(oldStr, newStr);
+    }
+    if (content !== original) {
+        tree.write(filePath, content);
+        return true;
+    }
+    return false;
+}
+function migrateCssFile(tree, filePath) {
+    let content = tree.read(filePath, 'utf-8');
+    if (!content)
+        return false;
+    const original = content;
+    for (const [oldStr, newStr] of CSS_REPLACEMENTS) {
+        content = content.replaceAll(oldStr, newStr);
+    }
+    if (content !== original) {
+        tree.write(filePath, content);
+        return true;
+    }
+    return false;
+}
+function replaceWholeWord(content, oldWord, newWord) {
+    const regex = new RegExp(`\\b${escapeRegex(oldWord)}\\b`, 'g');
+    return content.replace(regex, newWord);
+}
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+//# sourceMappingURL=color-naming.js.map

package/generators/migrate-to-v5/migration.js

@@ -1,4 +1,5 @@
 import { formatFiles } from '@nx/devkit';
+import migrateColorNaming from './color-naming.js';
 import migrateCreateProvider from './create-provider.js';
 import migrateRouterStateService from './router-state-service.js';
 import migrateViewportService from './viewport-service.js';
@@ -18,6 +19,11 @@ export default async function migrate(tree, schema) {
     if (shouldMigrateRouterStateService) {
         await migrateRouterStateService(tree);
     }
+    const shouldMigrateColorNaming = schema.migrateColorNaming !== false;
+    if (shouldMigrateColorNaming) {
+        console.log('  • Migrating theme → color naming...');
+        await migrateColorNaming(tree);
+    }
     if (!schema.skipFormat) {
         console.log('  • Formatting files...');
         await formatFiles(tree);

package/generators/migrate-to-v5/schema.json

@@ -23,6 +23,11 @@
       "type": "boolean",
       "description": "Migrate router state service to v5",
       "default": true
+    },
+    "migrateColorNaming": {
+      "type": "boolean",
+      "description": "Migrate theme naming to color naming (ProvideThemeDirective -> ProvideColorDirective, etc.)",
+      "default": true
     }
   },
   "required": []

package/generators/{tailwind-4-theme → tailwind-4-color-theme}/generator.js

@@ -5,11 +5,15 @@ export default async function generate(tree, schema) {
     const themesPath = schema.themesPath || 'src/themes.ts';
     const outputPath = schema.outputPath || 'src/styles/generated-tailwind-themes.css';
     const prefix = schema.prefix || 'et';
+    // The runtime prefix drives the theme-swap CSS variables (--<runtimePrefix>-color-primary)
+    // and selectors (.<runtimePrefix>-color--<name>). It defaults to `prefix` so existing
+    // consumers who only ever passed one prefix see no change in output.
+    const runtimePrefix = schema.runtimePrefix || prefix;
     // Step 1: Check if themes file exists
     if (!tree.exists(themesPath)) {
         logger.error(`❌ Themes file not found at: ${themesPath}`);
         logger.log(`\nPlease specify the correct path using --themesPath option.`);
-        logger.log(`Example: nx g @ethlete/core:tailwind-4-theme --themesPath=src/app/themes.ts\n`);
+        logger.log(`Example: nx g @ethlete/core:tailwind-4-color-theme --themesPath=src/app/themes.ts\n`);
         return;
     }
     logger.log(`📁 Reading themes from: ${themesPath}`);
@@ -43,7 +47,7 @@ export default async function generate(tree, schema) {
     }
     // Step 5: Generate Tailwind CSS
     logger.log('\n🎨 Generating Tailwind theme CSS...');
-    const css = generateTailwindThemeCss(themes, prefix, schema);
+    const css = generateTailwindThemeCss(themes, prefix, runtimePrefix, schema);
     // Step 6: Write the generated CSS file
     const outputDir = outputPath.substring(0, outputPath.lastIndexOf('/'));
     if (outputDir && !tree.exists(outputDir)) {
@@ -51,7 +55,14 @@ export default async function generate(tree, schema) {
     }
     tree.write(outputPath, css);
     logger.log(`✅ Generated Tailwind themes at: ${outputPath}`);
-    // Step 7: Try to find and update main styles file
+    // Step 7: Generate the `EthleteColorThemeNameRegistry` augmentation, so `etProvideColor`
+    // (and anything else that accepts a `RegisteredColorThemeName`) is checked/autocompleted
+    // against this app's actual theme names, instead of a plain `string`.
+    const typesOutputPath = schema.typesOutputPath || outputPath.replace(/\.css$/, '.d.ts');
+    const typesDts = generateColorThemeNameTypes(themes, schema);
+    tree.write(typesOutputPath, typesDts);
+    logger.log(`✅ Generated color theme name types at: ${typesOutputPath}`);
+    // Step 8: Try to find and update main styles file
     const mainStylesFiles = findMainStylesFile(tree);
     if (mainStylesFiles.length > 0) {
         logger.log('\n📝 Found potential main styles files:');
@@ -95,12 +106,9 @@ function extractThemesFromContent(content, filePath) {
     if (!initializer) {
         throw new Error('THEMES export has no initializer');
     }
-    // Handle 'satisfies' expression: [array] satisfies Type[]
-    if (initializer.isKind(SyntaxKind.SatisfiesExpression)) {
-        initializer = initializer.getExpression();
-    }
-    // Handle 'as const': [array] as const
-    if (initializer.isKind(SyntaxKind.AsExpression)) {
+    // Handle 'satisfies X'/'as const' wrappers, in either order: [array] satisfies Type[],
+    // [array] as const, or both combined.
+    while (initializer.isKind(SyntaxKind.SatisfiesExpression) || initializer.isKind(SyntaxKind.AsExpression)) {
         initializer = initializer.getExpression();
     }
     if (!initializer.isKind(SyntaxKind.ArrayLiteralExpression)) {
@@ -122,8 +130,9 @@ function extractThemesFromContent(content, filePath) {
                 logger.warn(`⚠️  Theme ${name} has no initializer`);
                 continue;
             }
-            // Handle 'as const' on individual theme objects
-            if (themeObj.isKind(SyntaxKind.AsExpression)) {
+            // Handle 'as const' and 'satisfies X' wrappers on individual theme objects, in
+            // either order (e.g. `{...} satisfies Theme`, `{...} as const`, or both combined).
+            while (themeObj.isKind(SyntaxKind.AsExpression) || themeObj.isKind(SyntaxKind.SatisfiesExpression)) {
                 themeObj = themeObj.getExpression();
             }
             if (!themeObj.isKind(SyntaxKind.ObjectLiteralExpression)) {
@@ -167,9 +176,9 @@ function parseThemeObject(obj, sourceFile) {
                     theme.isDefault = true;
                 }
                 break;
-            case 'isDefaultAlt':
-                if (initializer.isKind(SyntaxKind.TrueKeyword)) {
-                    theme.isDefaultAlt = true;
+            case 'type':
+                if (initializer.isKind(SyntaxKind.StringLiteral)) {
+                    theme.type = initializer.getLiteralValue();
                 }
                 break;
             case 'primary':
@@ -188,8 +197,6 @@ function parseThemeObject(obj, sourceFile) {
 }
 function validateThemeConfiguration(themes) {
     const defaultThemes = themes.filter((t) => t.isDefault);
-    const defaultAltThemes = themes.filter((t) => t.isDefaultAlt);
-    const bothDefaultAndAlt = themes.filter((t) => t.isDefault && t.isDefaultAlt);
     // Error: No default theme
     if (defaultThemes.length === 0) {
         throw new Error('No default theme found. At least one theme must have isDefault: true');
@@ -198,13 +205,18 @@ function validateThemeConfiguration(themes) {
     if (defaultThemes.length > 1) {
         throw new Error(`Multiple default themes found: ${defaultThemes.map((t) => t.name).join(', ')}. Only one theme can have isDefault: true`);
     }
-    // Error: Theme has both isDefault and isDefaultAlt
-    if (bothDefaultAndAlt.length > 0) {
-        throw new Error(`Theme "${bothDefaultAndAlt[0].name}" has both isDefault and isDefaultAlt set to true. A theme can only be one or the other`);
-    }
-    // Error: Multiple default alt themes
-    if (defaultAltThemes.length > 1) {
-        throw new Error(`Multiple default alt themes found: ${defaultAltThemes.map((t) => t.name).join(', ')}. Only one theme can have isDefaultAlt: true`);
+    // Error: Duplicate theme types
+    const typedThemes = themes.filter((t) => t.type);
+    const typeMap = new Map();
+    for (const theme of typedThemes) {
+        const existing = typeMap.get(theme.type) || [];
+        existing.push(theme.name);
+        typeMap.set(theme.type, existing);
+    }
+    for (const [type, names] of typeMap) {
+        if (names.length > 1) {
+            throw new Error(`Multiple themes with type "${type}" found: ${names.join(', ')}. Only one theme can have a given type`);
+        }
     }
 }
 function parseThemeSwatch(obj, sourceFile) {
@@ -219,7 +231,7 @@ function parseThemeSwatch(obj, sourceFile) {
         if (!initializer) {
             continue;
         }
-        if (propName === 'color' || propName === 'onColor') {
+        if (propName === 'color' || propName === 'onColor' || propName === 'inkColor') {
             const colorMap = parseColorMap(initializer, sourceFile);
             if (colorMap) {
                 swatch[propName] = colorMap;
@@ -295,132 +307,163 @@ function createCssThemeName(name) {
         .replace(/\s+/g, '-')
         .replace(/[^a-z0-9-]/g, '');
 }
-function generateTailwindThemeCss(themes, prefix, schema) {
+function generateColorThemeNameTypes(themes, schema) {
+    const themesPath = schema.themesPath || 'src/themes.ts';
+    const outputPath = schema.outputPath || 'src/styles/generated-tailwind-themes.css';
+    const typesOutputPath = schema.typesOutputPath || outputPath.replace(/\.css$/, '.d.ts');
+    const names = themes.map((theme) => `'${theme.name}'`).join(' | ');
+    return `/*
+ * Auto-generated by @ethlete/core:tailwind-4-color-theme
+ * DO NOT EDIT THIS FILE MANUALLY
+ *
+ * Regenerate by running:
+ * nx g @ethlete/core:tailwind-4-color-theme --themesPath=${themesPath}${schema.outputPath ? ` --outputPath=${outputPath}` : ''}${schema.typesOutputPath ? ` --typesOutputPath=${typesOutputPath}` : ''}${schema.prefix && schema.prefix !== 'et' ? ` --prefix=${schema.prefix}` : ''}${schema.runtimePrefix && schema.runtimePrefix !== schema.prefix ? ` --runtimePrefix=${schema.runtimePrefix}` : ''}
+ */
+
+declare module '@ethlete/core' {
+  interface EthleteColorThemeNameRegistry {
+    name: ${names};
+  }
+}
+
+export {};
+`;
+}
+function generateTailwindThemeCss(themes, utilityPrefix, runtimePrefix, schema) {
     const tailwindVars = [];
     const themeVars = [];
     const themesPath = schema.themesPath || 'src/themes.ts';
     const outputPath = schema.outputPath || 'src/styles/generated-tailwind-themes.css';
-    const header = `/* 
+    const header = `/*
  * Auto-generated Tailwind 4 theme colors from @ethlete/core
  * DO NOT EDIT THIS FILE MANUALLY
- * 
+ *
  * Generated from your theme definitions
  * This file can be regenerated by running:
- * nx g @ethlete/core:tailwind-4-theme --themesPath=${themesPath}${schema.outputPath ? ` --outputPath=${outputPath}` : ''}${schema.prefix && schema.prefix !== 'et' ? ` --prefix=${schema.prefix}` : ''}
+ * nx g @ethlete/core:tailwind-4-color-theme --themesPath=${themesPath}${schema.outputPath ? ` --outputPath=${outputPath}` : ''}${schema.prefix && schema.prefix !== 'et' ? ` --prefix=${schema.prefix}` : ''}${schema.runtimePrefix && schema.runtimePrefix !== utilityPrefix ? ` --runtimePrefix=${schema.runtimePrefix}` : ''}
  */
 
 `;
     // Validation is now done separately before this function is called
     const defaultThemes = themes.filter((t) => t.isDefault);
-    const defaultAltThemes = themes.filter((t) => t.isDefaultAlt);
-    const regularThemes = themes.filter((t) => !t.isDefault && !t.isDefaultAlt);
+    const regularThemes = themes.filter((t) => !t.isDefault);
     // Generate static Tailwind @theme block for each theme
     for (const theme of themes) {
         const name = createCssThemeName(theme.name);
         // Add comment for theme section
         tailwindVars.push(`  /* ${theme.name} theme */`);
         // Primary colors for Tailwind utilities
-        addTailwindColorVariants(tailwindVars, `${prefix}-${name}`, theme.primary.color);
+        addTailwindColorVariants(tailwindVars, `${utilityPrefix}-${name}`, theme.primary.color);
         tailwindVars.push('');
         // On colors for Tailwind utilities
-        addTailwindColorVariants(tailwindVars, `${prefix}-on-${name}`, theme.primary.onColor);
+        addTailwindColorVariants(tailwindVars, `${utilityPrefix}-on-${name}`, theme.primary.onColor);
+        tailwindVars.push('');
+        // Ink colors for standalone foreground usage
+        addTailwindColorVariants(tailwindVars, `${utilityPrefix}-${name}-ink`, theme.primary.inkColor || theme.primary.color);
         tailwindVars.push('');
         // Secondary colors if present
         if (theme.secondary) {
-            addTailwindColorVariants(tailwindVars, `${prefix}-${name}-secondary`, theme.secondary.color);
+            addTailwindColorVariants(tailwindVars, `${utilityPrefix}-${name}-secondary`, theme.secondary.color);
             tailwindVars.push('');
-            addTailwindColorVariants(tailwindVars, `${prefix}-on-${name}-secondary`, theme.secondary.onColor);
+            addTailwindColorVariants(tailwindVars, `${utilityPrefix}-on-${name}-secondary`, theme.secondary.onColor);
             tailwindVars.push('');
         }
         // Tertiary colors if present
         if (theme.tertiary) {
-            addTailwindColorVariants(tailwindVars, `${prefix}-${name}-tertiary`, theme.tertiary.color);
+            addTailwindColorVariants(tailwindVars, `${utilityPrefix}-${name}-tertiary`, theme.tertiary.color);
             tailwindVars.push('');
-            addTailwindColorVariants(tailwindVars, `${prefix}-on-${name}-tertiary`, theme.tertiary.onColor);
+            addTailwindColorVariants(tailwindVars, `${utilityPrefix}-on-${name}-tertiary`, theme.tertiary.onColor);
             tailwindVars.push('');
         }
     }
     tailwindVars.push('');
-    // Generate dynamic theme variables - check main themes and alt themes separately
+    // Main theme dynamic colors
     const mainThemes = [...defaultThemes, ...regularThemes];
     const hasSecondary = mainThemes.some((t) => t.secondary);
     const hasTertiary = mainThemes.some((t) => t.tertiary);
-    const hasAltSecondary = defaultAltThemes.some((t) => t.secondary);
-    const hasAltTertiary = defaultAltThemes.some((t) => t.tertiary);
-    // Main theme dynamic colors
     tailwindVars.push('  /* Dynamic theme colors (references runtime CSS variables) */');
-    addDynamicThemeColors(tailwindVars, prefix, 'theme', 'primary', true);
+    addDynamicThemeColors(tailwindVars, utilityPrefix, runtimePrefix, 'theme', 'primary', true);
+    addDynamicInkColors(tailwindVars, utilityPrefix, runtimePrefix, 'theme-ink', 'primary-ink');
     if (hasSecondary) {
-        addDynamicThemeColors(tailwindVars, prefix, 'theme-secondary', 'secondary', false);
+        addDynamicThemeColors(tailwindVars, utilityPrefix, runtimePrefix, 'theme-secondary', 'secondary', false);
     }
     if (hasTertiary) {
-        addDynamicThemeColors(tailwindVars, prefix, 'theme-tertiary', 'tertiary', false);
-    }
-    // Alt theme dynamic colors
-    tailwindVars.push('  /* Alt theme dynamic colors */');
-    addDynamicThemeColors(tailwindVars, prefix, 'alt-theme', 'alt-primary', true);
-    if (hasAltSecondary) {
-        addDynamicThemeColors(tailwindVars, prefix, 'alt-theme-secondary', 'alt-secondary', false);
+        addDynamicThemeColors(tailwindVars, utilityPrefix, runtimePrefix, 'theme-tertiary', 'tertiary', false);
     }
-    if (hasAltTertiary) {
-        addDynamicThemeColors(tailwindVars, prefix, 'alt-theme-tertiary', 'alt-tertiary', false);
-    }
-    // Generate runtime CSS for ALL themes (both main and alt variants)
+    // Generate runtime CSS for all themes
     themes.forEach((theme) => {
         const name = createCssThemeName(theme.name);
-        // Determine if this is the default or default-alt theme
+        // Determine if this is the default theme
         const isDefault = theme.isDefault;
-        const isDefaultAlt = theme.isDefaultAlt;
-        // Generate main theme variant (.et-theme--{name})
+        // Generate color variant (.<runtimePrefix>-color--{name})
         if (isDefault) {
-            // Default theme gets :root and .et-theme--default selectors
-            const selectors = [':root', `.${prefix}-theme--default`, `.${prefix}-theme--${name}`];
-            themeVars.push(`${selectors.join(', ')} {`);
-        }
-        else if (!isDefaultAlt) {
-            // Regular themes just get their own class
-            themeVars.push(`.${prefix}-theme--${name} {`);
-        }
-        if (isDefault || !isDefaultAlt) {
-            addThemeColorVariants(themeVars, prefix, '', theme);
-            themeVars.push('}\n');
-        }
-        // Generate alt theme variant (.et-theme-alt--{name})
-        if (isDefaultAlt) {
-            // Default alt theme gets :root and .et-theme-alt--default selectors
-            const selectors = [':root', `.${prefix}-theme-alt--default`, `.${prefix}-theme-alt--${name}`];
+            // Default color gets :root and .<runtimePrefix>-color--default selectors
+            const selectors = [':root', `.${runtimePrefix}-color--default`, `.${runtimePrefix}-color--${name}`];
             themeVars.push(`${selectors.join(', ')} {`);
         }
         else {
-            // All themes (including default and regular) get an alt variant
-            themeVars.push(`.${prefix}-theme-alt--${name} {`);
+            // Regular colors just get their own class
+            themeVars.push(`.${runtimePrefix}-color--${name} {`);
         }
-        addThemeColorVariants(themeVars, prefix, 'alt-', theme);
+        addThemeColorVariants(themeVars, runtimePrefix, '', theme);
         themeVars.push('}\n');
     });
+    // Convenience var aliases — available on any element with a color class (or root for default)
+    const aliasBlock = `/* Convenience aliases (rgb + solid + opacity variants) */
+@layer base {
+  :root, :where([class*="${runtimePrefix}-color--"]) {
+    --${runtimePrefix}-theme-color-primary-rgb: var(--${runtimePrefix}-color-primary);
+    --${runtimePrefix}-theme-color-primary-opacity: 1;
+    --${runtimePrefix}-theme-color-primary-solid: rgb(var(--${runtimePrefix}-theme-color-primary-rgb));
+    --${runtimePrefix}-theme-color-primary: rgb(var(--${runtimePrefix}-theme-color-primary-rgb) / var(--${runtimePrefix}-theme-color-primary-opacity));
+
+    --${runtimePrefix}-theme-color-on-primary-rgb: var(--${runtimePrefix}-color-on-primary);
+    --${runtimePrefix}-theme-color-on-primary-opacity: 1;
+    --${runtimePrefix}-theme-color-on-primary-solid: rgb(var(--${runtimePrefix}-theme-color-on-primary-rgb) / var(--${runtimePrefix}-theme-color-on-primary-opacity));
+    --${runtimePrefix}-theme-color-on-primary: rgb(var(--${runtimePrefix}-theme-color-on-primary-rgb) / var(--${runtimePrefix}-theme-color-on-primary-opacity));
+
+    --${runtimePrefix}-theme-color-ink-rgb: var(--${runtimePrefix}-color-primary-ink, var(--${runtimePrefix}-color-primary));
+    --${runtimePrefix}-theme-color-ink-opacity: 1;
+    --${runtimePrefix}-theme-color-ink-solid: rgb(var(--${runtimePrefix}-theme-color-ink-rgb) / var(--${runtimePrefix}-theme-color-ink-opacity));
+    --${runtimePrefix}-theme-color-ink: rgb(var(--${runtimePrefix}-theme-color-ink-rgb) / var(--${runtimePrefix}-theme-color-ink-opacity));
+  }
+}
+`;
     return `${header}@theme {
 ${tailwindVars.join('\n')}
 }
 
-${themeVars.join('\n')}`;
+@layer base {
+${themeVars.join('\n')}
+}
+
+${aliasBlock}`;
 }
-function addDynamicThemeColors(vars, prefix, tailwindName, cssVarName, addSpacingBefore) {
+function addDynamicThemeColors(vars, utilityPrefix, runtimePrefix, tailwindName, cssVarName, addSpacingBefore) {
     if (addSpacingBefore && vars.length > 0 && vars[vars.length - 1] !== '') {
         vars.push('');
     }
     // Color variants
-    vars.push(`  --color-${prefix}-${tailwindName}: rgb(var(--${prefix}-color-${cssVarName}));`);
-    vars.push(`  --color-${prefix}-${tailwindName}-hover: rgb(var(--${prefix}-color-${cssVarName}-hover));`);
-    vars.push(`  --color-${prefix}-${tailwindName}-focus: rgb(var(--${prefix}-color-${cssVarName}-focus));`);
-    vars.push(`  --color-${prefix}-${tailwindName}-active: rgb(var(--${prefix}-color-${cssVarName}-active));`);
-    vars.push(`  --color-${prefix}-${tailwindName}-disabled: rgb(var(--${prefix}-color-${cssVarName}-disabled));`);
+    vars.push(`  --color-${utilityPrefix}-${tailwindName}: rgb(var(--${runtimePrefix}-color-${cssVarName}));`);
+    vars.push(`  --color-${utilityPrefix}-${tailwindName}-hover: rgb(var(--${runtimePrefix}-color-${cssVarName}-hover));`);
+    vars.push(`  --color-${utilityPrefix}-${tailwindName}-focus: rgb(var(--${runtimePrefix}-color-${cssVarName}-focus));`);
+    vars.push(`  --color-${utilityPrefix}-${tailwindName}-active: rgb(var(--${runtimePrefix}-color-${cssVarName}-active));`);
+    vars.push(`  --color-${utilityPrefix}-${tailwindName}-disabled: rgb(var(--${runtimePrefix}-color-${cssVarName}-disabled));`);
     vars.push('');
     // On-color variants
-    vars.push(`  --color-${prefix}-on-${tailwindName}: rgb(var(--${prefix}-color-on-${cssVarName}));`);
-    vars.push(`  --color-${prefix}-on-${tailwindName}-hover: rgb(var(--${prefix}-color-on-${cssVarName}-hover));`);
-    vars.push(`  --color-${prefix}-on-${tailwindName}-focus: rgb(var(--${prefix}-color-on-${cssVarName}-focus));`);
-    vars.push(`  --color-${prefix}-on-${tailwindName}-active: rgb(var(--${prefix}-color-on-${cssVarName}-active));`);
-    vars.push(`  --color-${prefix}-on-${tailwindName}-disabled: rgb(var(--${prefix}-color-on-${cssVarName}-disabled));`);
+    vars.push(`  --color-${utilityPrefix}-on-${tailwindName}: rgb(var(--${runtimePrefix}-color-on-${cssVarName}));`);
+    vars.push(`  --color-${utilityPrefix}-on-${tailwindName}-hover: rgb(var(--${runtimePrefix}-color-on-${cssVarName}-hover));`);
+    vars.push(`  --color-${utilityPrefix}-on-${tailwindName}-focus: rgb(var(--${runtimePrefix}-color-on-${cssVarName}-focus));`);
+    vars.push(`  --color-${utilityPrefix}-on-${tailwindName}-active: rgb(var(--${runtimePrefix}-color-on-${cssVarName}-active));`);
+    vars.push(`  --color-${utilityPrefix}-on-${tailwindName}-disabled: rgb(var(--${runtimePrefix}-color-on-${cssVarName}-disabled));`);
+    vars.push('');
+}
+function addDynamicInkColors(vars, utilityPrefix, runtimePrefix, tailwindName, cssVarName) {
+    vars.push(`  --color-${utilityPrefix}-${tailwindName}: rgb(var(--${runtimePrefix}-color-${cssVarName}));`);
+    vars.push(`  --color-${utilityPrefix}-${tailwindName}-hover: rgb(var(--${runtimePrefix}-color-${cssVarName}-hover));`);
+    vars.push(`  --color-${utilityPrefix}-${tailwindName}-focus: rgb(var(--${runtimePrefix}-color-${cssVarName}-focus));`);
+    vars.push(`  --color-${utilityPrefix}-${tailwindName}-active: rgb(var(--${runtimePrefix}-color-${cssVarName}-active));`);
+    vars.push(`  --color-${utilityPrefix}-${tailwindName}-disabled: rgb(var(--${runtimePrefix}-color-${cssVarName}-disabled));`);
     vars.push('');
 }
 function addTailwindColorVariants(vars, colorName, colorSet) {
@@ -465,6 +508,17 @@ function addThemeColorVariants(vars, prefix, altPrefix, theme) {
         vars.push(`  --${prefix}-color-${altPrefix}on-${level}-focus: ${onFocusColor};`);
         vars.push(`  --${prefix}-color-${altPrefix}on-${level}-active: ${onActiveColor};`);
         vars.push(`  --${prefix}-color-${altPrefix}on-${level}-disabled: ${onDisabledColor};`);
+        const inkDefaultColor = swatch.inkColor?.default || defaultColor;
+        const inkHoverColor = swatch.inkColor?.hover || inkDefaultColor;
+        const inkFocusColor = swatch.inkColor?.focus || inkHoverColor;
+        const inkActiveColor = swatch.inkColor?.active || inkDefaultColor;
+        const inkDisabledColor = swatch.inkColor?.disabled || inkDefaultColor;
+        vars.push('');
+        vars.push(`  --${prefix}-color-${altPrefix}${level}-ink: ${inkDefaultColor};`);
+        vars.push(`  --${prefix}-color-${altPrefix}${level}-ink-hover: ${inkHoverColor};`);
+        vars.push(`  --${prefix}-color-${altPrefix}${level}-ink-focus: ${inkFocusColor};`);
+        vars.push(`  --${prefix}-color-${altPrefix}${level}-ink-active: ${inkActiveColor};`);
+        vars.push(`  --${prefix}-color-${altPrefix}${level}-ink-disabled: ${inkDisabledColor};`);
         if (theme.secondary || theme.tertiary) {
             vars.push('');
         }

package/generators/tailwind-4-color-theme/schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "tailwind-4-color-theme",
+  "title": "Tailwind 4 Theming Generator",
+  "description": "Generates Tailwind 4 compatible CSS from your Ethlete theme definitions",
+  "type": "object",
+  "properties": {
+    "themesPath": {
+      "type": "string",
+      "description": "Path to your themes file (relative to workspace root)",
+      "default": "src/themes.ts",
+      "x-prompt": "Where is your themes file located?"
+    },
+    "outputPath": {
+      "type": "string",
+      "description": "Where to output the generated Tailwind themes CSS",
+      "default": "src/styles/generated-tailwind-themes.css",
+      "x-prompt": "Where should the generated CSS be saved?"
+    },
+    "typesOutputPath": {
+      "type": "string",
+      "description": "Where to output the generated `EthleteColorThemeNameRegistry` augmentation (a .d.ts that narrows `etProvideColor` and other theme-name APIs to your actual theme names). Defaults to `outputPath` with its extension swapped to `.d.ts`."
+    },
+    "prefix": {
+      "type": "string",
+      "description": "Prefix for Tailwind utility color variable names (e.g., 'et' creates --color-et-primary, usable as bg-et-primary)",
+      "default": "et"
+    },
+    "runtimePrefix": {
+      "type": "string",
+      "description": "Prefix for the runtime theme-swap mechanism: the CSS custom properties (--<runtimePrefix>-color-primary) and selectors (.<runtimePrefix>-color--<name>) that ProvideColorDirective (etProvideColor) toggles between. Defaults to the same value as 'prefix'. Set this separately when your Tailwind utility prefix needs to differ from your runtime theme-switching prefix (e.g. because '--color-primary' is already a documented public API elsewhere in your app)."
+    },
+    "skipFormat": {
+      "type": "boolean",
+      "description": "Skip formatting files after generation",
+      "default": false
+    }
+  },
+  "required": ["themesPath"]
+}