@salesforce/afv-skills 1.22.0 → 1.23.0

package/skills/validating-slds/references/quality-checks.md

@@ -1,308 +0,0 @@
-# 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
-```

package/skills/validating-slds/references/report-format.md

@@ -1,302 +0,0 @@
-# SLDS Quality Report Format
-
-Guidelines for generating quality reports. **Default to the compact format** and expand sections when the user requests detail.
-
----
-
-## Default: Compact Report
-
-Always start with this format. It gives the user the full picture in a glanceable summary.
-
-````markdown
-# SLDS Quality Scorecard: `{component-name}`
-
-**Path:** `{component-path}` | **Complexity:** {small|medium|large} ({n} files, {n} lines)
-**Generated:** {date}
-
-## Automated Grade: {grade} ({score}/100)
-
-{grade-description}
-
-**Manual Review Gate:** {Pass|Advisory|Blocking}
-**Final Recommendation:** {Ready for production|Ready with follow-ups|Needs work|Failing}
-
-| Category | Score | Grade |
-|----------|-------|-------|
-| Linter Compliance | {score}/100 | {status-emoji} {grade} |
-| Theming | {score}/100 | {status-emoji} {grade} |
-| Accessibility | {score}/100 | {status-emoji} {grade} |
-| Code Quality | {score}/100 | {status-emoji} {grade} |
-| Component Usage | {score}/100 | {status-emoji} {grade} |
-
-**Issues:** {n} critical | {n} warnings | {n} info
-
-### Top Issues
-
-1. **{issue}** — `{file}:{line}` — {recommendation}
-2. **{issue}** — `{file}:{line}` — {recommendation}
-3. **{issue}** — `{file}:{line}` — {recommendation}
-
-> Automated score reflects linter + script findings only. Manual review can still block ship.
->
-> {accessibility-disclaimer-if-scored}
-
-*Ask for the full report to see all findings, code examples, and action items.*
-````
-
-### When to Show Compact
-
-- First response to a quality audit request
-- Quick validation mode
-- Auditing multiple components (show compact for each)
-
----
-
-## Expanded: Full Report
-
-Show this when the user asks to "expand", "show details", "full report", or "show all findings". Build on top of the compact report — don't repeat the summary, just add the detail sections below it.
-
-````markdown
----
-
-## Critical Issues ({count})
-
-Issues that **must be fixed** before deployment.
-
-### {issue-category}
-
-| # | File | Line | Issue | Recommendation |
-|---|------|------|-------|----------------|
-| 1 | `{file}` | {line} | {description} | {fix} |
-| 2 | `{file}` | {line} | {description} | {fix} |
-
-**Example fix:**
-```css
-/* Before */
-{problematic-code}
-
-/* After */
-{fixed-code}
-```
-
----
-
-## Warnings ({count})
-
-Issues that **should be fixed** but are not blocking.
-
-| # | File | Line | Issue | Impact |
-|---|------|------|-------|--------|
-| 1 | `{file}` | {line} | {description} | {impact} |
-
----
-
-## Info ({count})
-
-Suggestions for improvement.
-
-| # | Category | Finding | Suggestion |
-|---|----------|---------|------------|
-| 1 | {category} | {finding} | {suggestion} |
-
----
-
-## Detailed Findings
-
-### Manual Review Gate
-
-**Gate:** {Pass|Advisory|Blocking}
-
-| Review Area | Outcome | Notes |
-|-------------|---------|-------|
-| Loading states | {Pass|Advisory|Blocking} | {notes} |
-| Error states | {Pass|Advisory|Blocking} | {notes} |
-| Empty states | {Pass|Advisory|Blocking} | {notes} |
-| Disabled states | {Pass|Advisory|Blocking} | {notes} |
-| Semantic HTML | {Pass|Advisory|Blocking} | {notes} |
-| Blueprint compliance | {Pass|Advisory|Blocking} | {notes} |
-
----
-
-### Linter Compliance
-
-**Violations Found:** {count}
-
-| Rule | Count | Files Affected |
-|------|-------|----------------|
-| `slds/class-override` | {count} | {files} |
-| `slds/lwc-token-to-slds-hook` | {count} | {files} |
-| `slds/no-hardcoded-values` | {count} | {files} |
-
-<details>
-<summary>Full Linter Output</summary>
-
-```
-{linter-output}
-```
-
-</details>
-
----
-
-### Theming
-
-**Hooks Usage Summary:**
-
-| Hook Type | Used | Missing Fallback | Issues |
-|-----------|------|------------------|--------|
-| Color Hooks | {count} | {count} | {count} |
-| Spacing Hooks | {count} | {count} | {count} |
-| Typography Hooks | {count} | {count} | {count} |
-
-**Hook Pairing Analysis:**
-
-| Background Hook | Paired Text Hook | Status |
-|-----------------|------------------|--------|
-| `--slds-g-color-surface-1` | `--slds-g-color-on-surface-2` | {status} |
-
----
-
-### Accessibility
-
-> This section checks attribute presence only. It does not validate contrast ratios, keyboard flows, or screen reader behavior. Passing here does not guarantee WCAG compliance.
-
-| Check | Status | Details |
-|-------|--------|---------|
-| Lightning input labels | {status} | {count} inputs, {count} labeled |
-| Icon alternative text | {status} | {count} icons, {count} with alt |
-| Image alt attributes | {status} | {count} images, {count} with alt |
-| Heading hierarchy | {status} | {sequence} |
-| Focus indicators | {status} | {findings} |
-
----
-
-### Code Quality
-
-| Metric | Value | Status |
-|--------|-------|--------|
-| Total CSS lines | {count} | {status} |
-| !important usage | {count} | {status} |
-| Inline styles | {count} | {status} |
-| High z-index values | {count} | {status} |
-
----
-
-### Component Usage
-
-| Element Type | Native Count | LBC Alternative | Recommendation |
-|--------------|-------------|-----------------|----------------|
-| Inputs | {count} | `<lightning-input>` | {recommendation} |
-| Buttons | {count} | `<lightning-button>` | {recommendation} |
-| Selects | {count} | `<lightning-combobox>` | {recommendation} |
-
----
-
-## Action Items
-
-### Must Fix (Critical)
-
-- [ ] {action-item}
-
-### Should Fix (Warnings)
-
-- [ ] {action-item}
-
-### Nice to Have (Info)
-
-- [ ] {action-item}
-
----
-
-## Next Steps
-
-1. Address all **{count} critical issues** immediately
-2. Review and fix **{count} warnings** before code review
-3. Consider **{count} suggestions** for future improvements
-4. Re-run validation to confirm fixes
-
-**Estimated Effort:** {estimate}
-````
-
----
-
-## JSON Output
-
-For programmatic consumption (e.g., CI integration or tracking over time). Produce this only when explicitly requested or when auditing multiple components for comparison.
-
-```json
-{
-  "component": "{component-name}",
-  "path": "{component-path}",
-  "timestamp": "{iso-date}",
-  "complexity": {
-    "classification": "medium",
-    "totalFiles": 4,
-    "totalLines": 280
-  },
-  "scores": {
-    "automatedOverall": 85,
-    "automatedGrade": "B",
-    "categories": {
-      "linter": { "score": 100, "grade": "A" },
-      "theming": { "score": 80, "grade": "B" },
-      "accessibility": { "score": 75, "grade": "C" },
-      "codeQuality": { "score": 90, "grade": "A" },
-      "componentUsage": { "score": 85, "grade": "B" }
-    }
-  },
-  "manualReview": {
-    "gate": "Advisory",
-    "findings": []
-  },
-  "finalRecommendation": "Ready with follow-ups",
-  "findings": {
-    "critical": [],
-    "warnings": [],
-    "info": []
-  },
-  "summary": {
-    "filesAnalyzed": 4,
-    "totalLines": 280,
-    "critical": 0,
-    "warnings": 2,
-    "info": 3
-  }
-}
-```
-
----
-
-## Status Indicators
-
-| Score Range | Emoji | Meaning |
-|-------------|-------|---------|
-| 90-100 | ✅ | Excellent |
-| 80-89 | 🟢 | Good |
-| 70-79 | 🟡 | Acceptable |
-| 60-69 | 🟠 | Needs Work |
-| 0-59 | 🔴 | Critical |
-
----
-
-## Grade Descriptions
-
-| Grade | Description |
-|-------|-------------|
-| A | **Excellent** - Strong automated result. Requires a passing manual review gate before calling it production-ready. |
-| B | **Good** - Solid automated result. Requires manual review before a production recommendation. |
-| C | **Acceptable** - Automated issues should be addressed before production. |
-| D | **Needs Work** - Significant automated issues require attention before code review. |
-| F | **Critical** - Automated checks found blocking issues. Not suitable for deployment. |
-
----
-
-## Report Delivery Guidelines
-
-1. **Always default to compact** — show the scorecard first, expand on request
-2. **Separate automated grade from final recommendation** — manual review can override ship readiness
-3. **Group by severity** — critical issues first, then warnings, then info
-4. **Include actionable recommendations** — every finding should have a clear fix
-5. **Provide code examples** — show before/after for complex fixes in the expanded report
-6. **Note complexity** — a "B" on a large component means something different than a "B" on a small one
-7. **Add accessibility disclaimer** — when the accessibility score is included, note it checks attribute presence only