@salesforce/afv-skills 1.5.2 → 1.5.3

package/README.md

@@ -1,16 +1,15 @@
 # Agentforce Vibes Library
 
-AI skills and rules library for Agentforce Vibes development of Salesforce metadata.
+AI skills library for Agentforce Vibes development of Salesforce metadata.
 
 ## 📚 About
 
-This repository curates Salesforce-focused skills and system rules from the wider developer community to accelerate Agentforce Vibes agentic workflows. 
+This repository curates Salesforce-focused skills from the wider developer community to accelerate Agentforce Vibes agentic workflows. 
 
 ## 🗂️ Structure
 
 ```
 afv-library/
-├── rules/                # Single-file guardrails and standards
 ├── skills/               # Directory-based executable workflows
 │   ├── generating-apex/
 │   ├── generating-custom-object/
@@ -19,14 +18,14 @@ afv-library/
 ├── samples/              # Synced sample apps (e.g. from npm)
 │   └── ui-bundle-template-app-react-sample-b2e/
 │   └── ...
-├── scripts/              
+├── scripts/
 │   └── ...
 └── README.md
 ```
 
 ## Manual Usage
 
-Browse the repository and copy/paste any rule or skill directly into Agentforce Vibes or your preferred AI tool.
+Browse the repository and copy/paste any skill directly into Agentforce Vibes or your preferred AI tool.
 
 ## Samples
 
@@ -42,7 +41,7 @@ The GitHub Action runs these same commands and opens a PR only when the npm pack
 
 ## 🛠️ Agent Skills
 
-Agent Skills extend rules by bundling executable workflows, scripts, and reference materials into self-contained directories. Skills follow the open [Agent Skills specification](https://agentskills.io/) and are portable across many agent tools (Cursor, Claude Code, VS Code extensions, etc.).
+Agent Skills are modular capabilities that bundle executable workflows, scripts, and reference materials into self-contained directories. Skills follow the open [Agent Skills specification](https://agentskills.io/) and are portable across many agent tools (Agentforce Vibes, Cursor, Claude Code, etc).
 
 ### Directory Structure
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/afv-skills",
-  "version": "1.5.2",
+  "version": "1.5.3",
   "description": "Salesforce skills for Agentforce Vibes",
   "license": "CC-BY-NC-4.0",
   "files": [
@@ -11,8 +11,8 @@
     "registry": "https://registry.npmjs.org"
   },
   "devDependencies": {
-    "@salesforce/ui-bundle-template-app-react-sample-b2e": "^1.117.5",
-    "@salesforce/ui-bundle-template-app-react-sample-b2x": "^1.117.5",
+    "@salesforce/ui-bundle-template-app-react-sample-b2e": "^1.118.1",
+    "@salesforce/ui-bundle-template-app-react-sample-b2x": "^1.118.1",
     "@salesforce/webapp-template-app-react-sample-b2e-experimental": "^1.117.1",
     "@salesforce/webapp-template-app-react-sample-b2x-experimental": "^1.117.1",
     "@types/js-yaml": "^4.0.9",

package/skills/generating-apex/SKILL.md

@@ -6,7 +6,7 @@ description: Primary Apex authoring skill for class generation, refactoring, and
 # Generating Apex
 
 Use this skill for production-grade Apex: new classes, selectors, services, async jobs,
-invocable methods, and triggers; and for evidence-based review of existing `.cls`.
+invocable methods, and triggers; and for evidence-based review of existing `.cls` OR `.trigger`.
 
 ## Required Inputs
 
@@ -16,11 +16,11 @@ Gather or infer before authoring:
 - Target object(s) and business goal
 - Class name (derive using the naming table below)
 - Net-new vs refactor/fix; any org/API constraints
-- Deployment targets
+- Deployment targets (default to runSpecifiedTests and use generated tests where applicable)
 
 Defaults unless specified:
 - Sharing: `with sharing` (see sharing rules per type below)
-- Access: `public` (use `global` only when required by managed packages or `@InvocableMethod`)
+- Access: `public` (use `global` only when required by managed packages or `@RestResource`)
 - API version: `66.0` (minimum version)
 - ApexDoc comments: yes
 
@@ -48,9 +48,9 @@ All steps are sequential. Do not skip, merge, or reorder. If blocked, stop and a
 
 4. **Author with guardrails** -- apply every rule in the Rules section below
    - Generate `{ClassName}.cls` with ApexDoc
-   - Generate `{ClassName}.cls-meta.xml`
+   - Generate `{ClassName}.cls-meta.xml`   
 
-5. **Generate test classes** -- delegate to `generating-apex-test` to create `{ClassName}Test.cls` and `{ClassName}Test.cls-meta.xml`. Do not write test code in this skill. If the test skill is unavailable, record `test_skill=unavailable: <reason>` in Step 8.
+5. **Generate test classes** -- Load the skill `generating-apex-test` to create `{ClassName}Test.cls` and `{ClassName}Test.cls-meta.xml`.  Apex tests are always required to be generated to deploy. No test file creation or edits can occur without loading the  `generating-apex-test` skill to generate tests.
 
 ### Phase 2 — Validate (required before reporting)
 
@@ -64,7 +64,7 @@ Writing files is the midpoint, not the finish line. Steps 6 and 7 each require a
 
 7. **Execute Apex tests**
    - Run org tests including `{ClassName}Test` via `sf apex run test` or MCP.
-   - Delegate all test fixes/coverage work to `generating-apex-test`; iterate until green.
+   - Delegate all test generation/fixes/coverage work to `generating-apex-test`; iterate until the tests pass.
    - Capture pass/fail counts and coverage percentage for the report.
    - If unavailable, record `test_execution=unavailable: <error>` in the report.
 
@@ -93,7 +93,7 @@ If any constraint would be violated in generated code, **stop and explain the pr
 | Use bind variables for all dynamic SOQL with user input | Prevent SOQL injection |
 | Use Apex-native collections (`List`, `Map`, `Set`) rather than Java types | Prevent compile errors |
 | Verify methods exist in Apex before use | Prevent reliance on non-existent APIs |
-| Prefer structured logging over `System.debug()` | Debug string concatenation consumes CPU even when not observed |
+| Avoid `System.debug()` in main code paths | Debug statements evaluate even when loggign is not active and consume CPU. Use a logging framework if required on main code paths |
 | Never use `@future` methods | Use Queueable with `System.Finalizer`; `@future` cannot chain, cannot be called from Batch, and cannot accept non-primitive types |
 
 ### Bulkification & Governor Limits
@@ -142,6 +142,8 @@ Before finalizing, verify: CRUD/FLS enforced (SOQL + DML) · explicit sharing ke
 - Preserve exception cause chains: `new CustomException('message', cause)` (do not replace stack trace with concatenated messages)
 - Provide a custom exception class per service domain when meaningful
 - In `@AuraEnabled` methods, catch exceptions and rethrow as `AuraHandledException`
+- Fallback option: when no meaningful domain exception exists, catch generic `Exception` and either rethrow it or wrap it in a minimal custom exception that preserves the original cause.
+
 
 ### Null Safety
 
@@ -196,8 +198,9 @@ Class-level format:
 
 ```apex
 /**
- * @author Generated by Apex Skill
+ * Provides services for geolocation and address conversion.
  */
+public with sharing class GeolocationService { }
 ```
 
 Method-level format:
@@ -357,6 +360,10 @@ Deliverables per class:
 - `{ClassName}Test.cls` (generated via `generating-apex-test` skill)
 - `{ClassName}Test.cls-meta.xml` (generated via `generating-apex-test` skill)
 
+Deliverables per trigger:
+- `{TriggerName}.trigger`
+- `{TriggerName}.trigger-meta.xml` (default API version `66.0` or higher unless specified)
+
 Meta XML template:
 
 ```xml
@@ -396,4 +403,4 @@ Deploy: <dry-run or next step>
 
 ## Troubleshooting Boundary
 
-This skill handles production `.cls`/`.trigger` issues only: compile/parse failures, deployment dependency errors, runtime governor-limit failures. For test execution, assertions, coverage, or `sf apex run test` failures, delegate to `generating-apex-test`.
+This skill handles production `.cls`/`.trigger`/`.apex` issues only: compile/parse failures, deployment dependency errors, runtime governor-limit failures. For test execution, assertions, coverage, or `sf apex run test` failures, delegate to `generating-apex-test`.

package/skills/generating-apex/assets/abstract.cls

@@ -6,7 +6,6 @@
 >>>>>>> Stashed changes
  *              Provides common behavior and defines extension points for subclasses.
  *              Subclasses must implement the abstract methods to provide specific behavior.
- * @author Generated by Apex Class Writer Skill
  *
  * @example
  * // Extending this abstract class:

package/skills/generating-apex/assets/batch.cls

@@ -2,7 +2,6 @@
  * Batch Apex class for {describe the batch operation}.
  *              Processes {SObject} records in configurable batch sizes.
  *              Implements Database.Stateful to track cumulative results across chunks.
- * @author Generated by Apex Class Writer Skill
  *
  * @example
  * // Execute with default batch size

package/skills/generating-apex/assets/domain.cls

@@ -2,7 +2,6 @@
  * Domain class for {SObject}.
  *              Encapsulates field-level defaults, derivations, and validations.
  *              Operates only on in-memory SObject data — no SOQL or DML.
- * @author Generated by Apex Class Writer Skill
  */
 public with sharing class {SObject}Domain {
 

package/skills/generating-apex/assets/dto.cls

@@ -2,7 +2,6 @@
  * Data Transfer Object for {describe the data this DTO represents}.
  *              Used to pass structured data between layers without exposing SObjects.
  *              Serialization-friendly for use with JSON.serialize/deserialize and API responses.
- * @author Generated by Apex Class Writer Skill
  *
  * @example
  * // Create from constructor

package/skills/generating-apex/assets/exception.cls

@@ -2,7 +2,6 @@
  * Custom exception for {describe when this exception is thrown}.
  *              Use this exception to signal domain-specific errors that callers
  *              can catch and handle distinctly from system exceptions.
- * @author Generated by Apex Class Writer Skill
  *
  * @example
  * throw new {ClassName}('Account merge failed: duplicate detected.');

package/skills/generating-apex/assets/interface.cls

@@ -1,7 +1,6 @@
 /**
  * Interface for {describe the capability or contract this interface defines}.
  *              Implement this interface to provide {describe what implementations do}.
- * @author Generated by Apex Class Writer Skill
  *
  * @example
  * public class EmailNotificationService implements {InterfaceName} {

package/skills/generating-apex/assets/invocable.cls

@@ -2,7 +2,6 @@
  * Invocable Apex action for {describe the action}.
  * Callable from Flows, Process Builder, and Agentforce.
  * Accepts bulkified List<Request>, returns List<Response>.
- * @author Generated by Apex Class Writer Skill
  */
 public with sharing class {ClassName} {
 

package/skills/generating-apex/assets/queueable.cls

@@ -2,7 +2,6 @@
  * Queueable Apex class for {describe the async operation}.
  *              Accepts data through the constructor for stateful processing.
  *              Optionally implements Database.AllowsCallouts for external integrations.
- * @author Generated by Apex Class Writer Skill
  *
  * @example
  * // Enqueue the job

package/skills/generating-apex/assets/schedulable.cls

@@ -2,7 +2,6 @@
  * Schedulable Apex class for {describe the scheduled operation}.
  *              Delegates heavy processing to a Batch or Queueable job.
  *              Keep execute() lightweight — it should only launch other jobs.
- * @author Generated by Apex Class Writer Skill
  *
  * @example
  * // Schedule to run daily at 2 AM

package/skills/generating-apex/assets/selector.cls

@@ -2,7 +2,6 @@
  * Selector class for {SObject} queries.
  *              Encapsulates all SOQL for {SObject} records.
  *              All methods return bulkified results (Lists or Maps).
- * @author Generated by Apex Class Writer Skill
  */
 public inherited sharing class {SObject}Selector {
 

package/skills/generating-apex/assets/service.cls

@@ -2,7 +2,6 @@
  * Service class for {SObject} business logic.
  *              Follows separation of concerns: delegates queries to {SObject}Selector
  *              and SObject manipulation to {SObject}Domain where applicable.
- * @author Generated by Apex Class Writer Skill
  */
 public with sharing class {SObject}Service {
 

package/skills/generating-apex/assets/trigger.cls

@@ -1,5 +1,5 @@
 /**
- * @author Generated by Apex Class Writer Skill
+ * {SObject} Trigger
  */
 trigger {SObject}Trigger on {SObject} (
     before insert,

package/skills/generating-apex/assets/utility.cls

@@ -2,7 +2,6 @@
  * Utility class for {describe the category of utilities: String, Date, Collection, etc.}.
  *              All methods are static and side-effect-free (no SOQL, no DML).
  *              Private constructor prevents instantiation.
- * @author Generated by Apex Class Writer Skill
  */
 public with sharing class {ClassName} {
 

package/skills/generating-apex/references/AccountDeduplicationBatch.cls

@@ -3,7 +3,6 @@
  *              Compares Accounts by Name and BillingPostalCode to find potential duplicates.
  *              Flags duplicates by setting the Is_Potential_Duplicate__c checkbox.
  *              Implements Database.Stateful to track results across batch chunks.
- * @author Generated by Apex Class Writer Skill
  *
  * @example
  * // Run with default batch size (200)

package/skills/generating-apex/references/AccountSelector.cls

@@ -2,7 +2,6 @@
  * Selector class for Account queries.
  *              Encapsulates all SOQL for Account records.
  *              All methods return bulkified results (Lists or Maps).
- * @author Generated by Apex Class Writer Skill
  */
 public with sharing class AccountSelector {
 

package/skills/generating-apex/references/AccountService.cls

@@ -2,7 +2,6 @@
  * Service class for Account business logic.
  *              Provides account deduplication, enrichment, and territory assignment.
  *              Delegates queries to AccountSelector and SObject manipulation to AccountDomain.
- * @author Generated by Apex Class Writer Skill
  */
 public with sharing class AccountService {
 

package/skills/generating-apex-test/assets/test-class-template.cls

@@ -1,7 +1,7 @@
 /**
- * @description Test class for {ClassUnderTest}.
- *              Tests bulk operations (251+ records), positive/negative paths,
- *              and exception handling.
+ * Test class for {ClassUnderTest}.
+ * Tests bulk operations (251+ records), positive/negative paths,
+ * and exception handling.
  */
 @isTest
 private class {ClassUnderTest}Test {

package/skills/generating-apex-test/references/assertion-patterns.md

@@ -26,7 +26,7 @@ Assert.isTrue(accounts.size() > 0); // vague — use areEqual with exact count
 ### Good: Descriptive message, tests specific behavior
 
 ```apex
-Assert.areEqual(true, result, 'Service should return true for valid input');
+Assert.isTrue(result, 'Service should return true for valid input');
 Assert.areEqual(200, accounts.size(), 'All 200 accounts should be processed');
 ```
 

package/skills/generating-apex-test/references/async-testing.md

@@ -140,7 +140,7 @@ static void shouldExecuteFutureMethod() {
     Test.stopTest();
 
     Account updated = [SELECT Id, Processed__c FROM Account WHERE Id = :acc.Id];
-    Assert.areEqual(true, updated.Processed__c, 'Future should process record');
+    Assert.isTrue(updated.Processed__c, 'Future should process record');
 }
 ```
 

package/skills/uplifting-components-to-slds2/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: uplifting-components-to-slds2
+description: Migrate Lightning Web Components from SLDS 1 to SLDS 2 by running the SLDS linter and fixing violations. Use this skill whenever users mention SLDS 2, SLDS uplift, linter violations, LWC token migration, class overrides, hardcoded CSS values that need SLDS hook replacement, or styling hook selection. Covers all styling hook categories — color, spacing, sizing, typography, borders, radius, and shadows. Also use when users mention no-hardcoded-values, no-slds-class-overrides, lwc-to-slds-hooks, no-deprecated-tokens-slds1, or ask about SLDS component migration — even if they don't explicitly say "uplift" or "migration".
+---
+
+# Goal
+
+Systematically migrate Lightning Web Components from SLDS 1 to SLDS 2 using the SLDS linter and structured guidance for fixing violations across all styling hook categories.
+
+## SLDS 2 Styling Hook Categories
+
+| Category | Hook Prefix | What It Replaces |
+|---|---|---|
+| Color | `--slds-g-color-*` | Hardcoded colors, `--lwc-color*` tokens |
+| Spacing | `--slds-g-spacing-*` | Hardcoded margins, padding, gaps |
+| Sizing | `--slds-g-sizing-*` | Hardcoded widths, heights, dimensions |
+| Typography | `--slds-g-font-*` | Hardcoded font sizes, weights, line heights |
+| Border/Radius | `--slds-g-radius-border-*`, `--slds-g-sizing-border-*` | Hardcoded border-radius, border-width |
+| Shadow | `--slds-g-shadow-*` | Hardcoded box-shadow values |
+
+Color hooks require the most judgment (context-dependent selection). Non-color hooks are mostly numbered scales with straightforward mappings.
+
+## Prerequisites
+
+- Node.js 14.x or higher installed
+- Access to component CSS and markup files (`.html` for LWC, `.cmp` for Aura)
+- Terminal/command line access to run linter
+- Git repository for backup (recommended)
+
+---
+
+# Workflow
+
+```
+1. Run SLDS linter with auto-fix -> Handles simple violations automatically
+2. Review linter output -> Identify remaining manual fixes needed
+3. Fix by violation type -> Use per-rule reference guides
+4. Choose the right hook -> Context-first, inspect HTML before deciding
+5. Validate -> Re-run linter and confirm zero errors
+```
+
+## Step 1: Run SLDS Linter
+
+```bash
+npx @salesforce-ux/slds-linter@latest lint --fix .
+```
+
+The linter analyzes all CSS and markup files (`.html` for LWC, `.cmp` for Aura), auto-fixes simple violations, and reports remaining issues requiring manual intervention.
+
+## Step 2: Analyze Linter Output
+
+The linter reports violations in this format:
+
+```
+componentName.css
+  15:3  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
+
+  23:5  error    The '--lwc-colorBackground' design token is deprecated. Replace it with
+                 the SLDS 2 styling hook and set the fallback to '--lwc-colorBackground'.
+                 1. --slds-g-color-surface-2
+                 2. --slds-g-color-surface-container-2                      slds/lwc-token-to-slds-hook
+
+  30:8  warning  Consider replacing the #ffffff static value with an SLDS 2 styling hook
+                 that has a similar value:
+                 1. --slds-g-color-surface-1
+                 2. --slds-g-color-surface-container-1
+                 3. --slds-g-color-on-accent-1
+                 4. --slds-g-color-on-accent-2
+                 5. --slds-g-color-on-accent-3                              slds/no-hardcoded-values-slds2
+
+  31:15  error   Consider removing t(fontSizeMedium) or replacing it with
+                 var(--slds-g-font-size-base, var(--lwc-fontSizeMedium, 0.8125rem)).
+                 Set the fallback to t(fontSizeMedium). For more info, see
+                 Styling Hooks on lightningdesignsystem.com.               slds/no-deprecated-tokens-slds1
+```
+
+Four violation types, each with its own fix approach (see Step 3).
+
+**Important:** The linter flags all hardcoded values. Fix color, spacing, sizing, typography, border, and shadow values — but **skip layout values** (`100%`, `auto`, `0`, `inherit`, `none`). See [rule-no-hardcoded-values.md](references/rule-no-hardcoded-values.md) for the full fix-vs-skip triage table.
+
+## Step 3: Fix Violations by Type
+
+Each rule has a dedicated reference guide with full examples and decision logic:
+
+| Violation Rule | Quick Summary | Reference |
+|---|---|---|
+| `slds/no-hardcoded-values-slds2` | Replace hardcoded values with SLDS hook + original as fallback | [rule-no-hardcoded-values.md](references/rule-no-hardcoded-values.md)|
+| `slds/lwc-token-to-slds-hook` | Replace `--lwc-*` tokens with SLDS 2 hook, keep LWC token as fallback | [rule-lwc-token-to-slds-hook.md](references/rule-lwc-token-to-slds-hook.md) |
+| `slds/no-slds-class-overrides` | Create component-prefixed class, add to markup alongside SLDS class | [rule-no-slds-class-overrides.md](references/rule-no-slds-class-overrides.md) |
+| `slds/no-deprecated-tokens-slds1` | Replace legacy `t()`/`token()` syntax with SLDS 2 hook + LWC fallback | [rule-no-deprecated-tokens-slds1.md](references/rule-no-deprecated-tokens-slds1.md) |
+
+**Always include fallback values** — `var(--slds-g-hook, originalValue)` where `originalValue` is the exact original from the source CSS.
+
+### Class Override Quick Reference
+
+Class overrides require changes to **both CSS and markup** (`.html` or `.cmp`). This is the most commonly missed step:
+
+1. **CSS:** Rename `.slds-*` selector → `{componentName}-{sldsElementPart}` (camelCase)
+2. **Markup:** Add the new class **alongside** the SLDS class — never remove the SLDS class
+
+```css
+/* Before */ .slds-button { border-radius: 8px; }
+/* After */  .myComponent-button { border-radius: 8px; }
+```
+```html
+<!-- Markup: both classes --> <button class="slds-button myComponent-button">Click</button>
+```
+
+See [rule-no-slds-class-overrides.md](references/rule-no-slds-class-overrides.md) for descendant selectors, multi-class selectors, and naming conventions.
+
+## Step 4: Choose the Right Hook
+
+**Color hooks** require context-based selection — inspect the HTML to determine the element's role before choosing a hook family. See **[color-hooks-decision-guide.md](references/color-hooks-decision-guide.md)** for decision trees, all 5 hook families, and background-foreground pairing rules.
+
+**Non-color hooks** are simpler — match the CSS value to the numbered scale. See **[non-color-hooks-decision-guide.md](references/non-color-hooks-decision-guide.md)** for value-to-hook lookup tables covering spacing, sizing, typography, borders, radius, and shadows.
+
+## Step 5: Validate and Verify
+
+**Linter feedback loop — repeat until zero errors:**
+
+```
+1. npx @salesforce-ux/slds-linter@latest lint .
+2. Review errors -> fix by type (Step 3)
+3. Re-run linter
+4. Repeat until output shows: 0 errors
+```
+
+---
+
+# Validation
+
+- [ ] No `.slds-*` classes in CSS selectors
+- [ ] No `var(--lwc-*)` tokens without SLDS 2 replacements
+- [ ] All hooks include fallback values
+- [ ] Background/foreground color hooks from same family
+- [ ] Original SLDS classes preserved in HTML
+- [ ] Spacing uses numbered hooks (not named like `spacing-medium`)
+- [ ] Typography uses numbered hooks (not named like `font-weight-bold`)
+- [ ] Component renders correctly in light/dark mode and density settings
+
+See **[migration-checklist.md](references/migration-checklist.md)** for the full validation checklist.
+
+---
+
+# Output
+
+Return the fully migrated CSS (and updated HTML markup where class overrides were fixed) with zero SLDS linter violations. All styling hooks must include fallback values preserving the original CSS values.
+
+---
+
+# Advanced Patterns
+
+## Color-Mix for Transparency
+
+When a hardcoded value uses `rgba()` or transparency, use `color-mix()` with the SLDS hook to preserve opacity:
+
+```css
+/* Before */
+border-color: rgba(186, 5, 23, 0.7);
+
+/* After — use oklab color space for perceptual consistency */
+border-color: color-mix(in oklab, var(--slds-g-color-palette-red-40, rgb(181,54,45)), transparent 30%);
+```
+
+**Formula:** To achieve X% opacity, use `(100 - X)%` transparent in `color-mix`.
+- 70% opacity → `transparent 30%`
+- 50% opacity → `transparent 50%`
+
+Use opaque `rgb()` as fallback (not `rgba()`) — `color-mix` handles the transparency.
+
+## calc() Expressions with Tokens
+
+When migrating `t('calc(...)')` or `calc()` with deprecated tokens:
+
+```css
+/* Before — Aura t() with calc */
+height: t('calc(' + lineHeightButton + ' + 2px)');
+
+/* After — if calc is still needed */
+height: calc(var(--lwc-lineHeightButton) + 2px);
+
+/* After — if calc was unnecessary, simplify */
+height: var(--lwc-lineHeightButton);
+```
+
+For `calc()` with `--lwc-*` tokens being replaced:
+
+```css
+/* Before */
+padding: calc(var(--lwc-spacingMedium) + 4px);
+
+/* After */
+padding: calc(var(--slds-g-spacing-4, var(--lwc-spacingMedium)) + 4px);
+```
+
+**Tip:** Often the `calc()` is unnecessary and can be simplified. Check if the result matches an existing hook value.
+
+---
+
+# Key Constraints
+
+- **Never invent hook names** — only use hooks documented in the SLDS design system
+- **Always include fallback values** — the fallback must be the exact original value from the source CSS
+- **Never change hardcoded numerical values** — values like `100%`, `50%`, `200px`, `1.5`, `auto`, `0`, `inherit`, `none`, `flex: 1` are structural/layout values. Do not replace them with hooks and do not remove them — they are not styling hook candidates
+- **No exact match? Leave as-is** — if a hardcoded value doesn't closely correspond to any hook's rendered value, leave it unchanged rather than force-fitting
+- **Match hook number to original value intensity** — don't default to `-1`. Pick the variant closest to the original. See [color-hooks-decision-guide.md](references/color-hooks-decision-guide.md)
+- **Only numbered scales** — named hooks like `spacing-medium`, `font-weight-bold`, `radius-large` do NOT exist
+
+# Troubleshooting
+
+| Issue | Solution |
+|---|---|
+| Linter suggests 2+ color hook options | Inspect HTML context to determine element's semantic role — see color-hooks-decision-guide.md |
+| Visual appearance changed after migration | Verify fallback values match originals; check surface vs container family |
+| No hook available for hardcoded value | Leave unchanged; do not invent custom hook names |
+| Linter says "Remove the static value" for `100%`, `auto`, etc. | Leave unchanged — these are layout values. Removing them breaks rendering. |
+| CSS class naming errors | Use exact camelCase component name: `myComponent-button`, not `MyComponent-button` |
+| Spacing/sizing doesn't match | Check value-to-hook mapping in non-color-hooks-decision-guide.md; verify spacing vs sizing usage |
+| Named hook not working (e.g., `spacing-medium`) | Named hooks don't exist — use numbered scale: `spacing-4` for 16px, `font-weight-7` for inline bold emphasis (not headings) |
+| Component looks different in compact density | Use density-aware hooks (`--slds-g-spacing-var-*`) for components that adapt to density |
+
+---
+
+# References
+
+- **[Color Hooks Decision Guide](references/color-hooks-decision-guide.md)** — All 5 color hook families, decision trees, background-foreground pairing, palette accessibility
+- **[Non-Color Hooks Decision Guide](references/non-color-hooks-decision-guide.md)** — Spacing, sizing, typography, borders, radius, and shadow hooks with lookup tables
+- **[Rule: No Hardcoded Values](references/rule-no-hardcoded-values.md)** — Linter behavior, fix-vs-skip triage, replacement pattern, utility class workflow
+- **[Rule: LWC Token to SLDS Hook](references/rule-lwc-token-to-slds-hook.md)** — Deprecated `--lwc-*` token replacement patterns
+- **[Rule: No Deprecated Tokens SLDS1](references/rule-no-deprecated-tokens-slds1.md)** — Legacy `t()`/`token()` Aura syntax replacement patterns
+- **[Rule: No SLDS Class Overrides](references/rule-no-slds-class-overrides.md)** — Class renaming and HTML updates
+- **[Migration Examples](references/examples.md)** — Before/after examples by scenario and complexity
+- **[Common Patterns](references/common-patterns.md)** — Classes never to override, deprecated SLDS 2 classes, palette fallbacks, tokens with no SLDS 2 equivalent
+- **[Migration Checklist](references/migration-checklist.md)** — Full validation checklist