git.compounddata.com > llmgentools > percentage/plan.md
homepage: https://compounddata.com/notes/llm-generated-single-page-tools
git clone: https://git.compounddata.com/llmgentools
summary history files
percentage/plan.md

plan.md

Goal

Build a single-file percentage calculator web application that provides three essential percentage calculations: finding a percentage of a number, determining what percentage one number is of another, and calculating percentage change between two values. The application delivers immediate, accurate results through a clean interface prioritizing usability and accessibility. All code (HTML, CSS, and JavaScript) is contained within a single file for easy deployment and portability.

The tool targets users who need quick percentage calculations for shopping discounts, financial analysis, academic work, or general math tasks. Users receive instant feedback as they type, with clear explanations showing both results in natural language and underlying mathematical formulas. This educational approach helps users understand the calculation process while providing immediate utility.

Requirements

MUST Implement

  • Single file application containing all HTML, CSS, and JavaScript
  • Three calculation modes with mathematically correct formulas:
    • "What is X% of Y?" — calculated as $Y \times (X / 100)$
    • "X is what percent of Y?" — calculated as $(X / Y) \times 100$, handling division by zero
    • "Percentage increase/decrease from X to Y" — calculated as $((Y - X) / |X|) \times 100$
  • Minimal CSS styling prioritizing usability:
    • Clear visual hierarchy between input fields and results
    • Sufficient contrast for readability
    • Responsive layout working on mobile and desktop
    • Focus states for keyboard navigation
  • Real-time calculation as users type
  • Input validation handling edge cases (zero values, empty inputs)
  • Results presentation:
    • Natural language sentences (e.g., "X% of Y is Z")
    • Mathematical formula display showing calculation steps
    • 2 decimal place precision
    • Color coding for percentage changes (green increase, red decrease)
  • One-sentence application description in header
  • Copy-to-clipboard functionality for results

SHOULD Implement

  • Keyboard navigation support with logical tab order
  • Reset/clear buttons for each calculator section
  • ARIA labels for screen reader accessibility
  • Minimum 44px touch targets for mobile usability

Research

Single-page applications (SPAs) transform web development by loading a single HTML page and dynamically updating content without full page reloads, offering smoother user experiences similar to native applications . Key best practices include optimizing performance through efficient DOM updates and ensuring maintainability through clean code structure .

Minimal CSS frameworks prioritize readability through proper spacing, clear typography hierarchy, sufficient color contrast, and responsive breakpoints without visual clutter . The focus remains on functional elements being immediately distinguishable.

Percentage calculations require careful handling of floating-point arithmetic and division by zero. Core formulas use multiplication for finding percentages, division for ratios, and comparison for changes . Critical details include checking for zero denominators , rounding to 2 decimal places using Math.round(num * 100) / 100, and using Math.abs() for consistent percentage change calculations regardless of starting value direction.

Phases and TODO

Phase 1: Foundation and First Calculator

  • [x] Create semantic HTML5 structure with proper document structure (doctype, html, head, body)
  • [x] Implement "What is X% of Y?" calculator section with two number inputs and result display area
  • [x] Build minimal CSS foundation:
    • [x] CSS reset with box-sizing border-box
    • [x] System font stack (-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, etc.)
    • [x] Container with max-width 800px and auto margins for centering
    • [x] Basic spacing system (padding 20px base, responsive adjustments)
    • [x] Input styling with borders, padding, and focus states (blue border #4a90d9)
    • [x] Mobile-responsive breakpoints (max-width 600px)
  • [x] Write JavaScript calculation logic:
    • [x] Event listeners for 'input' events on number fields
    • [x] Formula implementation: value * (percent / 100)
    • [x] Number formatting function for 2 decimal places using Math.round
    • [x] Basic input validation (isNaN checks, empty input handling)
    • [x] Real-time result updates to DOM
  • [x] Test calculation accuracy:
    • [x] Whole numbers (20% of 50 = 10)
    • [x] Decimal inputs (12.5% of 80 = 10)
    • [x] Negative numbers (-10% of 100 = -10)
    • [x] Zero values (0% of 100 = 0)

Phase 2: Complete Calculator Suite and Explanations

  • [x] Implement "X is what percent of Y?" calculator with division-by-zero protection
  • [x] Implement "Percentage increase/decrease from X to Y" with absolute value denominator
  • [x] Add natural language sentence generation for each result type
  • [x] Add mathematical formula display showing calculation steps
  • [x] Implement copy-to-clipboard using navigator.clipboard API with visual feedback
  • [x] Add color coding for increase (green #38a169) vs decrease (red #e53e3e)
  • [x] Add error message display for division by zero cases

Phase 3: Polish and UX Refinements

  • [x] Add one-sentence application description in header subtitle
  • [x] Add reset/clear buttons for each calculator section
  • [x] Add ARIA labels for accessibility (aria-label on inputs, aria-labelledby on sections, aria-live for results, role="alert" for errors)
  • [x] Verify minimum 44px touch targets on mobile inputs and buttons (min-height: 44px on .btn and input)
  • [x] Final cross-browser testing (vanilla JS ensures broad compatibility)