design-systems-slds-validate
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 scorecard", "SLDS quality report", "audit SLDS compliance", "how good is my SLDS", "check SLDS quality", "rate my SLDS styling", "evaluate my component's SLDS", "is this component's SLDS ready to ship?", "look at my LWC for SLDS issues", "audit SLDS before I submit", "review my component's SLDS before code review", or any time a user wants an SLDS quality assessment or SLDS production-readiness check on an LWC. Not for fixing violations (use design-systems-slds2-migrate), building new components (use design-systems-slds-apply), or accessibility/WCAG/ARIA audits (use experience-accessibility-validate).
- Installs
- 5.9K
- Last 24h
- +19
- Trending rank
- #6163
- Security
- Pass
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/forcedotcom/sf-skills --skill design-systems-slds-validate- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads design-systems-slds-validate automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
Security audits
Independent scans of the skill's instructions and bundled files.
SKILL.md
The instructions your agent reads when the skill is triggered.
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-migrateinstead - Building new components — use
design-systems-slds-applyinstead - 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.jsfiles — 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-1in.classAandon-accent-1in.classBwould 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
Category Score = 100 - (critical_issues × 10) - (warnings × 3) - (info × 1)
Minimum score: 0
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
Overall = (Linter × 0.30) + (Theming × 0.20) + (Accessibility × 0.20)
+ (CodeQuality × 0.15) + (ComponentUsage × 0.15)
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 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, orBlocking) - 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:
- Run linter:
npx @salesforce-ux/slds-linter@latest lint <path> - Count violations by type
- Report summary only
Quick Quality Check: <component-name>
─────────────────────────────────────
Linter Violations:
• Class Override: 0
• Deprecated Tokens: 3
• Hardcoded Values: 5
Quick Automated Grade: C (estimated)
Run full validation for detailed report.
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 - Complete list of all quality checks with detection patterns
- Report Format - Quality report template and formatting guide
- Analyze Script - 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
FAQ
What does the design-systems-slds-validate skill do?
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 scorecard", "SLDS quality report", "audit SLDS compliance", "how good is my SLDS", "check SLDS quality", "rate my SLDS styling", "evaluate my component's SLDS", "is this component's SLDS ready to ship?", "look at my LWC for SLDS issues", "audit SLDS before I submit", "review my component's SLDS before code review", or any time a user wants an SLDS quality assessment or SLDS production-readiness check on an LWC. Not for fixing violations (use design-systems-slds2-migrate), building new components (use design-systems-slds-apply), or accessibility/WCAG/ARIA audits (use experience-accessibility-validate).
How do I install design-systems-slds-validate?
Run npx skills add https://github.com/forcedotcom/sf-skills --skill design-systems-slds-validate in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/design-systems-slds-validate/ (personal) or .claude/skills/design-systems-slds-validate/ (project).
Which AI agents can use design-systems-slds-validate?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is design-systems-slds-validate safe to install?
Security partners have reviewed it: Gen Agent Trust Hub passed; Socket passed; Snyk passed. As with any skill, read the SKILL.md and bundled scripts before installing.
Who maintains design-systems-slds-validate?
It is published by forcedotcom in forcedotcom/sf-skills. It has 5,887 recorded installs.
More from forcedotcom/sf-skills
platform-apex-generate
forcedotcom/sf-skills
Primary Apex authoring skill for class generation, refactoring, and review. ALWAYS ACTIVATE when the user mentions Apex, .cls, triggers, or asks to create/refactor a class (service, selector, domain, batch, queueable, schedulable, invocable, DTO, utility, interface, abstract, exception, REST resource). Use this skill for requests involving SObject CRUD, mapping collections, fetching related records, scheduled jobs, batch jobs, trigger design, @AuraEnabled controllers, @RestResource endpoints, custom REST APIs, or code review of existing Apex.
platform-apex-test-generate
forcedotcom/sf-skills
Use to generate and validate Apex test classes with TestDataFactory patterns, bulk testing (251+ records), mocking, assertions, and disciplined test-fix loops. Use when creating Apex test classes (for triggers, services, controllers, batch jobs, queueables, and callouts), improving coverage, debugging or fixing failing Apex tests, or running test/coverage analysis. Triggers on Test.cls files, sf apex run test, coverage reports. Do NOT trigger for production Apex (use platform-apex-generate) or Jest/LWC tests.
platform-apex-test-run
forcedotcom/sf-skills
Apex test execution, coverage analysis, and test-fix loops with 120-point scoring. Use when the user runs Apex tests, checks code coverage, fixes failing tests, or touches Test.cls / Test.cls files. DO NOT TRIGGER when writing Apex production code (use platform-apex-generate), Agentforce agent testing (use agentforce-test), or Jest/LWC tests (use experience-lwc-generate).
platform-apex-logs-debug
forcedotcom/sf-skills
Salesforce debug log analysis and troubleshooting with 100-point scoring. TRIGGER when: user analyzes debug logs, hits governor limits, reads stack traces, or touches .log files from Salesforce orgs. DO NOT TRIGGER when: running Apex tests (use platform-apex-test-run), generating or fixing Apex code (use platform-apex-generate), or Agentforce session tracing (use agentforce-observe).
platform-soql-query
forcedotcom/sf-skills
Use when the user needs SOQL/SOSL authoring or optimization: natural-language-to-query generation, relationship queries, aggregates, query-plan/selectivity analysis, and performance or safety improvements. TRIGGER when the user writes, optimizes, or debugs SOQL/SOSL, touches .soql files, or asks about relationship queries, aggregates, or query performance. DO NOT TRIGGER for bulk data operations (use platform-data-manage), Apex DML logic (use platform-apex-generate), or report/dashboard queries.
platform-metadata-deploy
forcedotcom/sf-skills
Salesforce DevOps automation using sf CLI v2. TRIGGER when: user deploys metadata, validates a deploy or does a dry-run, deploys to a Production org, quick-deploys a validated job ID, ships/promotes to prod, creates/manages scratch orgs or sandboxes, sets up CI/CD pipelines, or troubleshoots deployment errors with sf project deploy. DO NOT TRIGGER when: writing Apex code, building LWC components (use experience-lwc-generate), creating metadata definitions (use platform-custom-object-generate), deleting metadata from an org (use platform-destructive-deploy), or querying org data (use platform-data-manage).
Popular frontend & design skills
setup-matt-pocock-skills
mattpocock/skills
Configure this repo for the engineering skills: set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.
frontend-design
anthropics/skills
Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.
hyperframes-animation
heygen-com/hyperframes
All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.
prototype
mattpocock/skills
Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.
hyperframes-core
heygen-com/hyperframes
The HyperFrames composition contract — build one renderable project. Use for composition structure, the data- timing attributes, class="clip", tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.
vercel-react-best-practices
vercel-labs/agent-skills
React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.