ScreenReaderStudio는 웹 페이지나 HTML 코드를 입력하면, 스크린 리더가 어떻게 읽을지를 시각적으로 예측하고 접근성 문제를 진단해 주는 도구입니다. 스크린 리더 환경을 직접 확인하기 어려운 개발자를 위해, 웹 접근성 개선을 직관적이고 효율적으로 지원합니다.
Deployed website | Frontend Repository | Backend Repository
- ScreenReaderStudio
- 📖 Table of Contents
- 🛠 Tech Stacks
- 🔥 Motivation
- 📋 Features
- 🏔 Challenges
- 💭 Memoir
토스의 기술 블로그 게시글 중 우리가 몰랐던 시각 장애인의 UX을 읽다가 다음과 같은 문장을 접했습니다.
“그런데 스크린 리더가 ‘아이콘 하트’라고 읽어주면, 사용자는 이게 찜하기 버튼인지 알기 어려워요.”
이 문장을 통해, 시각장애 사용자에게는 스크린 리더가 읽어주는 한 문장, 한 단어가 곧 UI의 전부일 수 있다는 사실을 다시금 인식하게 되었습니다. 시각 정보 없이 콘텐츠를 해석해야 하는 환경에서, 텍스트 외 요소들이 어떻게 설명되느냐는 곧 UX의 핵심이 될 수 있기 때문입니다.
또한, 이 문구를 읽는 순간, 과거 웹 개발 중 img 태그에 alt 속성을 빠뜨렸을 때 콘솔에서 경고 메시지를 본 기억이 떠올랐습니다.
그 당시에는 단순히 린트 에러처럼 여겼던 그 경고가, 이제는 사용자에게 ‘이 이미지는 무엇인가’를 설명해주는 기능이었음을 깨닫게 된 것 이었습니다.
이와 같은 경험을 통해, 우리는 잘 만들었다고 생각하는 웹 서비스에서도 어떤 사용자에게는 사용하기 어려운 서비스일 수 있다는 점을 체감하게 되었습니다. 하지만 스크린 리더의 동작을 실제로 확인해보는 것은 여전히 어렵고, 개발 도중 혹은 배포 이후에도 즉각적으로 접근하기 힘든 영역이기도 합니다.
따라서, 스크린 리더가 실제로 어떻게 읽어줄지를 시각적으로 예측해주고, 접근성 문제를 자동으로 진단해주는 도구가 있다면 분명 도움이 될 것이라는 문제의식이 생겼습니다.
이러한 계기로, 개발자와 디자이너가 스크린 리더 환경을 별도의 설정 없이 손쉽게 파악하고, 접근성 이슈를 빠르게 인지하고 개선할 수 있도록 돕는 도구인 ScreenReaderStudio를 개발하게 되었습니다.
서비스의 첫 화면입니다. 진행하고 싶은 페이지의 URL 혹은 HTML 코드를 입력한 후 원하는 스크린 리더 타입을 선택한 뒤, 분석 버튼을 눌러 스크린 리더 대본 생성 및 접근성 이슈 분석을 진행할 수 있습니다.
선택한 스크린 리더 타입에 해당하는 스크린 리더 대본이 생성됩니다. 원하는 항목을 선택하면 해당 항목을 하이라이팅으로 확인할 수 있고, TTS로 음성이 출력됩니다.
axe-core를 통한 접근성 이슈 분석의 결과 화면입니다. 영향 요소를 선택하면 해당 요소가 iframe에서 하이라이팅되어 어떤 요소에 접근성 이슈가 있는지 확인할 수 있습니다.
로그인한 사용자에 한하여 분석 결과를 공유할 수 있습니다. 카카오 로그인을 통해 회원가입 및 로그인을 진행할 수 있습니다.
위와 같이 사용자가 로그인 한 경우, 분석 결과를 공유할 수 있는 링크 복사 버튼이 생깁니다. 해당 버튼을 클릭하면, 공유 링크가 복사되고 결과를 다른 사람과 공유할 수 있습니다.
공유 링크를 방문하면 위와 같이 분석을 진행한 사용자가 아니더라도 스크린 리더 대본과 접근성 이슈 분석 결과를 확인할 수 있습니다.
초기 기획 단계에서 ScreenReaderStudio는 사용자가 입력한 페이지 URL이 아닌, 개별 컴포넌트의 JSX 코드만을 기반으로 접근성 분석 및 스크린 리더 대본을 생성하는 구조를 고민했습니다. 이는 개발자 친화적인 인터페이스를 제공하며, Storybook이나 디자인 시스템 같은 문맥에서 개별 컴포넌트 단위로 접근성을 확인할 수 있도록 하기 위함이었습니다.
이를 위해 Babel을 사용해 JSX 코드를 JavaScript AST로 변환하고, @babel/traverse로 트리를 순회하며 접근성 이슈를 탐지하는 분석 로직을 구성하려 했습니다.
- 실제 서비스에 사용되는 React 컴포넌트는 단순한
<button>이나<img>수준의 요소가 아닌 경우가 대부분이며, 수많은 외부 라이브러리, 중첩된 컴포넌트, 동적 props, context 의존 등이 얽혀 있는 구조입니다. - 이로 인해 Babel로 추출한 AST만으로는 컴포넌트의 실제 렌더링 결과를 예측하기 어렵고, 의미 있는 접근성 분석 결과를 도출하는 데 한계가 있었습니다.
- 접근성 분석은 본질적으로 렌더링된 DOM의 구조, 시멘틱 요소, 포커스 흐름 등 실행 시점의 상태에 의존합니다.
- JSX 코드를 정적으로 분석하는 것은 컴파일 결과나 브라우저 환경에서 실제로 생성된 DOM과 다를 수 있으며, 분석 정확도가 낮아질 수밖에 없습니다.
- 예를 들어 조건부 렌더링, 사용자 상호작용에 따른 변경 사항 등은 정적 분석으로는 포착이 불가능합니다.
- 실무에서는 개별 컴포넌트가 아닌, 전체 페이지 단위의 접근성 품질이 중요합니다.
- 예를 들어, 버튼이 존재하더라도 그 버튼이 어디에 위치해 있는지, 어떤 시멘틱 구조 내에 포함되어 있는지, 페이지 내에서 어떤 역할을 수행하는지 등은 페이지 전반의 문맥을 고려해야 분석이 가능합니다.
- 단일 컴포넌트만 따로 떼어내 접근성 진단을 한다는 것은 실질적인 분석 시나리오와 맞지 않음을 점차 깨닫게 되었습니다.
초기에는 개발자 관점에서 접근하기 쉬운 인터페이스를 제공하고자 JSX 코드 기반의 분석을 시도했지만, 점차 접근성 분석의 본질은 정적 코드 분석이 아닌 실제 사용자 환경에서의 인터랙션 가능성, 화면 구조, 콘텐츠 흐름을 바탕으로 해야 한다는 사실을 직시하게 되었습니다.
그 결과, "코드가 아닌 웹페이지 전체를 대상으로 분석해야 한다"는 관점을 받아들이게 되었고, “URL 기반 접근성 분석” 이라는 방향으로 전환하게 되었습니다.
접근성 분석의 정확성과 실효성을 보장하기 위해, JSX 코드 대신 전체 웹페이지를 Headless Browser로 렌더링하고 분석하는 구조로 변경했습니다. (→ 2. 클라이언트에서는 iframe을 사용하려면 겪는 문제와 해결 방법 참고)
- Babel 기반 JSX 분석 폐기
- 서버 측에서 Puppeteer로 페이지를 실제로 렌더링한 후, axe-core를 통해 실시간 DOM 기반 접근성 분석 수행
- 컴포넌트 단위가 아닌 페이지 전체 단위로 스크린 리더 대본과 이슈를 생성하는 구조 채택
- 실제 환경 기반 분석: 렌더링 이후의 DOM을 기준으로 하기 때문에, 조건부 렌더링, 동적 콘텐츠도 정확하게 분석 가능
- 정확도 향상: 코드 구조가 복잡하더라도 최종 출력된 HTML에 기반해 분석하므로, 누락 없이 이슈를 포착할 수 있음
- 개발자 실무 흐름과 정합: 실제 접근성 테스트는 페이지 단위로 진행되며, 이 흐름과 구조적으로 일치
- 개별 컴포넌트 테스트는 불가: 컴포넌트 단위에서의 마이크로한 분석은 불가능하며, 별도의 storybook 환경 등을 분석 대상으로 삼아야 함
- 개발 초기 아이디어와의 괴리: 초기 기획과는 다소 결이 달라졌으나, 최종 사용자 요구와 분석 신뢰도 측면에서 훨씬 효과적인 구조로 진화했다고 판단
JSX 코드 기반의 정적 분석은 기술적으로 시도해볼 수 있는 접근이었지만, 실제 웹 접근성 분석이라는 목적에는 부합하지 않는 방법이었습니다. 결과적으로 우리는 “코드를 분석하는 것이 아니라, 사용자에게 보여지는 결과를 분석하는 것이 본질”이라는 점을 깨달았습니다.
이러한 반성과 판단을 통해, ScreenReaderStudio는 코드 기반 분석이 아닌 URL 기반 페이지 분석 중심의 아키텍처로 재설계되었고, 이는 이후 iframe, 서버 렌더링, Skeleton UI 도입 등 모든 기술 결정의 기반이 되었습니다. 이 과정은 단순한 기술 변경이 아닌, 문제의 본질을 다시 정의하고 구조적으로 대응한 전환의 시작점이었습니다.
ScreenReaderStudio는 초기에는 사용자가 입력한 웹페이지 URL을 클라이언트 측 iframe에 로드하여, 접근성 분석 및 스크린 리더 대본을 생성하려는 방향을 검토했습니다. 이는 서버 인프라를 줄이고, 빠른 분석 피드백을 제공하기 위한 가볍고 직관적인 아키텍처를 지향한 선택이었습니다.
iframe을 통해 실제 페이지를 불러오고, DOM을 분석하거나 음성 대본을 생성하는 방식을 고려했으나, 보안 정책과 브라우저 동작 원리에 의해 치명적인 한계를 갖고 있다는 사실을 점차 깨닫게 되었습니다.
- 외부 URL을 iframe에 로드할 경우, CORS 및 브라우저의 sandbox 제한으로 인해 DOM 접근이 차단되고, 페이지 내부의 JS 동작도 제약됩니다.
- 특히
sandbox="allow-scripts allow-same-origin"은 보안상 위험하다고 판단되어 일부 브라우저에서 강제 제한되며, 외부 API 요청(fetch/XHR) 등은 대부분 CORS 에러로 실패합니다.
Access to XMLHttpRequest at 'https://ko.wikipedia.org/...' from origin 'http://localhost:3000' has been blocked by CORS policy- iframe 내부에서 불러오는 CSS, 이미지, JS 등의 상대 경로 리소스가 깨지거나 404 오류가 발생하는 문제가 빈번하게 발생했습니다.
<base href="...">태그를 주입해 상대 경로 문제를 보완하려 했으나, 이는 HTML 문서에 국한되며 JS의 네트워크 요청에는 영향을 주지 않아 근본적인 해결책이 되지 못했습니다.
- iframe은 단순한 정적 HTML은 로드할 수 있지만, JavaScript 기반의 SPA 구조나 조건부 렌더링이 많은 페이지는 클라이언트 측에서 완전하게 구성된 DOM을 추출할 수 없습니다.
- 이로 인해 분석의 정확성이 떨어지며, 실제 사용자 시나리오와 괴리된 결과를 초래했습니다.
초기에는 iframe을 통해 웹페이지를 직접 브라우저에 불러오고, 그 상태에서 접근성 분석을 수행하는 것이 가장 빠르고 직관적인 방법이라고 판단했습니다. 그러나 점차 분석이 실패하는 사례들이 누적되면서, CORS, sandbox, 자원 로딩 등 다양한 보안 정책과 브라우저의 기본 동작 원리에 의해 클라이언트 측에서 외부 페이지를 안전하게 다루는 것이 구조적으로 불가능하다는 사실을 인식하게 되었습니다.
“그렇다면 어떻게 해서 브라우저는 우리가 iframe으로 불러온 외부 페이지를 이렇게 강하게 보호할 수 있는가?”라는 의문에서 출발해, 우리는 웹의 보안 모델을 더 깊이 조사하기 시작했습니다. 이 과정에서 브라우저는 사용자의 보안을 위해 외부 콘텐츠에 대한 자바스크립트 접근을 철저히 제한하도록 설계되어 있으며, 특히 클라이언트 환경에서는 보안 위협(CSRF, XSS 등)을 막기 위해 의도적으로 많은 기능이 봉인되어 있다는 사실을 이해하게 되었습니다.
하지만 조사 도중 발견한 흥미로운 사실은, 서버에서는 이런 제약이 존재하지 않는다는 점이었습니다. 서버에서는 브라우저처럼 보안 상의 이유로 요청을 제한하지 않으며, Puppeteer와 같은 Headless Browser를 통해 실제 브라우저 환경을 에뮬레이션하여 페이지를 로드하고 분석할 수 있습니다. 서버는 동일 출처 정책이나 CORS를 적용받지 않기 때문에, 클라이언트에서 차단되던 외부 요청이나 DOM 접근도 자유롭게 가능합니다.
결과적으로 우리는 “웹페이지를 클라이언트가 아닌 서버에서 렌더링하고 분석해야 한다”는 방향으로 전환하게 되었고, 이는 단순한 기술 스택 변경이 아니라, 웹의 보안 모델을 이해한 끝에 내린 구조적 전환이었습니다.
iframe 기반 접근의 한계를 극복하기 위해, 서버에서 Headless Chrome(Puppeteer)을 통해 페이지를 실제로 렌더링하고, axe-core를 통해 DOM을 분석하는 구조로 전환했습니다.
- 클라이언트 iframe 접근 방식 폐기
- 서버에서 Puppeteer를 통해 페이지 로딩 및 JavaScript 실행
- 분석 스크립트(axe-core) 주입 후, 실시간 DOM 구조 기반 접근성 진단 수행
- 분석 결과 및 스크린 리더 대본을 클라이언트로 전송하여 시각화
- 보안 정책 우회 가능: 서버에서 직접 외부 페이지를 요청하고 분석하므로, CORS나 sandbox 등의 브라우저 보안 정책에 영향을 받지 않습니다.
- 동적 콘텐츠 지원: JavaScript로 생성되는 SPA 페이지, 조건부 렌더링 등도 완전히 분석 가능
- 정확도 향상: 렌더링이 완료된 DOM을 기준으로 분석하므로, 실제 사용자 경험과 일치하는 결과를 도출
- 페이지 문맥 인식 가능: 전체 구조, 시멘틱 계층, 상호작용 흐름 등을 바탕으로 한 의미 있는 분석 수행 가능
- 서버 자원 소모: Puppeteer는 Chrome 인스턴스를 띄우기 때문에, CPU/메모리 소모가 높고 동시 요청 처리에 제약이 있습니다.
- 서버리스 환경의 제약: Vercel, Netlify 등 일부 플랫폼은 Puppeteer 실행에 제약이 있어, Railway 등 별도 인프라 필요
- 분석 속도 이슈: 렌더링과 분석에 수 초 이상이 소요될 수 있어, 사용자 피드백과 UX 설계가 반드시 병행되어야 함
iframe을 활용한 클라이언트 기반 분석은, 초기에는 가장 단순하고 효과적인 방법처럼 보였으나, 보안 정책(CORS/sandbox)과 브라우저 환경 제약으로 인해 구조적으로 실현 불가능한 방법이었습니다.
우리는 “브라우저는 외부 페이지를 보호하려는 방향으로 설계되어 있다”는 웹 보안의 본질을 마주하게 되었고, 분석을 클라이언트가 아닌 서버에서 수행해야 한다는 명확한 판단에 도달하게 되었습니다.
결국 ScreenReaderStudio는 iframe 기반 분석이 아닌, 서버 측 Headless Browser + 접근성 분석 엔진(axe-core) 조합을 중심으로 구조를 재설계했으며, 이는 단순한 기술 스택 변경을 넘어 웹 보안 모델에 대한 이해를 바탕으로 한 구조적 전환의 결과였습니다.
ScreenReaderStudio는 사용자가 입력한 웹페이지를 서버 측에서 Headless Browser로 렌더링하고, DOM을 기반으로 axe-core를 통해 접근성 분석 및 스크린 리더 대본을 생성하는 구조입니다. 이러한 분석 과정은 웹페이지의 복잡도와 네트워크 상태에 따라 수 초 이상의 시간이 소요될 수 있습니다. 이는 정적인 분석 툴과는 달리 브라우저 수준의 렌더링을 포함하기 때문입니다.
초기에는 결과 화면에 접근성 이슈와 스크립트가 모두 준비된 이후에만 결과 UI를 보여주는 구조였습니다. 하지만 분석 로직이 실행되고 있다는 피드백이 사용자에게 전혀 전달되지 않는다는 치명적인 UX 문제가 존재했습니다. 사용자 입장에서는 “버튼을 눌렀는데 아무런 반응이 없다”는 인상을 받을 수 있으며, 이로 인해 페이지를 이탈하거나 다시 요청을 보내는 불필요한 행위가 발생할 수 있습니다.
- Puppeteer가 실행되고 외부 웹페이지가 렌더링된 후
axe-core가 분석을 수행하는 데 걸리는 시간은 일반적으로 3~6초, 복잡한 웹페이지의 경우 10초 이상까지 소요될 수 있습니다. - 결과가 준비되기 전까지 아무런 시각적 변화가 없기 때문에, 사용자는 서비스가 멈췄거나 실패했다고 오해할 가능성이 높습니다.
- 초기 구현에서는 분석 중임을 알리는 spinner나 로딩 메시지, 또는 페이지 구성 요소의 placeholder가 전혀 존재하지 않았습니다.
- 텍스트 기반의 단순 안내(
"분석 중입니다...")만 존재했는데, 이는 시각적으로 너무 약하고 사용자 경험을 향상시키기엔 부족했습니다.
단순한 텍스트 로딩 메시지나 spinner 아이콘 하나로는 해결이 어렵다고 판단했습니다. 이 문제는 단순히 "로딩이 보이지 않는다"는 UI 문제를 넘어서, 사용자에게 "서비스가 현재 제대로 작동 중이다" 라는 심리적 확신을 줘야 하는 문제였기 때문입니다.
특히 ScreenReaderStudio의 경우, 분석 결과가 나타나기 전까지는 화면에 아무런 콘텐츠가 없기 때문에, 분석 결과의 형태를 예상 가능하게 시각적으로 제공해줄 필요가 있었습니다.
위 문제를 해결하기 위해, 결과 화면의 최종 분석 결과 레이아웃을 미리 흉내 내는 Skeleton UI를 도입했습니다.
Skeleton UI는 분석이 진행되는 동안에도 사용자에게 화면 구성의 윤곽을 먼저 보여줌으로써, 결과가 곧 제공될 것이라는 기대감을 유지시켜주는 전략적인 UI 패턴입니다.
- 분석 결과가 아직 도착하지 않았을 때, 로딩 상태를 감지하여 Skeleton UI를 렌더링합니다.
- 결과 리스트(
분석된 DOM 구조 + 문제 항목 + 스크린 리더 대본)의 형태를 모방하여, 다음과 같은 skeleton 컴포넌트들을 구현했습니다:- 스크린 리더 대본 preview 영역 → 긴 회색 블록
- 접근성 문제 리스트 → 리스트 형태의 작은 skeleton 블럭 반복
- 섹션별 구분 헤더 → 약간 어두운 색조의 사각형
- TailwindCSS의
animate-pulse와bg-gray-200등의 유틸리티 클래스를 활용해 최소한의 CSS로 Skeleton 효과를 구현 - Skeleton 컴포넌트는 기존 컴포넌트와 동일한 레이아웃 구조를 유지하여 UI 전환이 부드럽게 일어나도록 설계
- 사용자 피드백 개선: 로딩 중에도 서비스가 작동 중이라는 신호를 명확히 전달할 수 있습니다.
- 이탈률 감소: 사용자 입장에서 “기다릴 가치가 있는 상태”라는 신호를 받게 되어 조기 이탈을 방지합니다.
- 전환 자연화: Skeleton → 실제 데이터로의 전환이 시각적으로 자연스러워 UX 일관성 유지합니다.
- 심리적 체감 시간 단축: 분석 결과를 기다리는 동안 실제보다 더 빠르게 결과가 도착했다고 느끼는 효과를 줄 수 있습니다.
- Skeleton은 가짜 데이터이기 때문에, 결과 구조가 자주 변경되면 Skeleton 구조도 함께 유지보수가 필요합니다.
- Skeleton UI도 과하게 복잡하면 오히려 렌더링에 부담을 주거나 사용자 혼란을 유발할 수 있으므로, 최소한의 형태로 간결하게 구성하는 것이 중요합니다.
- 초기 페이지 로딩이 빠르더라도 네트워크 지연이나 서버 부하가 발생하는 경우를 대비해 Skeleton은 항상 fallback으로 유지해야 합니다.
로딩이 길어질 수밖에 없는 구조적 특성을 가진 서비스에서는, 단순한 스피너나 텍스트로는 부족합니다. 사용자에게 분석이 진행되고 있다는 명확한 피드백을 제공하고, 기대감을 유지시키기 위한 시각적 구조가 필요합니다.
이러한 UX 문제를 해결하기 위해 Skeleton UI를 도입함으로써, 분석 과정의 신뢰도와 사용자 경험을 크게 향상시킬 수 있었습니다. 이 결정은 단순한 디자인 변경이 아닌, 사용자 이탈을 막고 서비스 품질을 높이기 위한 전략적 UI 최적화였습니다.
이번 프로젝트를 진행하며 혼자서 서비스의 처음부터 끝까지 책임지는 일이 얼마나 큰 도전인지를 깊이 느꼈습니다. 어떤 컴포넌트가 필요할지부터 시작해서 화면 구성을 어떻게 할지, 또 어떻게 사용자에게 전달할지까지 전 과정을 스스로 판단하고 선택해야 했습니다. 그동안 당연하게 여겼던 의사결정조차 스스로 내리려니 더 많은 고민이 필요했고, 작은 선택 하나에도 결과가 달라질 수 있다는 점에서 많은 부담을 느끼기도 했습니다. 하지만 동시에, 내가 직접 모든 흐름을 설계하고 구현해냈다는 점에서 큰 성취감과 자신감을 얻을 수 있었습니다.
프로젝트 중에는 기술적인 도전도 많았습니다. 그동안 문서로만 접했던 도구나 라이브러리를 실전에서 사용해보며, 단순히 사용법을 익히는 것을 넘어 ‘이 도구가 어떤 문제를 해결하기 위한 것인가’를 이해하려고 노력했습니다. 특히 처음으로 Next.js를 제대로 사용해 보면서, 프레임워크에 대한 표면적인 이해를 넘어, SEO, App Router, SSR 등의 개념을 직접 적용하고 경험할 수 있었습니다. 기술을 배우는 것 자체보다 중요한 건 ‘문제를 해결하기 위한 적절한 수단으로 기술을 고르는 능력’이라는 점을 체감한 순간이기도 했습니다.
개발을 진행하면서 사용자 경험에 대해 더 깊이 고민하게 된 것도 중요한 변화였습니다. 시각장애인이 웹을 사용하는 방식을 시뮬레이션하는 과정에서, 우리가 너무 쉽게 간과하고 있던 요소들이 실제 사용자에게는 얼마나 큰 장벽이 되는지를 실감할 수 있었습니다. 단순히 작동하는 UI를 만드는 것을 넘어서, 누구에게나 접근 가능한 UI를 만들기 위한 기준과 태도가 필요하다는 것을 배웠습니다. 보이지 않는 정보를 어떻게 전달할 것인지, 화면에 보이는 요소들을 어떻게 더 명확하게 설명할 수 있을지를 고민하면서, 접근성은 선택이 아니라 기본이 되어야 함을 깨달았습니다.
이번 프로젝트는 단순히 기술적인 성장에 그치지 않고, 개발자로서 가져야 할 문제 해결 태도, 사용자 중심의 시각, 그리고 더 나은 서비스를 만들기 위한 책임감을 다지는 계기가 되었습니다. 끝으로, 내가 만들고 있는 서비스가 단지 기능적으로 완성되는 것을 넘어서, 누군가에게 실질적인 도움이 될 수 있다는 믿음이 생긴 것이 가장 큰 수확이었습니다.