ModuWeb 프로젝트 개요 — 웹 접근성 위젯 구조와 기능

프로젝트 소개

프로젝트 명: ModuWeb

부제: WAT: Web Accessibility Tools

ModuWeb은 웹 접근성 지원 도구입니다. 다양한 사용자의 접근성 요구사항을 충족시키기 위해 설계된 모듈형 플러그인 시스템입니다. 이 프로젝트는 웹 표준과 웹 접근성 지침(WCAG 2.1 AA·KWCAG 2.1)을 목표로 개발하며, 사용자 친화적인 인터페이스를 제공합니다.
웹 접근성 기능을 적용해 콘텐츠를 보다 쉽게 이용할 수 있게 돕습니다.

프로젝트 목표

웹 접근성 환경 개선
평등한 웹 경험 제공
WCAG 2.1 AA·KWCAG 2.1 지향
모듈형 도구로 사용자 맞춤화

핵심 특징

스크립트 한 줄 설치 (CDN·오프라인 단일 파일)
TTS 화면 낭독·STT 음성 명령
장애 유형별 프로필 7종
내 색상: 배경·글자색 선택과 7:1 짝 색 추천
키보드 조작과 단축키
설정 자동 저장·내보내기/가져오기

프로젝트 현황

버전 정보

현재 버전2.3.11
마지막 업데이트2026-10-21
라이선스Apache-2.0
개발 팀대구사이버대학교
언어 지원6개 언어 (ko·en-US·en-GB·ja·zh·de)
변경 이력CHANGELOG.md

배포 형태

CDNjsDelivr @2 (2.x 최신 자동 반영)
단일 파일webAccTools.standalone.min.js
폴더 배포webAccTools.js + assets/
런타임 의존성없음 (jQuery 불필요)
배포 zipGitHub Releases

개발환경 및 기술 스택

개발 도구

버전 관리

Git · GitHub

Git 기반 소스 관리, Pull Request로 변경 반영

빌드 도구

Rollup 4

src/ ES 모듈을 IIFE 번들 3종(일반·min·standalone)으로 생성

테스팅

Jest 30 · jsdom

단위 테스트(tests/unit)와 수동 점검표(tests/manual)

코드 검사

ESLint 8

JS 규칙 검사와 CSS 셀렉터 누수 검사(lint:css)

CI · 배포

GitHub Actions

테스트·dist 동기화 검사, Pages 데모 배포, 릴리스

브라우저 지원

데스크톱 브라우저

Chrome90+
Firefox88+ (음성 명령 미지원)
Safari14.1+
Edge90+

모바일 브라우저

iOS Safari14.5+
Android Chrome90+
Samsung Internet14+

핵심 기술

Web Speech API

Native

speechSynthesis 화면 낭독, SpeechRecognition 음성 명령

사전 중계 서버

JSONP

사이트가 운영하는 serverEndpoint로 검색 (API 키는 서버에만)

HTML5

Semantic

접근성 중심 마크업

JavaScript

ES Modules

트랜스파일 없이 번들 (정적 클래스 필드·옵셔널 체이닝 사용)

CSS3

Modern

Flexbox, Grid, Custom Properties

시스템 아키텍처

전체 아키텍처 개요

핵심 (src/wat · src/core)

WAT

StateManager

ConfigurationManager

OptionsProcessor

ErrorHandler

음성 (src/tts · src/stt)

TTSManager

AutoTTS

FocusTTS

KeyboardTTS

TextExtractor

STTManager

VoiceCommand

기능 모듈 (src/wat)

PanelBuilder

SettingsApplier

CustomColorEditor

CustomColorTheme

Dictionary

PageStructure

OverlayManager

IframeStyler

document 이벤트 (CustomEvent)

wat:initialized

wat:settings:*

wat:stt:stateChanged

wat:media:*

wat:dictionary:*

초기화 플로우

WAT 인스턴스 생성

data-wat-auto 스크립트 속성(자동 초기화) 또는 new WAT(options)로 인스턴스를 만듭니다. 생성자는 config.json 로드를 비동기로 시작합니다.

상태·모듈 준비

localStorage에 저장된 설정(watSettings)으로 StateManager를 만들고 TTSManager, STTManager, PanelBuilder, SettingsApplier 등 모듈 인스턴스를 생성합니다.

설정·언어 로드 (init)

init()이 위젯 CSS를 주입하고 config 로드를 기다린 뒤 언어 파일(locales)을 불러옵니다.

패널 생성과 설정 적용

패널 HTML을 만들고 저장된 설정을 페이지에 다시 적용한 뒤 탭·이벤트 리스너·iframe 처리를 설정합니다.

초기화 완료

document에 wat:initialized 이벤트를 발생시킵니다 (detail에 version·language·features).

모듈 간 통신

패널 UI

WAT

페이지 DOM

SettingsApplier

document 이벤트

패널 UI → WAT
라디오·버튼 조작이 changeFontSize() 같은 WAT 메서드를 호출

WAT → 페이지 DOM
<html>의 data-* 속성 변경 (CSS가 색상 모드·채도 등을 적용)

WAT → 페이지 DOM
StyleBatchProcessor가 글자 크기·줄 간격 등 동적 스타일을 모아 한 번에 적용, iframe에도 동기화

WAT → SettingsApplier
savePreferences()가 localStorage(watSettings)에 저장하고 StateManager의 settings 갱신

SettingsApplier → document 이벤트
wat:settings:saved 발생 (위젯을 넣은 페이지가 구독할 수 있음)

모듈은 WAT 인스턴스(plugin)를 통해 서로를 호출합니다. TTS 시작·읽기 가이드 변경 같은 상태 변화는 StateManager의 subscribe() 옵저버가 패널 버튼에 반영합니다.

주요 기능

접근성 도구

시각적 지원

시인성 및 가독성 향상

폰트 크기(1.2·1.5·2배)와 폰트 종류 변경
줄 간격·글자 간격·텍스트 정렬 조정
화면 확대 (1.2·1.5·2배)
이미지 표시 모드 (숨기기·대체텍스트로 변환)

색상 인식 지원

색상 대비 및 인식 개선

색상 모드 5종: 기본·밝게·어둡게·반전·내 색상 (첫 방문 때 OS 다크 모드 반영)
내 색상: 배경·글자색 직접 선택, 명도 대비 표시, 7:1 짝 색 추천 (WCAG 1.4.8)
채도 변경: 높게·낮게·흑백
색약 보정: 적색약·녹색약 보정 필터

집중력 지원

집중력 향상을 위한 시각적 도구

커서 집중 모드: 마스킹·밑줄·커서 확대
미디어 정지·음소거, 애니메이션 정지
페이지 자동 스크롤과 위·아래 이동

키보드 접근성

마우스 없이 모든 기능 사용

패널 전체를 키보드로 조작, 포커스 표시
단축키: Alt+Shift+T 선택 영역 낭독 · Alt+Shift+D 사전 검색 · Alt+Shift+S 음성 명령
settings.ui.keyboardShortcuts: false로 단축키 끄기 (WCAG 2.1.4)

음성 인터페이스

TTS (Text-to-Speech)

텍스트를 음성으로 변환하는 기능

자동 읽기 - 페이지 요소를 차례로 읽고 이전·다음 이동 (AutoTTS)
포커스 탐지 낭독 - Tab으로 이동한 요소와 클릭·선택한 텍스트 읽기 (FocusTTS)
선택 영역 낭독 - 선택한 텍스트를 Alt+Shift+T로 읽기 (KeyboardTTS)
환경설정에서 낭독 음성 선택, 읽기 속도는 API로 조절
비밀번호 칸은 값을 읽지 않고 라벨만 읽음

STT (Speech-to-Text)

음성 명령으로 페이지 조작

"이동·클릭·실행 + 대상 이름"으로 링크·버튼 누르기
체크박스·라디오 버튼 켜고 끄기
연속 인식, 상태 표시창, 권한 거부·오류 시 자동 종료
SpeechRecognition을 지원하는 브라우저에서 동작 (Firefox 미지원)

보조 기능

사전 검색

단어 의미 검색

더블클릭 또는 선택 후 Alt+Shift+D로 검색
결과를 팝업 레이어로 표시
사전 중계 서버(serverEndpoint)가 설정된 사이트에서만 패널에 나타남

페이지 구조

페이지 개요 확인과 위치 이동

제목·랜드마크·링크 목록
목록에서 해당 위치로 이동하거나 링크 실행

설정 관리

개인화 설정

장애 유형별 프로필 7종: 저시력·색맹·난독증·시각 장애·고령자·움직임 민감·신체 장애
설정 자동 저장 (localStorage), 설정 내보내기/가져오기 (JSON 파일)
전체 초기화

언어·패널

도구 자체의 표시 방식

6개 언어: 한국어·영어(미국·영국)·일본어·중국어·독일어
패널 위치(왼쪽·오른쪽), 보기 모드(아이콘·목차)
창 축소: 아이콘 띠로 줄이고 상태 유지

개발자 기능

API 및 확장성

가장 간단한 설치는 <script src="…/webAccTools.standalone.min.js" data-wat-auto></script> 한 줄입니다. 세밀하게 제어하려면 아래처럼 직접 초기화합니다.

// 초기화 완료 이벤트는 init() 전에 등록 (document에 발생)
document.addEventListener('wat:initialized', (e) => console.log('WAT 초기화 완료', e.detail.version));

// WAT 인스턴스 생성 및 초기화
const wat = new WAT({ configPath: './config.json', language: 'ko' });
window.watPlugin = wat;
wat.init();

// 설정이 저장될 때마다 알림
document.addEventListener('wat:settings:saved', (e) => console.log(e.detail.settings));

// 색상 · 프로필
wat.changeColorTheme('dark');
wat.setCustomColors({ bg: '#fdf6e3', fg: '#3b2f1e' });
wat.applyProfileSettings('lowVision');

// TTS · STT
wat.ttsManager.toggleAutoTTS();
wat.setTTSSpeechRate(1.2);
wat.toggleVoiceCommand();

프로젝트 구조도

디렉토리 구조

ModuWeb/
├── src/                                # 소스 (ES 모듈), 빌드하면 dist/ 생성
│   ├── index.js                        # 진입점: window.WAT 등록, data-wat-auto 자동 초기화
│   ├── standalone.js                   # 단일 파일 번들 진입점 (CSS·아이콘·한국어 내장)
│   ├── wat/                            # WAT 메인 클래스, 상태 관리, 패널·설정·내 색상 등 기능 모듈
│   ├── core/                           # 설정·옵션 처리, 상수·기본값(프로필), 색 대비 계산, 유틸
│   ├── tts/                            # 화면 낭독 (자동·포커스·선택 영역, 낭독 텍스트 추출)
│   └── stt/                            # 음성 명령
│
├── dist/                               # 배포 파일 (빌드 결과, 저장소에 함께 커밋)
│   ├── webAccTools.js                  # 일반 번들
│   ├── webAccTools.min.js              # 압축 번들
│   ├── webAccTools.standalone.min.js   # 단일 파일 (CDN·오프라인)
│   ├── watInit.js                      # 초기화 스크립트 예시
│   └── assets/
│       ├── css/                        # webAccTools.css (스타일 원본)
│       ├── fonts/                      # Koddi 온고딕 웹폰트
│       ├── images/                     # 아이콘
│       └── locales/                    # 언어 파일 (ko·en-US·en-GB·ja·zh·de)
│
├── examples/                           # 예제 (index·basic·auto-init·standalone·custom-examples·api-examples·color-filter)
├── tests/                              # Jest 단위 테스트(unit), 수동 점검표(manual)
├── docs/                               # 이 페이지, 아키텍처 다이어그램, 스크린샷
├── scripts/                            # config 생성(.env), 배포 zip, CSS 셀렉터 검사
├── packaging/                          # 배포 zip에 넣는 설치 안내·예제
├── rollup.config.js                    # 빌드 설정
├── config.example.json                 # 설정 예시 (config.json은 git 제외)
└── LICENSE · NOTICE                    # Apache-2.0

모듈 구조

WAT Framework Core (src/wat · src/core)

WAT.js

→

StateManager

ConfigurationManager

OptionsProcessor

ErrorHandler

TTS Modules (src/tts)

TTSManager

→

AutoTTS

FocusTTS

KeyboardTTS

BaseTTS (Focus·Keyboard 공통 부모)

TextExtractor

STT Modules (src/stt)

STTManager

→

VoiceCommand (Web Speech API SpeechRecognition)

UI Components (src/wat · src/core)

PanelBuilder

CustomColorEditor

PageStructure

OverlayManager

ContainerManager

Feature · Utility Modules

SettingsApplier

CustomColorTheme

Dictionary

IframeStyler

StyleBatchProcessor

colorContrast

autoInit

클래스 다이어그램

WAT

+ options: Object

+ state: StateManager

+ ttsManager: TTSManager

+ sttManager: STTManager

+ settingsApplier: SettingsApplier

+ panelBuilder: PanelBuilder

+ init(): Promise

+ cleanup(): void

+ changeColorTheme(theme): void

+ setCustomColors({ bg, fg }): boolean

+ applyProfileSettings(profileName)

StateManager

- _state: Object

- _observers: Map

- _history: Array

+ get(path, defaultValue): any

+ set(path, value): void

+ subscribe(path, callback): Function

+ getState(): Object

TTSManager

+ autoTTS: AutoTTS

+ focusTTS: FocusTTS

+ keyboardTTS: KeyboardTTS

+ currentState: string

+ toggleAutoTTS(): void

+ toggleFocusTTS(): void

+ executeKeyboardTTS(): void

+ setSpeechRate(rate): void

+ setVoice(voiceURI): void

STTManager

+ voiceCommand: VoiceCommand

+ currentState: string

+ toggleVoiceCommand(): void

+ setLanguage(language): void

+ getStatus(): Object

WAT

→

StateManager

WAT

→

TTSManager

→

AutoTTS · FocusTTS · KeyboardTTS

WAT

→

STTManager

→

VoiceCommand

WAT

→

SettingsApplier · PanelBuilder · Dictionary 등

데이터 플로우

사용자 입력

패널 조작, 단축키(Alt+Shift+T·D·S), 포커스 이동, 더블클릭, 음성 명령 등

이벤트 처리

WAT가 등록한 클릭·키보드·포커스 리스너가 해당 WAT 메서드나 TTSManager·STTManager를 호출

페이지에 적용

<html> data-* 속성과 StyleBatchProcessor의 일괄 스타일로 페이지와 iframe에 반영

상태 갱신과 저장

StateManager 상태를 바꾸고, 설정은 localStorage(watSettings·watCustomColors)에 저장해 다음 방문 때 복원

UI 업데이트와 알림

옵저버가 패널 상태를 갱신하고, document에 wat:* 이벤트를 발생시킴