Free Pinyin Tone Mark Typer & Converter for Mandarin Chinese

Technical Specification: Pinyin Tone Mark Typer

Overview

A browser-based utility designed to bridge the gap between standard keyboard input and the requirement for properly formatted Mandarin Pinyin characters. The tool will support two distinct modes: 'Numeric Conversion' (typing 'ma1' -> 'mā') and 'Manual Insertion' (clicking buttons for specific tone characters).

Core Features

1. Smart Numeric Conversion: Automatically detects patterns like 'v1', 'a2', 'i3', 'u4' and converts them into the corresponding accented character.
2. Visual Keyboard Interface: A set of buttons displaying all valid Mandarin vowels with all four tone options, allowing users to build Pinyin syllables visually.
3. Real-Time Output: As the user types in the input box, the output updates instantly.
4. Batch Processing: Support for multi-sentence input while preserving spaces and punctuation.
5. Clipboard Integration: 'Copy All' functionality that clears formatting, ensuring compatibility with standard text fields.
6. Instructional Guide: A small 'Quick Start' helper section that explains the number-to-tone mapping (1=macron, 2=acute, 3=caron, 4=grave).

UI Layout

• Header: Title and brief descriptive subtitle.
• Main Workspace: A split-pane design. Left side (or top) contains the 'Input' textarea, right side (or bottom) contains the 'Result' display.
• Toolbar: A floating or sticky toolbar between the input and output containing the vowel/tone buttons for easy manual selection.
• Action Bar: 'Clear' and 'Copy' buttons positioned at the bottom of the workspace.

Aesthetic & Design Guidelines

• Palette: Professional, clean 'SaaS' light mode. Background: #f8fafc, Text: #1e293b, Primary Action: #4f46e5 (Indigo), Borders: #e2e8f0.
• Typography: Inter or system-ui sans-serif for high readability.
• Animations:
  • Subtle fade-in for the output text on change.
  • Click-scale effect (button scales down to 0.98 on press) for interactive elements.
  • Smooth border-color transitions on input focus.
• Responsiveness: Single column layout on mobile, expanding to a two-column or side-by-side workspace on tablets and desktop.

Developer Directives (Constraint Compliance)

1. Single File Architecture: All CSS and JS must be inside the single HTML file. Use <style> and <script> tags.
2. No Persistence: Do not use localStorage, sessionStorage, or cookies. The state must reside strictly in a JavaScript variable object.
3. No External Frameworks: Pure Vanilla JS only. Do not use jQuery or React. Use standard addEventListener and document.querySelector methods.
4. Iframe Compatibility: The app must be fully functional inside an iframe with a null origin. Avoid any code that tries to access the top-level parent window or browser APIs that require permissions/storage.
5. Modals: If a confirmation or alert is needed (e.g., 'Text Copied!'), implement it as a custom div that fades in/out, not a browser-native alert() or confirm().
6. Security: Always use textContent or innerText to prevent XSS if you are dynamically inserting user input. Never use innerHTML to insert raw user strings.