@salesforce/afv-skills 1.5.1 → 1.5.3

package/skills/generating-ui-bundle-metadata/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: generating-ui-bundle-metadata
+description: "Scaffold new Salesforce UI bundles and configure their metadata — sf ui-bundle generate, UIBundle bundles (meta XML, ui-bundle.json with routing/headers/outputDir), and CSP Trusted Sites for external domains. Use whenever creating a new UI bundle, setting up UI bundle metadata structure, configuring routing or headers, setting outputDir, adding external domains that need CSP registration, or editing bundle configuration. Triggers on: create UI bundle, create ui-bundle, new app, sf ui-bundle generate, metadata, ui-bundle.json, CSP, trusted site, bundle configuration, meta XML, routing config, external domain, headers config, outputDir."
+---
+
+# UI Bundle Metadata
+
+## Scaffolding a New UI Bundle
+
+Use `sf ui-bundle generate` to create new apps — not create-react-app, Vite, or other generic scaffolds.
+
+**UI bundle name (`-n`):** Alphanumerical only — no spaces, hyphens, underscores, or special characters. Example: `CoffeeBoutique` (not `Coffee Boutique`).
+
+After generation:
+1. Replace all default boilerplate — "React App", "Vite + React", default `<title>`, placeholder text
+2. Populate the home page with real content (landing section, banners, hero, navigation)
+3. Update navigation and placeholders (see the `building-ui-bundle-frontend` skill)
+
+Always install dependencies before running any scripts in the UI bundle directory.
+
+---
+
+## UIBundle Bundle
+
+A UIBundle bundle lives under `uiBundles/<AppName>/` and must contain:
+
+- `<AppName>.uibundle-meta.xml` — filename must exactly match the folder name
+- A build output directory (default: `dist/`) with at least one file
+
+### Meta XML
+
+Required fields: `masterLabel`, `version` (max 20 chars), `isActive` (boolean).
+Optional: `description` (max 255 chars).
+
+### ui-bundle.json
+
+Optional file. Allowed top-level keys: `outputDir`, `routing`, `headers`.
+
+**Constraints:**
+- Valid UTF-8 JSON, max 100 KB
+- Root must be a non-empty object (never `{}`, arrays, or primitives)
+
+**Path safety** (applies to `outputDir` and `routing.fallback`): Reject backslashes, leading `/` or `\`, `..` segments, null/control characters, globs (`*`, `?`, `**`), and `%`. All resolved paths must stay within the bundle.
+
+#### outputDir
+Non-empty string referencing a subdirectory (not `.` or `./`). Directory must exist and contain at least one file.
+
+#### routing
+If present, must be a non-empty object. Allowed keys: `rewrites`, `redirects`, `fallback`, `trailingSlash`, `fileBasedRouting`.
+
+- **trailingSlash**: `"always"`, `"never"`, or `"auto"`
+- **fileBasedRouting**: boolean
+- **fallback**: non-empty string satisfying path safety; target file must exist
+- **rewrites**: non-empty array of `{ route?, rewrite }` objects — e.g., `{ "route": "/app/:path*", "rewrite": "/index.html" }`
+- **redirects**: non-empty array of `{ route?, redirect, statusCode? }` objects — statusCode must be 301, 302, 307, or 308
+
+#### headers
+Non-empty array of `{ source, headers: [{ key, value }] }` objects.
+
+**Example:**
+```json
+{
+  "routing": {
+    "rewrites": [{ "route": "/app/:path*", "rewrite": "/index.html" }],
+    "trailingSlash": "never"
+  },
+  "headers": [
+    {
+      "source": "/assets/**",
+      "headers": [{ "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }]
+    }
+  ]
+}
+```
+
+**Never suggest:** `{}` as root, empty `"routing": {}`, empty arrays, `[{}]`, `"outputDir": "."`, `"outputDir": "./"`.
+
+---
+
+## CSP Trusted Sites
+
+Salesforce enforces Content Security Policy headers. Any external domain not registered as a CSP Trusted Site will be blocked (images won't load, API calls fail, fonts missing).
+
+### When to Create
+
+Whenever the app references a new external domain: CDN images, external fonts, third-party APIs, map tiles, iframes, external stylesheets.
+
+### Steps
+
+1. **Identify external domains** — extract the origin (scheme + host) from each external URL in the code
+2. **Check existing registrations** — look in `force-app/main/default/cspTrustedSites/`
+3. **Map resource type to CSP directive:**
+
+| Resource Type | Directive Field |
+|--------------|----------------|
+| Images | `isApplicableToImgSrc` |
+| API calls (fetch, XHR) | `isApplicableToConnectSrc` |
+| Fonts | `isApplicableToFontSrc` |
+| Stylesheets | `isApplicableToStyleSrc` |
+| Video / audio | `isApplicableToMediaSrc` |
+| Iframes | `isApplicableToFrameSrc` |
+
+Always also set `isApplicableToConnectSrc` to `true` for preflight/redirect handling.
+
+4. **Create the metadata file** — follow `implementation/csp-metadata-format.md` for the `.cspTrustedSite-meta.xml` format. Place in `force-app/main/default/cspTrustedSites/`.
+

package/skills/{managing-webapp-agentforce-conversation-client → implementing-ui-bundle-agentforce-conversation-client}/SKILL.md

@@ -1,10 +1,10 @@
 ---
-name: managing-webapp-agentforce-conversation-client
+name: implementing-ui-bundle-agentforce-conversation-client
 description: "Adds or modifies AgentforceConversationClient in React apps (.tsx or .jsx files). Use when user says \"add chat widget\", \"embed agentforce\", \"add agent\", \"add chatbot\", \"integrate conversational AI\", or asks to change colors, dimensions, styling, or configure agentId, width, height, inline mode, or styleTokens for travel agent, HR agent, employee agent, or any Salesforce agent chat."
 metadata:
   author: ACC Components
   version: 1.0.0
-  package: "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental"
+  package: "@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client"
   sdk-package: "@salesforce/agentforce-conversation-client"
   last-updated: 2025-03-18
 ---
@@ -58,13 +58,13 @@ Skip this step if:
 Use this import path by default in app code:
 
 ```tsx
-import { AgentforceConversationClient } from "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental";
+import { AgentforceConversationClient } from "@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client";
 ```
 
 If the package is not installed, install it:
 
 ```bash
-npm install @salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental
+npm install @salesforce/ui-bundle-template-feature-react-agentforce-conversation-client
 ```
 
 Only use a local relative import (for example, `./components/AgentforceConversationClient`) when the user explicitly asks to use a patched/local component in that app.
@@ -79,7 +79,7 @@ Add to the target React component file using the canonical package import:
 
 ```tsx
 import { Outlet } from "react-router";
-import { AgentforceConversationClient } from "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental";
+import { AgentforceConversationClient } from "@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client";
 
 export default function AgentChatHost() {
   return (

package/skills/{managing-webapp-agentforce-conversation-client → implementing-ui-bundle-agentforce-conversation-client}/references/constraints.md

@@ -8,7 +8,7 @@ This document lists all invalid approaches and patterns to avoid when working wi
 
 - ✅ **DO edit**: Any React files that import and use `<AgentforceConversationClient />` (for example, shared shells, route components, or feature pages)
 - ❌ **DO NOT edit**: AgentforceConversationClient.tsx, AgentforceConversationClient.jsx, index.tsx, index.jsx, or any files inside:
-  - `node_modules/@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental/src/`
+  - `node_modules/@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client/src/`
   - `packages/template/feature/feature-react-agentforce-conversation-client/src/`
   - `src/components/AgentforceConversationClient.tsx` (patched templates)
   - Any path containing `/components/AgentforceConversationClient.`
@@ -127,7 +127,7 @@ import "./agent-styles.css";
 
 ### ❌ Wrong - Editing implementation file
 
-Reading or editing: `node_modules/@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental/src/AgentforceConversationClient.tsx`
+Reading or editing: `node_modules/@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client/src/AgentforceConversationClient.tsx`
 
 ### ✅ Correct - Editing usage file
 

package/skills/{managing-webapp-agentforce-conversation-client → implementing-ui-bundle-agentforce-conversation-client}/references/examples.md

@@ -109,7 +109,7 @@ export default function SupportPage() {
 
 ```tsx
 import { Outlet } from "react-router";
-import { AgentforceConversationClient } from "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental";
+import { AgentforceConversationClient } from "@salesforce/ui-bundle-template-feature-react-agentforce-conversation-client";
 
 export default function AgentChatHost() {
   return (

package/skills/{implementing-webapp-file-upload → implementing-ui-bundle-file-upload}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: implementing-webapp-file-upload
-description: "Add file upload functionality to React webapps with progress tracking and Salesforce ContentVersion integration. Use when the user wants to upload files, attach documents, handle file input, create file dropzones, track upload progress, or link files to Salesforce records. This feature provides programmatic APIs ONLY — no components or hooks are exported. Build your own custom UI using the upload() API. ALWAYS use this feature instead of building file upload from scratch with FormData or XHR."
+name: implementing-ui-bundle-file-upload
+description: "Add file upload functionality to React UI bundles with progress tracking and Salesforce ContentVersion integration. Use when the user wants to upload files, attach documents, handle file input, create file dropzones, track upload progress, or link files to Salesforce records. This feature provides programmatic APIs ONLY — no components or hooks are exported. Build your own custom UI using the upload() API. ALWAYS use this feature instead of building file upload from scratch with FormData or XHR."
 ---
 
 # File Upload API (workflow)
 
-When the user wants file upload functionality in a React webapp, follow this workflow. This feature provides **APIs only** — you must build the UI components yourself using the provided APIs.
+When the user wants file upload functionality in a React UI bundle, follow this workflow. This feature provides **APIs only** — you must build the UI components yourself using the provided APIs.
 
 ## CRITICAL: This is an API-only package
 
@@ -26,12 +26,12 @@ The source code contains reference components for demonstration, but they are **
 ## 1. Install the package
 
 ```bash
-npm install @salesforce/webapp-template-feature-react-file-upload-experimental
+npm install @salesforce/ui-bundle-template-feature-react-file-upload
 ```
 
 Dependencies are automatically installed:
 
-- `@salesforce/webapp-experimental` (API client)
+- `@salesforce/ui-bundle` (API client)
 - `@salesforce/sdk-data` (data SDK)
 
 ## 2. Understand the three upload patterns
@@ -47,7 +47,7 @@ Upload files to Salesforce and get back `contentBodyId` for each file. No Conten
 - Deferred record linking scenarios
 
 ```tsx
-import { upload } from "@salesforce/webapp-template-feature-react-file-upload-experimental";
+import { upload } from "@salesforce/ui-bundle-template-feature-react-file-upload";
 
 const results = await upload({
   files: [file1, file2],
@@ -71,7 +71,7 @@ Upload files and immediately link them to an existing Salesforce record by creat
 - Direct upload-and-attach scenarios
 
 ```tsx
-import { upload } from "@salesforce/webapp-template-feature-react-file-upload-experimental";
+import { upload } from "@salesforce/ui-bundle-template-feature-react-file-upload";
 
 const results = await upload({
   files: [file1, file2],
@@ -99,7 +99,7 @@ Upload files without a record, then link them after the record is created.
 import {
   upload,
   createContentVersion,
-} from "@salesforce/webapp-template-feature-react-file-upload-experimental";
+} from "@salesforce/ui-bundle-template-feature-react-file-upload";
 
 // Step 1: Upload files (no recordId)
 const uploadResults = await upload({
@@ -128,7 +128,7 @@ The package provides the backend — you build the frontend. Here's a minimal ex
 import {
   upload,
   type FileUploadProgress,
-} from "@salesforce/webapp-template-feature-react-file-upload-experimental";
+} from "@salesforce/ui-bundle-template-feature-react-file-upload";
 import { useState } from "react";
 
 function CustomFileUpload({ recordId }: { recordId?: string }) {
@@ -212,7 +212,7 @@ If the user wants to upload files to their own profile or personal library:
 import {
   upload,
   getCurrentUserId,
-} from "@salesforce/webapp-template-feature-react-file-upload-experimental";
+} from "@salesforce/ui-bundle-template-feature-react-file-upload";
 
 const userId = await getCurrentUserId();
 await upload({ files, recordId: userId });
@@ -366,7 +366,7 @@ The package includes a reference implementation in `src/features/fileupload/` wi
 
 **Upload fails with CORS error:**
 
-- Ensure the webapp is properly deployed to Salesforce or running on `localhost`
+- Ensure the UI bundle is properly deployed to Salesforce or running on `localhost`
 - Check that the org allows the origin in CORS settings
 
 **No progress updates:**

package/skills/searching-media/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: searching-media
-description: "Searches for and retrieves existing visual media (images, logos, icons, photos, graphics, banners, thumbnails, hero images, backgrounds) from any source. Use this skill ANY TIME a user request involves finding, searching, getting, fetching, retrieving, grabbing, looking up, or locating media. Takes PRIORITY and activates FIRST when ANY media search/retrieval is mentioned, regardless of what else happens with the media afterward. Triggers for requests like \"search for logo\", \"find hero image\", \"get company logo\", \"locate icons\", \"fetch background image\", \"retrieve product photos\". Handles the search and source selection workflow. Does not apply when the request is to generate NEW images with AI, design custom graphics from scratch, or edit existing images."
+description: "Searches for and retrieves existing visual media (images, logos, icons, photos, graphics, banners, thumbnails, hero images, backgrounds) from sources such as Salesforce CMS, Data 360 or any other source. Use this skill ANY TIME a user request involves finding, searching, getting, fetching, retrieving, grabbing, looking up, or locating media. Takes PRIORITY and activates FIRST when ANY media search/retrieval is mentioned, regardless of what else happens with the media afterward. Triggers for requests like \"search for logo\", \"find hero image\", \"get company logo\", \"locate icons\", \"fetch background image\", \"retrieve product photos\". Handles the search and source selection workflow. Does not apply when the request is about brand search, to generate NEW images with AI, design custom graphics from scratch, or edit existing images."
 compatibility: "Requires search_media_cms_channels and/or search_electronic_media MCP tools"
 metadata:
   version: "1.0"

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