@the_awkward_customer/tokens-component-manifest

Component-level design tokens with preserved aliases for multi-dimensional theming.

Overview

This package contains component tokens extracted from Figma with preserved alias chains, enabling runtime resolution based on multiple dimensions (sentiment, emphasis, state, density, theme).

Installation

npm install @the_awkward_customer/tokens-component-manifest

Usage

import {
  componentManifest,
  modeConfiguration,
  buttonTokens,
  badgeTokens
} from '@the_awkward_customer/tokens-component-manifest';

// Access component tokens
console.log(buttonTokens);

// Access mode configuration
console.log(modeConfiguration.dimensions);

Building & Validation

Development Build

This package is automatically generated from Figma exports. Do not manually edit files in src/generated/.

# Full build with validation
npm run build

# Individual steps
npm run transform  # Transform Figma exports to manifest
npm run compile    # Compile TypeScript
npm run validate   # Run pre-publish validation

Pre-Publish Validation ⭐

CRITICAL: Always run validation before publishing to prevent runtime failures.

# Comprehensive validation (5 checks)
npm run validate

# Case sensitivity check only
npm run validate:case

The build process automatically runs validation. If validation fails, the build will fail.

Validation Checks

1. Case Sensitivity ✅ - All primitive references must be lowercase
2. Alias Resolution ⚠️ - Token aliases must resolve correctly
3. Mode Configuration ✅ - Mode dimensions and defaults must be complete
4. Primitive Files ⚠️ - Primitive CSS files should exist
5. Critical Tokens ✅ - Regression tests for known issues

Exit Codes:

• 0 - All checks passed
• 1 - Critical failures detected

Generated Files

• src/generated/manifest.json - Component token manifest (JSON)
• src/generated/manifest.ts - Component token manifest (TypeScript)
• src/generated/mode-config.json - Mode configuration (JSON)
• src/generated/mode-config.ts - Mode configuration (TypeScript)
• src/generated/types.ts - TypeScript type definitions
• src/generated/component-exports.ts - Individual component token exports

Scripts

| Script | Description | |--------|-------------| | npm run build | Full build: transform + compile + validate | | npm run transform | Transform Figma exports to manifest | | npm run compile | Compile TypeScript to JavaScript | | npm run validate | Run pre-publish validation suite | | npm run validate:case | Check case sensitivity only | | npm run clean | Remove generated files |

Publishing Workflow

Before publishing a new version:

1. Update Figma Exports (if needed)

   # Copy latest exports from figma-exports/

2. Build and Validate

   npm run build
   # This runs: transform → compile → validate

3. Verify Output

   # Check validation passes
   npm run validate
   
   # Visual inspection
   node ../test-scripts/inspect-primitive-refs.js

4. Test Components

   # Run component-specific tests
   node ../test-scripts/test-badge-resolution.js

5. Update Version

   # Edit package.json version
   # Update CHANGELOG.md

6. Commit and Publish

   git add .
   git commit -m "chore: release v1.0.0-alpha.5"
   npm publish

Troubleshooting

Validation Failures

Case Sensitivity Issues:

❌ CASE SENSITIVITY BUG DETECTED: Reference contains uppercase
Expected: primitive.radii-radius-04

Fix: Update Figma export or check transformer normalization in scripts/generators/manifest-generator.js

Unresolved Aliases:

⚠️ WARNING: 6 unresolved aliases found

Action: This is usually acceptable if <5% of aliases are unresolved. Review with verify-external-refs.js

Build Errors

Transform fails:

• Check Figma exports exist in figma-exports/
• Verify export file names match expected format

Compile fails:

• Check TypeScript errors
• Ensure all dependencies are installed

Related Documentation

• Test Scripts README - Complete testing guide
• Design Tokens README - Main design tokens documentation
• Alpha.4 Bug Fix - Case sensitivity fix documentation

License

MIT