A modern, accessible web app for mastering Japanese Hiragana & Katakana
through interactive flashcards, quizzes, and audio pronunciation.

Features • Getting Started • Usage • Structure • Contributing

---

✨ Features

🃏 Learning Modes

Mode	Description
Flashcards	Flip cards with smooth 3D animations to reveal pronunciations
Quiz Mode	Multiple-choice questions with instant feedback and scoring
Hiragana Only	Focus exclusively on Hiragana characters
Katakana Only	Focus exclusively on Katakana characters
Mixed Mode	Challenge yourself with both scripts at once

♿ Accessibility First

NihongoFlash is built with accessibility as a core requirement, not an afterthought:

• Full Keyboard Navigation — Tab, Enter, Space, and Arrow keys work throughout
• Screen Reader Support — ARIA labels, live regions, and semantic HTML
• Reduced Motion — Respects prefers-reduced-motion user preference
• WCAG Compliant — Color contrast and focus indicators meet accessibility standards

🎯 Other Highlights

• 🔊 Audio Pronunciation via Web Speech API for authentic listening practice
• 📊 Progress Tracking with detailed learning statistics saved to Local Storage
• 🌙 Dark Theme optimized for extended study sessions
• 🎨 Color-coded Scripts — warm amber for Hiragana, cool blue for Katakana
• 📱 Fully Responsive — desktop, tablet, and mobile ready
• ⚡ Blazing Fast — Vite-powered with optimized production builds

---

🚀 Getting Started

Prerequisites

• Node.js v16 or higher
• npm or yarn

Installation

# 1. Clone the repository
git clone https://github.com/arc-en-fel/Japanese-flashcard-website-.git
cd Japanese-flashcard-website-

# 2. Install dependencies
npm install

# 3. Start the development server
npm run dev

Then open your browser and navigate to http://localhost:5173

Available Scripts

npm run dev       # Start development server with hot reload
npm run build     # Build optimized production bundle → /dist
npm run preview   # Preview the production build locally

---

🎮 Usage

Flashcard Mode

1. Go to the Learn section and select your script mode
2. Press Enter or Space (or click) to flip a card
3. Use ← → Arrow Keys to move between cards
4. Click the 🔊 audio button to hear the pronunciation

Quiz Mode

1. Go to the Quiz section and select your mode
2. Pick the correct romaji for each character shown
3. Get instant ✅ / ❌ feedback after each answer
4. Review your final score and accuracy

⌨️ Keyboard Shortcuts

Key	Action
Tab	Navigate between elements
Enter / Space	Flip card or activate button
← → Arrow Keys	Navigate between flashcards
Escape	Close modal / go back

---

🗾 Kana Coverage

Hiragana — 46 characters (click to expand)

Group	Characters
Vowels	あ い う え お
K	か き く け こ
S	さ し す せ そ
T	た ち つ て と
N	な に ぬ ね の
H	は ひ ふ へ ほ
M	ま み む め も
Y	や ゆ よ
R	ら り る れ ろ
W	わ を
N	ん

Katakana — 46 characters (click to expand)

Complete mirror set of the Hiragana table above in Katakana script.

---

📁 Project Structure

Japanese-flashcard-website-/
├── src/
│   ├── components/         # Reusable UI components
│   │   ├── FlashCard.tsx   # 3D flip card component
│   │   ├── QuizQuestion.tsx
│   │   ├── Navigation.tsx
│   │   └── ProgressBar.tsx
│   ├── pages/              # Route-level page components
│   │   ├── Home.tsx
│   │   ├── Learn.tsx
│   │   ├── Quiz.tsx
│   │   ├── About.tsx
│   │   └── Contact.tsx
│   ├── hooks/              # Custom React hooks
│   │   ├── useAudio.ts     # Web Speech API integration
│   │   └── useProgress.ts  # Progress tracking & persistence
│   ├── data/
│   │   └── kanaData.ts     # Hiragana & Katakana character data
│   ├── types/
│   │   └── index.ts        # Shared TypeScript types
│   ├── App.tsx
│   ├── main.tsx
│   └── index.css
├── public/
├── index.html
└── package.json

---

🛠️ Tech Stack

Frontend

APIs & Tools

---

🧪 Code Quality

• Fisher-Yates shuffle for unbiased quiz question randomization
• Dev-only data validator — checks kana data integrity on startup with zero production impact
• TypeScript strict mode for a fully type-safe codebase
• Proper cleanup of timeouts and speech synthesis on component unmount
• Component-scoped transitions for optimal rendering performance

---

🤝 Contributing

Contributions are very welcome! Here's how to get involved:

# 1. Fork the repo and create your branch
git checkout -b feature/your-feature-name

# 2. Commit your changes with a clear message
git commit -m "feat: add your feature"

# 3. Push and open a Pull Request
git push origin feature/your-feature-name

Please open an issue first for major changes so we can discuss what you'd like to change.

---

📝 License

This project is 100% free and open source, available under the AGPL-3.0 License.

---

📧 Contact

Have a suggestion, found a bug, or just want to say hi?

• 📮 Email: Click Here
• 🐛 Bug Reports: Open an Issue

---

Happy Learning! 頑張ってください！ (Ganbatte kudasai — Do your best!)

⭐ If this project helped you, consider giving it a star!