@william-xu-web/c-a11y 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +25 -0
- package/README.en.md +152 -0
- package/README.md +152 -0
- package/dist/c-a11y.esm.js +826 -0
- package/dist/c-a11y.esm.js.map +7 -0
- package/dist/c-a11y.min.js +827 -0
- package/dist/c-a11y.min.js.map +7 -0
- package/package.json +41 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 William
|
|
4
|
+
|
|
5
|
+
MIT License
|
|
6
|
+
|
|
7
|
+
Copyright (c) 2026 Leonid Shoresh
|
|
8
|
+
|
|
9
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
10
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
11
|
+
in the Software without restriction, including without limitation the rights
|
|
12
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
13
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
14
|
+
furnished to do so, subject to the following conditions:
|
|
15
|
+
|
|
16
|
+
The above copyright notice and this permission notice shall be included in all
|
|
17
|
+
copies or substantial portions of the Software.
|
|
18
|
+
|
|
19
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
20
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
21
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
22
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
23
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
24
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
25
|
+
SOFTWARE.
|
package/README.en.md
ADDED
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
# A11y
|
|
2
|
+
|
|
3
|
+
The most comprehensive web accessibility overlay widget. Just one script tag adds a floating accessibility toolbar to any website with **20+ assistive features** covering visual, motor, cognitive, and auditory disabilities.
|
|
4
|
+
|
|
5
|
+
Compliant with [WCAG 2.1](https://www.w3.org/TR/WCAG21/).
|
|
6
|
+
|
|
7
|
+
## Quick Start
|
|
8
|
+
|
|
9
|
+
Add one line to your HTML — the widget auto-initializes, no extra JavaScript needed:
|
|
10
|
+
|
|
11
|
+
```html
|
|
12
|
+
<script src="/path/to/c-a11y.min.js" defer></script>
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Or install via npm:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
npm install @william-xu-web/c-a11y
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
```javascript
|
|
22
|
+
import { init } from "@william-xu-web/c-a11y";
|
|
23
|
+
const widget = init({ lang: "zh", position: "bottom-left" });
|
|
24
|
+
|
|
25
|
+
// To remove the widget and clean up all event listeners:
|
|
26
|
+
widget.destroy();
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## Features
|
|
30
|
+
|
|
31
|
+
### Vision & Display
|
|
32
|
+
|
|
33
|
+
| Feature | WCAG | Helps |
|
|
34
|
+
| --------------------------------- | ------------- | --------------------- |
|
|
35
|
+
| Font Size (+/-/reset) | 1.4.4 | Low vision, elderly |
|
|
36
|
+
| High Contrast (dark/light/invert) | 1.4.3 | Low vision |
|
|
37
|
+
| Dark Mode | 1.4.3 | Light sensitivity |
|
|
38
|
+
| Grayscale | 1.4.1 | Color blindness |
|
|
39
|
+
| Color Saturation (slider) | 1.4.1 | Color sensitivity |
|
|
40
|
+
| Text Spacing | 1.4.12 | Dyslexia, low vision |
|
|
41
|
+
| Dyslexia Font (OpenDyslexic) | Best practice | Dyslexia |
|
|
42
|
+
| Hide Images | Best practice | Cognitive |
|
|
43
|
+
| Color Blind Simulation | 1.4.1 | Developers, awareness |
|
|
44
|
+
|
|
45
|
+
### Navigation & Reading
|
|
46
|
+
|
|
47
|
+
| Feature | WCAG | Helps |
|
|
48
|
+
| ------------------------------- | ---------------------- | ------------------- |
|
|
49
|
+
| Keyboard Navigation | 2.1.1 | Motor disabilities |
|
|
50
|
+
| Focus Indicators | 2.4.7 | Motor, low vision |
|
|
51
|
+
| Heading Map / TOC | 2.4.10 (AA in SI 5568) | Screen reader users |
|
|
52
|
+
| Page Structure (ARIA landmarks) | 2.4.1 | Screen reader users |
|
|
53
|
+
| Reading Guide (ruler) | Best practice | Dyslexia, ADHD |
|
|
54
|
+
| Line Focus / Content Mask | Best practice | ADHD, cognitive |
|
|
55
|
+
| Big Cursor | Best practice | Motor, low vision |
|
|
56
|
+
| Screen Reader Preview | 1.1.1, 1.3.1 | Developers |
|
|
57
|
+
|
|
58
|
+
### Media & Content
|
|
59
|
+
|
|
60
|
+
| Feature | WCAG | Helps |
|
|
61
|
+
| ---------------------- | ------------- | --------------------- |
|
|
62
|
+
| Read on Hover (TTS) | Best practice | Blind, low vision |
|
|
63
|
+
| Read Selection (TTS) | Best practice | Blind, low vision |
|
|
64
|
+
| Read Page Aloud (TTS) | Best practice | Blind, low vision |
|
|
65
|
+
| Link Highlighting | 1.4.1, 2.4.4 | Low vision, cognitive |
|
|
66
|
+
| Image Alt Text Overlay | 1.1.1 | Blind, low vision |
|
|
67
|
+
| Stop Animations | 2.3.1, 2.3.3 | Seizure, vestibular |
|
|
68
|
+
| Mute All Sounds | 1.4.2 | Deaf, cognitive |
|
|
69
|
+
|
|
70
|
+
## Configuration
|
|
71
|
+
|
|
72
|
+
```html
|
|
73
|
+
<script>
|
|
74
|
+
window.OpenA11yConfig = {
|
|
75
|
+
position: "bottom-left", // 'bottom-left', 'bottom-right', 'top-left', 'top-right'
|
|
76
|
+
lang: "zh", // 'zh', 'en'
|
|
77
|
+
bottomOffset: 0, // extra pixels to push the button up on desktop
|
|
78
|
+
mobileBottomOffset: 60, // extra pixels to push the button up on mobile (≤ 480px)
|
|
79
|
+
statementUrl: "/accessibility-statement", // link to existing statement
|
|
80
|
+
statementData: {
|
|
81
|
+
orgName: "My Company",
|
|
82
|
+
orgPhone: "13088888888",
|
|
83
|
+
orgEmail: "access@example.com",
|
|
84
|
+
coordinatorName: "John Doe",
|
|
85
|
+
lastAuditDate: "2026-01-15",
|
|
86
|
+
},
|
|
87
|
+
};
|
|
88
|
+
</script>
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
| Option | Type | Default | Description |
|
|
92
|
+
| -------------------- | ------ | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
93
|
+
| `position` | string | `'bottom-left'` | Widget button placement: `'bottom-left'`, `'bottom-right'`, `'top-left'`, `'top-right'` |
|
|
94
|
+
| `lang` | string | auto-detect | UI language: `'zh'`, `'en'` |
|
|
95
|
+
| `bottomOffset` | number | `0` | Extra pixels to raise the button above the default position on desktop (screens > 768px). Only affects bottom positions. |
|
|
96
|
+
| `mobileBottomOffset` | number | `0` | Extra pixels to raise the button on mobile (screens ≤ 768px). Useful when the site has a fixed bottom navbar. Only affects bottom positions. |
|
|
97
|
+
| `statementUrl` | string | — | URL to an existing accessibility statement page |
|
|
98
|
+
| `statementData` | object | — | Data for the built-in accessibility statement generator |
|
|
99
|
+
|
|
100
|
+
## Languages
|
|
101
|
+
|
|
102
|
+
The widget UI supports 2 languages, switchable at runtime:
|
|
103
|
+
|
|
104
|
+
- **Chinese** - zh
|
|
105
|
+
- **English** - en
|
|
106
|
+
|
|
107
|
+
## Regulatory Compliance
|
|
108
|
+
|
|
109
|
+
### WCAG 2.1
|
|
110
|
+
|
|
111
|
+
The widget addresses WCAG 2.1 success criteria including:
|
|
112
|
+
|
|
113
|
+
- 1.4.10 Reflow
|
|
114
|
+
- 1.4.12 Text Spacing
|
|
115
|
+
- 1.4.13 Content on Hover or Focus
|
|
116
|
+
- 2.3.3 Animation from Interactions
|
|
117
|
+
- 4.1.3 Status Messages
|
|
118
|
+
|
|
119
|
+
### Project Structure
|
|
120
|
+
|
|
121
|
+
```
|
|
122
|
+
src/
|
|
123
|
+
c-a11y.js Main entry point
|
|
124
|
+
styles.js All CSS (injected into Shadow DOM)
|
|
125
|
+
i18n.js Translations (Chinese/English)
|
|
126
|
+
storage.js localStorage persistence
|
|
127
|
+
utils.js Shared utilities
|
|
128
|
+
modules/ One file per feature (24 modules)
|
|
129
|
+
dist/
|
|
130
|
+
c-a11y.min.js Minified IIFE bundle (~89 KB)
|
|
131
|
+
c-a11y.esm.js ES module for bundlers
|
|
132
|
+
demo.html Demo page
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
### Architecture
|
|
136
|
+
|
|
137
|
+
- **Shadow DOM** isolation prevents style conflicts with host pages
|
|
138
|
+
- **Zero runtime dependencies** - pure vanilla JavaScript
|
|
139
|
+
- **Module pattern** - each feature is self-contained with `enable()`/`disable()`/`toggle()`
|
|
140
|
+
- **localStorage** persistence for user preferences across sessions
|
|
141
|
+
- **ARIA live regions** for screen reader announcements (WCAG 4.1.3)
|
|
142
|
+
|
|
143
|
+
## Browser Support
|
|
144
|
+
|
|
145
|
+
- Chrome 80+
|
|
146
|
+
- Firefox 78+
|
|
147
|
+
- Safari 14+
|
|
148
|
+
- Edge 80+
|
|
149
|
+
|
|
150
|
+
## Links
|
|
151
|
+
|
|
152
|
+
- [WCAG 2.1 Specification](https://www.w3.org/TR/WCAG21/)
|
package/README.md
ADDED
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
# A11y
|
|
2
|
+
|
|
3
|
+
最全面的网页无障碍覆盖小部件。只需一个 script 标签，即可为任何网站添加浮动式无障碍工具栏，提供 **20+ 辅助功能**，覆盖视觉、运动、认知和听觉障碍。
|
|
4
|
+
|
|
5
|
+
符合[WCAG 2.1](https://www.w3.org/TR/WCAG21/)。
|
|
6
|
+
|
|
7
|
+
## 快速开始
|
|
8
|
+
|
|
9
|
+
在 HTML 中添加一行代码 —— 小部件自动初始化，无需额外的 JavaScript：
|
|
10
|
+
|
|
11
|
+
```html
|
|
12
|
+
<script src="/path/to/c-a11y.min.js" defer></script>
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
或通过 npm 安装：
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
npm install @william-xu-web/c-a11y
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
```javascript
|
|
22
|
+
import { init } from "@william-xu-web/c-a11y";
|
|
23
|
+
const widget = init({ lang: "zh", position: "bottom-left" });
|
|
24
|
+
|
|
25
|
+
// 移除小部件并清理所有事件监听器：
|
|
26
|
+
widget.destroy();
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## 功能
|
|
30
|
+
|
|
31
|
+
### 视觉与显示
|
|
32
|
+
|
|
33
|
+
| 功能 | WCAG | 适用人群 |
|
|
34
|
+
| ---------------------------- | -------- | ---------------- |
|
|
35
|
+
| 字体大小（放大/缩小/重置） | 1.4.4 | 低视力、老年人 |
|
|
36
|
+
| 高对比度（深色/浅色/反色） | 1.4.3 | 低视力 |
|
|
37
|
+
| 深色模式 | 1.4.3 | 光敏感 |
|
|
38
|
+
| 灰度 | 1.4.1 | 色盲 |
|
|
39
|
+
| 色彩饱和度（滑块） | 1.4.1 | 色彩敏感 |
|
|
40
|
+
| 文字间距 | 1.4.12 | 阅读障碍、低视力 |
|
|
41
|
+
| 阅读障碍字体（OpenDyslexic） | 最佳实践 | 阅读障碍 |
|
|
42
|
+
| 隐藏图片 | 最佳实践 | 认知障碍 |
|
|
43
|
+
| 色盲模拟 | 1.4.1 | 开发者、意识教育 |
|
|
44
|
+
|
|
45
|
+
### 导航与阅读
|
|
46
|
+
|
|
47
|
+
| 功能 | WCAG | 适用人群 |
|
|
48
|
+
| --------------------- | ------------ | ---------------- |
|
|
49
|
+
| 键盘导航 | 2.1.1 | 运动障碍 |
|
|
50
|
+
| 焦点指示器 | 2.4.7 | 运动障碍、低视力 |
|
|
51
|
+
| 标题地图 / 目录 | 2.4.10 | 屏幕阅读器用户 |
|
|
52
|
+
| 页面结构（ARIA 地标） | 2.4.1 | 屏幕阅读器用户 |
|
|
53
|
+
| 阅读辅助线（标尺） | 最佳实践 | 阅读障碍、多动症 |
|
|
54
|
+
| 行聚焦 / 内容遮罩 | 最佳实践 | 多动症、认知障碍 |
|
|
55
|
+
| 大光标 | 最佳实践 | 运动障碍、低视力 |
|
|
56
|
+
| 屏幕阅读器预览 | 1.1.1, 1.3.1 | 开发者 |
|
|
57
|
+
|
|
58
|
+
### 媒体与内容
|
|
59
|
+
|
|
60
|
+
| 功能 | WCAG | 适用人群 |
|
|
61
|
+
| ---------------- | ------------ | ---------------- |
|
|
62
|
+
| 悬停朗读（TTS） | 最佳实践 | 视障、低视力 |
|
|
63
|
+
| 选中朗读（TTS） | 最佳实践 | 视障、低视力 |
|
|
64
|
+
| 整页朗读（TTS） | 最佳实践 | 视障、低视力 |
|
|
65
|
+
| 链接高亮 | 1.4.1, 2.4.4 | 低视力、认知障碍 |
|
|
66
|
+
| 图片替代文本覆盖 | 1.1.1 | 视障、低视力 |
|
|
67
|
+
| 停止动画 | 2.3.1, 2.3.3 | 癫痫、前庭障碍 |
|
|
68
|
+
| 静音所有声音 | 1.4.2 | 听障、认知障碍 |
|
|
69
|
+
|
|
70
|
+
## 配置
|
|
71
|
+
|
|
72
|
+
```html
|
|
73
|
+
<script>
|
|
74
|
+
window.OpenA11yConfig = {
|
|
75
|
+
position: "bottom-left", // 'bottom-left', 'bottom-right', 'top-left', 'top-right'
|
|
76
|
+
lang: "zh", // 'zh', 'en'
|
|
77
|
+
bottomOffset: 0, // 桌面端额外向上偏移的像素值
|
|
78
|
+
mobileBottomOffset: 60, // 移动端（≤ 480px）额外向上偏移的像素值
|
|
79
|
+
statementUrl: "/accessibility-statement", // 链接到已有的无障碍声明页面
|
|
80
|
+
statementData: {
|
|
81
|
+
orgName: "我的公司",
|
|
82
|
+
orgPhone: "13088888888",
|
|
83
|
+
orgEmail: "access@example.com",
|
|
84
|
+
coordinatorName: "张三",
|
|
85
|
+
lastAuditDate: "2026-01-15",
|
|
86
|
+
},
|
|
87
|
+
};
|
|
88
|
+
</script>
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
| 选项 | 类型 | 默认值 | 说明 |
|
|
92
|
+
| -------------------- | ------ | --------------- | ------------------------------------------------------------------------------------------------------ |
|
|
93
|
+
| `position` | string | `'bottom-left'` | 小部件按钮位置：`'bottom-left'`、`'bottom-right'`、`'top-left'`、`'top-right'` |
|
|
94
|
+
| `lang` | string | 自动检测 | 界面语言：`'zh'`、`'en'` |
|
|
95
|
+
| `bottomOffset` | number | `0` | 桌面端（屏幕 > 768px）按钮相对于默认位置的额外向上偏移像素值。仅对底部位置生效。 |
|
|
96
|
+
| `mobileBottomOffset` | number | `0` | 移动端（屏幕 ≤ 768px）按钮的额外向上偏移像素值。当网站有固定在底部的导航栏时很有用。仅对底部位置生效。 |
|
|
97
|
+
| `statementUrl` | string | — | 已有无障碍声明页面的 URL |
|
|
98
|
+
| `statementData` | object | — | 内置无障碍声明生成器的数据 |
|
|
99
|
+
|
|
100
|
+
## 语言
|
|
101
|
+
|
|
102
|
+
小部件界面支持 2 种语言，可在运行时切换：
|
|
103
|
+
|
|
104
|
+
- **中文** - zh
|
|
105
|
+
- **英语** - en
|
|
106
|
+
|
|
107
|
+
## 法规合规
|
|
108
|
+
|
|
109
|
+
### WCAG 2.1
|
|
110
|
+
|
|
111
|
+
本小部件同时涵盖 WCAG 2.1 以下标准：
|
|
112
|
+
|
|
113
|
+
- 1.4.10 回流（Reflow）
|
|
114
|
+
- 1.4.12 文字间距
|
|
115
|
+
- 1.4.13 悬停或焦点时的内容
|
|
116
|
+
- 2.3.3 交互动画
|
|
117
|
+
- 4.1.3 状态消息
|
|
118
|
+
|
|
119
|
+
### 项目结构
|
|
120
|
+
|
|
121
|
+
```
|
|
122
|
+
src/
|
|
123
|
+
c-a11y.js 主入口
|
|
124
|
+
styles.js 所有 CSS（注入 Shadow DOM）
|
|
125
|
+
i18n.js 翻译文件（中文/英语）
|
|
126
|
+
storage.js localStorage 持久化
|
|
127
|
+
utils.js 共享工具函数
|
|
128
|
+
modules/ 每个功能一个文件（共 24 个模块）
|
|
129
|
+
dist/
|
|
130
|
+
c-a11y.min.js 压缩版 IIFE 包（约 89 KB）
|
|
131
|
+
c-a11y.esm.js 供打包工具使用的 ES 模块
|
|
132
|
+
demo.html 演示页面
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
### 架构
|
|
136
|
+
|
|
137
|
+
- **Shadow DOM** 隔离防止与宿主页面样式冲突
|
|
138
|
+
- **零运行时依赖** — 纯原生 JavaScript
|
|
139
|
+
- **模块模式** — 每个功能自包含，提供 `enable()` / `disable()` / `toggle()` 方法
|
|
140
|
+
- **localStorage** 持久化用户偏好，跨会话保留
|
|
141
|
+
- **ARIA 实时区域** 用于屏幕阅读器通知（WCAG 4.1.3）
|
|
142
|
+
|
|
143
|
+
## 浏览器支持
|
|
144
|
+
|
|
145
|
+
- Chrome 80+
|
|
146
|
+
- Firefox 78+
|
|
147
|
+
- Safari 14+
|
|
148
|
+
- Edge 80+
|
|
149
|
+
|
|
150
|
+
## 相关链接
|
|
151
|
+
|
|
152
|
+
- [WCAG 2.1 规范](https://www.w3.org/TR/WCAG21/)
|