JSPM

w1-system-font-validator

2.0.4
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 6
  • Score
    100M100P100Q48067F
  • License MIT

VS Code extension for validating W1 System font variables (both fontConfig.json and localFontConfig.json)

Package Exports

  • w1-system-font-validator
  • w1-system-font-validator/dist/extension.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (w1-system-font-validator) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

W1 System Font Validator - VSCode Extension v2.0.2+

Advanced VS Code extension for validating W1 System font variables with unified font system support and organized configuration structure.

Features

  • Unified Font System Validation - Supports both package and local fonts with identical validation logic
  • Smart Weight/Style Validation - Checks actual font availability against CSS usage
  • CSS Context Analysis - Links font-family variables with font-weight declarations in the same CSS rule
  • Migration Assistant - Detects deprecated weight-specific patterns and suggests modern alternatives
  • Intelligent Hover Info - Shows available weights and styles for any font-family variable
  • Real-time Validation - Validates as you type with smart debouncing

Quick Start

Installation

From VSIX (Development)

  1. Download or build the .vsix file
  2. In VS Code/Cursor: Extensions → "..." → "Install from VSIX..."
  3. Select the .vsix file
  4. Reload window

Building from Source

git clone <repository>
cd w1-system-font-manager-vsc-extension
npm install
npm run build
npm run package

Basic Setup

The extension automatically detects font configurations in your project:

New Structure (v2.0.2+):

  • src/w1-system-config/w1-system-font-manager/fontConfig.json - Package-based fonts
  • src/w1-system-config/w1-system-local-font-manager/localFontConfig.json - Local file-based fonts

Legacy Structure (still supported):

  • fontConfig.json - Package-based fonts (project root)
  • localFontConfig.json - Local file-based fonts (project root)

The extension automatically detects both structures and prioritizes the new organized structure.

🚀 New Organized Structure Benefits

Why the new structure?

  • 🗂️ Organized: All W1 system configs in one place (src/w1-system-config/)
  • 🔧 Scalable: Easy to add more W1 system package configurations
  • 🧹 Clean: No config clutter in project root
  • 🎯 Consistent: Matches modern project organization (like src/payload/)

Migration from Legacy Structure:

  1. Update your CLIs: Install latest @werk1/w1-system-font-manager and @werk1/w1-system-local-font-manager
  2. Run setup: CLI will automatically create new structure
  3. Extension works immediately: No manual migration needed - extension detects both
  4. Clean up: Remove old config files from root when ready

First Usage

Create a CSS file with W1 font variables and observe real-time validation:

.heading {
  font-family: var(--fontfamily_primary);
  font-weight: 700; /* Valid weight - no error */
}

.text {
  font-family: var(--fontfamily_primary);
  font-weight: 600; /* Invalid weight - shows error */
}

Architecture

Core Concepts

The extension performs intelligent CSS analysis by parsing CSS rules and correlating font-family variables with font-weight and font-style declarations. It validates against actual font configurations to ensure type-safe font usage.

System Integration

The extension integrates with both W1 Font Manager and W1 Local Font Manager, supporting unified validation across package-based and local file-based font systems within the W1 ecosystem.

Data Structure

interface FontRole {
  displayName: string;
  availableWeights: Record<string, WeightInfo>;
  variables: {
    family: string;
  };
}

interface WeightInfo {
  weight: number;
  style: 'normal' | 'italic';
}

interface ValidationResult {
  diagnostics: Diagnostic[];
  hasErrors: boolean;
  processedRules: number;
}

API Reference

Main Commands

W1 Font Validator: Debug Current File

Trigger manual validation with comprehensive debug output.

Usage: Open Command Palette (Ctrl+Shift+P) and run the command

Output: Detailed validation information in VS Code Output Panel

W1 Font Validator: Reload Configuration

Force reload font configurations from project files.

Usage: Run when configuration files change

Configuration Options

{
  "w1FontValidator.validateOnType": true,
  "w1FontValidator.showHoverInfo": true,
  "w1FontValidator.supportLocalFonts": true,
  "w1FontValidator.supportPackageFonts": true,
  "w1FontValidator.debugMode": false
}

Settings:

  • validateOnType (boolean) - Enable real-time validation
  • showHoverInfo (boolean) - Show hover information for font variables
  • supportLocalFonts (boolean) - Validate local font configurations
  • supportPackageFonts (boolean) - Validate package font configurations
  • debugMode (boolean) - Enable verbose debug logging

CLI Commands

This extension does not provide CLI commands. It operates within VS Code/Cursor editor environment.

Advanced Usage

Context-Aware Validation

The extension analyzes complete CSS rules to understand font context:

.component {
  font-family: var(--fontfamily_primary);
  font-weight: 500; /* Validates against primary font's available weights */
  font-style: italic; /* Checks if italic is available for weight 500 */
}

Supported Font Systems

Package-Based Fonts (fontConfig.json)

{
  "roles": {
    "primary": {
      "displayName": "Inter",
      "availableWeights": {
        "400": {"weight": 400, "style": "normal"},
        "400_italic": {"weight": 400, "style": "italic"},
        "700": {"weight": 700, "style": "normal"}
      },
      "variables": {
        "family": "--fontfamily_primary"
      }
    }
  }
}

Local File-Based Fonts (localFontConfig.json)

{
  "detailedRoles": {
    "primary_local": {
      "displayName": "Inter",
      "availableWeights": {
        "400": {"weight": 400, "style": "normal"},
        "400_italic": {"weight": 400, "style": "italic"},
        "700": {"weight": 700, "style": "normal"}
      },
      "variables": {
        "family": "--fontfamily_primary_local"
      }
    }
  }
}

Migration Assistant

The extension detects deprecated patterns and suggests modern alternatives:

/* Deprecated - Will show warning */
.heading {
  font-family: var(--font_primary_bold);
}

/* Modern - Recommended */
.heading {
  font-family: var(--fontfamily_primary);
  font-weight: 700;
}

Development

Local Development Setup

# Clone and setup
git clone <repository>
cd w1-system-font-manager-vsc-extension
npm install
npm run build

Build System

  • TypeScript: Full extension development with VS Code APIs
  • Webpack: Bundling for extension distribution
  • VSIX Packaging: Extension packaging for distribution
  • Watch Mode: Live development with auto-rebuild

Contributing

  • Follow VS Code extension development guidelines
  • Include tests for validation logic
  • Update debug capabilities for new features
  • Follow semantic versioning

Migration & Compatibility

Version History

  • v2.0: Unified font system support with enhanced validation
  • v1.5: Added migration assistant and hover information
  • v1.0: Initial CSS validation for W1 font variables

Breaking Changes

v2.0 Migration

Enhanced validation may detect previously undetected issues:

// v1.x - May not catch invalid combinations
// v2.0+ - Validates weight + style combinations
.text {
  font-family: var(--fontfamily_primary);
  font-weight: 500;
  font-style: italic; // Now validates if 500 italic exists
}

Compatibility

  • VS Code version: >=1.74.0
  • Node.js version: >=16.0.0
  • Supports both W1 Font Manager v1.4+ and W1 Local Font Manager v2.0+
  • Works with CSS, SCSS, Less, and CSS Modules

Troubleshooting

Common Issues

Extension not providing validation

Solution: Verify font configuration files exist in project root:

# Check for configuration files
ls -la fontConfig.json localFontConfig.json

# Run debug command in VS Code
# Command Palette → "W1 Font Validator: Debug Current File"

No hover information displayed

Solution: Ensure hover info is enabled and you're hovering over valid font variables:

{
  "w1FontValidator.showHoverInfo": true
}

Validation not working in specific files

Solution: Check supported file types and patterns:

  • Files must be *.css, *.scss, *.less, or *.module.css
  • Files in /styles/ directories are automatically included
  • globals.css and global.css are supported

Debug Mode

Enable comprehensive debug output:

  1. Open Output Panel: View → Output
  2. Select "W1 Font Validator" from dropdown
  3. Enable debug mode in settings
  4. View real-time validation logs

Debug Output Example:

[W1 Font Validator] Validating: global.css
Configuration loaded: fontConfig.json
Found 3 font-family variables
Found 2 invalid weight combinations
Validation completed with 2 diagnostics

Validation Examples

Valid Usage

.heading {
  font-family: var(--fontfamily_primary);
  font-weight: 700; /* Available weight */
}

.text {
  font-family: var(--fontfamily_primary_local);
  font-weight: 400;
  font-style: italic; /* Available combination */
}

Invalid Usage (Shows Errors)

.heading {
  font-family: var(--fontfamily_primary);
  font-weight: 600; /* NOT available for this font */
}

.text {
  font-family: var(--fontfamily_nonexistent); /* Invalid variable */
}

Deprecated Patterns (Shows Warnings)

.heading {
  font-family: var(--font_primary_bold); /* Deprecated */
  /* Should be: font-family: var(--fontfamily_primary); font-weight: 700; */
}

Supported File Types

  • *.css - Standard CSS files
  • *.scss - Sass files
  • *.less - Less files
  • *.module.css - CSS Modules
  • Files in /styles/ directories
  • globals.css and global.css

License

MIT © Werk1