What You'll Build
In this project, you'll use an AI assistant (Claude, ChatGPT, or any tool you prefer) to create a browser-based code review scorecard. The finished tool will let you:
- Evaluate code against a 12-point quality checklist covering readability, structure, error handling, and more
- See a live animated gauge that fills as you check off items, changing color from red to green
- Load sample code snippets to practice reviewing real-world patterns
- Add notes and comments to individual checklist items
- Export the completed scorecard as a shareable summary
What You'll Need
An AI Chat Tool
Claude, ChatGPT, Gemini, or any AI assistant that can generate code. Free tiers work fine.
A Text Editor
VS Code, Notepad, TextEdit — anything that lets you save an .html file.
Some coding familiarity helps
This is an intermediate project. You don't need to be a developer, but having completed a beginner project first will help you follow along with the more advanced CSS animations.
Describe the Scorecard UI with Checklist
Open your AI tool and start a new conversation. The scorecard needs two main areas: a checklist of quality criteria on one side, and a visual score display on the other. Here's a detailed prompt:
Build me a single HTML file for a code review scorecard tool. It should have:
- A two-column layout: checklist on the left (wider), score display on the right (sticky sidebar)
- A 12-point code review checklist organized into 4 categories:
• Readability (3 items): meaningful variable names, consistent formatting, clear comments
• Structure (3 items): single responsibility functions, no deep nesting, proper file organization
• Error Handling (3 items): input validation, try-catch blocks, meaningful error messages
• Best Practices (3 items): no hardcoded values, DRY principle followed, no unused code
- Each checklist item is a checkbox with a label and a short description underneath
- The right sidebar shows: current score as "X / 12", a percentage, and a letter grade (A through F)
- The score updates live as items are checked/unchecked
- Use a dark theme with clean, modern styling
Put all HTML, CSS, and JavaScript in one file. Use Tailwind CSS via CDN.
Save the output as code-review-scorecard.html and open it in your browser. Check that all 12 items appear, that checking them updates the score, and that the letter grade changes accordingly. The grading scale should be roughly: A (10-12), B (8-9), C (6-7), D (4-5), F (0-3).
Build the Scoring System
The basic checklist works, but a good scorecard needs more than just pass/fail checkboxes. Let's add weighted scoring and the ability to add notes to each item:
Enhance the scoring system for the code review scorecard:
- Change each checklist item from a simple checkbox to a 3-state toggle: "Pass" (green, full points), "Partial" (yellow, half points), "Fail" (red, zero points). Default state should be unset (gray).
- Add a small text input below each checklist item labeled "Notes" where the reviewer can type a brief comment (e.g., "Function names are good but some variables are single letters")
- Update the sidebar score to reflect the weighted system: show total points earned out of total possible points
- Add category subtotals — show a mini score for each of the 4 categories (Readability: 2.5/3, Structure: 3/3, etc.)
- Add a "Reset All" button that clears all selections and notes back to the default unset state, with a confirmation dialog
- Color-code each category header based on its subtotal: green if all items pass, yellow if any are partial, red if any fail
Keep everything in one HTML file with the dark theme.
The three-state scoring (Pass / Partial / Fail) is more useful than simple checkboxes because real code reviews are rarely black and white. A function might have good naming conventions overall but a few unclear abbreviations — that's a "Partial" on readability, not a complete fail.
Add the Animated Gauge Visualization
This is the most visually impressive part of the project — an animated circular gauge that fills up as the score increases. This is a great exercise in CSS animations:
Add an animated circular score gauge to the code review scorecard sidebar:
- Replace the plain text score with a large SVG circular gauge (about 200px diameter)
- The gauge should be a circle with a thick stroke. Use an SVG circle with stroke-dasharray and stroke-dashoffset to show progress.
- The filled portion should animate smoothly when the score changes (use CSS transition on stroke-dashoffset, duration 0.6s with ease-out)
- Color the gauge based on the score: red (#ef4444) for 0-33%, amber (#f59e0b) for 34-66%, green (#22c55e) for 67-100%
- Show the percentage number in large bold text in the center of the circle
- Show the letter grade below the percentage in a smaller font
- Add a subtle glow effect around the gauge that matches the current color (red glow, amber glow, or green glow)
- Below the gauge, show a horizontal bar chart with 4 small bars — one for each category — showing their individual completion percentage
- Each bar should also animate when values change
Use only CSS transitions for all animations — no JavaScript animation libraries. Keep everything in one file.
The SVG gauge technique used here — manipulating stroke-dashoffset on a circle — is the same approach used by fitness apps, dashboard widgets, and progress indicators across the web. It's a powerful CSS technique worth understanding.
Here are common issues and how to ask the AI to fix them:
Gauge fills clockwise from the wrong position
Tell the AI: "The gauge starts filling from the right side (3 o'clock). Rotate the SVG circle by -90 degrees so it starts from the top (12 o'clock position). Add transform: rotate(-90deg) to the SVG element."
Color transition is jarring
Tell the AI: "The color snaps from red to green instantly. Add a CSS transition on the stroke color as well: transition: stroke-dashoffset 0.6s ease-out, stroke 0.4s ease so the color fades smoothly."
Category bars don't show up
Tell the AI: "The horizontal category bars are invisible. Make sure the bar container has a visible background (like a dark gray track) and the filled portion uses the category color. Set a minimum width of 2px so zero-state bars are still visible."
Add Sample Code Loading
A scorecard is only useful if there's code to review. Adding pre-loaded code samples gives users something to practice with right away:
Add a code sample panel to the code review scorecard:
- Add a collapsible panel above the checklist labeled "Code Under Review"
- Include a dropdown to load sample code snippets. Add 3 built-in samples:
1. "Good Example" — a well-written JavaScript function with clear names, error handling, and comments (should score 10-12/12)
2. "Needs Work" — a function with some issues: a few single-letter variables, missing error handling, but decent structure (should score 5-7/12)
3. "Poor Example" — a function with deeply nested logic, no comments, hardcoded values, and no error handling (should score 1-3/12)
- Display the code in a styled code block with monospace font, line numbers, and basic syntax highlighting (color keywords, strings, and comments differently)
- Add a "Paste Your Own" option that shows a textarea where users can paste their own code to review
- When a sample is loaded, reset the scorecard to the unset state so the user can evaluate fresh
Keep everything in one file with the dark theme.
The three sample code snippets at different quality levels serve as a calibration tool. Users can load the "Good Example," review it, and see if their score matches the expected range. This teaches them what each checklist criterion actually looks like in real code.
Add Export and Share Features
Once the review is complete, users need a way to share their findings. This step adds professional export capabilities:
Add export and sharing features to the code review scorecard:
- Add an "Export Summary" button that generates a formatted text report including:
• Overall score and letter grade
• Category breakdown with subtotals
• Each checklist item's status (Pass/Partial/Fail) and any reviewer notes
• A timestamp of when the review was completed
- The report should open in a modal with a "Copy to Clipboard" button
- Add a "Download as Markdown" button that saves the report as a .md file
- Add a "Save Review" button that stores the current scorecard state (all selections and notes) to localStorage with a name/label
- Add a "Load Review" dropdown that shows previously saved reviews and loads them back
- Show a small history list at the bottom: "Recent Reviews" with the name, date, and score of each saved review
Keep everything in one file with the dark theme.
The Markdown export is particularly useful because it produces a format that can be pasted directly into GitHub pull request comments, Notion pages, or Slack messages. This bridges the gap between a learning tool and something practical for real code review workflows.
What You Learned
This project teaches more than just code review. By completing it, you practiced:
Code Quality Assessment
You learned the 12 criteria that separate good code from bad code: naming, structure, error handling, and best practices.
Building Scoring UIs
You built a multi-state scoring system with weighted points, category subtotals, and live-updating displays — patterns used in surveys, quizzes, and assessment tools.
CSS Animations for Data
You built an SVG circular gauge with animated stroke-dashoffset, color transitions, and category bar charts — all using pure CSS.
Understanding Good Code
By reviewing sample code at different quality levels, you developed an eye for what makes code maintainable, readable, and robust.
Tips for Working with AI on This Project
Get the checklist right first. The gauge animation is flashy, but the checklist is the core feature. Make sure all 12 items work correctly before adding visual polish.
Test the gauge at every score level. Check 0/12, 6/12, and 12/12 specifically. The gauge should look correct at both extremes and in the middle.
Use the browser inspector for SVG debugging. If the gauge looks wrong, right-click it and "Inspect Element." You can see the stroke-dasharray and stroke-dashoffset values in real time.
Review the sample code yourself first. Before looking at the expected scores, read each code sample and form your own opinion. Then use the scorecard to see if your assessment matches.
Ready for your next project?
Explore more hands-on projects, or check out the tutorials for deeper dives into specific AI tools.