a11y-control 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.
Files changed (9) hide show
  1. package/README.md +219 -0
  2. package/_agent/skills/accessibility-integration/SKILL.md +101 -0
  3. package/package.json +35 -0
  4. package/src/A11yControl.js +402 -0
  5. package/src/a11y-control.js +30 -0
  6. package/src/constants.js +66 -0
  7. package/src/icons.js +67 -0
  8. package/src/reading-guide.js +47 -0
  9. package/src/styles.js +435 -0
package/README.md ADDED
@@ -0,0 +1,219 @@
1
+ # `<a11y-control>` (A11yControl)
2
+
3
+ > A plug-and-play accessibility menu, **WCAG 2.1 AA** compliant, built as a native Web Component.
4
+ > Zero dependencies. Zero build. One single tag.
5
+
6
+ **[🌐 Live Demo](https://quentinmerle.github.io/a11y-control/demo/)**
7
+
8
+ ---
9
+
10
+ ## ⚖️ Legal Disclaimer
11
+
12
+ This component is an assistive tool designed to improve user experience, but please note:
13
+ - **Assistive Aid Only**: Using this menu does not automatically guarantee compliance with legal standards (like WCAG, ADA, or Section 508).
14
+ - **Not an Audit**: It is not a substitute for professional accessibility testing or certified audits.
15
+ - **Liability**: Website owners are responsible for their own site's legal compliance. This software is provided "as-is" without warranty of any kind.
16
+
17
+ ---
18
+
19
+ ## ⚡ Quick Start — 30 Seconds
20
+
21
+ ```html
22
+ <!-- 1. Load the component -->
23
+ <script type="module" src="./src/a11y-control.js"></script>
24
+
25
+ <!-- 2. Add the tag (before </body>) -->
26
+ <a11y-control lang="en"></a11y-control>
27
+ ```
28
+
29
+ That's it. The component handles the rest.
30
+
31
+ ---
32
+
33
+ ## Project Integration
34
+
35
+ ### Vanilla HTML
36
+ ```html
37
+ <script type="module" src="./src/a11y-control.js"></script>
38
+ <a11y-control lang="en"></a11y-control>
39
+ ```
40
+
41
+ ### React / Next.js
42
+ ```jsx
43
+ import { useEffect } from 'react';
44
+
45
+ export default function App() {
46
+ useEffect(() => {
47
+ // Dynamic import to ensure it only runs on the client
48
+ import('./path/to/a11y-control.js');
49
+ }, []);
50
+
51
+ return (
52
+ <>
53
+ {/* your app */}
54
+ <a11y-control lang="en" />
55
+ </>
56
+ );
57
+ }
58
+ ```
59
+
60
+ ### Vue
61
+ ```vue
62
+ <template>
63
+ <a11y-control lang="en" />
64
+ </template>
65
+
66
+ <script setup>
67
+ import './path/to/a11y-control.js';
68
+ </script>
69
+ ```
70
+
71
+ ### Via npm (local)
72
+ ```js
73
+ import './node_modules/a11y-control/src/a11y-control.js';
74
+ ```
75
+
76
+ ---
77
+
78
+ ## Attributes
79
+
80
+ | Attribute | Values | Default |
81
+ |---|---|---|
82
+ | `lang` | `"en"` \| `"fr"` | `"en"` |
83
+ | `position` | `"bottom-right"` \| `"bottom-left"` \| `"top-right"` \| `"top-left"` | `"bottom-right"` |
84
+
85
+ ```html
86
+ <!-- Examples -->
87
+ <a11y-control lang="fr" position="bottom-left"></a11y-control>
88
+ <a11y-control lang="en" position="top-right"></a11y-control>
89
+ ```
90
+
91
+ ---
92
+
93
+ ## Features
94
+
95
+ | Control | Effect | WCAG Success Criterion |
96
+ |---|---|---|
97
+ | 🔡 Font Size | 80% → 200% (10% increments) | 1.4.4 Resize Text |
98
+ | ◑ High Contrast | Black background, white text, yellow links | 1.4.6 Contrast Enhanced |
99
+ | ⬛ Grayscale | `filter: grayscale(100%)` on `<html>` | 1.4.11 Non-text Contrast |
100
+ | 🔗 Highlight Links | Bold + outline on all `<a>` tags | 1.4.1 Use of Color |
101
+ | T Dyslexia Font | OpenDyslexic loaded on demand | 1.4.8 Visual Presentation |
102
+ | — Reading Guide | Horizontal bar following the cursor | 1.4.8 Visual Presentation |
103
+ | ⏸ Reduce Motion | All transitions/animations set to 0ms | 2.3.3 Animation |
104
+ | 🌙 Dark/Light Mode | Toggles dark theme for the page and menu | 1.4.3 Contrast (Minimum) |
105
+
106
+ Preferences are **automatically saved** in `localStorage` and restored on every visit.
107
+
108
+ ---
109
+
110
+ ## Theming — CSS Custom Properties
111
+
112
+ Customize the appearance from your global stylesheet (variables are exposed via `:host`):
113
+
114
+ ```css
115
+ a11y-control {
116
+ --a11y-accent: #005fcc; /* Primary color (buttons, active toggles) */
117
+ --a11y-accent-hover: #0047a3;
118
+ --a11y-bg: #ffffff; /* Panel background */
119
+ --a11y-surface: #f5f5f5; /* Row background on hover */
120
+ --a11y-border: #d0d0d0;
121
+ --a11y-text: #1a1a1a;
122
+ --a11y-text-muted: #555555;
123
+ --a11y-radius: 12px;
124
+ --a11y-shadow: 0 8px 32px rgba(0, 0, 0, 0.18);
125
+ }
126
+ ```
127
+
128
+ ---
129
+
130
+ ## CSS Classes Applied to `<html>`
131
+
132
+ The component toggles these classes so **your own CSS** can also react:
133
+
134
+ | Class | Active when |
135
+ |---|---|
136
+ | `a11y-high-contrast` | High Contrast enabled |
137
+ | `a11y-grayscale` | Grayscale enabled |
138
+ | `a11y-dyslexia` | Dyslexia Font enabled |
139
+ | `a11y-reduce-motion` | Reduce Motion enabled |
140
+ | `a11y-highlight-links`| Highlight Links enabled |
141
+ | `a11y-dark-mode` | Dark Mode enabled |
142
+
143
+ ```css
144
+ /* Example — adapt your design to High Contrast mode */
145
+ html.a11y-high-contrast .hero {
146
+ border: 2px solid #fff;
147
+ }
148
+ ```
149
+
150
+ ---
151
+
152
+ ## Keyboard & Accessibility
153
+
154
+ The component is fully keyboard-operable:
155
+
156
+ | Key | Action |
157
+ |---|---|
158
+ | `Tab` | Navigate between controls |
159
+ | `Shift + Tab` | Navigate backward |
160
+ | `Enter` / `Space` | Activate a button or toggle |
161
+ | `Escape` | Close the panel, return focus to trigger button |
162
+
163
+ **Built-in ARIA:** `role="dialog"`, `aria-modal`, `aria-expanded`, `aria-checked` (`role="switch"`), `aria-live` on the font size counter, focus trap, and focus restoration.
164
+
165
+ ---
166
+
167
+ ## Project Structure
168
+
169
+ ```
170
+ src/
171
+ ├── a11y-control.js ← Entry point (import/script this)
172
+ ├── AccessibilityMenu.js ← Custom Element class
173
+ ├── constants.js ← Default preferences, i18n
174
+ ├── icons.js ← SVG icons
175
+ ├── styles.js ← Shadow CSS + global styles
176
+ └── reading-guide.js ← Reading guide feature
177
+ ```
178
+
179
+ ---
180
+
181
+ ## Local Development
182
+
183
+ ```bash
184
+ # Start a dev server
185
+ npm run dev
186
+ # → http://localhost:3000/demo/
187
+ ```
188
+
189
+ ---
190
+
191
+ ## Browser Compatibility
192
+
193
+ All modern browsers supporting **Custom Elements v1 + Shadow DOM**:
194
+
195
+ | Chrome | Firefox | Safari | Edge |
196
+ |---|---|---|---|
197
+ | ✅ 67+ | ✅ 63+ | ✅ 12.1+ | ✅ 79+ |
198
+
199
+ ---
200
+
201
+ ---
202
+
203
+ ## 🤖 AI Agent Support
204
+
205
+ This project is **Agent-Ready**. It includes a specialized "Skill" for AI assistants (like Windsurf, Cursor, or Antigravity) to help you integrate and maintain accessibility.
206
+
207
+ The skill provides instructions for:
208
+ - Seamless integration in any framework.
209
+ - Ensuring new components are compatible with the menu (CSS variables, relative units).
210
+ - Automated verification loops for accessibility checks.
211
+
212
+ **How to use:**
213
+ If you've installed via npm, you can find the skill in `node_modules/a11y-control/_agent/skills/accessibility-integration`. Copy this folder to your project's `_agent/skills/` to activate it for your assistant.
214
+
215
+ ---
216
+
217
+ ## License
218
+
219
+ MIT — feel free to use, modify, and distribute.
package/_agent/skills/accessibility-integration/SKILL.md ADDED
@@ -0,0 +1,101 @@
1
+ ---
2
+ name: Integrate A11yControl
3
+ description: How to integrate the <a11y-control> web component into a web project (Vanilla, React, Vue, etc.)
4
+ ---
5
+
6
+ # Integrate A11yControl
7
+
8
+ Use this skill to quickly add a production-ready accessibility menu to any website or application.
9
+
10
+ ## 📋 Prerequisites
11
+ The project must support ES Modules (modern browsers or a bundler like Vite/Webpack).
12
+
13
+ ## 🛠 Integration Steps
14
+
15
+ ### 1. Identify the Entry Point
16
+ Locate the main HTML file (`index.html`) or the root component of the application.
17
+
18
+ ### 2. Load the Component
19
+ Insert the script tag to load the Web Component.
20
+
21
+ **Vanilla HTML:**
22
+ ```html
23
+ <script type="module" src="./src/a11y-control.js"></script>
24
+ ```
25
+
26
+ **NPM (if installed):**
27
+ ```javascript
28
+ import 'a11y-control';
29
+ ```
30
+
31
+ ### 3. Insert the Tag
32
+ Add the `<a11y-control>` tag before the closing `</body>` tag.
33
+
34
+ **Basic Configuration:**
35
+ ```html
36
+ <a11y-control lang="en" position="bottom-right"></a11y-control>
37
+ ```
38
+
39
+ ### 4. Configuration Options
40
+ | Attribute | Description | Options | Default |
41
+ |---|---|---|---|
42
+ | `lang` | UI Language | `en`, `fr` | `en` |
43
+ | `position` | Button position | `bottom-right`, `bottom-left`, `top-right`, `top-left` | `bottom-right` |
44
+
45
+ ## 🎨 Professional Recommendation: Theming
46
+ Suggest to the user to customize the menu colors to match their brand using CSS variables in their global stylesheet:
47
+
48
+ ```css
49
+ a11y-control {
50
+ --a11y-accent: #your-brand-color;
51
+ --a11y-radius: 8px;
52
+ }
53
+ ```
54
+
55
+ ## 🧩 Developing Compatible Components
56
+
57
+ To ensure that **new components** created in this project automatically respect the accessibility features, follow these rules:
58
+
59
+ ### 1. Font Sizes (Inheritance)
60
+ **NEVER** use hardcoded `px` for font sizes. Always use `rem`, `em`, or percentage.
61
+ - **Why**: The menu scales `html { font-size: % }`. Using `rem` ensures all your components scale proportionally (80% to 200%).
62
+
63
+ ### 2. Colors & Contrast
64
+ Use CSS Variables for your theme colors and add overrides for high-contrast mode.
65
+ ```css
66
+ .my-component {
67
+ background: var(--bg-color, #fff);
68
+ color: var(--text-color, #1a1a1a);
69
+ }
70
+
71
+ /* React to the high-contrast class on <html> */
72
+ html.a11y-high-contrast .my-component {
73
+ background: #000 !important;
74
+ color: #fff !important;
75
+ border: 1px solid #fff;
76
+ }
77
+ ```
78
+
79
+ ### 3. Reduced Motion
80
+ Use the global class to kill animations if the user requests it.
81
+ ```css
82
+ html.a11y-reduce-motion *,
83
+ html.a11y-reduce-motion *::before,
84
+ html.a11y-reduce-motion *::after {
85
+ animation-duration: 0.01ms !important;
86
+ animation-iteration-count: 1 !important;
87
+ transition-duration: 0.01ms !important;
88
+ scroll-behavior: auto !important;
89
+ }
90
+ ```
91
+
92
+ ### 4. Links & Interactive Elements
93
+ Ensure all interactive elements have highly visible focus rings, especially for `html.a11y-high-contrast` and `html.a11y-highlight-links`.
94
+
95
+ ## ⚖️ Mandatory Legal Disclosure
96
+ When integrating, always inform the user that this tool is an **assistive aid** and not a substitute for a full accessibility audit.
97
+
98
+ ## 🤖 Agent Verification Loop
99
+ 1. Check if the script is loaded correctly.
100
+ 2. Verify the tag is present in the DOM.
101
+ 3. Check for console errors related to module paths.
package/package.json ADDED
@@ -0,0 +1,35 @@
1
+ {
2
+ "name": "a11y-control",
3
+ "version": "1.0.0",
4
+ "description": "A plug-and-play accessibility menu, WCAG 2.1 AA compliant, built as a native Web Component.",
5
+ "type": "module",
6
+ "main": "src/a11y-control.js",
7
+ "exports": {
8
+ ".": "./src/a11y-control.js"
9
+ },
10
+ "files": [
11
+ "src",
12
+ "README.md",
13
+ "_agent"
14
+ ],
15
+ "scripts": {
16
+ "dev": "npx serve . --listen 3131"
17
+ },
18
+ "repository": {
19
+ "type": "git",
20
+ "url": "git+https://github.com/QuentinMerle/accessibility-menu.git"
21
+ },
22
+ "keywords": [
23
+ "accessibility",
24
+ "wcag",
25
+ "web-component",
26
+ "a11y",
27
+ "menu",
28
+ "dark-mode"
29
+ ],
30
+ "author": "Quentin Merle",
31
+ "license": "MIT",
32
+ "devDependencies": {
33
+ "serve": "^14.0.0"
34
+ }
35
+ }