Skip to content

borghei/Claude-Skills / engineering/design-auditor

design-auditor

Verified

Grade a UI (Design, AI-slop and Accessibility, A-F) and gate it in CI: batch WCAG contrast, token compliance, slop detection. Use when asked to audit, score or gate a UI; to fix one, use interface-refinement.

scripts/design_scorer.py

View on GitHub
#!/usr/bin/env python3
"""
Design Scorer — 12-category weighted design audit scoring system.

Computes Design Grade (A-F), AI Slop Grade (A-F), and Accessibility Grade (A-F)
from audit findings JSON input. Supports trend tracking against baselines and
generates prioritized fix recommendations. Validation and weighting live in
score_model.py; weights and grade bands in references/scoring-model.json.

Usage:
    python design_scorer.py --input findings.json --output report.json
    python design_scorer.py --input findings.json --baseline previous.json --verbose
    python design_scorer.py --input findings.json --format text

Exit codes: 0 scored, 2 missing file, invalid JSON or invalid findings.
"""

import argparse
import importlib.util as _ilu
import json
import os
import sys
from datetime import datetime


def _sibling(name):
    path = os.path.join(os.path.dirname(os.path.abspath(__file__)), name + ".py")
    spec = _ilu.spec_from_file_location(name, path)
    mod = _ilu.module_from_spec(spec)
    sys.modules[name] = mod
    spec.loader.exec_module(mod)
    return mod


_sm = _sibling("score_model")
PRIORITY_LABELS = _sm.PRIORITY_LABELS
validate_findings = _sm.validate_findings
compute_weighted_score = _sm.compute_weighted_score
extract_recommendations = _sm.extract_recommendations
compute_trend = _sm.compute_trend
count_by_priority = _sm.count_by_priority
load_json_file = _sm.load_json_file


def score_to_design_grade(score: float) -> str:
    """Convert a 0-100 weighted score to a Design Grade."""
    return _sm.grade_for(score, "design")


def score_to_slop_grade(score: float) -> str:
    """Convert AI slop category score (0-10) to a grade; higher means fewer slop patterns."""
    return _sm.grade_for(score, "ai_slop")


def score_to_accessibility_grade(score: float) -> str:
    """Convert accessibility category score (0-10) to grade."""
    return _sm.grade_for(score, "accessibility")


def generate_report(data: dict, baseline_data: dict | None = None) -> dict:
    """Generate a complete scored audit report."""
    scores = compute_weighted_score(data)
    recommendations = extract_recommendations(data)
    priority_counts = count_by_priority(recommendations)

    # Extract individual grades
    ai_slop_score = data["categories"].get("ai_slop", {}).get("score", 5)
    accessibility_score = data["categories"].get("accessibility", {}).get("score", 5)

    report = {
        "metadata": {
            "generated_at": datetime.now().isoformat(),
            "tool": "design_scorer.py",
            "version": "2.0.0",
        },
        "grades": {
            "design_grade": score_to_design_grade(scores["total_score"]),
            "design_score": scores["total_score"],
            "ai_slop_grade": score_to_slop_grade(ai_slop_score),
            "ai_slop_score": ai_slop_score,
            "accessibility_grade": score_to_accessibility_grade(accessibility_score),
            "accessibility_score": accessibility_score,
        },
        "category_breakdown": scores["categories"],
        "coherence": scores["coherence"],
        "recommendations": recommendations,
        "summary": {
            "total_findings": len(recommendations),
            "by_priority": priority_counts,
            "top_3_issues": recommendations[:3] if recommendations else [],
        },
    }

    # Add trend data if baseline provided
    if baseline_data is not None:
        baseline_scores = compute_weighted_score(baseline_data)
        report["trend"] = compute_trend(scores, baseline_scores)

    return report


def format_text_report(report: dict) -> str:
    """Format report as human-readable text."""
    lines = []
    lines.append("=" * 72)
    lines.append("DESIGN AUDIT REPORT")
    lines.append("=" * 72)
    lines.append(f"Generated: {report['metadata']['generated_at']}")
    lines.append("")

    # Grades
    grades = report["grades"]
    lines.append("GRADES")
    lines.append("-" * 40)
    lines.append(f"  Design Grade:        {grades['design_grade']} ({grades['design_score']}/100)")
    lines.append(f"  AI Slop Grade:       {grades['ai_slop_grade']} ({grades['ai_slop_score']}/10)")
    lines.append(f"  Accessibility Grade: {grades['accessibility_grade']} ({grades['accessibility_score']}/10)")
    lines.append("")

    # Category breakdown
    lines.append("CATEGORY BREAKDOWN")
    lines.append("-" * 72)
    lines.append(f"  {'Category':<42} {'Score':>6} {'Weight':>7} {'Contrib':>8}")
    lines.append(f"  {'-'*42} {'-'*6} {'-'*7} {'-'*8}")

    for key, cat in report["category_breakdown"].items():
        name = cat["name"]
        if len(name) > 40:
            name = name[:37] + "..."
        lines.append(
            f"  {name:<42} {cat['raw_score']:>5.1f} {cat['weight']*100:>6.0f}% {cat['weighted_contribution']:>7.2f}"
        )

    coh = report["coherence"]
    lines.append(
        f"  {'Overall Coherence Bonus':<42} {coh['raw_score']:>5.1f} {'5':>6}% {coh['weighted_contribution']:>7.2f}"
    )
    lines.append(f"  {'':<42} {'':>6} {'Total':>7} {grades['design_score']:>7.2f}")
    lines.append("")

    # Summary
    summary = report["summary"]
    lines.append("FINDINGS SUMMARY")
    lines.append("-" * 40)
    lines.append(f"  Total findings: {summary['total_findings']}")
    for pri, count in summary["by_priority"].items():
        if count > 0:
            lines.append(f"    {PRIORITY_LABELS.get(pri, pri)}: {count}")
    lines.append("")

    # Top issues
    if summary["top_3_issues"]:
        lines.append("TOP ISSUES")
        lines.append("-" * 40)
        for i, issue in enumerate(summary["top_3_issues"], 1):
            lines.append(f"  {i}. [{issue['priority'].upper()}] {issue['description']}")
            if issue.get("fix"):
                lines.append(f"     Fix: {issue['fix']}")
            lines.append(f"     Category: {issue['category']}")
            lines.append("")

    # Trend (if present)
    if "trend" in report:
        lines.append("TREND vs BASELINE")
        lines.append("-" * 72)
        trend = report["trend"]
        overall = trend.get("_overall", {})
        direction_symbol = {"improved": "+", "declined": "-", "unchanged": "="}

        for key, t in trend.items():
            if key == "_overall":
                continue
            sym = direction_symbol.get(t["direction"], "?")
            lines.append(
                f"  {t['name']:<42} {t['baseline']:.1f} -> {t['current']:.1f} ({sym}{abs(t['delta']):.1f})"
            )

        lines.append("")
        sym = direction_symbol.get(overall.get("direction", "unchanged"), "?")
        lines.append(
            f"  Overall: {overall.get('baseline_total', 0):.1f} -> "
            f"{overall.get('current_total', 0):.1f} ({sym}{abs(overall.get('delta', 0)):.1f})"
        )
        lines.append("")

    # All recommendations
    if report["recommendations"]:
        lines.append("ALL RECOMMENDATIONS (by priority)")
        lines.append("-" * 72)
        current_priority = None
        for rec in report["recommendations"]:
            if rec["priority"] != current_priority:
                current_priority = rec["priority"]
                lines.append(f"\n  [{current_priority.upper()}]")
            lines.append(f"    - {rec['description']}")
            if rec.get("fix"):
                lines.append(f"      Fix: {rec['fix']}")
    lines.append("")
    lines.append("=" * 72)
    return "\n".join(lines)


def format_verbose(report: dict) -> str:
    """Format report with extra detail for verbose output."""
    text = format_text_report(report)
    lines = [text, ""]
    lines.append("DETAILED CATEGORY FINDINGS")
    lines.append("=" * 72)

    for key, cat in report["category_breakdown"].items():
        findings = cat.get("findings", [])
        if findings:
            lines.append(f"\n{cat['name']} (Score: {cat['raw_score']}/10)")
            lines.append("-" * 50)
            for f in findings:
                pri = f.get("priority", "medium")
                lines.append(f"  [{pri.upper()}] {f.get('description', '')}")
                if f.get("fix"):
                    lines.append(f"    Suggested fix: {f['fix']}")
                if f.get("impact"):
                    lines.append(f"    Impact score: {f['impact']}/10")

    lines.append("")
    return "\n".join(lines)


def main():
    parser = argparse.ArgumentParser(
        description="Design Scorer — 12-category weighted design audit scoring system",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
  %(prog)s --input findings.json --output report.json
  %(prog)s --input findings.json --baseline previous.json --verbose
  %(prog)s --input findings.json --format text
        """,
    )
    parser.add_argument("--input", "-i", required=True, help="Path to audit findings JSON file")
    parser.add_argument("--output", "-o", help="Path to write report JSON (default: stdout)")
    parser.add_argument("--baseline", "-b", help="Path to baseline findings JSON for trend comparison")
    parser.add_argument(
        "--format",
        "-f",
        choices=["json", "text"],
        default="json",
        help="Output format (default: json)",
    )
    parser.add_argument("--verbose", "-v", action="store_true", help="Include detailed category findings")

    args = parser.parse_args()

    # Load input
    data = load_json_file(args.input)

    # Validate
    errors = validate_findings(data)
    if errors:
        print("Validation errors:", file=sys.stderr)
        for err in errors:
            print(f"  - {err}", file=sys.stderr)
        sys.exit(2)

    # Load baseline if provided
    baseline_data = None
    if args.baseline:
        baseline_data = load_json_file(args.baseline)
        baseline_errors = validate_findings(baseline_data)
        if baseline_errors:
            print("Baseline validation errors:", file=sys.stderr)
            for err in baseline_errors:
                print(f"  - {err}", file=sys.stderr)
            sys.exit(2)

    # Generate report
    report = generate_report(data, baseline_data)

    # Output
    if args.format == "text":
        output = format_verbose(report) if args.verbose else format_text_report(report)
    else:
        output = json.dumps(report, indent=2)
    if args.output:
        with open(args.output, "w", encoding="utf-8") as f:
            f.write(output)
        print(f"Report written to {args.output}")
    else:
        print(output)


if __name__ == "__main__":
    main()
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall