@salesforce/afv-skills 1.21.0 → 1.22.0

package/skills/design-systems-slds-validate/SKILL.md

@@ -0,0 +1,262 @@
+---
+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:
+  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:
+
+```bash
+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:
+
+```bash
+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 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](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
+
+```
+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](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

package/skills/design-systems-slds-validate/references/quality-checks.md

@@ -0,0 +1,308 @@
+# SLDS Quality Checks Reference
+
+Complete catalog of quality checks performed during SLDS component validation.
+
+> **Scope note:** The SLDS linter already catches class overrides (`slds/class-override`), deprecated tokens (`slds/lwc-token-to-slds-hook`), and hardcoded values (`slds/no-hardcoded-values`). The checks below cover what the linter does **not** catch. Linter violation counts are incorporated into the final score separately — see Step 1 in SKILL.md.
+
+### Detection Legend
+
+| Symbol | Meaning |
+|--------|---------|
+| **Script** | Automated by `analyze-quality.cjs` |
+| **Linter** | Caught by the SLDS linter |
+| **Manual** | Requires agent review (Step 3) |
+
+---
+
+## Table of Contents
+
+- [Theming and Styling Checks](#theming-and-styling-checks)
+- [Accessibility Checks](#accessibility-checks)
+- [Code Quality Checks](#code-quality-checks)
+- [Component Usage Checks](#component-usage-checks)
+- [Detection Patterns](#detection-patterns)
+
+---
+
+## Theming and Styling Checks
+
+### Hook Fallbacks (not caught by linter)
+
+| ID | Check | Severity | Detection | Pass Criteria |
+|----|-------|----------|-----------|---------------|
+| T002 | Fallback values present | Critical | Script | All `var(--slds-g-*)` include a fallback value |
+
+### Hook Family Pairing
+
+| ID | Check | Severity | Detection | Pass Criteria |
+|----|-------|----------|-----------|---------------|
+| T010 | File-level hook family pairing | Warning | Script | Each background hook family present in a file has a matching `on-*` family present somewhere in the same file |
+| T011 | Surface/container pairing correctness | Warning | Manual | `surface-*` and `surface-container-*` backgrounds are paired with appropriate `on-surface-*` text in the same selector/context |
+| T012 | Accent pairing correctness | Warning | Manual | `accent-*` and `accent-container-*` backgrounds are paired with appropriate `on-accent-*` text in the same selector/context |
+| T013 | Feedback pairing correctness | Warning | Manual | Feedback colors are paired with the correct `on-error-*`, `on-warning-*`, `on-success-*`, or `on-info-*` text hooks in the same selector/context |
+
+### Spacing Hook Usage
+
+| ID | Check | Severity | Detection | Pass Criteria |
+|----|-------|----------|-----------|---------------|
+| T020 | Spacing uses hooks | Warning | Manual | Spacing uses `var(--slds-g-spacing-*)` or utilities |
+| T021 | No magic pixel values | Warning | Script | No arbitrary `px` values for spacing |
+| T022 | Base-8 alignment | Info | Manual | Spacing values align to 4, 8, 12, 16, 24, 32, 48px |
+
+### Typography Hook Usage
+
+| ID | Check | Severity | Detection | Pass Criteria |
+|----|-------|----------|-----------|---------------|
+| T030 | Font family hooks | Warning | Manual | `font-family` uses `var(--slds-g-font-family-*)` |
+| T031 | Font size hooks | Warning | Manual | `font-size` uses `var(--slds-g-font-scale-*)` or `var(--slds-g-font-size-base)` — NOT `var(--slds-g-font-size-N)` |
+| T032 | Font weight hooks | Warning | Manual | `font-weight` uses `var(--slds-g-font-weight-*)` |
+| T033 | Line height hooks | Info | Manual | `line-height` uses `var(--slds-g-font-line-height-*)` |
+
+### Other Styling Hooks
+
+| ID | Check | Severity | Detection | Pass Criteria |
+|----|-------|----------|-----------|---------------|
+| T040 | Shadow hooks | Warning | Manual | Shadows use `var(--slds-g-shadow-*)` |
+| T041 | Border radius hooks | Warning | Manual | Border radius uses `var(--slds-g-radius-*)` |
+| T042 | Border width hooks | Info | Manual | Border width uses `var(--slds-g-border-width-*)` |
+
+### Hook Validity
+
+| ID | Check | Severity | Detection | Pass Criteria |
+|----|-------|----------|-----------|---------------|
+| T050 | Color hooks numbered | Warning | Manual | Every `--slds-g-color-*` hook ends in a number (no bare `on-surface`, `on-accent`, etc.) |
+| T051 | No invented hooks | Critical | Script | Every `--slds-g-*` hook referenced actually exists in `metadata/hooks-index.json` |
+
+---
+
+## Accessibility Checks
+
+### Labels and Names
+
+| ID | Check | Severity | Detection | Pass Criteria |
+|----|-------|----------|-----------|---------------|
+| A001 | Input labels | Critical | Script | All `<lightning-input>` have `label` attribute |
+| A002 | Button names | Critical | Manual | All `<button>`, `<lightning-button>` have accessible names |
+| A003 | Link names | Critical | Manual | All `<a>` have descriptive text content |
+| A004 | Icon alt text | Critical | Script | All icons have `alternative-text` or empty for decorative |
+| A005 | Image alt text | Critical | Script | All `<img>` have `alt` attribute |
+
+### ARIA and Semantics
+
+| ID | Check | Severity | Detection | Pass Criteria |
+|----|-------|----------|-----------|---------------|
+| A010 | Heading hierarchy | Warning | Script | H1 → H2 → H3 without skipping |
+| A011 | ARIA roles | Warning | Manual | `role` attributes used correctly |
+| A012 | ARIA labels | Warning | Manual | `aria-label`, `aria-labelledby` used appropriately |
+| A013 | ARIA live | Info | Manual | Dynamic content uses `aria-live` regions |
+| A014 | ARIA invalid | Warning | Manual | Invalid form fields have `aria-invalid="true"` |
+
+### Keyboard and Focus
+
+| ID | Check | Severity | Detection | Pass Criteria |
+|----|-------|----------|-----------|---------------|
+| A020 | Tab order | Warning | Script | `tabindex` values are 0 or -1 only |
+| A021 | Focus visible | Warning | Script | No `outline: none` without alternative focus style |
+| A022 | Interactive elements | Warning | Script | Clickable elements are `<button>` or `<a>` |
+| A023 | Focus management | Info | Manual | Modals trap focus, return focus on close |
+
+### Visual Accessibility
+
+| ID | Check | Severity | Detection | Pass Criteria |
+|----|-------|----------|-----------|---------------|
+| A030 | Color not sole indicator | Warning | Manual | Status/errors use icon or text, not just color |
+| A031 | Touch targets | Info | Manual | Interactive elements >= 44x44px on mobile |
+| A032 | Text sizing | Info | Manual | Text can scale without breaking layout |
+
+---
+
+## Code Quality Checks
+
+### CSS Anti-patterns
+
+| ID | Check | Severity | Detection | Pass Criteria |
+|----|-------|----------|-----------|---------------|
+| Q001 | No !important | Warning | Script | No `!important` declarations |
+| Q002 | No inline styles (HTML) | Warning | Script | No `style="..."` attributes in HTML |
+| Q025 | No inline styles (JS) | Warning | Script | No `.style.*=` direct property assignment in JS |
+| Q003 | No deep nesting | Info | Manual | Selectors <= 3 levels deep |
+| Q004 | No ID selectors | Info | Manual | No `#id` in CSS selectors |
+| Q005 | No universal selectors | Info | Manual | No `*` in CSS selectors |
+
+### Naming Conventions
+
+| ID | Check | Severity | Detection | Pass Criteria |
+|----|-------|----------|-----------|---------------|
+| Q010 | Component prefix | Warning | Manual | Custom classes use component prefix |
+| Q011 | CamelCase prefix | Warning | Manual | Prefix follows camelCase convention |
+| Q012 | Avoid dynamic SLDS class manipulation | Warning | Script | Avoid `.classList.add/remove/toggle('slds-*')` patterns in JS |
+| Q013 | BEM consistency | Info | Manual | Class names follow consistent BEM pattern |
+
+### Maintainability
+
+| ID | Check | Severity | Detection | Pass Criteria |
+|----|-------|----------|-----------|---------------|
+| Q020 | No magic numbers | Warning | Manual | All numeric values have clear purpose |
+| Q021 | Z-index scale | Warning | Script | Z-index values follow defined scale |
+| Q022 | No fixed dimensions | Warning | Manual | Avoid fixed `width`/`height` in px |
+| Q023 | CSS file size | Info | Manual | CSS file < 500 lines |
+
+---
+
+## Component Usage Checks
+
+### Lightning Base Components
+
+| ID | Check | Severity | Detection | Pass Criteria |
+|----|-------|----------|-----------|---------------|
+| C001 | Use LBC inputs | Warning | Script | Use `<lightning-input>` not `<input>` |
+| C002 | Use LBC buttons | Warning | Script | Use `<lightning-button>` not `<button>` |
+| C003 | Use LBC icons | Warning | Manual | Use `<lightning-icon>` not custom SVG |
+| C004 | Use LBC combobox | Warning | Script | Use `<lightning-combobox>` not `<select>` |
+| C005 | Use LBC datatable | Info | Manual | Use `<lightning-datatable>` for tables |
+
+### SLDS Blueprint Compliance
+
+| ID | Check | Severity | Detection | Pass Criteria |
+|----|-------|----------|-----------|---------------|
+| C010 | Card structure | Warning | Manual | Cards use `slds-card` class structure |
+| C011 | Modal structure | Warning | Manual | Modals use `slds-modal` class structure |
+| C012 | Form structure | Warning | Manual | Forms use `slds-form` or `slds-form-element` |
+| C013 | Button variants | Info | Manual | Buttons use `slds-button_*` variants |
+
+### Semantic HTML
+
+| ID | Check | Severity | Detection | Pass Criteria |
+|----|-------|----------|-----------|---------------|
+| C020 | Use button element | Warning | Manual | Clickable elements use `<button>` |
+| C021 | Use nav element | Info | Manual | Navigation uses `<nav>` |
+| C022 | Use article element | Info | Manual | Self-contained content uses `<article>` |
+| C023 | Use section element | Info | Manual | Thematic grouping uses `<section>` |
+| C024 | No div soup | Info | Manual | Meaningful elements used over nested `<div>` |
+
+---
+
+## Detection Patterns
+
+### Regex Patterns for CSS Analysis
+
+> Hardcoded colors, SLDS class overrides, and deprecated LWC tokens are already caught by the SLDS linter. These patterns cover supplementary checks only.
+
+```javascript
+// Missing fallback — matches var(--slds-g-*) with NO comma before closing paren
+const MISSING_FALLBACK = /var\(--slds-g-[^,)]+\)/g;
+
+// !important usage
+const IMPORTANT = /!important/g;
+
+// Magic pixel spacing values (not inside a var() fallback)
+const MAGIC_PX = /\b(?:margin(?:-[a-z-]+)?|padding(?:-[a-z-]+)?|gap|row-gap|column-gap)\s*:\s*\d+px\b(?![^;]*var\()/g;
+
+// High z-index (3+ digits)
+const HIGH_ZINDEX = /z-index\s*:\s*(\d{3,})/g;
+
+// Focus outline removed
+const OUTLINE_NONE = /outline\s*:\s*none/g;
+```
+
+### Regex Patterns for HTML Analysis
+
+> Native `<input>` labeling via `<label for="">` requires cross-element analysis that regex cannot handle reliably. The checks below focus on Lightning Base Component attributes and structural issues.
+
+```javascript
+// Lightning input without label attribute
+const LBC_INPUT_NO_LABEL = /<lightning-input(?![^>]*\blabel\b)[^>]*>/gi;
+
+// Icon without alternative-text
+const ICON_NO_ALT = /<lightning-icon(?![^>]*alternative-text)[^>]*>/gi;
+
+// Image without alt
+const IMG_NO_ALT = /<img(?![^>]*\balt\b)[^>]*>/gi;
+
+// Inline styles
+const INLINE_STYLE = /style\s*=\s*["'][^"']+["']/gi;
+
+// Positive tabindex (should be 0 or -1 only)
+const TABINDEX_POSITIVE = /tabindex\s*=\s*["']([1-9]\d*)["']/gi;
+
+// Heading hierarchy (track sequence to detect skipped levels)
+const HEADINGS = /<h([1-6])[^>]*>/gi;
+
+// Div with click handler (should be button)
+const CLICKABLE_DIV = /<div[^>]*onclick[^>]*>/gi;
+
+// Native elements where LBC alternatives exist (info-level)
+const NATIVE_INPUT = /<input\s/gi;
+const NATIVE_BUTTON = /<button\s/gi;
+const NATIVE_SELECT = /<select\s/gi;
+```
+
+### File Analysis Strategy
+
+1. **CSS Files**: Parse with regex, track line numbers, categorize findings; cross-reference hooks against `hooks-index.json` (T051)
+2. **HTML Files**: Parse with regex, validate structure, check attributes
+3. **JS Files**: Check for inline style assignment (`.style.*=`) and dynamic SLDS class manipulation (`.classList.add('slds-*')`)
+4. **Cross-file/manual**: Review relationships between files that regex cannot validate reliably
+
+---
+
+## Severity Levels
+
+| Level | Weight | Action Required |
+|-------|--------|-----------------|
+| Critical | -10 pts | Must fix before deployment |
+| Warning | -3 pts | Should fix, review if acceptable |
+| Info | -1 pt | Nice to fix, no blocking |
+
+---
+
+## Category Scoring
+
+The script outputs individual category scores. It does **not** produce a combined overall grade — the agent computes that using the formula in SKILL.md Step 4:
+
+```
+Overall = (Linter × 0.30) + (Theming × 0.20) + (Accessibility × 0.20)
+        + (CodeQuality × 0.15) + (ComponentUsage × 0.15)
+```
+
+> **Linter Compliance** is scored separately from linter output (count violations × 10, min 0).
+
+### Automation Coverage
+
+The script automates **17 of 53** checks listed above (marked **Script** in the Detection column). The remaining 36 require agent manual review (Step 3 in SKILL.md). Categories with fewer automated checks — especially Code Quality (4 of 13) and Component Usage (3 of 14) — will tend toward 100 when no automated findings exist. Treat the automated score as provisional: manual review findings must be reported separately and can block a production recommendation even when the score is high.
+
+### Theming
+
+```
+Score = 100 - (critical issues in category × 10)
+              - (warnings in category × 3)
+              - (info in category × 1)
+Min: 0
+```
+
+### Accessibility
+
+```
+Score = 100 - (critical issues in category × 10)
+              - (warnings in category × 3)
+              - (info in category × 1)
+Min: 0
+```
+
+### Code Quality
+
+```
+Score = 100 - (critical issues in category × 10)
+              - (warnings in category × 3)
+              - (info in category × 1)
+Min: 0
+```
+
+### Component Usage
+
+```
+Score = 100 - (critical issues in category × 10)
+              - (warnings in category × 3)
+              - (info in category × 1)
+Min: 0
+```