Audit Lightning Web Components for SLDS design-system compliance and produce a scored quality report. Runs the SLDS linter and analyzes CSS for theming hook usage and pairing, scoring SLDS findings across categories into an overall grade. Use when asked to "score my component's SLDS", "SLDS scorecar

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 Step 1: Run SLDS Linter Run the linter to collect baseline violation data: 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%: 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: 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: 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 found in metadata is flagged as critical — this catches the most common agent mistake of inventing hooks from naming patterns. Step 3: Agent Manual Review These checks require understanding the component's purpose and cannot be automated reliably. Review each and classify findings as either: Blocking — incorrect blueprint structure, missing required states, or semantic/interaction issues that make the component not production ready Advisory — worthwhile improvements that do not block shipping on their own Review Area What to Look For Loading states Does the component show a spinner or skeleton when fetching data? Error states Are errors surfaced to the user with actionable messages? Empty states Is there a meaningful empty state when no data exists? Disabled states Do interactive elements visually and functionally handle disabled? Semantic HTML Are <nav , <article , <section used where appropriate? SLDS blueprint compliance Do cards, modals, forms follow SLDS blueprint structure? Manual review findings are not automated, but they do affect the final recommendation. Do not report an automated grade as the only verdict. Step 4: Calculate Automated Scores and Final Recommendation Component Complexity Before scoring, classify the component to give the score context: Complexity Criteria Report Note Small 1 2 files, < 100 total lines Score is high confidence (small surface area) Medium 3 6 files, 100 500 total lines Score reflects typical component Large 7+ files, 500+ total lines Score reflects absolute issue count — even well built large components may score lower Include the complexity classification in the report header. This prevents misreading a "B" on a 1000 line component vs. a "B" on a 20 line component. Automated Scoring Formula Categories and Weights Category Weight Source Linter Compliance 30% SLDS linter output (Step 1) Theming 20% Script: fallbacks, hook pairing (Step 2) Accessibility 20% Script: labels, alt text, focus (Step 2) Code Quality 15% Script: !important, inline styles, z index (Step 2) Component Usage 15% Script: native elements (Step 2) plus manual semantic/blueprint review (Step 3) Automated Overall Score Automated Grade Thresholds Score Grade Meaning 90 100 A Excellent automated score 80 89 B Good automated score 70 79 C Acceptable automated score 60 69 D Weak automated score 0 59 F Failing automated score Manual Review Gate After computing the automated score, apply the manual review outcome: Gate When to use it Effect on final recommendation Pass No manual findings Final recommendation can follow the automated score Advisory Only non blocking manual findings Final recommendation can be "Ready with follow ups" at best Blocking One or more blocking manual findings Final recommendation is not ready for production , regardless of automated grade Final Recommendation Rules Use both the automated score and the manual review gate: Final Recommendation Conditions Ready for production Automated grade A/B, no critical findings, manual gate = Pass Ready with follow ups Automated grade A/B, no critical findings, manual gate = Advisory Needs work Any critical findings, automated grade C/D, or manual gate = Blocking Failing Automated grade F Step 5: Generate Quality Report Use the template in [report format.md](references/report format.md) to produce the final report. Default to the compact format for initial output and expand sections on request. The report includes: Executive summary with automated grade and final recommendation Manual review gate outcome ( Pass , Advisory , or Blocking ) Scores by category with visual indicators Detailed findings organized by severity Specific code locations and recommendations Checklist of required actions Quick Validation Mode For a rapid quality check without full analysis: 1. Run linter: npx @salesforce ux/slds linter@latest lint <path 2. Count violations by type 3. Report summary only Edge Cases and False Positives Situation Guidance Headless components (JS only, no HTML) Skip HTML checks; score only CSS + linter categories Wrapper/container components May legitimately have minimal CSS; don't penalize low hook usage Intentional native elements <button inside custom SLDS blueprints is correct; suppress C002 if inside an slds blueprint structure Components outside LEX LWR/Experience Cloud components may not use Lightning Base Components; note context in report Test/demo components Lower the bar — note in report but don't block on warnings If a check produces a false positive, note it in the report as "suppressed" with justification rather than silently dropping it. References [Quality Checks](references/quality checks.md) Complete list of all quality checks with detection patterns [Report Format](references/report format.md) Quality report template and formatting guide [Analyze Script](scripts/analyze quality.cjs) Automated analysis for linter complementary checks design systems slds2 migrate skill How to fix linter violations design systems slds apply skill Guide for building new components with correct patterns

design-systems-slds-validate