forcedotcom/sf-skills / skills/design-systems-slds-validate
design-systems-slds-validate
VerifiedAudit 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).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.3 KB |
| references/quality-checks.md | markdown | 13.2 KB |
| references/report-format.md | markdown | 8.0 KB |
| scripts/analyze-quality.cjsexecutable | script | 15.6 KB |
scripts/analyze-quality.cjs
View on GitHub#!/usr/bin/env node
/**
* SLDS Quality Analyzer
*
* Analyzes CSS and HTML files for SLDS quality issues beyond what the linter catches.
*
* Usage: node analyze-quality.cjs <component-path> [--hooks-index <path>]
*
* Output: JSON with findings categorized by severity
*/
const fs = require('fs');
const path = require('path');
function resolveHooksIndexPath(args) {
const idx = args.indexOf('--hooks-index');
if (idx !== -1 && idx + 1 < args.length) {
return path.resolve(args[idx + 1]);
}
return null;
}
let HOOKS_INDEX_PATH = null;
// Severity levels
const CRITICAL = 'critical';
const WARNING = 'warning';
const INFO = 'info';
// Detection patterns
// NOTE: Checks that the SLDS linter already handles are excluded here to avoid
// double-counting. The linter covers: slds/class-override (L001),
// slds/lwc-token-to-slds-hook (L002), slds/no-hardcoded-values (L003).
// This script focuses on what the linter does NOT catch.
const PATTERNS = {
// CSS patterns (linter-complementary only)
css: {
missingFallback: {
pattern: /var\(--slds-g-[^,)]+\)/g,
severity: CRITICAL,
id: 'T002',
message: 'SLDS hook without fallback value',
recommendation: 'Add fallback: var(--slds-g-color-surface-1, #fff)'
},
important: {
pattern: /!important/g,
severity: WARNING,
id: 'Q001',
message: '!important declaration found',
recommendation: 'Remove !important, use proper specificity'
},
magicPixels: {
pattern: /\b(?:margin(?:-[a-z-]+)?|padding(?:-[a-z-]+)?|gap|row-gap|column-gap)\s*:\s*(\d+)px\b(?![^;]*var\()/g,
severity: WARNING,
id: 'T021',
message: 'Magic pixel value not using spacing hook',
recommendation: 'Use var(--slds-g-spacing-*) or utility class'
},
highZindex: {
pattern: /z-index\s*:\s*(\d{3,})/g,
severity: WARNING,
id: 'Q021',
message: 'High z-index value',
recommendation: 'Use defined z-index scale'
},
outlineNone: {
pattern: /outline\s*:\s*none/g,
severity: WARNING,
id: 'A021',
message: 'Focus outline removed without alternative',
recommendation: 'Provide alternative focus indicator'
}
},
// JS patterns (inline styles and dynamic class manipulation)
js: {
inlineStyleJS: {
pattern: /\.style\.\w+\s*=/g,
severity: WARNING,
id: 'Q025',
message: 'Inline style manipulation in JavaScript',
recommendation: 'Use CSS classes instead of direct style property assignment'
},
classListManipulation: {
pattern: /\.classList\.(add|remove|toggle)\(\s*['"]slds-/g,
severity: WARNING,
id: 'Q012',
message: 'Dynamic SLDS class manipulation in JavaScript',
recommendation: 'Prefer declarative class bindings; avoid manipulating slds-* classes directly'
}
},
// HTML patterns
html: {
inlineStyle: {
pattern: /style\s*=\s*["'][^"']+["']/gi,
severity: WARNING,
id: 'Q002',
message: 'Inline style attribute',
recommendation: 'Move styles to CSS file'
},
lightningInputNoLabel: {
pattern: /<lightning-input(?![^>]*\blabel\b)[^>]*>/gi,
severity: CRITICAL,
id: 'A001',
message: 'Lightning input without label attribute',
recommendation: 'Add label attribute to lightning-input'
},
iconNoAlt: {
pattern: /<lightning-icon(?![^>]*alternative-text)[^>]*>/gi,
severity: CRITICAL,
id: 'A004',
message: 'Icon without alternative-text',
recommendation: 'Add alternative-text (or empty string for decorative)'
},
imgNoAlt: {
pattern: /<img(?![^>]*\balt\b)[^>]*>/gi,
severity: CRITICAL,
id: 'A005',
message: 'Image without alt attribute',
recommendation: 'Add alt attribute'
},
positiveTabindex: {
pattern: /tabindex\s*=\s*["']([1-9]\d*)["']/gi,
severity: WARNING,
id: 'A020',
message: 'Positive tabindex value',
recommendation: 'Use tabindex="0" or "-1" only'
},
clickableDiv: {
pattern: /<div[^>]*onclick[^>]*>/gi,
severity: WARNING,
id: 'A022',
message: 'Div with click handler instead of button',
recommendation: 'Use <button> or <lightning-button> for interactive elements'
},
nativeInput: {
pattern: /<input\s/gi,
severity: WARNING,
id: 'C001',
message: 'Native input element',
recommendation: 'Consider <lightning-input> for built-in labeling and validation'
},
nativeButton: {
pattern: /<button\s(?![^>]*class\s*=\s*["'][^"']*slds-button)/gi,
severity: WARNING,
id: 'C002',
message: 'Native button element',
recommendation: 'Consider <lightning-button> for SLDS styling consistency (suppressed if slds-button class present)'
},
nativeSelect: {
pattern: /<select\s/gi,
severity: WARNING,
id: 'C004',
message: 'Native select element',
recommendation: 'Consider <lightning-combobox> for consistency'
}
}
};
/**
* Find all files with given extensions in directory
*/
function findFiles(dir, extensions) {
const files = [];
function walk(currentDir) {
try {
const items = fs.readdirSync(currentDir);
for (const item of items) {
const fullPath = path.join(currentDir, item);
const stat = fs.statSync(fullPath);
if (stat.isDirectory() && !item.startsWith('.') && item !== 'node_modules') {
walk(fullPath);
} else if (stat.isFile()) {
const ext = path.extname(item).toLowerCase();
if (extensions.includes(ext)) {
files.push(fullPath);
}
}
}
} catch (err) {
// Skip directories we can't read
}
}
walk(dir);
return files;
}
/**
* Analyze a single file
*/
function analyzeFile(filePath, patterns) {
const findings = [];
const content = fs.readFileSync(filePath, 'utf-8');
const lines = content.split('\n');
for (const [name, config] of Object.entries(patterns)) {
const regex = new RegExp(config.pattern.source, config.pattern.flags);
let match;
while ((match = regex.exec(content)) !== null) {
// Find line number
const beforeMatch = content.substring(0, match.index);
const lineNumber = beforeMatch.split('\n').length;
const lineContent = lines[lineNumber - 1] || '';
findings.push({
id: config.id,
severity: config.severity,
file: filePath,
line: lineNumber,
column: match.index - beforeMatch.lastIndexOf('\n'),
match: match[0].substring(0, 50),
message: config.message,
recommendation: config.recommendation,
context: lineContent.trim().substring(0, 80)
});
}
}
return findings;
}
/**
* Analyze heading hierarchy in HTML
*/
function analyzeHeadings(filePath) {
const findings = [];
const content = fs.readFileSync(filePath, 'utf-8');
const headingRegex = /<h([1-6])[^>]*>/gi;
const headings = [];
let match;
while ((match = headingRegex.exec(content)) !== null) {
headings.push({
level: parseInt(match[1]),
index: match.index
});
}
// Check for skipped levels
for (let i = 1; i < headings.length; i++) {
const prev = headings[i - 1].level;
const curr = headings[i].level;
if (curr > prev + 1) {
const beforeMatch = content.substring(0, headings[i].index);
const lineNumber = beforeMatch.split('\n').length;
findings.push({
id: 'A010',
severity: WARNING,
file: filePath,
line: lineNumber,
message: `Skipped heading level: h${prev} to h${curr}`,
recommendation: `Use h${prev + 1} instead of h${curr}`
});
}
}
return findings;
}
/**
* Load valid hook tokens from hooks-index.json
*/
let _validHooks = null;
function loadValidHooks() {
if (_validHooks) return _validHooks;
if (!HOOKS_INDEX_PATH) return null;
try {
const data = JSON.parse(fs.readFileSync(HOOKS_INDEX_PATH, 'utf-8'));
_validHooks = new Set(data.hooks.map(h => h.token));
} catch {
console.error(`WARNING: Could not load hooks-index.json at ${HOOKS_INDEX_PATH}`);
console.error('Invented-hook detection (T051) will be skipped.');
_validHooks = null;
}
return _validHooks;
}
/**
* Check for invented hooks (T051) — hooks referenced in CSS that don't exist in metadata
*/
function analyzeInventedHooks(filePath) {
const findings = [];
const validHooks = loadValidHooks();
if (!validHooks) return findings; // skip if metadata unavailable
const content = fs.readFileSync(filePath, 'utf-8');
const lines = content.split('\n');
const hookRef = /var\((--slds-g-[^,)]+)/g;
let match;
while ((match = hookRef.exec(content)) !== null) {
const hookName = match[1].trim();
if (!validHooks.has(hookName)) {
const beforeMatch = content.substring(0, match.index);
const lineNumber = beforeMatch.split('\n').length;
const lineContent = lines[lineNumber - 1] || '';
findings.push({
id: 'T051',
severity: CRITICAL,
file: filePath,
line: lineNumber,
match: hookName,
message: `Invented hook — "${hookName}" does not exist in hooks-index.json`,
recommendation: 'Verify the hook exists via: node scripts/search-hooks.cjs --prefix "' + hookName + '"',
context: lineContent.trim().substring(0, 80)
});
}
}
return findings;
}
/**
* Check for hook pairing issues
*/
function analyzeHookPairing(filePath) {
const findings = [];
const content = fs.readFileSync(filePath, 'utf-8');
// Find all background hooks
const bgHookRegex = /--slds-g-color-(surface|accent|success|warning|error|info)(?:-container)?-\d/g;
const textHookRegex = /--slds-g-color-on-(surface|accent|success|warning|error|info)(?:-container)?-\d/g;
const bgHooks = content.match(bgHookRegex) || [];
const textHooks = content.match(textHookRegex) || [];
// Extract families
const bgFamilies = new Set(bgHooks.map(h => {
const match = h.match(/--slds-g-color-(\w+(?:-container)?)-\d/);
return match ? match[1] : null;
}).filter(Boolean));
const textFamilies = new Set(textHooks.map(h => {
const match = h.match(/--slds-g-color-on-(\w+(?:-container)?)-\d/);
return match ? match[1] : null;
}).filter(Boolean));
// Check for mismatches
for (const bgFamily of bgFamilies) {
const expectedTextFamily = bgFamily.replace('-container', '');
if (!textFamilies.has(expectedTextFamily) && !textFamilies.has(bgFamily)) {
findings.push({
id: 'T010',
severity: WARNING,
file: filePath,
message: `Background hook family '${bgFamily}' may lack matching text hook`,
recommendation: `Pair with --slds-g-color-on-${expectedTextFamily}-*`
});
}
}
return findings;
}
/**
* Calculate scores from findings
*/
function calculateScores(findings) {
const weights = {
[CRITICAL]: 10,
[WARNING]: 3,
[INFO]: 1
};
// NOTE: Linter findings (L001, L002, L003) come from the SLDS linter output,
// not from this script. They should be merged in by the calling agent.
// This script only produces findings for the other categories.
const categories = {
theming: { issues: 0, ids: ['T002', 'T010', 'T011', 'T021', 'T051'] },
accessibility: { issues: 0, ids: ['A001', 'A004', 'A005', 'A010', 'A020', 'A021', 'A022'] },
codeQuality: { issues: 0, ids: ['Q001', 'Q002', 'Q012', 'Q021', 'Q025'] },
componentUsage: { issues: 0, ids: ['C001', 'C002', 'C004'] }
};
// Count weighted issues per category
for (const finding of findings) {
const weight = weights[finding.severity];
for (const [category, config] of Object.entries(categories)) {
if (config.ids.includes(finding.id)) {
config.issues += weight;
break;
}
}
}
// Calculate scores
const scores = {};
for (const [category, config] of Object.entries(categories)) {
scores[category] = Math.max(0, 100 - config.issues);
}
return scores;
}
/**
* Get grade from score
*/
function getGrade(score) {
if (score >= 90) return 'A';
if (score >= 80) return 'B';
if (score >= 70) return 'C';
if (score >= 60) return 'D';
return 'F';
}
/**
* Main analysis function
*/
function analyze(componentPath) {
const resolvedPath = path.resolve(componentPath);
if (!fs.existsSync(resolvedPath)) {
console.error(`Error: Path does not exist: ${resolvedPath}`);
process.exit(1);
}
const findings = [];
// Find and analyze CSS files
const cssFiles = findFiles(resolvedPath, ['.css']);
for (const file of cssFiles) {
findings.push(...analyzeFile(file, PATTERNS.css));
findings.push(...analyzeHookPairing(file));
findings.push(...analyzeInventedHooks(file));
}
// Find and analyze HTML files
const htmlFiles = findFiles(resolvedPath, ['.html']);
for (const file of htmlFiles) {
findings.push(...analyzeFile(file, PATTERNS.html));
findings.push(...analyzeHeadings(file));
}
// Find and analyze JS files
const jsFiles = findFiles(resolvedPath, ['.js']);
for (const file of jsFiles) {
findings.push(...analyzeFile(file, PATTERNS.js));
}
// Calculate scores
const scores = calculateScores(findings);
// Organize findings by severity
const organized = {
critical: findings.filter(f => f.severity === CRITICAL),
warning: findings.filter(f => f.severity === WARNING),
info: findings.filter(f => f.severity === INFO)
};
// Calculate total lines for complexity classification
let totalLines = 0;
for (const file of [...cssFiles, ...htmlFiles, ...jsFiles]) {
totalLines += fs.readFileSync(file, 'utf-8').split('\n').length;
}
const totalFiles = cssFiles.length + htmlFiles.length + jsFiles.length;
let complexity = 'small';
if (totalFiles >= 7 || totalLines >= 500) complexity = 'large';
else if (totalFiles >= 3 || totalLines >= 100) complexity = 'medium';
// Build result
const result = {
component: path.basename(resolvedPath),
path: resolvedPath,
timestamp: new Date().toISOString(),
complexity: {
classification: complexity,
totalFiles,
totalLines
},
note: "These are automated category scores only. Combine them with SLDS linter results and the required Step 3 manual review gate in SKILL.md before making a final ship recommendation.",
scores: {
theming: { score: scores.theming, grade: getGrade(scores.theming) },
accessibility: { score: scores.accessibility, grade: getGrade(scores.accessibility) },
codeQuality: { score: scores.codeQuality, grade: getGrade(scores.codeQuality) },
componentUsage: { score: scores.componentUsage, grade: getGrade(scores.componentUsage) }
},
findings: organized,
summary: {
filesAnalyzed: totalFiles,
cssFiles: cssFiles.length,
htmlFiles: htmlFiles.length,
jsFiles: jsFiles.length,
totalLines,
critical: organized.critical.length,
warnings: organized.warning.length,
info: organized.info.length
}
};
return result;
}
// CLI entry point
if (require.main === module) {
const args = process.argv.slice(2);
const positionalArgs = args.filter((a, i) => !a.startsWith('--') && (i === 0 || !args[i - 1].startsWith('--')));
if (positionalArgs.length === 0) {
console.log('SLDS Quality Analyzer');
console.log('Usage: node analyze-quality.cjs <component-path> [--hooks-index <path>]');
console.log('');
console.log('Options:');
console.log(' --hooks-index <path> Path to hooks-index.json (optional; enables T051 invented-hook detection)');
console.log('');
console.log('Output: JSON analysis of SLDS quality issues');
process.exit(0);
}
HOOKS_INDEX_PATH = resolveHooksIndexPath(args);
const result = analyze(positionalArgs[0]);
console.log(JSON.stringify(result, null, 2));
}
module.exports = { analyze, PATTERNS };
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |