@bernierllc/validators-css-syntax

CSS syntax validation for the BernierLLC validators ecosystem - validates CSS declarations, selectors, and at-rules.

Installation

npm install @bernierllc/validators-css-syntax

Features

• Invalid Syntax Detection: Detects malformed CSS that cannot be parsed
• Selector Validation: Checks for invalid CSS selector syntax
• Property Validation: Validates CSS property names (including vendor prefixes)
• Value Validation: Checks CSS property values for common errors
• At-Rule Validation: Validates CSS at-rules (@media, @keyframes, etc.)
• Best Practice Warnings: Detects missing semicolons and other style issues

Usage

Basic Usage

import { validateCssSyntax } from '@bernierllc/validators-css-syntax';

const css = `
  .container {
    display: flex;
    colr: red; /* Invalid property name */
  }
`;

const problems = await validateCssSyntax(css);

problems.forEach(problem => {
  console.log(`${problem.severity}: ${problem.message}`);
  console.log(`  Rule: ${problem.ruleId}`);
  if (problem.suggestion) {
    console.log(`  Suggestion: ${problem.suggestion}`);
  }
});

Using Individual Rules

import {
  invalidSyntax,
  invalidSelector,
  invalidProperty,
  invalidValue,
  invalidAtRule,
  missingSemicolon
} from '@bernierllc/validators-css-syntax';

// Use individual rules as needed
const rules = [invalidProperty, invalidValue];

// Create custom validator with specific rules
import { createPrimitiveValidator, createRuleContext } from '@bernierllc/validators-core';
import { createSharedUtils } from '@bernierllc/validators-utils';

const customValidator = createPrimitiveValidator('custom-css', 'parsing', rules);
const context = createRuleContext('custom-css', {}, createSharedUtils());

const problems = await customValidator.validate(css, context);

Using the Validator Object

import { cssSyntaxValidator } from '@bernierllc/validators-css-syntax';
import { createRuleContext } from '@bernierllc/validators-core';
import { createSharedUtils } from '@bernierllc/validators-utils';

const context = createRuleContext(
  'css-syntax',
  {},
  createSharedUtils(),
  { strictMode: true }
);

const problems = await cssSyntaxValidator.validate(css, context);

Validation Rules

css-syntax/invalid-syntax

Detects CSS that cannot be parsed by the CSS parser.

Severity: Error

Example:

/* Invalid: Missing closing brace */
.broken {
  color: red;
/* Parser will attempt to recover but may report syntax errors */

css-syntax/invalid-selector

Validates CSS selector syntax.

Severity: Error

Examples:

/* Invalid: Consecutive class indicators */
..double-class { color: red; }

/* Invalid: Consecutive ID indicators */
##double-id { color: blue; }

/* Invalid: Consecutive combinators */
div > > p { color: green; }

css-syntax/invalid-property

Checks for unknown or invalid CSS property names.

Severity: Error (Warn for vendor-prefixed properties)

Examples:

.test {
  /* Invalid: Typo in property name */
  colr: red;
  bakground: blue;

  /* Valid: Vendor prefix */
  -webkit-transform: rotate(45deg);

  /* Valid: Custom property */
  --primary-color: #007bff;
}

css-syntax/invalid-value

Validates CSS property values.

Severity: Error

Examples:

.test {
  /* Invalid: Unclosed function */
  transform: rotate(45deg;

  /* Invalid: Invalid hex color */
  color: #ZZZ;

  /* Valid */
  color: #fff;
  background: url("image.jpg");
}

css-syntax/invalid-at-rule

Validates CSS at-rules.

Severity: Error

Examples:

/* Invalid: Unknown at-rule */
@unknown { color: red; }

/* Invalid: Multiple @charset */
@charset "UTF-8";
@charset "ISO-8859-1";

/* Valid */
@media screen and (min-width: 768px) {
  .container { width: 750px; }
}

@keyframes fadeIn {
  from { opacity: 0; }
  to { opacity: 1; }
}

css-syntax/missing-semicolon

Detects missing semicolons in CSS declarations (best practice warning).

Severity: Warn

Fixable: Yes

Example:

.test {
  color: red     /* Missing semicolon */
  background: blue;
}

API Reference

validateCssSyntax(css: string, utils?: SharedUtils): Promise<Problem[]>

Validates CSS syntax using all available rules.

Parameters:

• css - The CSS string to validate
• utils (optional) - Shared utilities for validation (auto-created if not provided)

Returns: Promise<Problem[]> - Array of validation problems

cssSyntaxValidator

The complete CSS syntax validator object.

Properties:

• name: 'css-syntax'
• domain: 'parsing'
• rules: Array of all validation rules
• validate(css, context): Validation function

metadata

Package metadata including version and rule information.

Properties:

• name: '@bernierllc/validators-css-syntax'
• version: Package version
• domain: 'parsing'
• rules: Array of rule metadata

Problem Structure

Each problem returned by the validator has the following structure:

interface Problem {
  ruleId: string;              // e.g., 'css-syntax/invalid-property'
  message: string;             // Human-readable error message
  severity: Severity;          // 'off' | 'info' | 'warn' | 'error'
  domain: ValidationDomain;    // 'parsing'
  location?: {
    line?: number;
    column?: number;
  };
  suggestion?: string;         // How to fix the problem
  fixable?: boolean;          // Whether the problem can be auto-fixed
  evidence?: {
    snippet?: string;          // Code snippet showing the problem
  };
}

Supported CSS Features

This validator supports:

• CSS3 standard properties
• Vendor-prefixed properties (-webkit-, -moz-, -ms-, -o-)
• CSS custom properties (--variable-name)
• Modern at-rules (@media, @keyframes, @supports, @container, @layer, etc.)
• All CSS selector types (class, ID, attribute, pseudo-class, pseudo-element)
• Flexbox and Grid properties
• Font-face declarations
• SVG properties

Notes

• The validator uses the css-tree parser, which is error-tolerant and will attempt to recover from syntax errors
• Some severely malformed CSS may not trigger all validation rules if the parser cannot construct an AST
• Validation focuses on detecting common errors and best practice violations
• For production CSS validation, consider using this alongside a CSS linter like Stylelint

Integration Status

• Logger: Not applicable - Pure validation function
• Docs-Suite: Ready - Markdown documentation with code examples
• NeverHub: Not applicable - Primitive validator with no service dependencies

Dependencies

• @bernierllc/validators-core - Core validation framework
• @bernierllc/validators-utils - Shared validation utilities
• css-tree - CSS parser and AST tools

License

Copyright (c) 2025 Bernier LLC. All rights reserved.

This package is licensed to the client under a limited-use license. The client may use and modify this code only within the scope of the project it was delivered for. Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.