afv-library/skills/validating-slds/references/report-format.md

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.

# SLDS Quality Scorecard: `{component-name}`

**Path:** `{component-path}` | **Complexity:** {small|medium|large} ({n} files, {n} lines)
**Generated:** {date}

## Grade: {grade} ({score}/100)

{grade-description}

| 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}

> {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.

---

## 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

### 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.

{
  "component": "{component-name}",
  "path": "{component-path}",
  "timestamp": "{iso-date}",
  "complexity": {
    "classification": "medium",
    "totalFiles": 4,
    "totalLines": 280
  },
  "scores": {
    "overall": 85,
    "grade": "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" }
    }
  },
  "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 - Component follows SLDS best practices. Minor improvements possible. Ready for production.
B	Good - Component is well-structured with minor issues. Address warnings before deployment.
C	Acceptable - Component has notable issues that should be addressed. Not recommended for production without fixes.
D	Needs Work - Component has significant quality issues. Requires attention before code review.
F	Critical - Component has blocking issues that must be resolved. Not suitable for deployment.

---

Report Delivery Guidelines

1. Always default to compact — show the scorecard first, expand on request
2. Group by severity — critical issues first, then warnings, then info
3. Include actionable recommendations — every finding should have a clear fix
4. Provide code examples — show before/after for complex fixes in the expanded report
5. Note complexity — a "B" on a large component means something different than a "B" on a small one
6. Add accessibility disclaimer — when the accessibility score is included, note it checks attribute presence only