/design-systems-slds-validate

name: design-systems-slds-validate
description: "Audit Lightning Web Components for SLDS compliance and produce a scored quality report. Runs the SLDS linter, analyzes CSS for theming hook usage and pairing, checks HTML for accessibility attributes, and scores findings across categories into an overall grade. Use when asked to \"score my component\", \"SLDS scorecard\", \"quality report\", \"audit SLDS compliance\", \"how good is my SLDS\", \"check component quality\", \"rate my component\", \"evaluate my component\", \"is this component ready to ship?\", \"look at my LWC for issues\", \"audit this before I submit\", \"review my component before code review\", or any time a user wants a quality assessment or production-readiness check on an LWC or SLDS component. Not for fixing violations (use design-systems-slds2-migrate) or building new components (use design-systems-slds-apply)."
metadata:
  cliTools:
    - tool: ["node"]
      semver: ">=18.0.0"
    - tool: ["npx"]
      semver: ">=7.0.0"
  relatedSkills:
    - "design-systems-slds-apply"
    - "design-systems-slds2-migrate"
  version: "1.0"

SLDS Quality Audit

Audit Lightning Web Components for SLDS compliance and produce an automated scorecard plus a required manual review gate. Combines SLDS linter output with supplementary static analysis to catch what the linter misses.

Scope

Also valid for: auditing SLDS compliance across a project or component set, and before/after quality comparison after making changes.

Not for:

• **Fixing** linter violations — use `design-systems-slds2-migrate` instead
• **Building** new components — use `design-systems-slds-apply` instead
• **Just running the linter** — run `npx @salesforce-ux/slds-linter@latest lint .` directly
• **Full WCAG accessibility audit** — this skill checks attribute presence only (labels, alt text, focus indicators), not contrast ratios, keyboard flows, or screen reader behavior
• **Framework-specific template auditing** beyond `.css`, `.html`, and `.js` files — JSX/TSX/Vue/Svelte outputs need additional manual review

---

Quality Validation Process

1. Run SLDS Linter     → Collect violation counts (linter's job)
2. Run Analyze Script  → Check what linter doesn't cover (supplementary)
3. Agent Review        → Required manual review gate
4. Score & Grade       → Compute automated score + final recommendation
5. Generate Report     → Produce formatted scorecard

Step 1: Run SLDS Linter

Run the linter to collect baseline violation data:

npx @salesforce-ux/slds-linter@latest lint <component-path> 2>&1

Count violations by rule. These feed directly into the **Linter Compliance** score:

| Rule | Impact | |------|--------| | `slds/class-override` | Breaks theming, dark mode | | `slds/lwc-token-to-slds-hook` | SLDS 1 technical debt | | `slds/no-hardcoded-values` | Breaks theming, accessibility |

**Linter Compliance Score** = `100 - (total_violations × 10)`, minimum 0.

**If the linter is unavailable** (no Node.js, no network access, CI sandbox restrictions): skip this step, note "Linter not run" in the report header, mark Linter Compliance as N/A, and compute the Overall score using the remaining 4 categories renormalized to 100%:

Overall (linter unavailable) = (Theming × 0.29) + (Accessibility × 0.29)
                              + (CodeQuality × 0.21) + (ComponentUsage × 0.21)

Step 2: Run Supplementary Analysis

Run the analyze script to catch issues the linter doesn't cover. The bundled analyzer scans `.css`, `.html`, and `.js` files only:

node scripts/analyze-quality.cjs <component-path>

The script outputs JSON with findings organized by severity. It checks:

CSS Checks (linter-complementary)

| Check | What It Catches | Severity | |-------|----------------|----------| | Missing fallbacks | `var(--slds-g-*)` without a fallback value | Critical | | Invented hooks (T051) | `--slds-g-*` tokens not found in `hooks-index.json` (requires `--hooks-index`) | Critical | | Hook pairing | Background hooks without matching foreground hooks | Warning | | `!important` | Specificity overrides | Warning | | Magic pixel values | Hardcoded `px` not using spacing hooks | Warning | | High z-index | z-index values > 99 | Warning | | Outline removal | `outline: none` without alternative focus style | Warning |

JS Checks

| Check | What It Catches | Severity | |-------|----------------|----------| | Inline style assignment | `.style.*=` direct property assignment | Warning | | SLDS class manipulation | Dynamic `.classList.add('slds-*')` manipulation | Warning |

HTML Checks

| Check | What It Catches | Severity | |-------|----------------|----------| | LBC input labels | `<lightning-input>` without `label` attribute | Critical | | Icon alt text | `<lightning-icon>` without `alternative-text` | Critical | | Image alt text | `<img>` without `alt` | Critical | | Heading hierarchy | Skipped heading levels (h2 to h4) | Warning | | Positive tabindex | `tabindex` values other than 0 or -1 | Warning | | Clickable divs | `<div onclick>` instead of `<button>` | Warning | | Inline styles | `style="..."` attributes | Warning | | Native elements | `<input>`, `<button>`, `<select>` where LBC alternatives exist | Warning |

Hook Pairing Validation

The script checks that background/foreground hooks are semantically paired:

surface-* backgrounds     → on-surface-* text
surface-container-* bg    → on-surface-* text
accent-* backgrounds      → on-accent-* text
accent-container-* bg     → on-accent-* text

> **Limitation:** Hook pairing is checked at the file level, not per-selector. A file with `surface-1` in `.classA` and `on-accent-1` in `.classB` would pass because both surface and accent families are present. Review pairing correctness per-selector during manual review (Step 3).

Invented Hook Detection (T051)

The script cross-references every `--slds-g-*` token in CSS against `hooks-index.json`. Any hook not fou