diff --git a/app/figma-plugin/src/ui.template.html b/app/figma-plugin/src/ui.template.html
index 8fe745ab..838cbcb7 100644
--- a/app/figma-plugin/src/ui.template.html
+++ b/app/figma-plugin/src/ui.template.html
@@ -146,6 +146,7 @@ <h2>Ready to analyze</h2>
         maxDepth: result.maxDepth,
       });
       el.className = 'visible';
+      CanICode.initReportInteractions(el);
       document.getElementById('footer').style.display = '';
     }
 
diff --git a/app/shared/styles.css b/app/shared/styles.css
index 1e8ea33f..ae6c5a7b 100644
--- a/app/shared/styles.css
+++ b/app/shared/styles.css
@@ -68,11 +68,11 @@ body {
    ================================================================ */
 
 /* ---- Details/summary reset ---- */
-.rpt-cat > summary::-webkit-details-marker,
+.rpt-rule > summary::-webkit-details-marker,
 .rpt-issue > summary::-webkit-details-marker { display: none; }
-.rpt-cat > summary::marker,
+.rpt-rule > summary::marker,
 .rpt-issue > summary::marker { content: ""; }
-.rpt-cat > summary,
+.rpt-rule > summary,
 .rpt-issue > summary { list-style: none; }
 
 /* ---- Overall Score ---- */
@@ -115,10 +115,12 @@ body {
   display: flex;
   flex-direction: column;
   align-items: center;
-  position: relative;
   cursor: pointer;
   text-decoration: none;
   color: var(--fg);
+  background: none;
+  border: none;
+  padding: 4px;
   transition: opacity 0.15s;
 }
 .rpt-gauge-item:hover { opacity: 0.8; }
@@ -270,25 +272,80 @@ body {
 }
 .rpt-opps-link:hover { color: var(--fg); }
 
-/* ---- Categories ---- */
-.rpt-cats > * + * {
-  margin-top: 12px;
+/* ---- Category Tabs (shadcn pill style) ---- */
+.rpt-tabs {
+  margin-bottom: 24px;
+  position: relative;
 }
-.rpt-cat {
-  overflow: hidden;
+@media (max-width: 600px) {
+  .rpt-tab-list::after {
+    content: "";
+    position: sticky;
+    right: 0;
+    width: 40px;
+    min-height: 100%;
+    background: linear-gradient(to right, transparent, var(--bg));
+    pointer-events: none;
+    flex-shrink: 0;
+    margin-left: -40px;
+  }
 }
-.rpt-cat-header {
-  padding: 14px 20px;
+.rpt-tab-list {
   display: flex;
-  align-items: center;
-  gap: 12px;
+  gap: 4px;
+  padding: 4px;
+  background: var(--bg);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  overflow-x: auto;
+  white-space: nowrap;
+  -webkit-overflow-scrolling: touch;
+}
+.rpt-tab-list::-webkit-scrollbar { display: none; }
+.rpt-tab-list { scrollbar-width: none; }
+.rpt-tab {
+  padding: 6px 12px;
+  font-size: 13px;
+  font-weight: 500;
+  color: var(--fg-muted);
+  background: transparent;
+  border: none;
+  border-radius: 6px;
   cursor: pointer;
-  transition: background 0.15s;
-  user-select: none;
+  transition: all 0.15s;
+  white-space: nowrap;
+  flex-shrink: 0;
+}
+.rpt-tab:hover { color: var(--fg); background: rgba(0,0,0,0.04); }
+.rpt-tab.active {
+  color: var(--fg);
+  background: var(--card);
+  box-shadow: 0 1px 2px rgba(0,0,0,0.06);
+}
+.rpt-tab-count {
+  font-size: 11px;
+  color: var(--fg-muted);
+  margin-left: 2px;
+}
+.rpt-tab.active .rpt-tab-count { color: var(--fg-muted); }
+.rpt-tab-panel { display: none; padding-top: 16px; }
+.rpt-tab-panel.active { display: block; }
+.rpt-cat-empty {
+  padding: 24px 20px;
+  font-size: 14px;
+  color: var(--green);
+  font-weight: 500;
+  text-align: center;
+}
+
+/* ---- Gauge item active highlight ---- */
+.rpt-gauge-item.active {
+  opacity: 1;
+  background: rgba(0,0,0,0.04);
+  border-radius: var(--radius);
 }
-.rpt-cat-header:hover { background: rgba(0,0,0,0.02); }
 
-/* Score badge */
+/* ---- Score badge ---- */
 .rpt-badge {
   display: inline-flex;
   align-items: center;
@@ -306,65 +363,76 @@ body {
 .rpt-badge.score-amber { background: var(--amber-bg); color: #b45309; border-color: rgba(245,158,11,0.2); }
 .rpt-badge.score-red   { background: var(--red-bg);   color: #b91c1c; border-color: rgba(239,68,68,0.2); }
 
-.rpt-cat-info {
-  flex: 1;
-  min-width: 0;
-}
-.rpt-cat-name {
-  font-size: 14px;
-  font-weight: 600;
+/* ---- Rule Section ---- */
+.rpt-tab-panel > .rpt-rule + .rpt-rule {
+  margin-top: 12px;
 }
-.rpt-cat-desc {
-  font-size: 12px;
-  color: var(--fg-muted);
+.rpt-rule {
+  overflow: hidden;
 }
-.rpt-cat-count {
-  font-size: 12px;
-  color: var(--fg-muted);
-  white-space: nowrap;
+.rpt-rule-header {
+  padding: 14px 20px;
+  display: flex;
+  align-items: flex-start;
+  gap: 12px;
+  cursor: pointer;
+  user-select: none;
+  transition: background 0.15s;
 }
-.rpt-cat-chevron {
+.rpt-rule-header:hover { background: rgba(0,0,0,0.02); }
+.rpt-rule-chevron {
   width: 16px;
   height: 16px;
   color: var(--fg-muted);
   transition: transform 0.2s;
   flex-shrink: 0;
+  margin-top: 2px;
+  margin-left: auto;
 }
-.rpt-cat[open] > .rpt-cat-header .rpt-cat-chevron {
+.rpt-rule[open] > .rpt-rule-header .rpt-rule-chevron {
   transform: rotate(180deg);
 }
-.rpt-cat-body {
-  border-top: 1px solid var(--border);
-}
-.rpt-cat-empty {
-  padding: 16px 20px;
+.rpt-rule-name {
   font-size: 14px;
-  color: var(--green);
-  font-weight: 500;
-}
-
-/* ---- Severity Group ---- */
-.rpt-sev-group {
-  padding: 12px 20px;
+  font-weight: 600;
+  display: block;
 }
-.rpt-sev-header {
+.rpt-rule-meta {
+  font-size: 12px;
+  color: var(--fg-muted);
   display: flex;
   align-items: center;
-  gap: 8px;
-  margin-bottom: 8px;
+  gap: 6px;
+  margin-top: 2px;
 }
-.rpt-sev-label {
-  font-size: 11px;
-  font-weight: 600;
-  text-transform: uppercase;
-  letter-spacing: 0.04em;
+.rpt-rule-title {
+  display: block;
+  flex: 1;
+  min-width: 0;
 }
-.rpt-sev-count {
+.rpt-rule-info {
+  display: block;
+  padding: 8px 0 4px;
   font-size: 12px;
   color: var(--fg-muted);
-  margin-left: auto;
+  line-height: 1.6;
+  margin-top: 8px;
+}
+.rpt-rule-info-line {
+  display: block;
+}
+.rpt-rule-info-line + .rpt-rule-info-line {
+  margin-top: 4px;
+}
+.rpt-rule-info strong {
+  color: var(--fg);
+  font-weight: 500;
 }
-.rpt-sev-issues > * + * {
+.rpt-rule-issues {
+  padding: 8px 12px;
+  border-top: 1px solid var(--border);
+}
+.rpt-rule-issues > * + * {
   margin-top: 4px;
 }
 
@@ -379,16 +447,11 @@ body {
   align-items: center;
   gap: 10px;
   padding: 8px 12px;
-  font-size: 14px;
+  font-size: 13px;
   cursor: pointer;
   transition: background 0.15s;
 }
 .rpt-issue-header:hover { background: rgba(0,0,0,0.02); }
-.rpt-issue-name {
-  font-weight: 500;
-  white-space: nowrap;
-  flex-shrink: 0;
-}
 .rpt-issue-msg {
   color: var(--fg-muted);
   font-size: 12px;
@@ -415,10 +478,25 @@ body {
   padding: 12px;
   background: #fafafa;
   border-top: 1px solid var(--border);
-  font-size: 14px;
+  font-size: 13px;
 }
 .rpt-issue-body > * + * {
-  margin-top: 8px;
+  margin-top: 6px;
+}
+.rpt-issue-suggestion {
+  font-weight: 500;
+  color: var(--fg);
+}
+.rpt-issue-guide {
+  font-size: 12px;
+  color: var(--fg-muted);
+  padding: 4px 8px;
+  background: var(--blue-bg);
+  border-radius: 4px;
+  display: inline-block;
+}
+.rpt-issue-guide::before {
+  content: "ℹ️ ";
 }
 .rpt-issue-path {
   font-family: var(--font-mono);
@@ -426,17 +504,6 @@ body {
   color: var(--fg-muted);
   word-break: break-all;
 }
-.rpt-issue-info {
-  color: var(--fg-muted);
-  line-height: 1.6;
-}
-.rpt-issue-info > * + * {
-  margin-top: 4px;
-}
-.rpt-issue-info strong {
-  color: var(--fg);
-  font-weight: 500;
-}
 .rpt-issue-actions {
   display: flex;
   align-items: center;
@@ -494,11 +561,12 @@ body {
   .rpt-gauges { padding: 16px; }
   .rpt-summary-inner { gap: 12px; }
   .rpt-summary-total { border-left: none; padding-left: 0; }
+  .rpt-tab-list { gap: 8px; padding: 4px 12px; }
+  .rpt-tab { padding: 6px 14px; }
   .rpt-opps-item { padding: 10px 16px; gap: 10px; }
   .rpt-opps-bar-wrap { width: 80px; }
   .rpt-opps-link { font-size: 11px; }
-  .rpt-cat-header { padding: 10px 14px; gap: 8px; }
-  .rpt-sev-group { padding: 10px 14px; }
+  .rpt-rule-header { padding: 10px 14px; gap: 8px; }
   .rpt-issue-header { padding: 6px 10px; gap: 6px; font-size: 12px; }
   .rpt-issue-body { padding: 10px; font-size: 12px; }
 }
diff --git a/app/web/src/index.html b/app/web/src/index.html
index 494b730e..dd877dce 100644
--- a/app/web/src/index.html
+++ b/app/web/src/index.html
@@ -364,6 +364,7 @@ <h1>Analyze your Figma designs</h1>
         figmaToken: getToken() || undefined,
       });
       el.classList.add('visible');
+      CanICode.initReportInteractions(el);
       el.scrollIntoView({ behavior: 'smooth', block: 'start' });
     }
 
diff --git a/src/browser.ts b/src/browser.ts
index 2e88c06e..2fcec2cd 100644
--- a/src/browser.ts
+++ b/src/browser.ts
@@ -34,7 +34,7 @@ export {
 } from "./core/ui-helpers.js";
 
 // Report rendering (shared with web/plugin)
-export { renderReportBody } from "./core/report-html/render.js";
+export { renderReportBody, initReportInteractions } from "./core/report-html/render.js";
 export type { ReportData } from "./core/report-html/render.js";
 
 // Import rules to register them with the global registry
diff --git a/src/core/contracts/category.ts b/src/core/contracts/category.ts
index 2bdfcbb8..62121fcc 100644
--- a/src/core/contracts/category.ts
+++ b/src/core/contracts/category.ts
@@ -5,8 +5,8 @@ export const CategorySchema = z.enum([
   "responsive-critical",
   "code-quality",
   "token-management",
-  "interaction",
   "minor",
+  "interaction",
 ]);
 
 export type Category = z.infer<typeof CategorySchema>;
@@ -18,6 +18,6 @@ export const CATEGORY_LABELS: Record<Category, string> = {
   "responsive-critical": "Responsive Critical",
   "code-quality": "Code Quality",
   "token-management": "Token Management",
-  "interaction": "Interaction",
   "minor": "Minor",
+  "interaction": "Interaction",
 };
diff --git a/src/core/contracts/rule.ts b/src/core/contracts/rule.ts
index 5cb211b2..786cb7e5 100644
--- a/src/core/contracts/rule.ts
+++ b/src/core/contracts/rule.ts
@@ -68,6 +68,8 @@ export interface RuleViolation {
   nodeId: string;
   nodePath: string;
   message: string;
+  suggestion: string;
+  guide?: string;
 }
 
 /**
diff --git a/src/core/report-html/index.ts b/src/core/report-html/index.ts
index 5630cbaa..7bc22d25 100644
--- a/src/core/report-html/index.ts
+++ b/src/core/report-html/index.ts
@@ -5,14 +5,14 @@ import type { AnalysisFile } from "../contracts/figma-node.js";
 import type { AnalysisResult } from "../engine/rule-engine.js";
 import type { ScoreReport } from "../engine/scoring.js";
 import { escapeHtml } from "../ui-helpers.js";
-import { renderReportBody } from "./render.js";
+import { renderReportBody, initReportInteractions } from "./render.js";
 import type { ReportData } from "./render.js";
 
 declare const __REPORT_CSS__: string;
 const reportCss: string = __REPORT_CSS__;
 
 export type { ReportData } from "./render.js";
-export { renderReportBody } from "./render.js";
+export { renderReportBody, initReportInteractions } from "./render.js";
 
 export interface NodeScreenshot {
   nodeId: string;
@@ -63,7 +63,6 @@ export function generateHtmlReport(
   <style>
 ${reportCss}
     .cli-topbar {
-      position: sticky; top: 0; z-index: 50;
       background: #09090b; color: white;
       border-bottom: 1px solid #27272a;
     }
@@ -97,6 +96,7 @@ ${reportCss}
 ${renderReportBody(data)}
   </main>
 
+  <script>(${String(initReportInteractions)})(document.querySelector('.cli-main'));</script>
 ${figmaToken ? renderFigmaCommentScript(figmaToken) : ""}
 </body>
 </html>`;
diff --git a/src/core/report-html/render.test.ts b/src/core/report-html/render.test.ts
index 20e17a57..b16325ba 100644
--- a/src/core/report-html/render.test.ts
+++ b/src/core/report-html/render.test.ts
@@ -8,8 +8,7 @@ import {
   renderReportBody,
   renderSummaryDot,
   renderOpportunities,
-  renderCategory,
-  renderSeverityGroup,
+  renderRuleSection,
   renderIssueRow,
 } from "./render.js";
 import type { ReportData } from "./render.js";
@@ -41,6 +40,7 @@ function makeViolation(ruleId: string, nodeId = "1-1"): RuleViolation {
     nodeId,
     nodePath: "Root > Frame > Node",
     message: `Issue: ${ruleId}`,
+    suggestion: `Fix: ${ruleId}`,
   };
 }
 
@@ -50,9 +50,12 @@ function makeIssue(opts: {
   severity: Severity;
   score?: number;
   nodeId?: string;
+  guide?: string;
 }): AnalysisIssue {
+  const v = makeViolation(opts.ruleId, opts.nodeId);
+  if (opts.guide) v.guide = opts.guide;
   return {
-    violation: makeViolation(opts.ruleId, opts.nodeId),
+    violation: v,
     rule: makeRule(opts.ruleId, opts.category),
     config: makeConfig(opts.severity, opts.score ?? -5),
     depth: 0,
@@ -107,7 +110,7 @@ function makeReportData(overrides?: Partial<ReportData>): ReportData {
     scores: makeScores(),
     issues: [
       makeIssue({ ruleId: "no-auto-layout", category: "pixel-critical", severity: "blocking", score: -10 }),
-      makeIssue({ ruleId: "hardcoded-color", category: "token-management", severity: "risk" }),
+      makeIssue({ ruleId: "hardcoded-color", category: "token-management", severity: "risk", nodeId: "2-1" }),
     ],
     nodeCount: 100,
     maxDepth: 5,
@@ -123,75 +126,75 @@ describe("renderReportBody", () => {
     expect(html).toContain('class="rpt-overall"');
     expect(html).toContain('class="rpt-score-value"');
     expect(html).toContain(">80<");
-    expect(html).toContain("Overall Score");
   });
 
-  it("renders category gauge grid", () => {
+  it("renders category gauge buttons", () => {
     const html = renderReportBody(makeReportData());
     expect(html).toContain('class="rpt-gauges-grid"');
-    expect(html).toContain('class="rpt-gauge-item"');
+    expect(html).toContain('data-tab="pixel-critical"');
     expect(html).toContain('class="rpt-gauge-label"');
-    // All 6 categories should be present
-    for (const cat of CATEGORIES) {
-      expect(html).toContain(`href="#cat-${cat}"`);
-    }
   });
 
-  it("renders issue summary with severity dots", () => {
+  it("renders issue summary", () => {
     const html = renderReportBody(makeReportData());
     expect(html).toContain('class="rpt-summary-inner"');
     expect(html).toContain("sev-blocking");
     expect(html).toContain("sev-risk");
-    expect(html).toContain("sev-missing");
-    expect(html).toContain("sev-suggestion");
     expect(html).toContain("Total");
   });
 
-  it("renders opportunities for blocking issues", () => {
+  it("renders category tabs", () => {
+    const html = renderReportBody(makeReportData());
+    expect(html).toContain('class="rpt-tab-list"');
+    for (const cat of CATEGORIES) {
+      expect(html).toContain(`data-tab="${cat}"`);
+      expect(html).toContain(`data-panel="${cat}"`);
+    }
+  });
+
+  it("first tab is active by default", () => {
+    const html = renderReportBody(makeReportData());
+    expect(html).toContain('class="rpt-tab active"');
+    expect(html).toContain('class="rpt-tab-panel active"');
+  });
+
+  it("renders opportunities as rule groups", () => {
     const html = renderReportBody(makeReportData());
-    expect(html).toContain('class="rpt-opps-title"');
     expect(html).toContain("Opportunities");
     expect(html).toContain("no auto layout");
+    expect(html).toContain("data-opp-rule");
+    expect(html).toContain("data-opp-cat");
   });
 
-  it("skips opportunities when no blocking issues", () => {
-    const data = makeReportData({
-      issues: [makeIssue({ ruleId: "test", category: "minor", severity: "suggestion" })],
-    });
+  it("skips opportunities when no issues", () => {
+    const data = makeReportData({ issues: [] });
     const html = renderReportBody(data);
     expect(html).not.toContain("Opportunities");
   });
 
-  it("renders all category sections", () => {
+  it("does not embed inline script (interactions initialized by caller)", () => {
     const html = renderReportBody(makeReportData());
-    for (const cat of CATEGORIES) {
-      expect(html).toContain(`id="cat-${cat}"`);
-    }
+    expect(html).not.toContain("<script>");
   });
 
-  it("renders footer with metadata", () => {
+  it("renders footer", () => {
     const html = renderReportBody(makeReportData());
     expect(html).toContain('class="rpt-footer"');
-    expect(html).toContain("CanICode");
     expect(html).toContain("100 nodes");
-    expect(html).toContain("Max depth 5");
   });
 
-  it("does not contain any Tailwind classes", () => {
+  it("does not contain Tailwind classes", () => {
     const html = renderReportBody(makeReportData());
-    // Common Tailwind patterns that should not appear
     expect(html).not.toMatch(/class="[^"]*\bflex\b/);
     expect(html).not.toMatch(/class="[^"]*\bbg-card\b/);
     expect(html).not.toMatch(/class="[^"]*\btext-sm\b/);
-    expect(html).not.toMatch(/class="[^"]*\bpx-\d/);
-    expect(html).not.toMatch(/class="[^"]*\bbg-red-500\b/);
   });
 });
 
 // ---- renderSummaryDot ----
 
 describe("renderSummaryDot", () => {
-  it("renders a dot with severity class", () => {
+  it("renders dot with severity class and count", () => {
     const html = renderSummaryDot("sev-blocking", 3, "Blocking");
     expect(html).toContain('class="rpt-dot sev-blocking"');
     expect(html).toContain(">3<");
@@ -207,102 +210,92 @@ describe("renderSummaryDot", () => {
 // ---- renderOpportunities ----
 
 describe("renderOpportunities", () => {
-  const issues = [
-    makeIssue({ ruleId: "no-auto-layout", category: "pixel-critical", severity: "blocking", score: -10 }),
-    makeIssue({ ruleId: "missing-component", category: "code-quality", severity: "blocking", score: -5, nodeId: "2-1" }),
-  ];
-
-  it("renders opportunity items", () => {
-    const html = renderOpportunities(issues, "fileKey123");
-    expect(html).toContain('class="rpt-opps-item"');
+  it("renders rule-based opportunity items with navigation data", () => {
+    const issues = [
+      makeIssue({ ruleId: "no-auto-layout", category: "pixel-critical", severity: "blocking", score: -10 }),
+      makeIssue({ ruleId: "no-auto-layout", category: "pixel-critical", severity: "blocking", score: -10, nodeId: "2-1" }),
+    ];
+    // Build rule groups manually (same as getTopRules)
+    const rg = {
+      ruleId: "no-auto-layout",
+      ruleName: "no auto layout",
+      severity: "blocking" as const,
+      severityClass: "sev-blocking",
+      why: "w", impact: "i", fix: "f",
+      issues,
+      totalScore: -20,
+    };
+    const html = renderOpportunities([rg]);
     expect(html).toContain("no auto layout");
-    expect(html).toContain("missing component");
-  });
-
-  it("renders bar with proportional width", () => {
-    const html = renderOpportunities(issues, "fileKey123");
-    expect(html).toContain('style="width:100%"'); // max score
-    expect(html).toContain('style="width:50%"'); // half of max
-  });
-
-  it("renders Go to node links with data-node-id", () => {
-    const html = renderOpportunities(issues, "fileKey123");
-    expect(html).toContain('data-node-id="1-1"');
-    expect(html).toContain('data-node-id="2-1"');
-    expect(html).toContain("Go to node →");
-  });
-
-  it("renders Figma deep links", () => {
-    const html = renderOpportunities(issues, "fileKey123");
-    expect(html).toContain("figma.com");
-    expect(html).toContain("fileKey123");
+    expect(html).toContain("2 issues");
+    expect(html).toContain("-20");
+    expect(html).toContain('data-opp-rule="no-auto-layout"');
+    expect(html).toContain('data-opp-cat="pixel-critical"');
   });
 });
 
-// ---- renderCategory ----
+// ---- renderRuleSection ----
 
-describe("renderCategory", () => {
-  const scores = makeScores();
-
-  it("renders as details element with category id", () => {
-    const html = renderCategory("pixel-critical", scores, [], "fk");
-    expect(html).toContain('id="cat-pixel-critical"');
-    expect(html).toContain("<details");
-    expect(html).toContain("</details>");
-  });
-
-  it("shows score badge with color class", () => {
-    const html = renderCategory("pixel-critical", scores, [], "fk");
-    expect(html).toContain('class="rpt-badge score-green"');
-    expect(html).toContain(">80<");
-  });
+describe("renderRuleSection", () => {
+  const issues = [
+    makeIssue({ ruleId: "no-auto-layout", category: "pixel-critical", severity: "blocking", score: -10, guide: "Icon wrappers excluded" }),
+    makeIssue({ ruleId: "no-auto-layout", category: "pixel-critical", severity: "blocking", score: -10, nodeId: "2-1" }),
+  ];
+  const rg = {
+    ruleId: "no-auto-layout",
+    ruleName: "No Auto Layout",
+    severity: "blocking" as const,
+    severityClass: "sev-blocking",
+    why: "Because layout", impact: "Breaks code", fix: "Apply auto-layout",
+    issues,
+    totalScore: -20,
+  };
 
-  it("shows No issues found when empty", () => {
-    const html = renderCategory("minor", scores, [], "fk");
-    expect(html).toContain("No issues found");
+  it("renders as details element with data-rule", () => {
+    const html = renderRuleSection(rg, "fk");
+    expect(html).toContain('<details class="card rpt-rule"');
+    expect(html).toContain('data-rule="no-auto-layout"');
   });
 
-  it("opens automatically when has blocking/risk issues", () => {
-    const issues = [makeIssue({ ruleId: "test", category: "pixel-critical", severity: "blocking" })];
-    const html = renderCategory("pixel-critical", scores, issues, "fk");
+  it("opens by default for blocking/risk", () => {
+    const html = renderRuleSection(rg, "fk");
     expect(html).toContain("open");
   });
 
-  it("stays closed when only suggestion issues", () => {
-    const issues = [makeIssue({ ruleId: "test", category: "minor", severity: "suggestion" })];
-    const html = renderCategory("minor", scores, issues, "fk");
+  it("stays closed for suggestion severity", () => {
+    const sugRg = { ...rg, severity: "suggestion" as const };
+    const html = renderRuleSection(sugRg, "fk");
     expect(html).not.toMatch(/details[^>]*\bopen\b/);
   });
 
-  it("renders chevron icon", () => {
-    const html = renderCategory("pixel-critical", scores, [], "fk");
-    expect(html).toContain('class="rpt-cat-chevron no-print"');
+  it("renders static Why/Impact/Fix in summary (always visible)", () => {
+    const html = renderRuleSection(rg, "fk");
+    expect(html).toContain("<strong>Why:</strong> Because layout");
+    expect(html).toContain("<strong>Impact:</strong> Breaks code");
+    expect(html).toContain("<strong>Fix:</strong> Apply auto-layout");
+    // These should be inside <summary>, not in the body
+    const summaryEnd = html.indexOf("</summary>");
+    const whyPos = html.indexOf("Because layout");
+    expect(whyPos).toBeLessThan(summaryEnd);
   });
-});
-
-// ---- renderSeverityGroup ----
 
-describe("renderSeverityGroup", () => {
-  const issues = [
-    makeIssue({ ruleId: "rule-a", category: "pixel-critical", severity: "blocking" }),
-    makeIssue({ ruleId: "rule-b", category: "pixel-critical", severity: "blocking", nodeId: "2-1" }),
-  ];
-
-  it("renders severity header with dot and label", () => {
-    const html = renderSeverityGroup("blocking", issues, "fk");
-    expect(html).toContain('class="rpt-dot-sm sev-blocking"');
-    expect(html).toContain("Blocking");
+  it("renders rule name, severity, issue count, total score", () => {
+    const html = renderRuleSection(rg, "fk");
+    expect(html).toContain("No Auto Layout");
+    expect(html).toContain("sev-blocking");
+    expect(html).toContain("2 issues");
+    expect(html).toContain(">-20<");
   });
 
-  it("renders issue count", () => {
-    const html = renderSeverityGroup("blocking", issues, "fk");
-    expect(html).toContain('class="rpt-sev-count">2<');
+  it("renders chevron", () => {
+    const html = renderRuleSection(rg, "fk");
+    expect(html).toContain('class="rpt-rule-chevron');
   });
 
-  it("renders all issue rows", () => {
-    const html = renderSeverityGroup("blocking", issues, "fk");
-    expect(html).toContain("rule a");
-    expect(html).toContain("rule b");
+  it("renders all issue rows inside", () => {
+    const html = renderRuleSection(rg, "fk");
+    expect(html).toContain("Issue: no-auto-layout");
+    expect(html.match(/class="rpt-issue"/g)?.length).toBe(2);
   });
 });
 
@@ -314,6 +307,7 @@ describe("renderIssueRow", () => {
     category: "pixel-critical",
     severity: "blocking",
     score: -10,
+    guide: "Icon wrappers are excluded",
   });
 
   it("renders as details element", () => {
@@ -321,32 +315,33 @@ describe("renderIssueRow", () => {
     expect(html).toContain('<details class="rpt-issue"');
   });
 
-  it("renders severity dot and score badge", () => {
+  it("renders message in summary", () => {
     const html = renderIssueRow(issue, "fk");
-    expect(html).toContain('class="rpt-dot-sm sev-blocking"');
-    expect(html).toContain('class="rpt-issue-score sev-blocking"');
-    expect(html).toContain(">-10<");
+    expect(html).toContain("Issue: no-auto-layout");
+    expect(html).toContain('class="rpt-issue-score');
   });
 
-  it("renders rule name and message", () => {
+  it("renders suggestion in body", () => {
     const html = renderIssueRow(issue, "fk");
-    expect(html).toContain('class="rpt-issue-name"');
-    expect(html).toContain("no auto layout");
-    expect(html).toContain("Issue: no-auto-layout");
+    expect(html).toContain('class="rpt-issue-suggestion"');
+    expect(html).toContain("Fix: no-auto-layout");
   });
 
-  it("renders node path", () => {
+  it("renders guide when present", () => {
     const html = renderIssueRow(issue, "fk");
-    expect(html).toContain('class="rpt-issue-path"');
-    expect(html).toContain("Root &gt; Frame &gt; Node");
+    expect(html).toContain('class="rpt-issue-guide"');
+    expect(html).toContain("Icon wrappers are excluded");
+  });
+
+  it("omits guide when absent", () => {
+    const noGuide = makeIssue({ ruleId: "test", category: "minor", severity: "suggestion" });
+    const html = renderIssueRow(noGuide, "fk");
+    expect(html).not.toContain("rpt-issue-guide");
   });
 
-  it("renders why/impact/fix", () => {
+  it("renders node path", () => {
     const html = renderIssueRow(issue, "fk");
-    expect(html).toContain("<strong>Why:</strong>");
-    expect(html).toContain("<strong>Impact:</strong>");
-    expect(html).toContain("<strong>Fix:</strong>");
-    expect(html).toContain("Because it matters");
+    expect(html).toContain("Root &gt; Frame &gt; Node");
   });
 
   it("renders Go to node link with data-node-id", () => {
@@ -363,22 +358,15 @@ describe("renderIssueRow", () => {
   it("renders comment button with figmaToken", () => {
     const html = renderIssueRow(issue, "fk", "figd_token");
     expect(html).toContain("Comment on Figma");
-    expect(html).toContain('data-file-key="fk"');
-    expect(html).toContain('data-message="Issue: no-auto-layout"');
-  });
-
-  it("escapes HTML in all user-facing strings", () => {
-    const xssIssue = makeIssue({
-      ruleId: "test",
-      category: "minor",
-      severity: "suggestion",
-    });
-    xssIssue.violation.message = '<img src=x onerror="alert(1)">';
-    xssIssue.violation.nodePath = '<script>alert("xss")</script>';
-    const html = renderIssueRow(xssIssue, "fk");
-    expect(html).not.toContain("<img ");
+  });
+
+  it("escapes HTML in user-facing strings", () => {
+    const xss = makeIssue({ ruleId: "test", category: "minor", severity: "suggestion" });
+    xss.violation.message = '<script>alert(1)</script>';
+    xss.violation.suggestion = '<img onerror="x">';
+    const html = renderIssueRow(xss, "fk");
     expect(html).not.toContain("<script>");
-    expect(html).toContain("&lt;img");
+    expect(html).not.toContain("<img ");
     expect(html).toContain("&lt;script&gt;");
   });
 });
@@ -391,12 +379,15 @@ describe("platform-neutral wording", () => {
     expect(html).not.toContain("Open in Figma");
     expect(html).toContain("Go to node");
   });
+});
 
-  it("uses Go to node in opportunities section", () => {
-    const data = makeReportData();
-    const html = renderReportBody(data);
-    // Check opportunities link text
-    expect(html).toContain("Go to node →");
-    expect(html).not.toContain("Figma →");
+// ---- Category order ----
+
+describe("category order", () => {
+  it("renders Minor before Interaction in tabs", () => {
+    const html = renderReportBody(makeReportData());
+    const minorPos = html.indexOf('data-tab="minor"');
+    const interactionPos = html.indexOf('data-tab="interaction"');
+    expect(minorPos).toBeLessThan(interactionPos);
   });
 });
diff --git a/src/core/report-html/render.ts b/src/core/report-html/render.ts
index ee25b155..eccd44bf 100644
--- a/src/core/report-html/render.ts
+++ b/src/core/report-html/render.ts
@@ -7,26 +7,22 @@
  * - Web app: CanICode.renderReportBody() → innerHTML
  * - Figma plugin: CanICode.renderReportBody() → innerHTML
  *
+ * Layout: category tabs → rule sections (static info) → node accordion (dynamic info)
  * Styled via self-contained CSS (app/shared/styles.css) — no Tailwind dependency.
  */
 
 import type { Category } from "../contracts/category.js";
-import type { Severity } from "../contracts/severity.js";
 import type { AnalysisIssue } from "../engine/rule-engine.js";
 import type { ScoreReport } from "../engine/scoring.js";
 import { buildFigmaDeepLink } from "../adapters/figma-url-parser.js";
 import {
   CATEGORIES,
   CATEGORY_LABELS,
-  SEVERITY_LABELS,
-  CATEGORY_DESCRIPTIONS,
-  SEVERITY_ORDER,
 } from "../ui-constants.js";
 import {
   escapeHtml,
   severityDot,
   severityBadge,
-  scoreBadgeStyle,
   renderGaugeSvg,
 } from "../ui-helpers.js";
 
@@ -42,6 +38,19 @@ export interface ReportData {
   figmaToken?: string;
 }
 
+/** Issues grouped by rule within a category */
+interface RuleGroup {
+  ruleId: string;
+  ruleName: string;
+  severity: string;
+  severityClass: string;
+  why: string;
+  impact: string;
+  fix: string;
+  issues: AnalysisIssue[];
+  totalScore: number;
+}
+
 // ---- Main render ----
 
 /**
@@ -50,8 +59,8 @@ export interface ReportData {
  */
 export function renderReportBody(data: ReportData): string {
   const { scores, issues, fileKey, figmaToken } = data;
-  const quickWins = getQuickWins(issues, 5);
   const issuesByCategory = groupIssuesByCategory(issues);
+  const ruleOpportunities = getTopRules(issues, 5);
 
   return `
     <!-- Overall Score -->
@@ -67,13 +76,13 @@ export function renderReportBody(data: ReportData): string {
     <!-- Category Gauges -->
     <section class="card rpt-gauges">
       <div class="rpt-gauges-grid">
-${CATEGORIES.map(cat => {
+${CATEGORIES.map((cat, i) => {
     const cs = scores.byCategory[cat];
-    return `        <a href="#cat-${cat}" class="rpt-gauge-item">
+    return `        <button type="button" class="rpt-gauge-item${i === 0 ? " active" : ""}" data-tab="${cat}">
           ${renderGaugeSvg(cs.percentage, 100, 7)}
           <span class="rpt-gauge-label">${CATEGORY_LABELS[cat]}</span>
           <span class="rpt-gauge-count">${cs.issueCount} issues</span>
-        </a>`;
+        </button>`;
   }).join("\n")}
       </div>
     </section>
@@ -92,11 +101,27 @@ ${CATEGORIES.map(cat => {
       </div>
     </section>
 
-${quickWins.length > 0 ? renderOpportunities(quickWins, fileKey) : ""}
+${ruleOpportunities.length > 0 ? renderOpportunities(ruleOpportunities) : ""}
+
+    <!-- Category Tabs -->
+    <div class="rpt-tabs">
+      <div class="rpt-tab-list" role="tablist">
+${CATEGORIES.map((cat, i) => {
+    const cs = scores.byCategory[cat];
+    return `        <button type="button" role="tab" class="rpt-tab${i === 0 ? " active" : ""}" data-tab="${cat}" aria-selected="${i === 0}">${CATEGORY_LABELS[cat]} <span class="rpt-tab-count">${cs.issueCount}</span></button>`;
+  }).join("\n")}
+      </div>
 
-    <!-- Categories -->
-    <div class="rpt-cats">
-${CATEGORIES.map(cat => renderCategory(cat, scores, issuesByCategory.get(cat) ?? [], fileKey, figmaToken)).join("\n")}
+${CATEGORIES.map((cat, i) => {
+    const catIssues = issuesByCategory.get(cat) ?? [];
+    const ruleGroups = groupIssuesByRule(catIssues);
+    return `      <div class="rpt-tab-panel${i === 0 ? " active" : ""}" data-panel="${cat}" role="tabpanel">
+${ruleGroups.length === 0
+    ? '        <div class="rpt-cat-empty">No issues found</div>'
+    : ruleGroups.map(rg => renderRuleSection(rg, fileKey, figmaToken)).join("\n")
+}
+      </div>`;
+  }).join("\n")}
     </div>
 
     <!-- Footer -->
@@ -116,8 +141,8 @@ export function renderSummaryDot(sevClass: string, count: number, label: string)
         </div>`;
 }
 
-export function renderOpportunities(issues: AnalysisIssue[], fileKey: string): string {
-  const maxAbs = issues.reduce((m, i) => Math.max(m, Math.abs(i.calculatedScore)), 1);
+export function renderOpportunities(ruleGroups: RuleGroup[]): string {
+  const maxAbs = ruleGroups.reduce((m, rg) => Math.max(m, Math.abs(rg.totalScore)), 1);
   return `
     <!-- Opportunities -->
     <section class="card rpt-opps">
@@ -126,84 +151,56 @@ export function renderOpportunities(issues: AnalysisIssue[], fileKey: string): s
           <span class="rpt-dot sev-blocking"></span>
           Opportunities
         </h2>
-        <p class="rpt-opps-desc">Top blocking issues — fix these first for the biggest improvement.</p>
+        <p class="rpt-opps-desc">Top impact rules — fix these first for the biggest improvement.</p>
       </div>
       <div class="rpt-opps-list">
-${issues.map(issue => {
-    const def = issue.rule.definition;
-    const link = buildFigmaDeepLink(fileKey, issue.violation.nodeId);
-    const barW = Math.round((Math.abs(issue.calculatedScore) / maxAbs) * 100);
-    return `        <div class="rpt-opps-item">
+${ruleGroups.map(rg => {
+    const barW = Math.round((Math.abs(rg.totalScore) / maxAbs) * 100);
+    const cat = rg.issues[0]?.rule.definition.category ?? "";
+    return `        <div class="rpt-opps-item" data-opp-rule="${esc(rg.ruleId)}" data-opp-cat="${cat}" style="cursor:pointer">
           <div class="rpt-opps-info">
-            <div class="rpt-opps-name">${esc(def.name)}</div>
-            <div class="rpt-opps-msg">${esc(issue.violation.message)}</div>
+            <div class="rpt-opps-name">${esc(rg.ruleName)}</div>
+            <div class="rpt-opps-msg">${rg.issues.length} issues</div>
           </div>
           <div class="rpt-opps-bar-wrap">
             <div class="rpt-opps-bar">
               <div class="rpt-opps-bar-fill" style="width:${barW}%"></div>
             </div>
-            <span class="rpt-opps-score">${issue.calculatedScore}</span>
+            <span class="rpt-opps-score">${rg.totalScore}</span>
           </div>
-          <a href="${link}" target="_blank" rel="noopener" data-node-id="${esc(issue.violation.nodeId)}" class="rpt-opps-link no-print">Go to node →</a>
         </div>`;
   }).join("\n")}
       </div>
     </section>`;
 }
 
-export function renderCategory(
-  cat: Category,
-  scores: ScoreReport,
-  issues: AnalysisIssue[],
+export function renderRuleSection(
+  rg: RuleGroup,
   fileKey: string,
   figmaToken?: string
 ): string {
-  const cs = scores.byCategory[cat];
-  const hasProblems = issues.some(i => i.config.severity === "blocking" || i.config.severity === "risk");
-
-  const bySeverity = new Map<Severity, AnalysisIssue[]>();
-  for (const sev of SEVERITY_ORDER) bySeverity.set(sev, []);
-  for (const issue of issues) bySeverity.get(issue.config.severity)?.push(issue);
-
-  return `
-      <details id="cat-${cat}" class="card rpt-cat"${hasProblems ? " open" : ""}>
-        <summary class="rpt-cat-header">
-          <span class="rpt-badge ${scoreBadgeStyle(cs.percentage)}">${cs.percentage}</span>
-          <div class="rpt-cat-info">
-            <div class="rpt-cat-name">${CATEGORY_LABELS[cat]}</div>
-            <div class="rpt-cat-desc">${esc(CATEGORY_DESCRIPTIONS[cat])}</div>
+  const isOpen = rg.severity === "blocking" || rg.severity === "risk";
+  return `        <details class="card rpt-rule" data-rule="${esc(rg.ruleId)}"${isOpen ? " open" : ""}>
+          <summary class="rpt-rule-header">
+            <span class="rpt-badge score-red">${rg.totalScore}</span>
+            <span class="rpt-rule-title">
+              <span class="rpt-rule-name">${esc(rg.ruleName)}</span>
+              <span class="rpt-rule-meta">
+                <span class="rpt-dot-sm ${rg.severityClass}"></span>
+                ${esc(rg.severity)} · ${rg.issues.length} issues
+              </span>
+              <span class="rpt-rule-info">
+                <span class="rpt-rule-info-line"><strong>Why:</strong> ${esc(rg.why)}</span>
+                <span class="rpt-rule-info-line"><strong>Impact:</strong> ${esc(rg.impact)}</span>
+                <span class="rpt-rule-info-line"><strong>Fix:</strong> ${esc(rg.fix)}</span>
+              </span>
+            </span>
+            <svg class="rpt-rule-chevron no-print" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2"><path d="M19 9l-7 7-7-7"/></svg>
+          </summary>
+          <div class="rpt-rule-issues">
+${rg.issues.map(issue => renderIssueRow(issue, fileKey, figmaToken)).join("\n")}
           </div>
-          <span class="rpt-cat-count">${cs.issueCount} issues</span>
-          <svg class="rpt-cat-chevron no-print" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2"><path d="M19 9l-7 7-7-7"/></svg>
-        </summary>
-        <div class="rpt-cat-body">
-${issues.length === 0
-    ? '          <div class="rpt-cat-empty">No issues found</div>'
-    : SEVERITY_ORDER
-        .filter(sev => (bySeverity.get(sev)?.length ?? 0) > 0)
-        .map(sev => renderSeverityGroup(sev, bySeverity.get(sev) ?? [], fileKey, figmaToken))
-        .join("\n")
-}
-        </div>
-      </details>`;
-}
-
-export function renderSeverityGroup(
-  sev: Severity,
-  issues: AnalysisIssue[],
-  fileKey: string,
-  figmaToken?: string
-): string {
-  return `          <div class="rpt-sev-group">
-            <div class="rpt-sev-header">
-              <span class="rpt-dot-sm ${severityDot(sev)}"></span>
-              <span class="rpt-sev-label">${SEVERITY_LABELS[sev]}</span>
-              <span class="rpt-sev-count">${issues.length}</span>
-            </div>
-            <div class="rpt-sev-issues">
-${issues.map(issue => renderIssueRow(issue, fileKey, figmaToken)).join("\n")}
-            </div>
-          </div>`;
+        </details>`;
 }
 
 export function renderIssueRow(
@@ -212,37 +209,113 @@ export function renderIssueRow(
   figmaToken?: string
 ): string {
   const sev = issue.config.severity;
-  const def = issue.rule.definition;
-  const link = buildFigmaDeepLink(fileKey, issue.violation.nodeId);
+  const v = issue.violation;
+  const link = buildFigmaDeepLink(fileKey, v.nodeId);
 
-  return `              <details class="rpt-issue">
-                <summary class="rpt-issue-header">
-                  <span class="rpt-dot-sm ${severityDot(sev)}"></span>
-                  <span class="rpt-issue-name">${esc(def.name)}</span>
-                  <span class="rpt-issue-msg">${esc(issue.violation.message)}</span>
-                  <span class="rpt-issue-score ${severityBadge(sev)}">${issue.calculatedScore}</span>
-                </summary>
-                <div class="rpt-issue-body">
-                  <div class="rpt-issue-path">${esc(issue.violation.nodePath)}</div>
-                  <div class="rpt-issue-info">
-                    <p><strong>Why:</strong> ${esc(def.why)}</p>
-                    <p><strong>Impact:</strong> ${esc(def.impact)}</p>
-                    <p><strong>Fix:</strong> ${esc(def.fix)}</p>
-                  </div>
-                  <div class="rpt-issue-actions no-print">
-                    <a href="${link}" target="_blank" rel="noopener" data-node-id="${esc(issue.violation.nodeId)}" class="rpt-btn">Go to node <span>→</span></a>${figmaToken ? `
-                    <button onclick="postComment(this)" data-file-key="${esc(fileKey)}" data-node-id="${esc(issue.violation.nodeId)}" data-message="${esc(issue.violation.message)}" class="rpt-btn">Comment on Figma</button>` : ""}
-                  </div>
+  return `            <details class="rpt-issue">
+              <summary class="rpt-issue-header">
+                <span class="rpt-issue-msg">${esc(v.message)}</span>
+                <span class="rpt-issue-score ${severityBadge(sev)}">${issue.calculatedScore}</span>
+              </summary>
+              <div class="rpt-issue-body">
+                <div class="rpt-issue-suggestion">${esc(v.suggestion)}</div>${v.guide ? `
+                <div class="rpt-issue-guide">${esc(v.guide)}</div>` : ""}
+                <div class="rpt-issue-path">${esc(v.nodePath)}</div>
+                <div class="rpt-issue-actions no-print">
+                  <a href="${link}" target="_blank" rel="noopener" data-node-id="${esc(v.nodeId)}" class="rpt-btn">Go to node <span>→</span></a>${figmaToken ? `
+                  <button onclick="postComment(this)" data-file-key="${esc(fileKey)}" data-node-id="${esc(v.nodeId)}" data-message="${esc(v.message)} — ${esc(v.suggestion)}" class="rpt-btn">Comment on Figma</button>` : ""}
                 </div>
-              </details>`;
+              </div>
+            </details>`;
 }
 
+// ---- Interactions ----
+
+/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access */
+
+/**
+ * Initialize tab switching + navigation for a rendered report.
+ * Call after inserting renderReportBody() HTML into a container.
+ * Uses 'any' to avoid DOM type dependency (this file targets Node.js).
+ */
+export function initReportInteractions(container: any): void {
+  // Remove previous handler if re-initialized (e.g., re-analysis)
+  if (container._rptHandler) {
+    container.removeEventListener("click", container._rptHandler);
+  }
+  function activate(cat: string, scrollTo: boolean) {
+    container.querySelectorAll(".rpt-tab").forEach((t: any) => {
+      const active = t.dataset.tab === cat;
+      t.classList.toggle("active", active);
+      t.setAttribute("aria-selected", String(active));
+    });
+    container.querySelectorAll(".rpt-tab-panel").forEach((p: any) => {
+      p.classList.toggle("active", p.dataset.panel === cat);
+    });
+    container.querySelectorAll(".rpt-gauge-item").forEach((g: any) => {
+      g.classList.toggle("active", g.dataset.tab === cat);
+    });
+    if (scrollTo) {
+      const tabList = container.querySelector(".rpt-tab-list");
+      if (tabList) tabList.scrollIntoView({ behavior: "smooth", block: "start" });
+    }
+  }
+  function focusRule(ruleId: string) {
+    const el = container.querySelector('[data-rule="' + ruleId + '"]');
+    if (el) {
+      el.open = true;
+      setTimeout(() => el.scrollIntoView({ behavior: "smooth", block: "start" }), 50);
+    }
+  }
+  const handler = (e: any) => {
+    const tab = e.target.closest("[data-tab]");
+    if (tab) {
+      const isGauge = tab.classList.contains("rpt-gauge-item");
+      activate(tab.dataset.tab ?? "", isGauge);
+      return;
+    }
+    const opp = e.target.closest("[data-opp-rule]");
+    if (opp) {
+      const cat = opp.dataset.oppCat ?? "";
+      const rule = opp.dataset.oppRule ?? "";
+      if (cat) activate(cat, false);
+      setTimeout(() => focusRule(rule), 50);
+    }
+  };
+  container._rptHandler = handler;
+  container.addEventListener("click", handler);
+}
+
+/* eslint-enable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access */
+
 // ---- Utils ----
 
-function getQuickWins(issues: AnalysisIssue[], limit: number): AnalysisIssue[] {
-  return issues
-    .filter(issue => issue.config.severity === "blocking")
-    .sort((a, b) => a.calculatedScore - b.calculatedScore)
+/** Get top N rules by total score impact */
+function getTopRules(issues: AnalysisIssue[], limit: number): RuleGroup[] {
+  const byRule = new Map<string, RuleGroup>();
+  for (const issue of issues) {
+    const id = issue.rule.definition.id;
+    let group = byRule.get(id);
+    if (!group) {
+      const def = issue.rule.definition;
+      group = {
+        ruleId: id,
+        ruleName: def.name,
+        severity: issue.config.severity,
+        severityClass: severityDot(issue.config.severity),
+        why: def.why,
+        impact: def.impact,
+        fix: def.fix,
+        issues: [],
+        totalScore: 0,
+      };
+      byRule.set(id, group);
+    }
+    group.issues.push(issue);
+    group.totalScore += issue.calculatedScore;
+  }
+  return [...byRule.values()]
+    .sort((a, b) => a.totalScore - b.totalScore)
     .slice(0, limit);
 }
 
@@ -253,4 +326,36 @@ function groupIssuesByCategory(issues: AnalysisIssue[]): Map<Category, AnalysisI
   return grouped;
 }
 
+/** Group issues by rule within a category, sorted by severity then score */
+function groupIssuesByRule(issues: AnalysisIssue[]): RuleGroup[] {
+  const byRule = new Map<string, RuleGroup>();
+  for (const issue of issues) {
+    const id = issue.rule.definition.id;
+    let group = byRule.get(id);
+    if (!group) {
+      const def = issue.rule.definition;
+      group = {
+        ruleId: id,
+        ruleName: def.name,
+        severity: issue.config.severity,
+        severityClass: severityDot(issue.config.severity),
+        why: def.why,
+        impact: def.impact,
+        fix: def.fix,
+        issues: [],
+        totalScore: 0,
+      };
+      byRule.set(id, group);
+    }
+    group.issues.push(issue);
+    group.totalScore += issue.calculatedScore;
+  }
+
+  const SEVERITY_RANK: Record<string, number> = { blocking: 0, risk: 1, "missing-info": 2, suggestion: 3 };
+  return [...byRule.values()].sort((a, b) => {
+    const sevDiff = (SEVERITY_RANK[a.severity] ?? 4) - (SEVERITY_RANK[b.severity] ?? 4);
+    return sevDiff !== 0 ? sevDiff : a.totalScore - b.totalScore;
+  });
+}
+
 const esc = escapeHtml;
diff --git a/src/core/rules/component/index.ts b/src/core/rules/component/index.ts
index 31f5bcfa..46c561d3 100644
--- a/src/core/rules/component/index.ts
+++ b/src/core/rules/component/index.ts
@@ -136,18 +136,17 @@ const missingComponentCheck: RuleCheckFn = (node, context, options) => {
         sameNameFrames &&
         firstFrame !== undefined &&
         sameNameFrames.length >= 2 &&
-        !seenStage1.has(node.name.toLowerCase())
+        !seenStage1.has(node.name.toLowerCase()) &&
+        firstFrame === node.id
       ) {
         seenStage1.add(node.name.toLowerCase());
-        if (firstFrame === node.id) {
-          return {
-            ruleId: missingComponentDef.id,
-            subType: "unused-component" as const,
-            nodeId: node.id,
-            nodePath: context.path.join(" > "),
-            message: missingComponentMsg.unusedComponent(matchingComponent.name, sameNameFrames.length),
-          };
-        }
+        return {
+          ruleId: missingComponentDef.id,
+          subType: "unused-component" as const,
+          nodeId: node.id,
+          nodePath: context.path.join(" > "),
+          ...missingComponentMsg.unusedComponent(matchingComponent.name, sameNameFrames.length),
+        };
       }
     }
 
@@ -163,7 +162,7 @@ const missingComponentCheck: RuleCheckFn = (node, context, options) => {
           subType: "name-repetition" as const,
           nodeId: node.id,
           nodePath: context.path.join(" > "),
-          message: missingComponentMsg.nameRepetition(node.name, sameNameFrames.length),
+          ...missingComponentMsg.nameRepetition(node.name, sameNameFrames.length),
         };
       }
     }
@@ -225,7 +224,7 @@ const missingComponentCheck: RuleCheckFn = (node, context, options) => {
           subType: "structure-repetition" as const,
           nodeId: node.id,
           nodePath: context.path.join(" > "),
-          message: missingComponentMsg.structureRepetition(node.name, count - 1),
+          ...missingComponentMsg.structureRepetition(node.name, count - 1),
         };
       }
     }
@@ -262,7 +261,7 @@ const missingComponentCheck: RuleCheckFn = (node, context, options) => {
         subType: "style-override" as const,
         nodeId: node.id,
         nodePath: context.path.join(" > "),
-        message: missingComponentMsg.styleOverride(componentName, overrides),
+        ...missingComponentMsg.styleOverride(componentName, overrides),
       };
     }
     return null;
@@ -306,7 +305,7 @@ const detachedInstanceCheck: RuleCheckFn = (node, context) => {
         ruleId: detachedInstanceDef.id,
         nodeId: node.id,
         nodePath: context.path.join(" > "),
-        message: detachedInstanceMsg(node.name, component.name),
+        ...detachedInstanceMsg(node.name, component.name),
       };
     }
   }
@@ -357,7 +356,7 @@ const variantStructureMismatchCheck: RuleCheckFn = (node, context) => {
     ruleId: variantStructureMismatchDef.id,
     nodeId: node.id,
     nodePath: context.path.join(" > "),
-    message: variantStructureMismatchMsg(node.name, mismatchCount, totalVariants),
+    ...variantStructureMismatchMsg(node.name, mismatchCount, totalVariants),
   };
 };
 
diff --git a/src/core/rules/component/missing-component.test.ts b/src/core/rules/component/missing-component.test.ts
index 17b2bd18..e5867f89 100644
--- a/src/core/rules/component/missing-component.test.ts
+++ b/src/core/rules/component/missing-component.test.ts
@@ -112,7 +112,7 @@ describe("missing-component — Stage 1: Component exists but not used", () => {
     expect(result).not.toBeNull();
     expect(result!.ruleId).toBe("missing-component");
     expect(result!.message).toContain('Component "Button" exists');
-    expect(result!.message).toContain("2 found");
+    expect(result!.suggestion).toContain("Replace frames with component instances");
   });
 
   it("only flags first occurrence (dedup)", () => {
@@ -298,7 +298,7 @@ describe("missing-component — Stage 3: Structure-based repetition", () => {
     expect(result!.ruleId).toBe("missing-component");
     expect(result!.message).toContain("Card A");
     expect(result!.message).toContain("1 sibling frame(s)");
-    expect(result!.message).toContain("extract a shared component");
+    expect(result!.suggestion).toContain("Extract a shared component");
   });
 
   it("only flags first matching sibling", () => {
@@ -535,7 +535,7 @@ describe("missing-component — Stage 4: Instance style overrides", () => {
     expect(result).not.toBeNull();
     expect(result!.message).toContain("Button");
     expect(result!.message).toContain("fills");
-    expect(result!.message).toContain("create a new variant");
+    expect(result!.suggestion).toContain("Create a new variant");
   });
 
   it("flags when instance has different cornerRadius from master", () => {
diff --git a/src/core/rules/interaction/index.ts b/src/core/rules/interaction/index.ts
index 8b53764f..1eb53aaa 100644
--- a/src/core/rules/interaction/index.ts
+++ b/src/core/rules/interaction/index.ts
@@ -115,7 +115,7 @@ const missingInteractionStateCheck: RuleCheckFn = (node, context) => {
       subType: state,
       nodeId: node.id,
       nodePath,
-      message: missingInteractionStateMsg[state](node.name),
+      ...missingInteractionStateMsg[state](node.name),
     };
   }
 
@@ -221,7 +221,7 @@ const missingPrototypeCheck: RuleCheckFn = (node, context) => {
     subType,
     nodeId: node.id,
     nodePath: context.path.join(" > "),
-    message: missingPrototypeMsg[subType](node.name),
+    ...missingPrototypeMsg[subType](node.name),
   };
 };
 
diff --git a/src/core/rules/naming/index.ts b/src/core/rules/naming/index.ts
index 0d784c5d..c4a77f12 100644
--- a/src/core/rules/naming/index.ts
+++ b/src/core/rules/naming/index.ts
@@ -37,7 +37,7 @@ const nonSemanticNameCheck: RuleCheckFn = (node, context) => {
       subType: getDefaultNameSubType(node.type),
       nodeId: node.id,
       nodePath: context.path.join(" > "),
-      message: nonSemanticNameMsg(node.type, node.name),
+      ...nonSemanticNameMsg(node.type, node.name),
     };
   }
 
@@ -54,7 +54,7 @@ const nonSemanticNameCheck: RuleCheckFn = (node, context) => {
       subType: "shape-name" as const,
       nodeId: node.id,
       nodePath: context.path.join(" > "),
-      message: nonSemanticNameMsg(node.type, node.name),
+      ...nonSemanticNameMsg(node.type, node.name),
     };
   }
 
@@ -113,7 +113,7 @@ const inconsistentNamingConventionCheck: RuleCheckFn = (node, context) => {
       ruleId: inconsistentNamingConventionDef.id,
       nodeId: node.id,
       nodePath: context.path.join(" > "),
-      message: inconsistentNamingMsg(node.name, nodeConvention, dominantConvention),
+      ...inconsistentNamingMsg(node.name, nodeConvention, dominantConvention),
     };
   }
 
@@ -165,7 +165,7 @@ const nonStandardNamingCheck: RuleCheckFn = (node, context) => {
             subType: "state-name" as const,
             nodeId: node.id,
             nodePath: context.path.join(" > "),
-            message: nonStandardNamingMsg.stateName(node.name, opt, suggestion),
+            ...nonStandardNamingMsg.stateName(node.name, opt, suggestion),
           };
         }
       }
diff --git a/src/core/rules/naming/non-standard-naming.test.ts b/src/core/rules/naming/non-standard-naming.test.ts
index 42274e2f..3022a5b0 100644
--- a/src/core/rules/naming/non-standard-naming.test.ts
+++ b/src/core/rules/naming/non-standard-naming.test.ts
@@ -23,7 +23,7 @@ describe("non-standard-naming", () => {
     expect(result).not.toBeNull();
     expect(result!.subType).toBe("state-name");
     expect(result!.message).toContain("Clicked");
-    expect(result!.message).toContain("pressed");
+    expect(result!.suggestion).toContain("pressed");
   });
 
   it("flags 'On' → suggests 'active'", () => {
@@ -40,7 +40,7 @@ describe("non-standard-naming", () => {
 
     expect(result).not.toBeNull();
     expect(result!.message).toContain("On");
-    expect(result!.message).toContain("active");
+    expect(result!.suggestion).toContain("active");
   });
 
   it("flags 'Inactive' → suggests 'disabled'", () => {
@@ -57,7 +57,7 @@ describe("non-standard-naming", () => {
 
     expect(result).not.toBeNull();
     expect(result!.message).toContain("Inactive");
-    expect(result!.message).toContain("disabled");
+    expect(result!.suggestion).toContain("disabled");
   });
 
   it("passes when all state names are standard", () => {
diff --git a/src/core/rules/rule-messages.ts b/src/core/rules/rule-messages.ts
index 57ad9837..5d524495 100644
--- a/src/core/rules/rule-messages.ts
+++ b/src/core/rules/rule-messages.ts
@@ -1,8 +1,21 @@
 /**
  * Centralized rule violation messages.
  * All message text lives here so CLI, web, plugin, and MCP share the same strings.
+ *
+ * Each message function returns { message, suggestion, guide? }:
+ * - message: what's wrong (node-specific, dynamic)
+ * - suggestion: how to fix it (node-specific, dynamic)
+ * - guide: exemption hint (optional, when the rule auto-excludes certain cases)
  */
 
+// ── Message return type ─────────────────────────────────────────────────────
+
+export interface ViolationMsg {
+  message: string;
+  suggestion: string;
+  guide?: string;
+}
+
 // ── Sub-type definitions ─────────────────────────────────────────────────────
 
 export type RawValueSubType = "color" | "font" | "shadow" | "opacity" | "spacing";
@@ -13,48 +26,76 @@ export type MissingComponentSubType = "unused-component" | "name-repetition" | "
 // ── raw-value ────────────────────────────────────────────────────────────────
 
 export const rawValueMsg = {
-  color: (name: string, hex: string) =>
-    `"${name}" uses raw fill color ${hex} without style or variable — bind to a color token`,
-  font: (name: string, fontDesc: string) =>
-    `"${name}" uses raw font${fontDesc} without text style — apply a text style`,
-  shadow: (name: string, shadowType: string, details: string) =>
-    `"${name}" has ${shadowType}${details} without effect style — apply an effect style`,
-  opacity: (name: string, pct: number) =>
-    `"${name}" uses raw opacity (${pct}%) without a variable binding — bind opacity to a variable`,
-  spacing: (name: string, label: string, value: number) =>
-    `"${name}" uses raw ${label} (${value}px) without a variable binding — bind spacing to a variable`,
+  color: (name: string, hex: string): ViolationMsg => ({
+    message: `"${name}" uses raw fill color ${hex} without style or variable`,
+    suggestion: `Bind to a color token`,
+  }),
+  font: (name: string, fontDesc: string): ViolationMsg => ({
+    message: `"${name}" uses raw font${fontDesc} without text style`,
+    suggestion: `Apply a text style`,
+  }),
+  shadow: (name: string, shadowType: string, details: string): ViolationMsg => ({
+    message: `"${name}" has ${shadowType}${details} without effect style`,
+    suggestion: `Apply an effect style`,
+  }),
+  opacity: (name: string, pct: number): ViolationMsg => ({
+    message: `"${name}" uses raw opacity (${pct}%) without a variable binding`,
+    suggestion: `Bind opacity to a variable`,
+  }),
+  spacing: (name: string, label: string, value: number): ViolationMsg => ({
+    message: `"${name}" uses raw ${label} (${value}px) without a variable binding`,
+    suggestion: `Bind spacing to a variable`,
+  }),
 };
 
 // ── irregular-spacing ────────────────────────────────────────────────────────
 
 export type IrregularSpacingSubType = "padding" | "gap";
 
-export const irregularSpacingMsg = (name: string, spacing: number, gridBase: number, nearest: number) =>
-  `"${name}" has spacing ${spacing}px not on ${gridBase}pt grid — round to nearest ${gridBase}pt multiple (${nearest}px)`;
+export const irregularSpacingMsg = (name: string, spacing: number, gridBase: number, nearest: number): ViolationMsg => ({
+  message: `"${name}" has spacing ${spacing}px not on ${gridBase}pt grid`,
+  suggestion: `Round to nearest ${gridBase}pt multiple (${nearest}px)`,
+});
 
 // ── no-auto-layout ───────────────────────────────────────────────────────────
 
 export const noAutoLayoutMsg = {
-  overlapping: (name: string) =>
-    `"${name}" has overlapping children without Auto Layout — apply auto-layout to separate overlapping children`,
-  nested: (name: string) =>
-    `"${name}" has nested containers without layout hints — apply auto-layout to organize nested containers`,
-  basic: (name: string, arrangement: string, directionHint: string) =>
-    `Frame "${name}" has no auto-layout${arrangement}${directionHint ? ` — apply ${directionHint} auto-layout` : " — apply auto-layout"}`,
+  overlapping: (name: string): ViolationMsg => ({
+    message: `"${name}" has overlapping children without Auto Layout`,
+    suggestion: `Apply auto-layout to separate overlapping children`,
+    guide: `If this is an intentional overlay (e.g., badge on avatar), this can be ignored`,
+  }),
+  nested: (name: string): ViolationMsg => ({
+    message: `"${name}" has nested containers without layout hints`,
+    suggestion: `Apply auto-layout to organize nested containers`,
+    guide: `Icon wrappers containing only vectors are automatically excluded`,
+  }),
+  basic: (name: string, arrangement: string, directionHint: string): ViolationMsg => ({
+    message: `Frame "${name}" has no auto-layout${arrangement}`,
+    suggestion: directionHint ? `Apply ${directionHint} auto-layout` : `Apply auto-layout`,
+    guide: `Single-child wrappers and icon containers are automatically excluded`,
+  }),
 };
 
 // ── absolute-position-in-auto-layout ─────────────────────────────────────────
 
-export const absolutePositionMsg = (name: string, parentName: string) =>
-  `"${name}" uses absolute positioning inside Auto Layout parent "${parentName}" — remove absolute positioning or restructure outside the auto-layout parent`;
+export const absolutePositionMsg = (name: string, parentName: string): ViolationMsg => ({
+  message: `"${name}" uses absolute positioning inside Auto Layout parent "${parentName}"`,
+  suggestion: `Remove absolute positioning or restructure outside the auto-layout parent`,
+  guide: `If this is a badge or overlay, name it with "badge", "overlay", or "icon" to auto-exclude`,
+});
 
 // ── fixed-size-in-auto-layout ────────────────────────────────────────────────
 
 export const fixedSizeMsg = {
-  bothAxes: (name: string, width: number, height: number) =>
-    `Container "${name}" (${width}×${height}) uses fixed size on both axes inside auto-layout — set at least one axis to HUG or FILL`,
-  horizontal: (name: string, width: number) =>
-    `"${name}" has fixed width (${width}px) inside auto-layout — set horizontal sizing to FILL`,
+  bothAxes: (name: string, width: number, height: number): ViolationMsg => ({
+    message: `Container "${name}" (${width}×${height}) uses fixed size on both axes inside auto-layout`,
+    suggestion: `Set at least one axis to HUG or FILL`,
+  }),
+  horizontal: (name: string, width: number): ViolationMsg => ({
+    message: `"${name}" has fixed width (${width}px) inside auto-layout`,
+    suggestion: `Set horizontal sizing to FILL`,
+  }),
 };
 
 // ── missing-size-constraint ──────────────────────────────────────────────────
@@ -62,14 +103,22 @@ export const fixedSizeMsg = {
 export type MissingSizeConstraintSubType = "max-width" | "min-width" | "wrap" | "grid";
 
 export const missingSizeConstraintMsg = {
-  maxWidth: (name: string, currentWidth: string) =>
-    `"${name}" uses FILL width (currently ${currentWidth}) without max-width — add maxWidth to prevent stretching on large screens`,
-  minWidth: (name: string, currentWidth: string) =>
-    `"${name}" uses FILL width (currently ${currentWidth}) without min-width — add minWidth to prevent collapsing on small screens`,
-  wrap: (name: string) =>
-    `"${name}" is in a wrap container without min-width — add minWidth to control when wrapping occurs`,
-  grid: (name: string) =>
-    `"${name}" is in a grid layout without size constraints — add min/max-width for proper column sizing`,
+  maxWidth: (name: string, currentWidth: string): ViolationMsg => ({
+    message: `"${name}" uses FILL width (currently ${currentWidth}) without max-width`,
+    suggestion: `Add maxWidth to prevent stretching on large screens`,
+  }),
+  minWidth: (name: string, currentWidth: string): ViolationMsg => ({
+    message: `"${name}" uses FILL width (currently ${currentWidth}) without min-width`,
+    suggestion: `Add minWidth to prevent collapsing on small screens`,
+  }),
+  wrap: (name: string): ViolationMsg => ({
+    message: `"${name}" is in a wrap container without min-width`,
+    suggestion: `Add minWidth to control when wrapping occurs`,
+  }),
+  grid: (name: string): ViolationMsg => ({
+    message: `"${name}" is in a grid layout without size constraints`,
+    suggestion: `Add min/max-width for proper column sizing`,
+  }),
 };
 
 // ── non-layout-container (was group-usage) ───────────────────────────────────
@@ -77,47 +126,67 @@ export const missingSizeConstraintMsg = {
 export type NonLayoutContainerSubType = "group" | "section";
 
 export const nonLayoutContainerMsg = {
-  group: (name: string) =>
-    `"${name}" is a Group — convert to Frame and apply auto-layout`,
-  section: (name: string) =>
-    `"${name}" is a Section used as layout container — convert to Frame and apply auto-layout`,
+  group: (name: string): ViolationMsg => ({
+    message: `"${name}" is a Group`,
+    suggestion: `Convert to Frame and apply auto-layout`,
+  }),
+  section: (name: string): ViolationMsg => ({
+    message: `"${name}" is a Section used as layout container`,
+    suggestion: `Convert to Frame and apply auto-layout`,
+  }),
 };
 
 // ── deep-nesting ─────────────────────────────────────────────────────────────
 
-export const deepNestingMsg = (name: string, depth: number, maxDepth: number) =>
-  `"${name}" is nested ${depth} levels deep within its component (max: ${maxDepth}) — extract into a sub-component to reduce depth`;
+export const deepNestingMsg = (name: string, depth: number, maxDepth: number): ViolationMsg => ({
+  message: `"${name}" is nested ${depth} levels deep within its component (max: ${maxDepth})`,
+  suggestion: `Extract into a sub-component to reduce depth`,
+});
 
 // ── missing-component ────────────────────────────────────────────────────────
 
 export const missingComponentMsg = {
-  unusedComponent: (componentName: string, count: number) =>
-    `Component "${componentName}" exists — use instances instead of repeated frames (${count} found) — replace frames with component instances`,
-  nameRepetition: (name: string, count: number) =>
-    `"${name}" appears ${count} times — extract as a reusable component`,
-  structureRepetition: (name: string, siblingCount: number) =>
-    `"${name}" and ${siblingCount} sibling frame(s) share the same internal structure — extract a shared component from the repeated structure`,
-  styleOverride: (componentName: string, overrides: string[]) =>
-    `"${componentName}" instance has style overrides (${overrides.join(", ")}) — create a new variant for this style combination`,
+  unusedComponent: (componentName: string, count: number): ViolationMsg => ({
+    message: `Component "${componentName}" exists but ${count} repeated frames found instead of instances`,
+    suggestion: `Replace frames with component instances`,
+  }),
+  nameRepetition: (name: string, count: number): ViolationMsg => ({
+    message: `"${name}" appears ${count} times`,
+    suggestion: `Extract as a reusable component`,
+  }),
+  structureRepetition: (name: string, siblingCount: number): ViolationMsg => ({
+    message: `"${name}" and ${siblingCount} sibling frame(s) share the same internal structure`,
+    suggestion: `Extract a shared component from the repeated structure`,
+  }),
+  styleOverride: (componentName: string, overrides: string[]): ViolationMsg => ({
+    message: `"${componentName}" instance has style overrides (${overrides.join(", ")})`,
+    suggestion: `Create a new variant for this style combination`,
+  }),
 };
 
 // ── detached-instance ────────────────────────────────────────────────────────
 
-export const detachedInstanceMsg = (name: string, componentName: string) =>
-  `"${name}" may be a detached instance of component "${componentName}" — restore as an instance of "${componentName}" or create a new variant`;
+export const detachedInstanceMsg = (name: string, componentName: string): ViolationMsg => ({
+  message: `"${name}" may be a detached instance of component "${componentName}"`,
+  suggestion: `Restore as an instance of "${componentName}" or create a new variant`,
+});
 
 // ── variant-structure-mismatch ───────────────────────────────────────────────
 
-export const variantStructureMismatchMsg = (name: string, mismatchCount: number, totalVariants: number) =>
-  `"${name}" has ${mismatchCount}/${totalVariants} variants with different child structures — unify variant structures using visibility toggles for optional elements`;
+export const variantStructureMismatchMsg = (name: string, mismatchCount: number, totalVariants: number): ViolationMsg => ({
+  message: `"${name}" has ${mismatchCount}/${totalVariants} variants with different child structures`,
+  suggestion: `Unify variant structures using visibility toggles for optional elements`,
+});
 
 // ── non-standard-naming ──────────────────────────────────────────────────────
 
 export type NonStandardNamingSubType = "state-name";
 
 export const nonStandardNamingMsg = {
-  stateName: (name: string, nonStandard: string, suggestion: string) =>
-    `"${name}" has non-standard state name "${nonStandard}" — use "${suggestion}" for dev-friendly naming`,
+  stateName: (name: string, nonStandard: string, suggested: string): ViolationMsg => ({
+    message: `"${name}" has non-standard state name "${nonStandard}"`,
+    suggestion: `Use "${suggested}" for dev-friendly naming`,
+  }),
 };
 
 // ── non-semantic-name (merged: default-name + non-semantic-name) ─────────────
@@ -144,22 +213,51 @@ export function getDefaultNameSubType(nodeType: string): NonSemanticNameSubType
   return DEFAULT_NAME_SUBTYPE_MAP[nodeType] ?? "frame";
 }
 
-export const nonSemanticNameMsg = (type: string, name: string) =>
-  `${type} "${name}" is a non-semantic name — rename to describe its role (e.g., "Header", "ProductCard", "Divider")`;
+const NON_SEMANTIC_EXAMPLES: Record<string, string> = {
+  FRAME: '"Header", "ProductCard", "Sidebar"',
+  GROUP: '"NavItems", "ButtonGroup", "CardContent"',
+  VECTOR: '"ArrowIcon", "CheckMark", "LogoSymbol"',
+  LINE: '"Divider", "Separator", "Underline"',
+  RECTANGLE: '"Background", "Divider", "Overlay"',
+  ELLIPSE: '"AvatarShape", "StatusDot", "Badge"',
+  STAR: '"RatingIcon", "FavoriteIcon", "StarBadge"',
+  REGULAR_POLYGON: '"PlayIcon", "WarningIcon", "ShapeDecor"',
+  TEXT: '"PageTitle", "Description", "Price"',
+  IMAGE: '"Avatar", "ProductPhoto", "Banner"',
+  COMPONENT: '"PrimaryButton", "InputField", "CardTemplate"',
+  COMPONENT_SET: '"Button", "Input", "Card"',
+  INSTANCE: '"CloseButton", "UserAvatar", "StarIcon"',
+};
+
+export const nonSemanticNameMsg = (type: string, name: string): ViolationMsg => {
+  const examples = NON_SEMANTIC_EXAMPLES[type] ?? '"Header", "ProductCard", "Icon"';
+  return {
+    message: `${type} "${name}" is a non-semantic name`,
+    suggestion: `Rename to describe its role (e.g., ${examples})`,
+  };
+};
 
 // ── missing-interaction-state ─────────────────────────────────────────────────
 
 export type MissingInteractionStateSubType = "hover" | "disabled" | "active" | "focus";
 
 export const missingInteractionStateMsg = {
-  hover: (name: string) =>
-    `"${name}" looks interactive but has no Hover state variant — add a State=Hover variant`,
-  disabled: (name: string) =>
-    `"${name}" looks interactive but has no Disabled state variant — add a State=Disabled variant`,
-  active: (name: string) =>
-    `"${name}" looks interactive but has no Active state variant — add a State=Active variant`,
-  focus: (name: string) =>
-    `"${name}" looks interactive but has no Focus state variant — add a State=Focus variant`,
+  hover: (name: string): ViolationMsg => ({
+    message: `"${name}" looks interactive but has no Hover state variant`,
+    suggestion: `Add a State=Hover variant`,
+  }),
+  disabled: (name: string): ViolationMsg => ({
+    message: `"${name}" looks interactive but has no Disabled state variant`,
+    suggestion: `Add a State=Disabled variant`,
+  }),
+  active: (name: string): ViolationMsg => ({
+    message: `"${name}" looks interactive but has no Active state variant`,
+    suggestion: `Add a State=Active variant`,
+  }),
+  focus: (name: string): ViolationMsg => ({
+    message: `"${name}" looks interactive but has no Focus state variant`,
+    suggestion: `Add a State=Focus variant`,
+  }),
 };
 
 // ── missing-prototype ─────────────────────────────────────────────────────────
@@ -167,23 +265,39 @@ export const missingInteractionStateMsg = {
 export type MissingPrototypeSubType = "button" | "navigation" | "tab" | "overlay" | "carousel" | "input" | "toggle";
 
 export const missingPrototypeMsg = {
-  button: (name: string) =>
-    `"${name}" looks like a button but has no click prototype — add an ON_CLICK interaction to define the click behavior`,
-  navigation: (name: string) =>
-    `"${name}" looks like a navigation link but has no click prototype — add an ON_CLICK interaction to define the destination`,
-  tab: (name: string) =>
-    `"${name}" looks like a tab but has no click prototype — add an ON_CLICK interaction to define tab switching behavior`,
-  overlay: (name: string) =>
-    `"${name}" looks like an overlay trigger but has no click prototype — add an ON_CLICK interaction to define open/close behavior`,
-  carousel: (name: string) =>
-    `"${name}" looks like a carousel but has no interaction prototype — add an ON_CLICK or ON_DRAG interaction to define slide navigation`,
-  input: (name: string) =>
-    `"${name}" looks like an input but has no click prototype — add an ON_CLICK interaction to define focus/interaction behavior`,
-  toggle: (name: string) =>
-    `"${name}" looks like a toggle but has no click prototype — add an ON_CLICK interaction to define on/off behavior`,
+  button: (name: string): ViolationMsg => ({
+    message: `"${name}" looks like a button but has no click prototype`,
+    suggestion: `Add an ON_CLICK interaction to define the click behavior`,
+  }),
+  navigation: (name: string): ViolationMsg => ({
+    message: `"${name}" looks like a navigation link but has no click prototype`,
+    suggestion: `Add an ON_CLICK interaction to define the destination`,
+  }),
+  tab: (name: string): ViolationMsg => ({
+    message: `"${name}" looks like a tab but has no click prototype`,
+    suggestion: `Add an ON_CLICK interaction to define tab switching behavior`,
+  }),
+  overlay: (name: string): ViolationMsg => ({
+    message: `"${name}" looks like an overlay trigger but has no click prototype`,
+    suggestion: `Add an ON_CLICK interaction to define open/close behavior`,
+  }),
+  carousel: (name: string): ViolationMsg => ({
+    message: `"${name}" looks like a carousel but has no interaction prototype`,
+    suggestion: `Add an ON_CLICK or ON_DRAG interaction to define slide navigation`,
+  }),
+  input: (name: string): ViolationMsg => ({
+    message: `"${name}" looks like an input but has no click prototype`,
+    suggestion: `Add an ON_CLICK interaction to define focus/interaction behavior`,
+  }),
+  toggle: (name: string): ViolationMsg => ({
+    message: `"${name}" looks like a toggle but has no click prototype`,
+    suggestion: `Add an ON_CLICK interaction to define on/off behavior`,
+  }),
 };
 
 // ── inconsistent-naming-convention ───────────────────────────────────────────
 
-export const inconsistentNamingMsg = (name: string, nodeConvention: string, dominantConvention: string) =>
-  `"${name}" uses ${nodeConvention} while siblings use ${dominantConvention} — rename to match ${dominantConvention} convention`;
+export const inconsistentNamingMsg = (name: string, nodeConvention: string, dominantConvention: string): ViolationMsg => ({
+  message: `"${name}" uses ${nodeConvention} while siblings use ${dominantConvention}`,
+  suggestion: `Rename to match ${dominantConvention} convention`,
+});
diff --git a/src/core/rules/structure/index.ts b/src/core/rules/structure/index.ts
index bf6f39a1..9f220bba 100644
--- a/src/core/rules/structure/index.ts
+++ b/src/core/rules/structure/index.ts
@@ -40,7 +40,7 @@ const noAutoLayoutCheck: RuleCheckFn = (node, context) => {
               subType: "overlapping" as const,
               nodeId: node.id,
               nodePath: context.path.join(" > "),
-              message: noAutoLayoutMsg.overlapping(node.name),
+              ...noAutoLayoutMsg.overlapping(node.name),
             };
           }
         }
@@ -59,7 +59,7 @@ const noAutoLayoutCheck: RuleCheckFn = (node, context) => {
           subType: "nested" as const,
           nodeId: node.id,
           nodePath: context.path.join(" > "),
-          message: noAutoLayoutMsg.nested(node.name),
+          ...noAutoLayoutMsg.nested(node.name),
         };
       }
     }
@@ -88,7 +88,7 @@ const noAutoLayoutCheck: RuleCheckFn = (node, context) => {
     subType: "basic" as const,
     nodeId: node.id,
     nodePath: context.path.join(" > "),
-    message: noAutoLayoutMsg.basic(node.name, arrangement, directionHint),
+    ...noAutoLayoutMsg.basic(node.name, arrangement, directionHint),
   };
 };
 
@@ -121,7 +121,7 @@ const absolutePositionInAutoLayoutCheck: RuleCheckFn = (node, context) => {
     ruleId: absolutePositionInAutoLayoutDef.id,
     nodeId: node.id,
     nodePath: context.path.join(" > "),
-    message: absolutePositionMsg(node.name, context.parent.name),
+    ...absolutePositionMsg(node.name, context.parent.name),
   };
 };
 
@@ -168,7 +168,7 @@ const fixedSizeInAutoLayoutCheck: RuleCheckFn = (node, context) => {
       subType: "both-axes" as const,
       nodeId: node.id,
       nodePath: context.path.join(" > "),
-      message: fixedSizeMsg.bothAxes(node.name, width, height),
+      ...fixedSizeMsg.bothAxes(node.name, width, height),
     };
   }
 
@@ -188,7 +188,7 @@ const fixedSizeInAutoLayoutCheck: RuleCheckFn = (node, context) => {
       subType: "horizontal" as const,
       nodeId: node.id,
       nodePath: context.path.join(" > "),
-      message: fixedSizeMsg.horizontal(node.name, width),
+      ...fixedSizeMsg.horizontal(node.name, width),
     };
   }
 
@@ -228,7 +228,7 @@ const missingSizeConstraintCheck: RuleCheckFn = (node, context) => {
       subType: "wrap" as const,
       nodeId: node.id,
       nodePath,
-      message: missingSizeConstraintMsg.wrap(node.name),
+      ...missingSizeConstraintMsg.wrap(node.name),
     };
   }
 
@@ -239,7 +239,7 @@ const missingSizeConstraintCheck: RuleCheckFn = (node, context) => {
       subType: "grid" as const,
       nodeId: node.id,
       nodePath,
-      message: missingSizeConstraintMsg.grid(node.name),
+      ...missingSizeConstraintMsg.grid(node.name),
     };
   }
 
@@ -253,7 +253,7 @@ const missingSizeConstraintCheck: RuleCheckFn = (node, context) => {
       subType: "max-width" as const,
       nodeId: node.id,
       nodePath,
-      message: missingSizeConstraintMsg.maxWidth(node.name, currentWidth),
+      ...missingSizeConstraintMsg.maxWidth(node.name, currentWidth),
     };
   }
 
@@ -285,7 +285,7 @@ const nonLayoutContainerCheck: RuleCheckFn = (node, context) => {
       subType: "group" as const,
       nodeId: node.id,
       nodePath: context.path.join(" > "),
-      message: nonLayoutContainerMsg.group(node.name),
+      ...nonLayoutContainerMsg.group(node.name),
     };
   }
 
@@ -295,7 +295,7 @@ const nonLayoutContainerCheck: RuleCheckFn = (node, context) => {
       subType: "section" as const,
       nodeId: node.id,
       nodePath: context.path.join(" > "),
-      message: nonLayoutContainerMsg.section(node.name),
+      ...nonLayoutContainerMsg.section(node.name),
     };
   }
 
@@ -330,7 +330,7 @@ const deepNestingCheck: RuleCheckFn = (node, context, options) => {
     ruleId: deepNestingDef.id,
     nodeId: node.id,
     nodePath: context.path.join(" > "),
-    message: deepNestingMsg(node.name, context.componentDepth, maxDepth),
+    ...deepNestingMsg(node.name, context.componentDepth, maxDepth),
   };
 };
 
diff --git a/src/core/rules/token/index.ts b/src/core/rules/token/index.ts
index 6fafccb3..766266dd 100644
--- a/src/core/rules/token/index.ts
+++ b/src/core/rules/token/index.ts
@@ -37,7 +37,7 @@ const rawValueCheck: RuleCheckFn = (node, context) => {
             subType: "color" as const,
             nodeId: node.id,
             nodePath,
-            message: rawValueMsg.color(node.name, hex),
+            ...rawValueMsg.color(node.name, hex),
           };
         }
       }
@@ -63,7 +63,7 @@ const rawValueCheck: RuleCheckFn = (node, context) => {
         subType: "font" as const,
         nodeId: node.id,
         nodePath,
-        message: rawValueMsg.font(node.name, fontDesc),
+        ...rawValueMsg.font(node.name, fontDesc),
       };
     }
   }
@@ -86,7 +86,7 @@ const rawValueCheck: RuleCheckFn = (node, context) => {
             subType: "shadow" as const,
             nodeId: node.id,
             nodePath,
-            message: rawValueMsg.shadow(node.name, shadowType, details),
+            ...rawValueMsg.shadow(node.name, shadowType, details),
           };
         }
       }
@@ -100,7 +100,7 @@ const rawValueCheck: RuleCheckFn = (node, context) => {
       subType: "opacity" as const,
       nodeId: node.id,
       nodePath,
-      message: rawValueMsg.opacity(node.name, Math.round(node.opacity * 100)),
+      ...rawValueMsg.opacity(node.name, Math.round(node.opacity * 100)),
     };
   }
 
@@ -115,7 +115,7 @@ const rawValueCheck: RuleCheckFn = (node, context) => {
         subType: "spacing" as const,
         nodeId: node.id,
         nodePath,
-        message: rawValueMsg.spacing(node.name, label, value),
+        ...rawValueMsg.spacing(node.name, label, value),
       };
     }
   }
@@ -165,7 +165,7 @@ const irregularSpacingCheck: RuleCheckFn = (node, context, options) => {
         subType: entry.subType,
         nodeId: node.id,
         nodePath: context.path.join(" > "),
-        message: irregularSpacingMsg(node.name, entry.value, gridBase, Math.round(entry.value / gridBase) * gridBase),
+        ...irregularSpacingMsg(node.name, entry.value, gridBase, Math.round(entry.value / gridBase) * gridBase),
       };
     }
   }