📖 Smart Word Definition Popup
A lightweight userscript that automatically displays word definitions when you select text on any webpage. Features adaptive theming that intelligently matches your website's color scheme with guaranteed readability.
✨ Features
- 🎯 Instant Definitions - Select any word to instantly see its definition
- 🎨 Adaptive Theming - Automatically matches the website's background and text colors
- ✅ Guaranteed Readability - WCAG AA compliant contrast ratios (4.5:1 minimum)
- 🪶 Lightweight - Minimal performance impact with optimized code
- 🎭 Smart Positioning - Popup intelligently adjusts based on viewport boundaries
- ⌨️ IBM Plex Mono - Clean, professional monospace typography
- 🔇 No Close Button - Minimal UI that auto-hides when needed
- 🌐 Works Everywhere - Compatible with all websites including complex layouts
- 🆓 Free API - Uses Free Dictionary API (no API key required)
🚀 Installation
Prerequisites
You need a userscript manager extension installed in your browser:
Steps
- Install a userscript manager (see links above)
- Click here to install: word-definition-popup.user.js
- Confirm installation in the userscript manager popup
- Done! Start selecting words on any webpage
📖 Usage
- Select any word on any webpage
- Wait 300ms (debounce delay)
- See the definition appear near your cursor
Supported Word Types
- Single English words (1-30 characters)
- Words with hyphens (e.g., "self-aware")
- Words with apostrophes (e.g., "don't")
Hiding the Popup
The popup automatically hides when you:
- Click anywhere outside the popup
- Start scrolling
- Press the ESC key
- Select new text
🎨 Adaptive Theming
The popup intelligently adapts to your website's design with guaranteed readability:
Background Color Detection
- Deep DOM traversal (up to 20 levels) to find backgrounds
- Handles semi-transparent overlays and complex layouts
- Prioritizes solid colors (opacity ≥ 80%)
- Falls back through: element → body → html → system preference
- Works perfectly on sites like Bluesky, Twitter/X, Reddit in dark mode
Text Color Adaptation
- Uses the same text color from the selected text
- Automatic contrast checking using WCAG standards
- Falls back to black/white if contrast ratio is below 4.5:1
- Ensures perfect readability in all scenarios
Smart Positioning
- Appears near your cursor
- Auto-adjusts when near viewport edges
- Never clips off-screen
Contrast Ratio Algorithm
The script uses the WCAG 2.1 formula to calculate contrast ratios:
// Ensures 4.5:1 minimum contrast for normal text (WCAG AA)
// Automatically corrects poor contrast scenarios
🛠️ Configuration
The script works out-of-the-box, but you can customize it by editing these values:
// Debounce delay (ms)
debounceTimer = setTimeout(() => {}, 300); // Change 300 to your preference
// Max word length
text.length < 30 // Change 30 to allow longer words
// Popup max width
max-width: 320px; // Edit in CSS
// Number of definitions shown
const meanings = entry.meanings.slice(0, 3); // Change 3 to show more/less
// DOM traversal depth
const maxDepth = 20; // Increase for even deeper scanning
// Minimum contrast ratio
if (contrastRatio < 4.5) // Change 4.5 for different standards
🔧 Technical Details
API
Uses the Free Dictionary API for word definitions:
Color Detection Algorithm
- Traverse DOM tree up to 20 levels deep
- Collect all non-transparent backgrounds with opacity > 0.1
- Prioritize solid colors with opacity ≥ 0.8
- Parse computed styles including rgba values
- Calculate luminance using WCAG formula:
L = 0.2126 × R + 0.7152 × G + 0.0722 × B
- Check contrast ratio between text and background:
CR = (L1 + 0.05) / (L2 + 0.05)
- Auto-correct text color if contrast < 4.5:1
- Fallback chain: element → body → html →
prefers-color-scheme
Performance Optimizations
- Debouncing: 300ms delay prevents excessive API calls
- Caching: Same word won't trigger new API call
- Minimal DOM: Single popup element reused
- Event delegation: Efficient event handling
- Lazy loading: Font loaded asynchronously
- Smart traversal: Stops at first solid background
🐛 Troubleshooting
Popup not appearing?
- Ensure the word is 2-30 characters long
- Check that it contains only English letters, hyphens, or apostrophes
- Verify userscript manager is enabled
Wrong colors or poor contrast?
- v1.2.1 fixed this! The script now ensures WCAG AA compliance
- If issues persist, check browser console for debug logs
- Report specific websites as GitHub issues with screenshots
Popup has white background on dark sites?
- Fixed in v1.2.1 with enhanced background detection
- The script now traverses deeper and handles opacity correctly
- Works on Bluesky, Twitter/X, Reddit, and other complex dark themes
Definition not found?
- Not all words are in the dictionary
- Try singular form (e.g., "book" instead of "books")
- Slang and very new words may not be available
Popup position issues?
- Clear browser cache and reload
- Check browser zoom level (100% recommended)
- Report edge cases as GitHub issues
Debug Mode
To see detailed theme detection logs:
- Open browser console (F12)
- Select a word
- Look for "Theme applied:" logs showing detected colors
📝 Changelog
v1.2.1 (2025-01-06)
- 🔧 Fixed contrast issues on complex dark themes (Bluesky, Twitter/X)
- 🎨 Enhanced background detection with deeper DOM traversal (20 levels)
- ✅ Added WCAG AA compliance with automatic contrast checking (4.5:1)
- 🔍 Improved handling of semi-transparent overlays
- 🌓 Better fallback to
prefers-color-scheme system preference
- 📊 Added debug logging for troubleshooting
- 🐛 Fixed rgba color parsing with alpha channel support
v1.2.0 (2025-01-06)
- ✨ Added adaptive text color matching selected text
- 🎨 Improved theme detection algorithm
- 🔧 Added userscript icon
- 📚 Created comprehensive README
v1.1.0 (2025-01-06)
- ❌ Removed close button for minimal UI
- 🎨 Implemented auto-theme based on background color
- 🔍 Smart color detection from DOM tree
v1.0.0 (2025-01-06)
- 🎉 Initial release
- ⚡ Core functionality with IBM Plex Mono font
- 📱 Smart viewport positioning
🤝 Contributing
Contributions are welcome! Here's how:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature)
- Commit your changes (
git commit -m 'Add amazing feature')
- Push to the branch (
git push origin feature/amazing-feature)
- Open a Pull Request
Development Setup
# Clone the repo
git clone https://github.com/doniwicaksono/word-definition-popup.git
# Edit the .user.js file
# Test in your browser with userscript manager
# Enable debug logs in browser console
# Look for "Theme applied:" messages
Reporting Issues
When reporting color/contrast issues, please include:
- Website URL
- Screenshot of the issue
- Browser console logs
- Browser and OS version
📄 License
This project is licensed under the MIT License - see below:
MIT License
Copyright (c) 2025 doniwicaksono
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
🙏 Acknowledgments
🌟 Tested On
- ✅ GitHub (light & dark themes)
- ✅ Twitter/X (light & dark themes)
- ✅ Reddit (light & dark themes)
- ✅ Bluesky (dark theme)
- ✅ Medium
- ✅ Stack Overflow
- ✅ Wikipedia
- ✅ News sites (CNN, BBC, etc.)
- ✅ Documentation sites (MDN, etc.)
Made with ❤️ for better reading experience
