From 85b41142483e15667a694a032bb346d581746191 Mon Sep 17 00:00:00 2001
From: hjkim0905 <eax9952@gmail.com>
Date: Mon, 25 May 2026 00:12:17 +0900
Subject: [PATCH] fix(skills): clarify modal focus restoration scope in
 frontend-a11y

---
 skills/frontend-a11y/SKILL.md | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/skills/frontend-a11y/SKILL.md b/skills/frontend-a11y/SKILL.md
index 6408b04b..46adc8cc 100644
--- a/skills/frontend-a11y/SKILL.md
+++ b/skills/frontend-a11y/SKILL.md
@@ -308,7 +308,9 @@ export function Dropdown({ options, onSelect }: { options: string[]; onSelect: (
 
 Focus must move logically when UI state changes — especially for modals and route transitions.
 
-### Modal Focus Trap
+### Modal Focus Restoration
+
+> This example covers initial focus and restoration. For a full focus trap (Tab/Shift+Tab cycling within the modal), use a library like [`focus-trap-react`](https://github.com/focus-trap/focus-trap-react) which handles edge cases like dynamic content and nested portals.
 
 ```tsx
 export function Modal({ isOpen, onClose, title, children }: { isOpen: boolean; onClose: () => void; title: string; children: React.ReactNode }) {
@@ -317,9 +319,11 @@ export function Modal({ isOpen, onClose, title, children }: { isOpen: boolean; o
 
   useEffect(() => {
     if (isOpen) {
+      // Save currently focused element and move focus into modal
       previousFocusRef.current = document.activeElement as HTMLElement;
       modalRef.current?.focus();
     } else {
+      // Restore focus to the element that opened the modal
       previousFocusRef.current?.focus();
     }
   }, [isOpen]);