w1-system-font-validator

v2.0.4

Published

4 months ago

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

0High
0Medium
0Low

werk1

font css validation w1-system local-fonts font-family font-weight

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)

Download or build the .vsix file
In VS Code/Cursor: Extensions → "..." → "Install from VSIX..."
Select the .vsix file
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:

Update your CLIs: Install latest @werk1/w1-system-font-manager and @werk1/w1-system-local-font-manager
Run setup: CLI will automatically create new structure
Extension works immediately: No manual migration needed - extension detects both
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:

Open Output Panel: View → Output
Select "W1 Font Validator" from dropdown
Enable debug mode in settings
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

Related Packages

@werk1/w1-system-font-manager - Package-based font management
@werk1/w1-system-local-font-manager - Local font file management
@werk1/w1-system-core - Core W1 System components