@salesforce-ux/eslint-plugin-slds 1.0.6-internal → 1.0.7-internal

package/README.md

@@ -27,6 +27,8 @@ module.exports = {
 
 ### ESLint v9+ (Flat Config)
 
+#### Basic Configuration
+
 ```javascript
 // eslint.config.js
 const { defineConfig } = require('eslint/config');
@@ -42,6 +44,31 @@ module.exports = defineConfig([
 ]);
 ```
 
+#### Using with Other Plugins
+
+To use the ESLint plugin with other plugins, add the `sldsCssPlugin()` helper function to the `eslint.config.mjs` configuration file. The `sldsCssPlugin()` function returns an object that contains the configurations for the ESLint plugin. This makes it easy to combine the ESLint plugin with other plugins while maintaining all the required dependencies.
+
+For example, to use the ESLint plugin with the CSS plugin, add the CSS plugin configuration to the object containing the ESLint plugin configuration.
+
+```javascript
+// eslint.config.mjs
+import { defineConfig } from 'eslint/config';
+import css from '@eslint/css';
+import { sldsCssPlugin } from '@salesforce-ux/eslint-plugin-slds';
+
+export default defineConfig([
+  {
+    files: ['**/*.css'],
+    language: 'css/css',
+    plugins: {
+      css: css,
+      ...sldsCssPlugin()
+    },
+    extends: ['@salesforce-ux/slds/recommended', 'css/recommended']
+  }
+]);
+```
+
 ## Migrate to the Latest Version
 
 By default, the latest version of the plugin supports legacy and flat config systems.
@@ -69,68 +96,6 @@ By default, the latest version of the plugin supports legacy and flat config sys
 - `reduce-annotations`: Identifies annotations that must be removed from the code.
 - `lwc-token-to-slds-hook`: Identifies the deprecated --lwc tokens that must be replaced with the latest --slds tokens. For more information, see lightningdesignsystem.com.
 
-## Closest Color Suggestion Logic
-
-This plugin suggests SLDS styling hooks that are perceptually closest to a given hardcoded color. The logic lives in `src/utils/color-lib-utils.ts` and is used by `no-hardcoded-values-slds2`.
-
-- **API surface**
-  - `findClosestColorHook(color, supportedColors, cssProperty): string[]`
-    Returns up to 5 hook names, ordered by category priority and perceptual distance.
-  - `isHardCodedColor(value): boolean`
-    Detects if a string likely represents a hardcoded color (excludes CSS `var(...)`).
-
-- **Perceptual metric**
-  - Uses `chroma.deltaE` (CIEDE2000) to compare the input color against known SLDS color values.
-  - A threshold (`DELTAE_THRESHOLD = 25`) controls how strict the matching is.
-  - Exact hex matches short-circuit to distance `0` to avoid float rounding differences.
-
-- **Category ordering**
-  - Hooks are ranked by category, then by distance (ascending):
-    1. Semantic hooks (e.g., surface, accent, error, success, etc.)
-    2. System hooks
-    3. Palette hooks
-  - Only the top 5 suggestions are returned.
-
-- **Property awareness**
-  - Suggestions consider the CSS property from rule context.
-  - Hooks declared for the same property (or `*`) are prioritized if within the distance threshold.
-
-- **CSS variables**
-  - Values using `var(...)` are not flagged as hardcoded colors and are excluded from matching.
-
-- **Semantic hook ordering by CSS property**
-  The sorter always applies the same category priority (semantic → system → palette). Within the semantic category, ordering is purely by perceptual distance for the current CSS property; there is no hardcoded sub-priority among semantic families (surface, accent, error, etc.). Property awareness comes from the metadata (`properties` on each hook).
-
-  - `color`
-    - Prefers semantic hooks that declare `properties: ['color']` (e.g., text/foreground-oriented tokens).
-    - If multiple semantic hooks are eligible, they are ordered by Delta E (closest first).
-    - If none are within threshold, the sorter may fall back to system, then palette.
-
-  - `background-color`
-    - Prefers semantic surface/role tokens that declare `['background-color']`.
-    - Among eligible semantic hooks, order is by Delta E.
-
-  - `border-color` (and `outline-color`)
-    - Prefers semantic or system hooks that declare `['border-color']` (or `['outline-color']`).
-    - If semantic hooks exist for borders, they are ranked before system; otherwise system hooks lead.
-    - Order within the chosen category is by Delta E.
-
-  - `box-shadow`
-    - For color components inside shadows, prefers hooks declaring `['box-shadow']` or universal `['*']`.
-    - Ordering within semantic remains by Delta E.
-
-  - Other properties
-    - If hook metadata specifies the current property, those hooks are preferred.
-    - Hooks with `['*']` (universal) are considered next.
-    - If still none within threshold, different-property hooks may be considered (still subject to category priority and Delta E).
-
-- **Example**
-  ```js
-  // Given a hex color and a CSS property like 'color'
-  const suggestions = findClosestColorHook('#ff0000', supportedColors, 'color');
-  // => ['--slds-...semantic-...', '--slds-...system-...', ...]
-  ```
-
 ## License
 
 ISC