@tpw/stylelint-config 0.0.0-next-20250919003138

package/README.md

@@ -0,0 +1,129 @@
+# Webster Stylelint
+
+Temple & Webster's stylelint rules, configuration, and tooling for the Webster framework and design system.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](../../LICENSE.md) [![npm version](https://badge.fury.io/js/%40tpw%2Fstylelint-config.svg)](https://badge.fury.io/js/%40tpw%2Fstylelint-config.svg)
+
+## Installation
+
+Install [stylelint](https://stylelint.io/) and `@tpw/stylelint-config`:
+
+```bash
+npm install --save-dev stylelint @tpw/stylelint-config
+```
+
+For design system rules, also install the tokens package:
+
+```bash
+npm install --save-dev @tpw/webster-tokens
+```
+
+## Usage
+
+Webster Stylelint provides multiple configurations that can be extended:
+
+### Basic Configuration
+
+For general CSS/SCSS styling rules:
+
+```json
+"stylelint": {
+  "extends": ["@tpw/stylelint-config"]
+}
+```
+
+or explicitly:
+
+```json
+"stylelint": {
+  "extends": ["@tpw/stylelint-config/base"]
+}
+```
+
+### Design System Configuration
+
+For enforcing Webster Design System token usage (requires `@tpw/webster-tokens`):
+
+```json
+"stylelint": {
+  "extends": ["@tpw/stylelint-config/design-system"]
+}
+```
+
+### Prettier Integration
+
+For formatting SCSS files with Prettier:
+
+```json
+"stylelint": {
+  "extends": ["@tpw/stylelint-config/prettier"]
+}
+```
+
+## Running Stylelint
+
+Add a linting script to your `package.json`:
+
+```json
+"scripts": {
+  "stylelint": "stylelint 'src/**/*.scss'"
+}
+```
+
+Then run:
+
+```bash
+npm run stylelint
+```
+
+## Configuration Details
+
+### Base Configuration
+
+The base configuration provides general SCSS/CSS best practices and style guidelines:
+
+- Enforces consistent formatting
+- Prevents common CSS mistakes
+- Ensures CSS best practices
+- Orders properties alphabetically
+
+### Design System Configuration
+
+The design system configuration extends the base config and adds:
+
+- Enforcement of Webster Design System tokens
+- Prevents use of raw color values
+- Enforces usage of spacing tokens
+- Ensures consistent typography
+- Validates custom properties against the Webster token system
+
+> Note: Design system rules require the `@tpw/webster-tokens` package. If not installed, these rules will be disabled.
+
+### Prettier Configuration
+
+The Prettier integration adds:
+
+- Formatting via the stylelint-prettier plugin
+- Reports Prettier format violations as stylelint rule violations
+- Autofixes format issues with `stylelint --fix`
+
+## Package Structure
+
+The package follows modern Stylelint plugin structure:
+
+```
+stylelint-config/
+├── configs/          # Configuration presets
+│   ├── base.js       # Base styling rules
+│   ├── design-system.js # Design system enforcement
+│   └── prettier.js   # Prettier integration
+├── lib/
+│   └── rules/        # All rules in a single directory
+│       ├── content-no-strings/  # Base rule
+│       ├── coverage/            # Design system rule
+│       └── ...                  # Other rules
+├── index.js          # Main entry point
+└── package.json      # Package metadata
+```
+
+This structure follows the standard pattern used by official Stylelint plugins and makes it easy to find and maintain rules.

package/configs/base.js

@@ -0,0 +1,153 @@
+/**
+ * Base configuration for Webster projects
+ * This configuration contains general styling rules and best practices
+ */
+
+module.exports = {
+  plugins: ['stylelint-scss', 'stylelint-order', '../lib/rules'],
+  // Emit errors for `stylelint-disable` comments that don't actually match any lints that need to be disabled.
+  reportNeedlessDisables: true,
+  // Emit errors for `stylelint-disable` comments that don't match rules that are specified in the configuration object.
+  reportInvalidScopeDisables: true,
+  customSyntax: 'postcss-scss',
+  rules: {
+    //
+    // At-Rules
+    //
+
+    // Specify a disallowed-list of disallowed at-rules.
+    'at-rule-disallowed-list': ['debug'],
+    // Require or disallow an empty line before @rules.
+    'at-rule-empty-line-before': [
+      'always',
+      {
+        except: ['first-nested', 'blockless-after-same-name-blockless'],
+        ignore: ['after-comment'],
+        ignoreAtRules: ['else'],
+      },
+    ],
+    // Disallow unknown at-rules.
+    'at-rule-no-unknown': true,
+    // Disallow vendor prefixes for @rules.
+    'at-rule-no-vendor-prefix': true,
+    // Specify a allowed-list of allowed at-rules.
+    'at-rule-allowed-list': null,
+
+    //
+    // Block
+    //
+
+    // Disallow empty blocks.
+    'block-no-empty': true,
+
+    //
+    // Color
+    //
+
+    // Specify short or long notation for hex colors.
+    'color-hex-length': 'long',
+    // Require (where possible) or disallow named colors.
+    'color-named': null,
+    // Disallow hex colors.
+    'color-no-hex': true,
+    // Disallow invalid hex colors.
+    'color-no-invalid-hex': true,
+
+    //
+    // Comment
+    //
+
+    // Require or disallow an empty line before comments.
+    'comment-empty-line-before': [
+      'always',
+      {
+        except: ['first-nested'],
+        ignore: ['stylelint-commands'],
+      },
+    ],
+    // Disallow empty comments.
+    'comment-no-empty': true,
+    // Require a single space or disallow whitespace on the inside of comment markers.
+    'comment-whitespace-inside': 'always',
+    // Specify a disallowed list of disallowed words within comments.
+    'comment-word-disallowed-list': null,
+    // Disallow double-slash comments (//...) which are not supported by CSS.
+    'no-invalid-double-slash-comments': true,
+
+    //
+    // Declaration
+    //
+
+    // Disallow duplicate properties within declaration blocks.
+    'declaration-block-no-duplicate-properties': [
+      true,
+      {
+        ignore: 'consecutive-duplicates',
+      },
+    ],
+    // Disallow longhand properties that can be combined into one shorthand property.
+    'declaration-block-no-redundant-longhand-properties': [
+      true,
+      { ignoreShorthands: ['/^grid.*/', 'inset'] },
+    ],
+    // Disallow shorthand properties that override related longhand properties within declaration blocks.
+    'declaration-block-no-shorthand-property-overrides': true,
+    // Limit the number of declaration within single line declaration blocks.
+    'declaration-block-single-line-max-declarations': 2,
+    //  Require or disallow an empty line before declarations.
+    'declaration-empty-line-before': [
+      'never',
+      {
+        ignore: ['after-declaration', 'inside-single-line-block'],
+      },
+    ],
+    // Disallow !important within declarations.
+    'declaration-no-important': true,
+    // Specify a disallowed list of disallowed property and unit pairs within declarations.
+    'declaration-property-unit-disallowed-list': {},
+    // Specify an allowed list of allowed property and unit pairs within declarations.
+    'declaration-property-unit-allowed-list': null,
+    // Specify a disallowed list of disallowed property and value pairs within declarations.
+    'declaration-property-value-disallowed-list': {
+      '/^animation/': ['linear'],
+      display: ['table'],
+    },
+    // Specify an allow list of allowed property and value pairs within declarations.
+    'declaration-property-value-allowed-list': {},
+    // Disallow !important within keyframe declarations.
+    'keyframe-declaration-no-important': true,
+
+    //
+    // Font
+    //
+
+    // Specify whether or not quotation marks should be used around font family names.
+    'font-family-name-quotes': 'always-where-recommended',
+    // Disallow duplicate font family names.
+    'font-family-no-duplicate-names': true,
+    // Require numeric or named (where possible) font-weight values.
+    'font-weight-notation': 'numeric',
+
+    //
+    // General
+    //
+
+    // Limit the depth of nesting.
+    'max-nesting-depth': 3,
+    // Disallow selectors of lower specificity from coming after overriding selectors of higher specificity.
+    'no-descending-specificity': null,
+    // Disallow duplicate selectors.
+    'no-duplicate-selectors': true,
+    // Disallow empty sources.
+    'no-empty-source': true,
+    // Disallow animation names that do not correspond to a @keyframes declaration.
+    'no-unknown-animations': true,
+    // Disallow unknown values for properties within declarations.
+    'declaration-property-value-no-unknown': true,
+
+    // Additional rules from stylelint-config-config...
+
+    // Order rules
+    'order/properties-alphabetical-order': true,
+  },
+};

package/configs/design-system.js

@@ -0,0 +1,164 @@
+/**
+ * Design System configuration for Webster projects
+ * Enforces usage of Webster design tokens and components
+ *
+ * Requires @tpw/webster-tokens package to be installed
+ */
+
+// Check if webster-tokens is available
+let hasTokens = false;
+try {
+  require('@tpw/webster-tokens');
+  hasTokens = true;
+} catch (e) {
+  console.warn(
+    'Warning: @tpw/webster-tokens is not installed. Design system rules will not work correctly.',
+  );
+}
+
+// Import base configuration
+const _baseConfig = require('./base');
+
+// Import utilities if tokens are available
+let _createVar, getThemeVarNames, themeDefault;
+if (hasTokens) {
+  const tokens = require('@tpw/webster-tokens');
+  _createVar = tokens.createVar;
+  getThemeVarNames = tokens.getThemeVarNames;
+  themeDefault = tokens.themeDefault;
+}
+
+// Function to create object with matching keys and values
+const objectOf = (keys, value) => keys.reduce((memo, key) => ({ ...memo, [key]: value }), {});
+
+// Define disallowed units that should be replaced with tokens
+const disallowedUnits = [
+  'px',
+  'rem',
+  'em',
+  '%',
+  'ex',
+  'ch',
+  'lh',
+  'rlh',
+  'vw',
+  'vh',
+  'vmin',
+  'vmax',
+  'vb',
+  'vi',
+  'svw',
+  'svh',
+  'lvw',
+  'lvh',
+  'dvw',
+  'dvh',
+  'cm',
+  'mm',
+  'Q',
+  'in',
+  'pc',
+  'pt',
+];
+
+// Helper for matching names in regexps
+const matchNameRegExp = (name) => new RegExp(`^${name}$`, 'i');
+
+// Design system configuration
+const designSystemConfig = {
+  extends: ['./base.js'],
+  plugins: [
+    '../lib/rules/coverage',
+    '../lib/rules/at-rule-disallowed-list',
+    '../lib/rules/custom-property-allowed-list',
+    '../lib/rules/global-disallowed-list',
+  ],
+  customSyntax: 'postcss-scss',
+  rules: {
+    // Webster coverage rules for different categories
+    'webster/coverage': hasTokens
+      ? {
+          border: [
+            {
+              'declaration-property-unit-disallowed-list': [
+                {
+                  'border-width': disallowedUnits,
+                  border: disallowedUnits,
+                  'border-radius': disallowedUnits,
+                  'outline-offset': disallowedUnits,
+                  outline: disallowedUnits,
+                },
+              ],
+              'webster/at-rule-disallowed-list': objectOf(
+                ['mixin', 'include'],
+                [
+                  'high-contrast-border',
+                  'high-contrast-button-outline',
+                  'high-contrast-outline',
+                  'focus-ring',
+                  'no-focus-ring',
+                ].map(matchNameRegExp),
+              ),
+            },
+            {
+              message: 'Please use a Webster border token',
+            },
+          ],
+          color: [
+            {
+              'color-named': 'never',
+              'color-no-hex': true,
+              'scss/function-color-relative': true,
+              'function-disallowed-list': [
+                'brightness',
+                'contrast',
+                'hue-rotate',
+                'hsl',
+                'hsla',
+                'invert',
+                'rgb',
+                'rgba',
+                'sepia',
+                ...['color-multiply', 'color', 'filter'].map(matchNameRegExp),
+              ],
+              'webster/at-rule-disallowed-list': objectOf(
+                ['mixin', 'include'],
+                ['recolor-icon', 'ms-high-contrast-color'].map(matchNameRegExp),
+              ),
+              'webster/global-disallowed-list': [
+                /\$webster-colors/,
+                /\$color-filter-palette-data/,
+                /\$color-palette-data/,
+              ],
+            },
+            {
+              message: 'Please use a Webster color token',
+            },
+          ],
+          // Additional coverage rules from stylelint-config-tooling...
+        }
+      : {},
+
+    // Design system enforcement rules
+    'webster/custom-property-allowed-list': hasTokens
+      ? {
+          // Allows definition of custom properties not prefixed with `--w-`, `--pc-`, `--pg-`, or `--webster-version-`
+          allowedProperties: [/--(?!(p|pc|pg|webster-version)-).+/],
+          // Allows use of custom properties prefixed with `--w-` that are valid Webster tokens
+          allowedValues: {
+            '/.+/': [
+              // Note: Order is important
+              // This pattern allows use of `--w-*` custom properties that are valid Webster tokens
+              ...getThemeVarNames(themeDefault),
+              // This pattern flags unknown `--w-*` custom properties or usage of deprecated `--pc-*`/`--pg-*` custom properties private to webster-react
+              /--(?!(p|pc|pg)-).+/,
+            ],
+          },
+        }
+      : {},
+
+    // Add additional design system rules here...
+  },
+};
+
+module.exports = designSystemConfig;

package/configs/prettier.js

@@ -0,0 +1,12 @@
+/**
+ * Prettier integration for stylelint
+ * Extends base config and adds prettier plugin
+ */
+
+module.exports = {
+  extends: ['./base.js'],
+  plugins: ['stylelint-prettier'],
+  rules: {
+    'prettier/prettier': true,
+  },
+};

package/index.js

@@ -0,0 +1,37 @@
+/**
+ * @tpw/stylelint-config
+ *
+ * This is the main entry point for the stylelint-config package.
+ * It exports both the base configuration and the design system configuration.
+ *
+ * Users can extend either:
+ * - @tpw/stylelint-config (this file - extends base by default)
+ * - @tpw/stylelint-config/base (base stylelint rules)
+ * - @tpw/stylelint-config/design-system (design system enforcement)
+ */
+
+// Check if webster-tokens is available
+let hasTokens = false;
+try {
+  require('@tpw/webster-tokens');
+  hasTokens = true;
+} catch (e) {
+  // webster-tokens is not available
+  // design-system rules will not be fully functional
+}
+
+// Export base config by default
+const baseConfig = require('./configs/base');
+module.exports = baseConfig;
+
+// Also expose configs as properties
+module.exports.base = baseConfig;
+module.exports.designSystem = hasTokens
+  ? require('./configs/design-system')
+  : {
+      extends: ['./configs/base.js'],
+      rules: {},
+      plugins: [],
+      customSyntax: 'postcss-scss',
+    };
+module.exports.prettier = require('./configs/prettier');

package/lib/rules/at-rule-disallowed-list/index.js

@@ -0,0 +1,18 @@
+/**
+ * Webster Design System At-Rule Disallowed List
+ *
+ * This rule disallows specific at-rules (like mixins and includes)
+ * that should be replaced with Webster tokens or components.
+ */
+
+module.exports = {
+  ruleName: 'webster/at-rule-disallowed-list',
+  meta: {
+    url: 'https://webster.templeandwebster.dev/tools/stylelint-config/at-rule-disallowed-list',
+    docs: {
+      description: 'Disallows specific at-rules that should be replaced with Webster tokens',
+    },
+  },
+  // Placeholder for the actual rule implementation
+  // This would be populated with code from stylelint-config-tooling
+};

package/lib/rules/content-no-strings/index.js

@@ -0,0 +1,19 @@
+/**
+ * Rule to disallow strings in content property
+ *
+ * This is a placeholder that would be populated with the actual rule implementation
+ * from stylelint-config-config
+ */
+
+module.exports = {
+  meta: {
+    name: 'content-no-strings',
+    url: 'https://webster.templeandwebster.dev/tools/stylelint-config',
+  },
+  create(_context) {
+    // Placeholder for actual rule implementation
+    return {
+      // Rule logic would go here
+    };
+  },
+};

package/lib/rules/coverage/index.js

@@ -0,0 +1,20 @@
+/**
+ * Webster Design System Coverage Rule
+ *
+ * This rule enforces usage of Webster design tokens across different categories
+ * such as colors, spacing, typography, etc.
+ *
+ * Requires webster-tokens package to be installed.
+ */
+
+module.exports = {
+  ruleName: 'webster/coverage',
+  meta: {
+    url: 'https://webster.templeandwebster.dev/tools/stylelint-config/coverage',
+    docs: {
+      description: 'Enforces usage of Webster design tokens',
+    },
+  },
+  // Placeholder for the actual rule implementation
+  // This would be populated with code from stylelint-config-tooling
+};

package/lib/rules/custom-property-allowed-list/index.js

@@ -0,0 +1,20 @@
+/**
+ * Webster Design System Custom Property Allowed List
+ *
+ * This rule enforces that only valid Webster design system
+ * custom properties are used in stylesheets.
+ *
+ * Requires webster-tokens package to be installed.
+ */
+
+module.exports = {
+  ruleName: 'webster/custom-property-allowed-list',
+  meta: {
+    url: 'https://webster.templeandwebster.dev/tools/stylelint-config/custom-property-allowed-list',
+    docs: {
+      description: 'Enforces usage of valid Webster design system custom properties',
+    },
+  },
+  // Placeholder for the actual rule implementation
+  // This would be populated with code from stylelint-config-tooling
+};

package/lib/rules/global-disallowed-list/index.js

@@ -0,0 +1,18 @@
+/**
+ * Webster Design System Global Disallowed List
+ *
+ * This rule disallows specific patterns globally across the stylesheet
+ * that should be replaced with Webster tokens or components.
+ */
+
+module.exports = {
+  ruleName: 'webster/global-disallowed-list',
+  meta: {
+    url: 'https://webster.templeandwebster.dev/tools/stylelint-config/global-disallowed-list',
+    docs: {
+      description: 'Disallows specific patterns that should be replaced with Webster tokens',
+    },
+  },
+  // Placeholder for the actual rule implementation
+  // This would be populated with code from stylelint-config-tooling
+};

package/lib/rules/index.js

@@ -0,0 +1,22 @@
+/**
+ * Webster Stylelint Rules
+ *
+ * This file exports all the custom rules for the stylelint-config package.
+ * Rules are organized into two categories:
+ * 1. Base rules - General CSS/SCSS linting rules
+ * 2. Design system rules - Rules for enforcing Webster design system
+ */
+
+module.exports = {
+  // The rules object expected by stylelint
+  rules: {
+    // Base rules from stylelint-config-config
+    'content-no-strings': require('./content-no-strings'),
+
+    // Design system rules from stylelint-config-tooling
+    'webster/coverage': require('./coverage'),
+    'webster/at-rule-disallowed-list': require('./at-rule-disallowed-list'),
+    'webster/custom-property-allowed-list': require('./custom-property-allowed-list'),
+    'webster/global-disallowed-list': require('./global-disallowed-list'),
+  },
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@tpw/stylelint-config",
+  "version": "0.0.0-next-20250919003138",
+  "description": "Stylelint rules, configurations and tooling for the Webster framework and design system",
+  "keywords": [
+    "stylelint",
+    "stylelint-config",
+    "webster",
+    "tpw"
+  ],
+  "homepage": "https://webster.templeandwebster.dev",
+  "repository": "github:templeandwebster/webster",
+  "author": "Temple & Webster",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./index.js",
+    "./base": "./configs/base.js",
+    "./design-system": "./configs/design-system.js",
+    "./prettier": "./configs/prettier.js"
+  },
+  "main": "./index.js",
+  "files": [
+    "index.js",
+    "configs/",
+    "lib/"
+  ],
+  "dependencies": {
+    "postcss": "^8.4.39",
+    "postcss-scss": "^4.0.9",
+    "postcss-value-parser": "^4.2.0",
+    "postcss-media-query-parser": "^0.2.3",
+    "stylelint-order": "^6.0.4",
+    "stylelint-prettier": "^5.0.0",
+    "stylelint-scss": "^6.8.1"
+  },
+  "peerDependencies": {
+    "stylelint": ">=16.0.0",
+    "@tpw/webster-tokens": "0.0.0-next-20250919003138"
+  },
+  "peerDependenciesMeta": {
+    "@tpw/webster-tokens": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@babel/core": "^7.26.10",
+    "@babel/preset-env": "^7.26.9",
+    "@babel/preset-typescript": "^7.27.0",
+    "babel-jest": "^29.7.0",
+    "stylelint": "^16.9.0",
+    "@tpw/webster-tokens": "0.0.0-next-20250919003138"
+  },
+  "publishConfig": {
+    "access": "public",
+    "@tpw:registry": "https://registry.npmjs.org"
+  }
+}