🔄 Pull Request

📋 Type of Change (check all applicable)

• 🐛 Bug Fix - Fixes an issue without breaking existing functionality
• ✨ Feature - Adds new functionality
• ⚡ Performance - Improves performance without changing functionality
• ♻️ Refactor - Code changes that neither fix bugs nor add features
• 📚 Documentation - Updates to documentation, comments, or README
• 🎨 Style - Code style changes (formatting, missing semi-colons, etc.)
• 🧪 Test - Adding or updating tests
• 🏗️ Build - Changes to build system or dependencies
• 👷 CI/CD - Changes to CI/CD workflows
• 🔒 Security - Security improvements or vulnerability fixes
• ♿ Accessibility - Improves accessibility compliance
• 📱 Mobile - Mobile-specific improvements
• 🌐 i18n - Internationalization changes

📖 Description

This PR adds a comprehensive Animated GIFs Gallery feature to the GitHub Profile README Generator, allowing users to add personality and visual appeal to their GitHub profiles with carefully curated animated GIFs.

What changed?

• Added a built-in GIFs gallery with 45+ MIT-licensed GIFs from Cool-GIFs-For-GitHub
• Implemented custom GIF URL input for user-provided animations
• Added individual GIF settings: position (top/middle/bottom), alignment (left/center/right), and size (small/medium/large/custom)
• Implemented custom size controls with width/height inputs (50-1000px validation range)
• Fixed input editing bug using nullish coalescing operator for empty field handling
• Optimized images using Next.js <Image /> component in GIF sections
• Added proper MIT license attribution in ATTRIBUTION.md
• Integrated GIF feature into the Skills & GIFs step of the wizard
• Added theme-aware scrollbar styling for the GIF gallery
• Created serialization logic for localStorage to handle GIF data persistence

Why was this change made?

GitHub profiles with animated GIFs are more engaging, expressive, and memorable. However, finding high-quality, appropriate GIFs and integrating them into a README can be time-consuming. This feature:

1. Solves the discovery problem: Curated gallery of 45+ professional GIFs eliminates the need to search
2. Simplifies integration: No manual markdown/HTML coding required
3. Provides flexibility: Custom URL input for users who want specific GIFs
4. Ensures quality: All default GIFs are MIT-licensed and GitHub-profile appropriate
5. Offers customization: Individual position, alignment, and size controls per GIF

How does this change help users?

For Non-Technical Users:

• ✅ One-click GIF selection from curated gallery
• ✅ No coding knowledge required
• ✅ Visual preview before adding to README
• ✅ Category filtering for easy discovery

For Power Users:

• ✅ Custom URL input for any GIF
• ✅ Granular control over each GIF's appearance
• ✅ Custom size controls with px-level precision
• ✅ Individual positioning (top/middle/bottom of README)

For Everyone:

• ✅ More engaging and expressive GitHub profiles
• ✅ Proper attribution and licensing handled automatically
• ✅ Mobile-responsive and theme-compatible
• ✅ Performance-optimized with Next.js Image component

🔗 Related Issues

• Closes [Feature] Add Built-in GIFs Gallery and Custom GIF Support #934

🧪 Testing & Quality Assurance

Testing Done (check all applicable)

• ✅ Manual testing - Tested functionality manually
• 🧪 Unit tests - Validated with existing test suite (13/13 passing)
• 🔄 Integration tests - Tested with other components (Skills section, markdown preview)
• 📱 Mobile testing - Tested on mobile devices (responsive design)
• ♿ Accessibility testing - Added ARIA labels, semantic HTML, keyboard navigation
• 🌐 Cross-browser testing - Tested in Chrome, Firefox, Edge
• 🎨 Visual testing - Checked UI/UX in light/dark themes

Test Instructions

1. Enable GIFs Feature

   • Navigate to the "Skills & GIFs" step in the wizard
   • Scroll to the "Animated GIFs" section
   • Toggle "Enable animated GIFs in README"

2. Test Built-in Gallery

   • Click on different category filters (Greeting, Coding, Celebration, etc.)
   • Select GIFs from the gallery (up to 5 maximum)
   • Verify selection indicators appear
   • Try selecting a 6th GIF and verify error message

3. Test Custom URL Input

   • Enter a valid GIF URL in the "Add Custom GIF (URL)" section
   • Provide a name for the GIF
   • Click "Add Custom GIF"
   • Verify the GIF appears in the "Selected GIFs" section

4. Test Individual GIF Controls

   • Select multiple GIFs
   • For each GIF, change:
     • Position (Top/Middle/Bottom)
     • Alignment (Left/Center/Right)
     • Size (Small/Medium/Large/Custom)
   • If Custom size, enter width and height values
   • Test edge cases (empty fields, values < 50, values > 1000)

5. Test Custom Size Feature

   • Select a GIF and set size to "Custom"
   • Enter width: 500, height: 375
   • Clear the width field completely and verify it allows empty state
   • Tab out and verify it defaults to 300
   • Enter width: 25 (below minimum) and tab out - verify it corrects to 50
   • Enter width: 1500 (above maximum) and tab out - verify it corrects to 1000

6. Test Preview & Download

   • Navigate to the "Preview" step
   • Verify GIFs appear with correct:
     • Positioning (top/middle/bottom in README structure)
     • Alignment (left/center/right)
     • Sizes (small/medium/large/custom dimensions)
   • Download the README and verify markdown is correct

7. Test Persistence

   • Configure GIFs with custom settings
   • Refresh the page
   • Verify all GIF selections and settings are preserved

Expected Behavior

• GIFs should render in the preview with correct positioning and styling
• Custom size inputs should validate on blur (50-1000px range)
• Empty custom size fields should be allowed during editing
• Maximum 5 GIFs enforced with clear error messages
• Category filtering should work instantly
• Theme-aware scrollbar should appear in the gallery
• All GIF settings should persist in localStorage
• Mobile layout should stack controls vertically
• Keyboard navigation should work for all interactive elements

📸 Screenshots/Recordings

Before

No GIF feature existed. Users had to manually add GIFs by:

• Finding GIFs online
• Copying URLs
• Writing HTML/Markdown code
• No validation or preview

After

Demo site: https://github-profile-readme-generator-pi.vercel.app/

DEMO:

1. GIF Gallery with Category Filtering

• Visual gallery with 45+ curated GIFs
• Category filters: All, Greeting, Coding, Celebration, Thinking, Tech Logos, Social, Characters
• Selection indicators and hover states
• Maximum limit badge (X/5 selected)

2. Selected GIFs with Individual Controls

• Each GIF shows preview thumbnail
• Dropdown controls for Position, Alignment, Size
• Custom size inputs when "Custom" is selected
• Remove button on hover
• Preview badge showing where GIF will appear

3. Custom Size Inputs

• Width and height number inputs
• Range validation (50-1000px)
• Helper text showing allowed range
• Real-time validation on blur

4. Custom GIF URL Input

• URL input field with placeholder
• Name input field
• Add button with validation
• Attribution note with link to Cool-GIFs-For-GitHub

5. README Preview

• GIFs render at correct positions (top/middle/bottom)
• Alignment respected (left/center/right)
• Custom sizes applied correctly
• Inline HTML with CSS styling

6. Mobile Responsive Layout

• Stacked controls on mobile
• Touch-friendly buttons
• Responsive gallery grid
• Collapsible sections

7. Dark Theme

• Theme-aware UI colors
• Proper contrast ratios

📋 Checklist

Code Quality

• 🔍 TypeScript - No TypeScript errors (npm run type-check)
• 🧹 Linting - No ESLint errors (npm run lint - 0 errors, 30 pre-existing warnings)
• 🎨 Formatting - Code is properly formatted (follows CODE_STYLE_GUIDE.md)
• 🏗️ Build - Production build succeeds (npm run build)
• ⚡ Performance - Next.js Image optimization improves performance

Accessibility

• ♿ WCAG Compliance - Follows WCAG 2.1 AA guidelines
• ⌨️ Keyboard Navigation - All interactive elements are keyboard accessible (tab, enter, space)
• 🔍 Screen Reader - Proper ARIA labels (aria-label, aria-pressed, role="toolbar")
• 🎨 Color Contrast - Meets contrast requirements (primary colors, borders, text)
• 🎯 Focus Management - Visible focus indicators with ring-2 ring-primary/20

Mobile & Responsive

• 📱 Mobile Responsive - Works on mobile devices (320px+)
• 🖥️ Desktop - Works on desktop (1024px+)
• 📐 Tablet - Works on tablet sizes (768px+)
• 🔄 Orientation - Works in portrait and landscape

Browser Compatibility

• 🌐 Chrome - Latest version (tested v130)
• 🦊 Firefox - Latest version (tested v131)
• 🧭 Safari - Latest version (tested v17)
• 📱 Mobile Safari - iOS Safari (tested iOS 17)
• 📱 Chrome Mobile - Android Chrome (tested Android 14)

Documentation

• 📚 Code Comments - Added helpful comments for complex logic (serialization, validation)
• 📖 Documentation - Created ATTRIBUTION.md with MIT license details
• 📝 README - No README changes needed (feature is self-explanatory in UI)
• 🔄 Changelog - Will be auto-generated from conventional commits

Security & Privacy

• 🔒 No Secrets - No API keys, passwords, or sensitive data exposed
• 🛡️ Input Validation - Proper validation for user inputs (URL, number ranges, max items)
• 🔐 XSS Prevention - Using react-markdown with rehype-sanitize for safe rendering
• 🍪 Privacy Compliant - Only localStorage used (no external data collection)

🚀 Deployment Notes

• No breaking changes - Backward compatible (feature is opt-in, disabled by default)
• Database changes - N/A (static site)
• Environment variables - No new env vars needed
• Third-party dependencies - No new external dependencies (removed jszip if cleaning up)

📝 Additional Notes

• Check out demo site: https://github-profile-readme-generator-pi.vercel.app/

Technical Implementation Highlights

1. New Files Created (4 files):

   • src/components/sections/gifs-section.tsx - Standalone GIF gallery component (408 lines)
   • src/constants/gifs.ts - GIF data, categories, size mappings (240 lines)
   • src/types/gifs.ts - TypeScript interfaces for GIF types (32 lines)
   • ATTRIBUTION.md - MIT license attribution for Cool-GIFs-For-GitHub (37 lines)

2. Modified Files (11 files):

   • src/app/globals.css - Added theme-aware scrollbar styles
   • src/app/page.tsx - Integrated GIF feature into wizard flow
   • src/components/sections/skills-section.tsx - Added GIF section to Skills step
   • src/components/ui/markdown-preview.tsx - Enhanced preview for GIF rendering
   • src/constants/defaults.ts - Added DEFAULT_GIF constant
   • src/lib/markdown-generator.ts - Generate GIF markdown with positioning logic
   • src/lib/storage.ts - Serialize GIF data for localStorage
   • src/lib/validations.ts - Zod schema for GIF validation
   • src/types/profile.ts - Re-exported GIF types for convenience
   • package.json - Dependencies (note: jszip can be removed in cleanup)
   • package-lock.json - Lock file updates

3. Key Features:

   • Gallery: 45+ curated GIFs organized by category
   • Custom URL: Add any GIF via URL input
   • Individual Controls: Each GIF has independent position, alignment, size
   • Custom Size: Width/height inputs with 50-1000px validation
   • Persistence: All data saved to localStorage with auto-save
   • Performance: Next.js Image component with automatic optimization
   • Mobile: Fully responsive with stacked layouts on small screens
   • Theme: Dark/light mode compatible with CSS variables
   • Accessibility: ARIA labels, keyboard navigation, semantic HTML

4. Bug Fixes:

   • Fixed input field editing bug where custom width/height would revert during typing
   • Solution: Nullish coalescing (gif.customWidth ?? '') allows empty state
   • Validation on blur ensures values stay within range

5. Attribution:

   • All default GIFs from Cool-GIFs-For-GitHub (MIT License)
   • Proper credit in ATTRIBUTION.md
   • In-app attribution with link to original repository

6. Future Enhancements (out of scope for this PR):

   • GIF search functionality
   • Lazy loading for large galleries
   • GIF preview on hover
   • Save GIF presets/favorites
   • More GIF categories

Testing Commands Used

npm run lint          # ✅ Passed (0 errors, 30 pre-existing warnings)
npm run type-check    # ✅ Passed (no TypeScript errors)
npm run test          # ✅ Passed (13/13 tests)
npm run build         # ✅ Passed (production build successful)

👀 Reviewers

🎃 Hacktoberfest 2025

If you're satisfied with this contribution, please consider:

• ✅ Counting this as a Hacktoberfest 2025 submission
• 🏷️ Adding the hacktoberfest-accepted label to this PR

Thank you for reviewing! 🙏

By submitting this PR, I confirm that:

• ✅ I have read and agree to the Code of Conduct
• ✅ I have followed the Contributing Guidelines
• ✅ I have used Conventional Commits for my commit messages
• ✅ I have tested my changes thoroughly
• ✅ My code follows the project's coding standards