This repository contains a collection of browser-based HTML+JavaScript tools for various tasks. All tools are intended to run entirely in the browser with no server-side processing.
This document provides instructions for AI coding assistants (Claude, ChatGPT, Gemini, Cursor, etc.) working on this repository.
CRITICAL REQUIREMENT: Always use plain HTML, vanilla JavaScript, and CSS with minimal dependencies.
- ❌ DO NOT use React, Vue, Angular, or any other frontend framework
- ❌ DO NOT use JSX or any transpilation step
- ❌ DO NOT introduce build tools (webpack, vite, rollup, etc.)
- ✅ DO use plain HTML5, vanilla JavaScript (ES6+), and CSS3
- ✅ DO keep tools as single self-contained HTML files when possible
- ✅ DO prioritize browser-native APIs and features
All tools must run entirely in the browser:
- ✅ All processing happens client-side using JavaScript
- ✅ All data stays in the user's browser
- ✅ Files are processed using FileReader API, Web APIs, etc.
- ❌ No backend services, APIs, or server endpoints (except for well-known, stable third-party services when absolutely necessary)
Each tool should typically be:
- A single, self-contained HTML file
- Include all CSS in a
<style>tag - Include all JavaScript in a
<script>tag - Clearly organized with comments separating sections
HTML:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Tool Name</title>
<style>
/* CSS here */
</style>
</head>
<body>
<!-- Content here -->
<script>
// JavaScript here
</script>
</body>
</html>JavaScript:
- Use modern ES6+ syntax (const/let, arrow functions, async/await, etc.)
- Use browser-native APIs (FileReader, Blob, Canvas, etc.)
- Prefer functional approaches where appropriate
- Add clear comments explaining complex logic
- Use descriptive variable and function names
CSS:
- Use system fonts for performance and consistency
- Responsive design with mobile-first approach
- Simple, clean styling
- Use CSS Grid and Flexbox for layouts
- NO emojis or icon characters in UI unless explicitly requested by the user
- Follow the standard color scheme and button styles (see "Standard Styling" section below)
Minimal External Dependencies:
- Use vanilla JavaScript and browser APIs whenever possible
- Only include external libraries when absolutely necessary for specialized functionality that cannot be reasonably implemented with native APIs
- When external libraries are required, load them from trusted CDNs only:
- cdnjs.cloudflare.com (preferred)
- cdn.jsdelivr.net (acceptable alternative)
- Always use specific version numbers in CDN URLs (never use
@latest) - Document why each dependency is needed
- Examples of acceptable dependencies:
- Specialized libraries (e.g., exif-js for EXIF data, jsdiff for text comparison)
- Mapping libraries (e.g., Leaflet for GeoJSON visualization)
- PDF.js for PDF processing
- OCR libraries (e.g., Tesseract.js)
Unacceptable Dependencies:
- React, Vue, Angular, Svelte, or any framework
- jQuery (use vanilla JavaScript instead)
- Bootstrap (write custom CSS instead)
- Lodash/Underscore (use native JavaScript methods)
- Any CDN sources other than cdnjs or jsDelivr
- Target modern evergreen browsers (Chrome, Firefox, Safari, Edge)
- Use standard Web APIs that have broad support
- Test features using MDN compatibility tables
- Provide graceful degradation or clear error messages for unsupported features
Input Handling:
- Support drag-and-drop for file inputs
- Provide clear feedback during processing
- Show loading states for long operations
- Handle errors gracefully with user-friendly messages
Output:
- Display results clearly and accessibly
- Provide download capabilities where appropriate
- Show previews of data when helpful
- Include copy-to-clipboard functionality when relevant
Accessibility:
- Use semantic HTML elements
- Include appropriate ARIA labels
- Ensure keyboard navigation works
- Use sufficient color contrast
- Single File: Create a new
.htmlfile in the root directory - Naming: Use kebab-case (e.g.,
my-new-tool.html) - Self-Contained: Include all HTML, CSS, and JavaScript in one file
- Test Locally: Open in browser directly (no build step needed)
- Update Index: Add the tool to
index.htmlin the appropriate category - Update README: Add a description in
README.mdunder "Available Tools"
- Understand First: Read the entire file to understand its structure
- Maintain Style: Follow the existing code style and patterns
- Test Thoroughly: Verify all functionality still works
- Document Changes: Add comments explaining significant modifications
All tools should follow this consistent visual style:
Color Scheme:
- Background:
#ffffff - Text:
#24292e - Secondary text:
#586069 - Border:
#e1e4e8 - Light background:
#f6f8fa - Link/Primary blue:
#0366d6(hover:#0256c5) - Light grey:
#fafbfc(hover:#f3f4f6)
Typography:
font-family: Helvetica, -apple-system, BlinkMacSystemFont, "Segoe UI", Arial, sans-serif;Button Styles:
- Primary buttons (main actions): Blue background (
#0366d6), white text - Secondary buttons (less important actions): Light grey background (
#fafbfc), dark text - All buttons:
8px 12pxpadding,6pxborder-radius,14pxfont-size
Page Header Pattern: Every tool must include a back link followed by the page title:
<a href="index.html" class="back-link">← Back to Browser Tools</a>
<h1>Tool Name</h1>Standard CSS for back link:
.back-link {
display: inline-block;
margin-bottom: 16px;
color: #0366d6;
text-decoration: none;
font-size: 14px;
}
.back-link:hover {
text-decoration: underline;
}Standard button CSS:
.btn {
background: #fafbfc;
color: #24292e;
padding: 8px 12px;
border-radius: 6px;
border: 1px solid rgba(27, 31, 35, 0.15);
cursor: pointer;
font-size: 14px;
line-height: 20px;
}
.btn:hover {
background: #f3f4f6;
}
.btn.primary {
background: #0366d6;
color: #fff;
}
.btn.primary:hover {
background: #0256c5;
}
.btn.secondary {
background: #fafbfc;
color: #24292e;
}
.btn.secondary:hover {
background: #f3f4f6;
}<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Tool Name</title>
<style>
/* =========================
CSS Styles
========================= */
/* Reset and base styles */
/* Layout */
/* Components */
/* Utilities */
</style>
</head>
<body>
<!-- =========================
HTML Structure
========================= -->
<a href="index.html" class="back-link">← Back to Browser Tools</a>
<h1>Tool Name</h1>
<script>
/* =========================
JavaScript
========================= */
// State variables
// Utility functions
// Event handlers
// Initialization
</script>
</body>
</html>// Drag and drop
dropZone.addEventListener("drop", (e) => {
e.preventDefault();
const files = e.dataTransfer.files;
handleFile(files[0]);
});
// File input
fileInput.addEventListener("change", (e) => {
handleFile(e.target.files[0]);
});
// Reading files
function handleFile(file) {
const reader = new FileReader();
reader.onload = (e) => {
const content = e.target.result;
processContent(content);
};
reader.readAsText(file);
}function downloadFile(content, filename, mimeType) {
const blob = new Blob([content], { type: mimeType });
const url = URL.createObjectURL(blob);
const a = document.createElement("a");
a.href = url;
a.download = filename;
a.click();
URL.revokeObjectURL(url);
}try {
// Risky operation
processData(data);
} catch (error) {
console.error("Error:", error);
showError("Failed to process data: " + error.message);
}
function showError(message) {
const errorDiv = document.getElementById("error");
errorDiv.textContent = message;
errorDiv.style.display = "block";
}Before considering a tool complete:
- Works in Chrome, Firefox, Safari, and Edge
- No console errors or warnings
- Handles edge cases (empty files, large files, malformed data)
- Provides clear error messages
- Responsive on mobile devices
- Accessible via keyboard navigation
- Drag-and-drop works correctly
- Download/copy functionality works
- No external dependencies unless documented and necessary
- External dependencies loaded from cdnjs or jsDelivr only
- Code is well-commented
- Follows standard styling (colors, buttons, header with back link)
- No emojis or icon characters in UI (unless explicitly requested)
- Primary buttons are blue, secondary buttons are light grey
- Includes "← Back to Browser Tools" link at top
- Added to index.html
- Documented in README.md
Good examples from this repository:
text-diff.html- Clean, focused, single-purpose toolcsv-to-json.html- Good file handling and preview functionalitypixel-coords.html- Simple, effective use of Canvas API
When in doubt:
- Keep it simple - The simplest solution is usually the best
- No frameworks - Vanilla JS can do everything you need
- Self-contained - One file, no build step
- User-focused - Prioritize clarity and usability