@salesforce/afv-skills 1.5.2 → 1.5.3

package/skills/uplifting-components-to-slds2/references/rule-no-hardcoded-values.md

@@ -0,0 +1,160 @@
+# Rule: No Hardcoded Values
+
+**Rule ID:** `slds/no-hardcoded-values-slds2`
+**Severity:** Warning
+**Scope:** All CSS properties with hardcoded values that have SLDS 2 hook equivalents — colors, spacing, sizing, typography, borders, radius, and shadows.
+
+---
+
+## What the Linter Does
+
+The linter detects hardcoded values and reports them as warnings. Here's real output for an icon component:
+
+```
+  3:10  warning  Consider replacing the 32px static value with an SLDS 2 styling hook
+                 that has a similar value: --slds-g-sizing-9.                              slds/no-hardcoded-values-slds2
+
+  5:21  warning  Dynamic element with css-class "icon-container" using static value
+                 "#066afe" for "background-color" css property. Consider replacing
+                 the #066AFE static value with an SLDS 2 styling hook:
+                 1. --slds-g-color-surface-inverse-1
+                 2. --slds-g-color-surface-inverse-2
+                 3. --slds-g-color-surface-container-inverse-1                             slds/no-hardcoded-values-slds2
+
+  9:9   warning  Dynamic element with css-class "account-icon" using static value
+                 "#ffffff" for "fill" css property. Consider replacing:
+                 1. --slds-g-color-on-accent-1
+                 2. --slds-g-color-on-accent-2
+                 3. --slds-g-color-error-base-95
+                 4. --slds-g-color-warning-base-95                                         slds/no-hardcoded-values-slds2
+```
+
+**Non-color values** get single suggestions — auto-fixable with `--fix`:
+
+```css
+/* 32px → sizing-9 (single suggestion, auto-fixed) */
+width: var(--slds-g-sizing-9, 32px);
+```
+
+**Color values** get multiple suggestions — requires manual selection. The linter suggests hooks based on color-value similarity, **not semantic context**. You must inspect the HTML to choose correctly.
+
+---
+
+## What to Fix vs What to Skip
+
+| Property Type | Example Values | Action |
+|---|---|---|
+| Color properties (`color`, `fill`, `background`, `background-color`, `stroke`, `border-*-color`, `outline-color`) | `#fff`, `rgb(0,0,0)` | **Fix** — replace with color hook + fallback |
+| Spacing properties (`margin`, `padding`, `gap`) | `16px`, `1rem`, `24px` | **Fix** — replace with spacing hook + fallback |
+| Sizing properties (`width`, `height`, `min-*`, `max-*`) | `32px`, `2rem` | **Fix** — replace with sizing hook + fallback |
+| Font properties (`font-size`, `font-weight`, `line-height`) | `14px`, `bold`, `1.5` | **Fix** — replace with typography hook + fallback |
+| Border properties (`border-radius`, `border-width`) | `8px`, `1px` | **Fix** — replace with radius/border hook + fallback |
+| Shadow properties (`box-shadow`) | `0 4px 8px rgba(…)` | **Fix** — replace with shadow hook + fallback |
+| Layout/structural values | `100%`, `auto`, `0`, `inherit`, `none` | **Skip** — leave unchanged, removing breaks rendering |
+
+When the linter says "Remove the static value" for a layout value like `width: 100%` or `height: auto`, **do not remove it**.
+
+---
+
+## Replacement Pattern
+
+Always include the original value as fallback:
+
+```css
+property: var(--slds-g-[hook], originalValue);
+```
+
+The fallback must be the **exact original value** from the source CSS (e.g., `#066AFE`, not a converted equivalent).
+
+---
+
+## Decision Tree
+
+When examining a hardcoded value or deprecated token, follow this decision tree:
+
+```
+1. SLDS utility class available?
+   └─ Yes → Remove CSS, add utility class to HTML
+   └─ No  ↓
+
+2. At least one 1:1 styling hook mapping?
+   ├─ Exactly one  → Use it with fallback
+   ├─ Multiple     → Inspect HTML context to choose (see decision guides)
+   └─ None         ↓
+
+3. No exact match
+   └─ No close match → Leave hardcoded
+```
+
+### Step 1: Check for Utility Classes
+
+If an SLDS utility class sets the exact property to the exact value, remove the CSS and replace with the class on the HTML element(s).
+
+**Best fit vs perfect fit:** Use existing utilities that get you close enough, even if it means combining two or three classes. This keeps markup readable, styles consistent, and avoids unnecessary custom CSS. Don't write new CSS rules for edge cases unless absolutely necessary.
+
+**When modifying CSS classes:**
+- Before removing a CSS declaration, ensure you understand how it's used in HTML and in JS (computed classes)
+- Update any tests after changing CSS classes — some tests use class query selectors that should be replaced with `data-tid` attributes
+
+#### Example: Replacing with Utility Classes
+
+Common CSS like `display: flex` with alignment can often be replaced entirely:
+
+```css
+/* Before — component.css */
+.container {
+    display: flex;
+    flex-direction: row;
+    justify-content: center;
+    align-items: center;
+}
+```
+
+```html
+<!-- Before — component.html -->
+<div class="container">
+```
+
+These styles map to SLDS grid utility classes:
+
+```html
+<!-- After — component.html (CSS removed entirely) -->
+<div class="slds-grid slds-grid_align-center slds-grid_vertical-align-center">
+```
+
+Note: `flex-direction: row` is the default for `display: flex` — it can be removed entirely.
+
+### Steps 2 & 3: Choose the Right Hook
+
+For choosing between multiple hooks or finding the closest match, see the decision guides:
+
+| Category | Decision Guide |
+|---|---|
+| Color (background, foreground, border color) | [color-hooks-decision-guide.md](color-hooks-decision-guide.md) — surface vs container, semantic vs palette, applied examples from real PRs |
+| Spacing, sizing, typography, borders, radius, shadows | [non-color-hooks-decision-guide.md](non-color-hooks-decision-guide.md) — numbered scales, closest-match rules, density-aware variants |
+
+---
+
+## Common Mistakes
+
+1. **Inventing hook names** — Only use hooks documented in the SLDS design system.
+2. **Missing fallback** — Always include the original value: `var(--slds-g-hook, originalValue)`
+3. **Confusing spacing and sizing** — Spacing is for margins/padding/gaps. Sizing is for width/height/dimensions.
+4. **Using named hooks** — `--slds-g-spacing-medium`, `--slds-g-font-weight-bold`, `--slds-g-radius-large` do NOT exist. Only numbered hooks exist.
+5. **Replacing layout values** — Don't replace `100%`, `auto`, `flex: 1`, `none`, or `0` with hooks.
+6. **Blindly trusting linter suggestions for colors** — The linter matches by color value, not semantic context. Always inspect HTML before choosing.
+
+## What NOT to Replace
+
+Leave these unchanged (no SLDS hooks apply):
+
+```css
+width: 100%;                   /* layout values */
+height: auto;                  /* layout values */
+flex: 1;                       /* layout values */
+display: none;                 /* layout values */
+transition: color 0.3s ease;   /* animation values */
+opacity: 0.5;                  /* opacity */
+background: linear-gradient(…); /* gradients */
+left: 50%;                     /* positioning offsets */
+```

package/skills/uplifting-components-to-slds2/references/rule-no-slds-class-overrides.md

@@ -0,0 +1,126 @@
+# Rule: No SLDS Class Overrides
+
+**Rule ID:** `slds/no-slds-class-overrides`
+**Severity:** Warning
+**Scope:** Detects CSS selectors that directly target `.slds-*` classes.
+
+---
+
+## What the Linter Does
+
+The linter detects CSS classes that directly override SLDS classes and reports them as **warnings**. It does **not** auto-fix — all changes require manual work in both CSS and HTML.
+
+```
+  1:1  warning  Overriding slds-button isn't supported. To differentiate SLDS and
+               custom classes, create a CSS class in your namespace.
+               Examples: myapp-input, myapp-button.                  slds/no-slds-class-overrides
+```
+
+**Manual steps required:**
+1. Rename `.slds-*` selectors in CSS to `{componentName}-{sldsElementPart}`
+2. Add the new component class to markup (`.html` for LWC, `.cmp` for Aura) **alongside** the original SLDS class
+3. Never remove the original SLDS class from markup
+
+---
+
+## Naming Convention
+
+**Format:** `{componentName}-{sldsElementPart}` (camelCase component name)
+
+| SLDS Class | Component: `userProfile` | Result |
+|---|---|---|
+| `.slds-button` | `userProfile` | `userProfile-button` |
+| `.slds-card` | `userProfile` | `userProfile-card` |
+| `.slds-modal__content` | `userProfile` | `userProfile-modal__content` |
+| `.slds-button_brand` | `userProfile` | `userProfile-button_brand` |
+
+---
+
+## Common Patterns
+
+### Pattern 1: Simple Selector
+
+```css
+/* Before CSS */
+.slds-button { border-radius: 8px; }
+
+/* After CSS */
+.myComponent-button { border-radius: 8px; }
+```
+
+```html
+<!-- After HTML (manual) -->
+<button class="slds-button myComponent-button">Click</button>
+```
+
+### Pattern 2: Descendant Selector
+
+```css
+/* Before CSS */
+.slds-card .slds-button { margin-top: 1rem; }
+
+/* After CSS */
+.myComponent-card .myComponent-button { margin-top: 1rem; }
+```
+
+```html
+<!-- After HTML (manual) — each SLDS class gets a component class -->
+<div class="slds-card myComponent-card">
+  <button class="slds-button myComponent-button">Click</button>
+</div>
+```
+
+### Pattern 3: Multi-Class Selector
+
+```css
+/* Before CSS */
+.slds-card.slds-p-around_medium { border: 1px solid blue; }
+
+/* After CSS */
+.myComponent-card.myComponent-p-around_medium { border: 1px solid blue; }
+```
+
+```html
+<!-- After HTML (manual) -->
+<div class="slds-card slds-p-around_medium myComponent-card myComponent-p-around_medium">
+```
+
+---
+
+## Core Rules
+
+1. **Never remove SLDS classes** from markup (`.html` or `.cmp`) — only ADD component classes alongside them
+2. **One-to-one mapping** — each SLDS class in a CSS selector gets exactly one component class
+3. **CamelCase component name** — `sampleComponent-button`, not `sample-component-button`
+4. **Preserve SLDS element names** — `.slds-button` becomes `componentName-button` (strip `slds-` prefix, keep the rest)
+
+---
+
+## Interaction with Other Rules
+
+If the overridden CSS properties include hardcoded colors, you must also apply `rule-no-hardcoded-values.md` to those properties:
+
+```css
+/* Before */
+.slds-icon-action-check { background: #4bca81; }
+
+/* After — both rules applied */
+.myComponent-icon-action-check { background: var(--slds-g-color-success-base-70, #4bca81); }
+```
+
+---
+
+---
+
+## Validation Checklist
+
+**CSS:**
+- [ ] All `.slds-*` overrides reported by the linter are addressed
+- [ ] Component name is camelCase
+- [ ] SLDS element names preserved after prefix
+
+**Markup (`.html` for LWC, `.cmp` for Aura):**
+- [ ] Original SLDS classes preserved
+- [ ] Component classes added alongside SLDS classes
+- [ ] Every element in CSS selector chain updated in markup
+- [ ] One component class per SLDS class