Maximum accessibility overhaul: skip link, reduced motion, ARIA fixes, external link labels, focus management, contrast, ESLint a11y, axe-core, page titles

Made-with: Cursor

Author: rayraycodes

eslint.config.js

@@ -0,0 +1,62 @@
+import js from '@eslint/js';
+import tseslint from 'typescript-eslint';
+import jsxA11y from 'eslint-plugin-jsx-a11y';
+
+export default [
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    files: ['**/*.{js,jsx,ts,tsx}'],
+    plugins: {
+      'jsx-a11y': jsxA11y,
+    },
+    languageOptions: {
+      parser: tseslint.parser,
+      parserOptions: {
+        ecmaVersion: 'latest',
+        sourceType: 'module',
+        ecmaFeatures: {
+          jsx: true,
+        },
+      },
+      globals: {
+        window: 'readonly',
+        document: 'readonly',
+        console: 'readonly',
+        module: 'readonly',
+        require: 'readonly',
+        process: 'readonly',
+        __dirname: 'readonly',
+        __filename: 'readonly',
+        exports: 'writable',
+        Buffer: 'readonly',
+        setTimeout: 'readonly',
+        clearTimeout: 'readonly',
+        setInterval: 'readonly',
+        clearInterval: 'readonly',
+        fetch: 'readonly',
+        FormData: 'readonly',
+        URL: 'readonly',
+        URLSearchParams: 'readonly',
+        Headers: 'readonly',
+        Request: 'readonly',
+        Response: 'readonly',
+        AbortController: 'readonly',
+        Blob: 'readonly',
+        File: 'readonly',
+        navigator: 'readonly',
+        localStorage: 'readonly',
+        sessionStorage: 'readonly',
+        Image: 'readonly',
+        ResizeObserver: 'readonly',
+        MutationObserver: 'readonly',
+        IntersectionObserver: 'readonly',
+        requestAnimationFrame: 'readonly',
+        cancelAnimationFrame: 'readonly',
+      },
+    },
+    rules: {
+      ...jsxA11y.configs.recommended.rules,
+    },
+  },
+];

package-lock.json

@@ -1,5 +1,6 @@
 {
       "name": "Regan Maharjan Portfolio Website",
+      "type": "module",
       "version": "0.1.0",
       "private": true,
       "dependencies": {
@@ -49,14 +50,18 @@
             "vaul": "^1.1.2"
       },
       "devDependencies": {
+            "@axe-core/react": "^4.11.1",
             "@types/node": "^20.10.0",
             "@types/react": "^19.2.4",
             "@types/react-dom": "^19.2.3",
             "@vitejs/plugin-react-swc": "^3.10.2",
+            "eslint-plugin-jsx-a11y": "^6.10.2",
+            "typescript-eslint": "^8.56.1",
             "vite": "6.3.5"
       },
       "scripts": {
             "dev": "vite",
-            "build": "vite build"
+            "build": "vite build",
+            "lint": "eslint src --ext .ts,.tsx"
       }
 }

package.json

@@ -1,4 +1,5 @@
 import { useEffect, useRef } from 'react';
+import { MotionConfig } from 'motion/react';
 import { HashRouter as Router, Routes, Route, Navigate, useLocation } from 'react-router-dom';
 import { Navigation } from './components/Navigation';
 import { Footer } from './components/Footer';
@@ -56,11 +57,13 @@ function AppContent() {
     };
   }, [location.pathname, isDetailPage]);
 
-  // Disable right-click context menu on all pages
+  // Scoped context menu prevention: only on images to avoid interfering with assistive tech
   useEffect(() => {
     const handleContextMenu = (e: MouseEvent) => {
-      e.preventDefault();
-      return false;
+      const target = e.target as HTMLElement;
+      if (target.closest('img')) {
+        e.preventDefault();
+      }
     };
 
     document.addEventListener('contextmenu', handleContextMenu);
@@ -75,10 +78,49 @@ function AppContent() {
     preloadCriticalImages();
   }, []);
 
+  // Page-specific document titles for screen reader users
+  const titleMap: Record<string, string> = {
+    '/': 'Regan Maharjan Portfolio',
+    '/about': 'About | Regan Maharjan',
+    '/experience': 'Experience | Regan Maharjan',
+    '/projects': 'Projects | Regan Maharjan',
+    '/impact': 'Stories of Impact | Regan Maharjan',
+    '/storiesofadventure': 'Stories of Adventure | Regan Maharjan',
+    '/accessibility': 'Accessibility | Regan Maharjan',
+    '/contact': 'Contact | Regan Maharjan',
+    '/photography': 'Photography | Regan Maharjan',
+    '/cms': 'Content Management | Regan Maharjan',
+  };
+  useEffect(() => {
+    const segments = location.pathname.split('/').filter(Boolean);
+    const basePath = segments[0] ? `/${segments[0]}` : '/';
+    const title = titleMap[basePath] ?? titleMap[location.pathname] ?? 'Regan Maharjan Portfolio';
+    document.title = title;
+  }, [location.pathname]);
+
+  // Focus main content on route change (helps keyboard/screen reader users)
+  useEffect(() => {
+    const main = document.getElementById('main-content');
+    main?.focus();
+  }, [location.pathname]);
+
   return (
-    <div className="min-h-screen bg-background flex flex-col">
+    <div className="min-h-screen bg-background flex flex-col relative">
+      {/* Skip link: first focusable element for keyboard users */}
+      <a
+        href="#main-content"
+        className="skip-link"
+        onClick={(e) => {
+          e.preventDefault();
+          const main = document.getElementById('main-content');
+          main?.focus();
+          main?.scrollIntoView();
+        }}
+      >
+        Skip to main content
+      </a>
       {!isHomePage && <Navigation />}
-      <main className="flex-1">
+      <main id="main-content" className="flex-1" tabIndex={-1}>
         <Routes>
           <Route path="/" element={
             <div className="min-h-screen flex flex-col items-center justify-center bg-background">
@@ -108,8 +150,10 @@ function AppContent() {
 
 export default function App() {
   return (
-    <Router>
-      <AppContent />
-    </Router>
+    <MotionConfig reducedMotion="user">
+      <Router>
+        <AppContent />
+      </Router>
+    </MotionConfig>
   );
 }

src/App.tsx

@@ -17,6 +17,8 @@ export function Navigation({ inline = false }: NavigationProps) {
   const topNavContainerRef = useRef<HTMLDivElement>(null);
   const navRef = useRef<HTMLElement>(null);
   const tabRefs = useRef<(HTMLAnchorElement | null)[]>([]);
+  const mobileMenuButtonRef = useRef<HTMLButtonElement>(null);
+  const firstMobileLinkRef = useRef<HTMLAnchorElement>(null);
 
   useEffect(() => {
     let rafId: number | null = null;
@@ -77,6 +79,22 @@ export function Navigation({ inline = false }: NavigationProps) {
     }, 150);
   }, [location.pathname, inline]);
 
+  // Mobile menu focus management: focus first link when opening, return focus to button when closing
+  const prevMobileMenuOpenRef = useRef(isMobileMenuOpen);
+  useEffect(() => {
+    if (inline) return;
+    if (isMobileMenuOpen) {
+      const timer = setTimeout(() => {
+        firstMobileLinkRef.current?.focus();
+      }, 100);
+      prevMobileMenuOpenRef.current = true;
+      return () => clearTimeout(timer);
+    } else if (prevMobileMenuOpenRef.current) {
+      prevMobileMenuOpenRef.current = false;
+      mobileMenuButtonRef.current?.focus();
+    }
+  }, [isMobileMenuOpen, inline]);
+
   const navLinks = inline ? (contentData.navigation.homeLinks || contentData.navigation.links) : contentData.navigation.links;
 
   // Icon mapping for navigation links
@@ -295,6 +313,7 @@ export function Navigation({ inline = false }: NavigationProps) {
           {/* Mobile Menu Button - touch-friendly (min 44px) */}
           <div className="flex-1 flex justify-end lg:justify-center">
             <button
+              ref={mobileMenuButtonRef}
               onClick={() => setIsMobileMenuOpen(!isMobileMenuOpen)}
               className="lg:hidden min-h-[44px] min-w-[44px] flex items-center justify-center rounded-lg hover:bg-black/5 active:bg-black/10 transition-colors touch-manipulation"
               aria-label={isMobileMenuOpen ? 'Close menu' : 'Open menu'}
@@ -315,12 +334,13 @@ export function Navigation({ inline = false }: NavigationProps) {
           className="lg:hidden bg-white border-t border-gray-200 shadow-lg"
         >
           <div className="w-full max-w-[90rem] mx-auto px-4 sm:px-6 py-4 sm:py-5 space-y-2 text-center">
-            {navLinks.map((link: { path: string; label: string }) => {
+            {navLinks.map((link: { path: string; label: string }, index: number) => {
               const isActive = location.pathname === link.path;
               const IconComponent = getIconForPath(link.path);
               return (
                 <Link
                   key={link.path}
+                  ref={index === 0 ? firstMobileLinkRef : undefined}
                   to={link.path}
                   onClick={() => setIsMobileMenuOpen(false)}
                   className={`block w-full py-4 px-6 rounded-xl transition-colors touch-manipulation min-h-[48px] flex items-center justify-center gap-2 ${

src/components/Navigation.tsx

@@ -98,25 +98,25 @@ export function About() {
                 className="text-gray-500 hover:text-gray-900 transition-colors inline-flex items-center"
                 aria-label="Email"
               >
-                <Mail className="w-5 h-5" />
+                <Mail className="w-5 h-5" aria-hidden />
               </a>
               <a
                 href={contentData.assets.links.linkedin}
                 target="_blank"
                 rel="noopener noreferrer"
                 className="text-gray-500 hover:text-gray-900 transition-colors inline-flex items-center"
-                aria-label="LinkedIn"
+                aria-label="LinkedIn (opens in new window)"
               >
-                <Linkedin className="w-5 h-5" />
+                <Linkedin className="w-5 h-5" aria-hidden />
               </a>
               <a
                 href={contentData.assets.links.instagram}
                 target="_blank"
                 rel="noopener noreferrer"
                 className="text-gray-500 hover:text-gray-900 transition-colors inline-flex items-center"
-                aria-label="Instagram"
+                aria-label="Instagram (opens in new window)"
               >
-                <Instagram className="w-5 h-5" />
+                <Instagram className="w-5 h-5" aria-hidden />
               </a>
             </div>
             <p className="text-lg md:text-xl text-gray-700 leading-relaxed mt-8">
@@ -125,7 +125,7 @@ export function About() {
                 to="/experience"
                 className="inline-flex items-center gap-1.5 text-gray-900 hover:text-gray-600 underline transition-colors"
               >
-                <FileText className="w-4 h-4 shrink-0" />
+                <FileText className="w-4 h-4 shrink-0" aria-hidden />
                 resume
               </Link>
               .

src/components/pages/About.tsx

@@ -77,7 +77,7 @@ export function Accessibility() {
                 whileHover={{ y: -4 }}
                 className="bg-gradient-to-b from-blue-50/50 to-white border border-blue-100 rounded-2xl p-8 transition-all duration-300 hover:shadow-lg"
               >
-                <principle.icon className="w-8 h-8 mb-4 text-blue-600" />
+                <principle.icon className="w-8 h-8 mb-4 text-blue-600" aria-hidden />
                 <h3 className="mb-2">{principle.title}</h3>
                 <p className="text-muted-foreground text-sm">{principle.description}</p>
               </motion.div>
@@ -118,7 +118,7 @@ export function Accessibility() {
                 <ul className="space-y-2">
                   {category.items.map((item) => (
                     <li key={item} className="flex items-start gap-2 text-sm">
-                      <CheckCircle2 className="w-4 h-4 text-green-600 flex-shrink-0 mt-0.5" />
+                      <CheckCircle2 className="w-4 h-4 text-green-600 flex-shrink-0 mt-0.5" aria-hidden />
                       <span className="text-muted-foreground">{item}</span>
                     </li>
                   ))}
@@ -159,7 +159,7 @@ export function Accessibility() {
               >
                 <div className="flex items-start gap-4">
                   <div className="w-12 h-12 rounded-xl bg-blue-100 flex items-center justify-center flex-shrink-0">
-                    <Zap className="w-6 h-6 text-blue-600" />
+                    <Zap className="w-6 h-6 text-blue-600" aria-hidden />
                   </div>
                   <div className="flex-1">
                     <h3 className="text-xl mb-1">{tool.name}</h3>
@@ -322,7 +322,7 @@ export function Accessibility() {
                   Send an Email
                 </Button>
               </a>
-              <a href={contentData.assets.links.linkedin} target="_blank" rel="noopener noreferrer">
+              <a href={contentData.assets.links.linkedin} target="_blank" rel="noopener noreferrer" aria-label="Connect on LinkedIn (opens in new window)">
                 <Button size="lg" variant="outline" className="rounded-full px-8">
                   Connect on LinkedIn
                 </Button>

src/components/pages/Accessibility.tsx

@@ -113,7 +113,7 @@ export function Contact() {
 
                   <Button type="submit" size="lg" className="w-full rounded-full group">
                     {form.submit}
-                    <Send className="ml-2 w-4 h-4 group-hover:translate-x-1 transition-transform" />
+                    <Send className="ml-2 w-4 h-4 group-hover:translate-x-1 transition-transform" aria-hidden />
                   </Button>
                 </form>
               </div>
@@ -139,14 +139,15 @@ export function Contact() {
                       href={link.href}
                       target="_blank"
                       rel="noopener noreferrer"
+                      aria-label={`${link.label} (opens in new window)`}
                       initial={{ opacity: 0, x: 30 }}
                       animate={{ opacity: 1, x: 0 }}
                       transition={{ duration: 0.6, delay: 0.6 + index * 0.1 }}
                       whileHover={{ x: 4 }}
                       className="flex items-center gap-4 p-4 surface-elevated rounded-xl transition-all duration-300 hover:shadow-md group"
                     >
                       <div className="w-12 h-12 rounded-xl bg-blue-100 flex items-center justify-center group-hover:bg-blue-200 transition-colors">
-                        <link.icon className="w-6 h-6 text-blue-600" />
+                        <link.icon className="w-6 h-6 text-blue-600" aria-hidden />
                       </div>
                       <div>
                         <div className="mb-1">{link.label}</div>
@@ -194,7 +195,7 @@ export function Contact() {
                   {cta.primary}
                 </Button>
               </a>
-              <a href={links.linkedin} target="_blank" rel="noopener noreferrer">
+              <a href={links.linkedin} target="_blank" rel="noopener noreferrer" aria-label="Connect on LinkedIn (opens in new window)">
                 <Button size="lg" variant="outline" className="rounded-full px-8">
                   {cta.secondary}
                 </Button>

src/components/pages/Contact.tsx

@@ -172,7 +172,7 @@ export function Experience() {
                   Send an Email
                 </Button>
               </a>
-              <a href={contentData.assets.links.linkedin} target="_blank" rel="noopener noreferrer">
+              <a href={contentData.assets.links.linkedin} target="_blank" rel="noopener noreferrer" aria-label="Connect on LinkedIn (opens in new window)">
                 <Button size="lg" variant="outline" className="rounded-full px-8">
                   Connect on LinkedIn
                 </Button>

src/components/pages/Experience.tsx

@@ -44,33 +44,33 @@ export function Home() {
               Feel free to explore!{' '}
               <Link 
                 to="/about" 
-                className="inline-flex items-center gap-1.5 px-3 sm:px-4 py-2 sm:py-2.5 rounded-lg bg-gray-200 hover:bg-gray-300 border-2 border-gray-300 hover:border-gray-400 transition-all font-semibold text-gray-900 shadow-sm hover:shadow-md my-1 sm:my-0"
+                className="inline-flex items-center gap-1.5 px-3 sm:px-4 py-2 sm:py-2.5 rounded-lg bg-gray-200 hover:bg-gray-300 border-2 border-gray-300 hover:border-gray-400 transition-all font-semibold text-gray-900 shadow-sm hover:shadow-md my-1 sm:my-0 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-500 focus-visible:ring-offset-2"
               >
-                <Hand className="w-4 h-4 sm:w-5 sm:h-5" />
+                <Hand className="w-4 h-4 sm:w-5 sm:h-5" aria-hidden />
                 Get to know me
               </Link>
               {' '}better,{' '}
               <Link 
                 to="/storiesofadventure" 
-                className="inline-flex items-center gap-1.5 px-3 sm:px-4 py-2 sm:py-2.5 rounded-lg bg-gray-200 hover:bg-gray-300 border-2 border-gray-300 hover:border-gray-400 transition-all font-semibold text-gray-900 shadow-sm hover:shadow-md my-1 sm:my-0"
+                className="inline-flex items-center gap-1.5 px-3 sm:px-4 py-2 sm:py-2.5 rounded-lg bg-gray-200 hover:bg-gray-300 border-2 border-gray-300 hover:border-gray-400 transition-all font-semibold text-gray-900 shadow-sm hover:shadow-md my-1 sm:my-0 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-500 focus-visible:ring-offset-2"
               >
-                <BookOpen className="w-4 h-4 sm:w-5 sm:h-5" />
+                <BookOpen className="w-4 h-4 sm:w-5 sm:h-5" aria-hidden />
                 dive into my stories
               </Link>
               ,{' '}
               <Link 
                 to="/projects" 
-                className="inline-flex items-center gap-1.5 px-3 sm:px-4 py-2 sm:py-2.5 rounded-lg bg-gray-200 hover:bg-gray-300 border-2 border-gray-300 hover:border-gray-400 transition-all font-semibold text-gray-900 shadow-sm hover:shadow-md my-1 sm:my-0"
+                className="inline-flex items-center gap-1.5 px-3 sm:px-4 py-2 sm:py-2.5 rounded-lg bg-gray-200 hover:bg-gray-300 border-2 border-gray-300 hover:border-gray-400 transition-all font-semibold text-gray-900 shadow-sm hover:shadow-md my-1 sm:my-0 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-500 focus-visible:ring-offset-2"
               >
-                <FolderKanban className="w-4 h-4 sm:w-5 sm:h-5" />
+                <FolderKanban className="w-4 h-4 sm:w-5 sm:h-5" aria-hidden />
                 check out my projects
               </Link>
               , and{' '}
               <Link 
                 to="/photography" 
-                className="inline-flex items-center gap-1.5 px-3 sm:px-4 py-2 sm:py-2.5 rounded-lg bg-gray-200 hover:bg-gray-300 border-2 border-gray-300 hover:border-gray-400 transition-all font-semibold text-gray-900 shadow-sm hover:shadow-md my-1 sm:my-0"
+                className="inline-flex items-center gap-1.5 px-3 sm:px-4 py-2 sm:py-2.5 rounded-lg bg-gray-200 hover:bg-gray-300 border-2 border-gray-300 hover:border-gray-400 transition-all font-semibold text-gray-900 shadow-sm hover:shadow-md my-1 sm:my-0 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-blue-500 focus-visible:ring-offset-2"
               >
-                <Camera className="w-4 h-4 sm:w-5 sm:h-5" />
+                <Camera className="w-4 h-4 sm:w-5 sm:h-5" aria-hidden />
                 browse my photo stories
               </Link>
               .