Skip to content

Commit 981dfdf

Browse files
shouzeshouze
committed
Make VitePress docs fully WCAG 2.1 AA accessible
- Add ARIA tabs pattern (roving tabindex, keyboard nav) to UseCaseTabs - Add table semantics (caption, scope, aria-label) to ComparisonTable - Fix heading hierarchy and landmarks in InstallSection, ProductionCta, TestimonialsSection, HowItWorks - Fix contrast failures: .ct-feature-desc, .ct-tool-alt, .ts-role → text-1/2; .ts-avatar #CC88FF → #8833cc; .td-ps #9933ff → #aa55ff - Switch Shiki light theme to github-light-high-contrast (fixes #D73A49, #6A737D, #22863A tokens below 4.5:1); add CSS fallback overrides - aria-hidden="true" on decorative TerminalDemo - Add .sr-only utility and global :focus-visible ring to custom.css - Fix hero alt="" (decorative image) in docs/index.md - Add .github/workflows/a11y.yml (pa11y-ci, WCAG2AA, sitemap-driven) - Add .pa11yci.json with WCAG2AA config and F77 ignore (Mermaid SVG ids) - Add docs:a11y and docs:build:a11y scripts (VITEPRESS_HOSTNAME override so sitemap.xml uses localhost URLs during CI audit) - Split mermaid+d3 into dedicated Rollup chunk; raise chunkSizeWarningLimit to 2500 kB to silence legitimate Mermaid size warning - Increase HowItWorks step description font-size 14px → 15px
1 parent 851e4d8 commit 981dfdf

File tree

17 files changed

+383
-73
lines changed

17 files changed

+383
-73
lines changed

‎.github/workflows/a11y.yml‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# Accessibility audit — WCAG 2.1 AA
2+
#
3+
# Runs pa11y-ci against the built VitePress docs to ensure the homepage and
4+
# key pages remain WCAG 2.1 AA compliant.
5+
#
6+
# Triggers:
7+
# - push to main touching docs/** or this workflow / config
8+
# - every pull_request touching the same paths
9+
# - workflow_dispatch (manual run)
10+
#
11+
# Strategy:
12+
# 1. Build the docs with `bun run docs:build:a11y` (sets VITEPRESS_HOSTNAME=
13+
# http://localhost:4173 so the generated sitemap.xml contains localhost
14+
# URLs that pa11y-ci can reach directly)
15+
# 2. Start `vitepress preview` in the background (serves on port 4173)
16+
# 3. Wait until the server is accepting connections
17+
# 4. Run pa11y-ci configured in .pa11yci.json (WCAG 2.1 AA, errors only)
18+
#
19+
# Chrome: Ubuntu-latest ships google-chrome-stable. We skip Puppeteer's own
20+
# Chromium download (PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=1) and point directly to
21+
# the system Chrome via PUPPETEER_EXECUTABLE_PATH at runtime. This cuts ~200 MB
22+
# from every CI run.
23+
name: Accessibility audit (WCAG 2.1 AA)
24+
25+
on:
26+
push:
27+
branches: [main]
28+
paths:
29+
- "docs/**"
30+
- ".github/workflows/a11y.yml"
31+
- ".pa11yci.json"
32+
pull_request:
33+
paths:
34+
- "docs/**"
35+
- ".github/workflows/a11y.yml"
36+
- ".pa11yci.json"
37+
workflow_dispatch:
38+
39+
# One audit at a time per branch; cancel stale runs on new push.
40+
concurrency:
41+
group: a11y-${{ github.ref }}
42+
cancel-in-progress: true
43+
44+
jobs:
45+
audit:
46+
name: WCAG 2.1 AA pages audit
47+
runs-on: ubuntu-latest
48+
49+
steps:
50+
- name: Checkout
51+
uses: actions/checkout@v6
52+
53+
- name: Setup Bun
54+
uses: oven-sh/setup-bun@ecf28ddc73e819eb6fa29df6b34ef8921c743461 # v2.1.3cf28ddc73e819eb6fa29df6b34ef8921c743461 # v2.1.3
55+
with:
56+
bun-version: latest
57+
58+
- name: Install dependencies
59+
run: bun install --frozen-lockfile
60+
61+
- name: Build docs (a11y — sitemap will use localhost URLs)
62+
run: bun run docs:build:a11y
63+
64+
# Start VitePress preview in the background; base URL: /github-code-search/
65+
# --port 4173 matches the URLs in .pa11yci.json
66+
- name: Start VitePress preview server
67+
run: bun run docs:preview -- --port 4173 &
68+
69+
# Poll until the preview server responds (max 60 s = 30 × 2 s).
70+
- name: Wait for preview server to be ready
71+
run: |
72+
echo "Waiting for VitePress preview on http://localhost:4173/github-code-search/ …"
73+
for i in $(seq 1 30); do
74+
if curl -sf http://localhost:4173/github-code-search/ > /dev/null 2>&1; then
75+
echo "Server ready after $((i * 2)) seconds."
76+
exit 0
77+
fi
78+
echo "Attempt $i/30 — retrying in 2 s …"
79+
sleep 2
80+
done
81+
echo "ERROR: preview server did not start within 60 seconds." >&2
82+
exit 1
83+
84+
# Run the audit. The env vars tell Puppeteer (used by pa11y) to use the
85+
# pre-installed system Chrome instead of downloading a Chromium binary.
86+
- name: Run accessibility audit (pa11y-ci)
87+
env:
88+
PUPPETEER_EXECUTABLE_PATH: /usr/bin/google-chrome-stable
89+
PUPPETEER_SKIP_CHROMIUM_DOWNLOAD: "1"
90+
run: bun run docs:a11y
91+
92+
# Upload the pa11y-ci JSON report as an artifact so failures are
93+
# easy to inspect without re-running the workflow.
94+
- name: Upload audit report
95+
if: always()
96+
uses: actions/upload-artifact@v4
97+
with:
98+
name: pa11y-ci-report
99+
path: a11y-report.json
100+
if-no-files-found: ignore

‎.github/workflows/cd.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ jobs:
4343
uses: actions/checkout@v6
4444

4545
- name: Setup Bun
46-
uses: oven-sh/setup-bun@3d267786b128fe76c2f16a390aa2448b815359f3 # v2.1.2
46+
uses: oven-sh/setup-bun@ecf28ddc73e819eb6fa29df6b34ef8921c743461 # v2.1.3d267786b128fe76c2f16a390aa2448b815359f3 # v2.1.2
4747
with:
4848
bun-version: latest
4949

‎.github/workflows/ci.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ jobs:
1616
uses: actions/checkout@v6
1717

1818
- name: Setup Bun
19-
uses: oven-sh/setup-bun@3d267786b128fe76c2f16a390aa2448b815359f3 # v2.1.2
19+
uses: oven-sh/setup-bun@ecf28ddc73e819eb6fa29df6b34ef8921c743461 # v2.1.3d267786b128fe76c2f16a390aa2448b815359f3 # v2.1.2
2020
with:
2121
bun-version: latest
2222

‎.github/workflows/docs.yml‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -57,13 +57,13 @@ jobs:
5757

5858
steps:
5959
- name: Checkout
60-
uses: actions/checkout@v4.2.2
60+
uses: actions/checkout@v6
6161
with:
6262
# Needed to fetch the gh-pages storage branch for versioned snapshots.
6363
fetch-depth: 0
6464

6565
- name: Setup Bun
66-
uses: oven-sh/setup-bun@v2.1.2
66+
uses: oven-sh/setup-bun@ecf28ddc73e819eb6fa29df6b34ef8921c743461 # v2.1.32.1.3
6767
with:
6868
bun-version: latest
6969

@@ -127,7 +127,7 @@ jobs:
127127

128128
steps:
129129
- name: Checkout
130-
uses: actions/checkout@v4.2.2
130+
uses: actions/checkout@v6
131131
with:
132132
# Full history needed to push to gh-pages and commit versions.json to main.
133133
fetch-depth: 0
@@ -146,7 +146,7 @@ jobs:
146146
echo "major=$MAJOR" >> "$GITHUB_OUTPUT"
147147
148148
- name: Setup Bun
149-
uses: oven-sh/setup-bun@v2.1.2
149+
uses: oven-sh/setup-bun@ecf28ddc73e819eb6fa29df6b34ef8921c743461 # v2.1.32.1.3
150150
with:
151151
bun-version: latest
152152

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ dist/
33
coverage/
44
.env
55
*.local
6+
a11y-report.json
67

78
# VitePress
89
docs/.vitepress/cache

‎.pa11yci.json‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
{
2+
"defaults": {
3+
"standard": "WCAG2AA",
4+
"reporters": ["cli", ["json", { "fileName": "./a11y-report.json" }]],
5+
"level": "error",
6+
"wait": 1500,
7+
"timeout": 60000,
8+
"chromeLaunchConfig": {
9+
"args": ["--no-sandbox", "--disable-setuid-sandbox", "--disable-dev-shm-usage"]
10+
},
11+
"ignore": [
12+
"WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.BgImage",
13+
"WCAG2AA.Principle1.Guideline1_4.1_4_3.G145.BgImage",
14+
"WCAG2AA.Principle4.Guideline4_1.4_1_1.F77"
15+
]
16+
}
17+
}

‎docs/.vitepress/config.mts‎

Lines changed: 68 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,9 @@ function buildBlogSidebarItems(): { text: string; link: string }[] {
3636
try {
3737
files = readdirSync(blogDir)
3838
.filter((f) => f.endsWith(".md") && f !== "index.md")
39-
.toSorted((a, b) => compareVersionArrays(parseBlogVersion(a), parseBlogVersion(b)));
39+
.toSorted((a, b) =>
40+
compareVersionArrays(parseBlogVersion(a), parseBlogVersion(b)),
41+
);
4042
} catch {
4143
// blog dir may not exist during the very first build
4244
}
@@ -116,10 +118,17 @@ export default defineConfig({
116118
"meta",
117119
{
118120
property: "og:image",
119-
content: "https://fulll.github.io/github-code-search/social-preview.png",
121+
content:
122+
"https://fulll.github.io/github-code-search/social-preview.png",
123+
},
124+
],
125+
[
126+
"meta",
127+
{
128+
property: "og:url",
129+
content: "https://fulll.github.io/github-code-search/",
120130
},
121131
],
122-
["meta", { property: "og:url", content: "https://fulll.github.io/github-code-search/" }],
123132
// ── Twitter Card ────────────────────────────────────────────────────────
124133
["meta", { name: "twitter:card", content: "summary_large_image" }],
125134
["meta", { name: "twitter:title", content: "github-code-search" }],
@@ -135,7 +144,8 @@ export default defineConfig({
135144
"meta",
136145
{
137146
name: "twitter:image",
138-
content: "https://fulll.github.io/github-code-search/social-preview.png",
147+
content:
148+
"https://fulll.github.io/github-code-search/social-preview.png",
139149
},
140150
],
141151
],
@@ -155,14 +165,47 @@ export default defineConfig({
155165
const { Resvg } = await import("@resvg/resvg-js");
156166
const { readFileSync, writeFileSync } = await import("node:fs");
157167
const { fileURLToPath } = await import("node:url");
158-
const svgPath = fileURLToPath(new URL("../public/social-preview.svg", import.meta.url));
159-
const pngPath = fileURLToPath(new URL("../public/social-preview.png", import.meta.url));
168+
const svgPath = fileURLToPath(
169+
new URL("../public/social-preview.svg", import.meta.url),
170+
);
171+
const pngPath = fileURLToPath(
172+
new URL("../public/social-preview.png", import.meta.url),
173+
);
160174
const svg = readFileSync(svgPath, "utf-8");
161-
const resvg = new Resvg(svg, { fitTo: { mode: "width", value: 1200 } });
175+
const resvg = new Resvg(svg, {
176+
fitTo: { mode: "width", value: 1200 },
177+
});
162178
writeFileSync(pngPath, resvg.render().asPng());
163179
},
164180
},
165181
],
182+
// ── Chunk splitting ──────────────────────────────────────────────────────
183+
// Mermaid alone is >900 kB minified; split it + the d3 sub-tree into
184+
// dedicated async chunks to eliminate the Rollup 500 kB warning and
185+
// improve long-term caching. No generic vendor catch-all — VitePress
186+
// internals (mark.js etc.) need Rollup's default resolution.
187+
build: {
188+
// Mermaid (bundled with d3) is legitimately large (~2.4 MB minified).
189+
// 2500 kB threshold avoids the Rollup warning without masking real bloat
190+
// on other chunks (next largest is katex at ~260 kB).
191+
chunkSizeWarningLimit: 2500,
192+
rollupOptions: {
193+
output: {
194+
manualChunks(id: string) {
195+
// Mermaid + d3 must be co-located (circular dependency between them).
196+
if (
197+
id.includes("node_modules/mermaid") ||
198+
id.includes("node_modules/vitepress-plugin-mermaid") ||
199+
id.includes("node_modules/d3") ||
200+
id.includes("node_modules/dagre-d3-es") ||
201+
id.includes("node_modules/internmap") ||
202+
id.includes("node_modules/robust-predicates")
203+
)
204+
return "mermaid";
205+
},
206+
},
207+
},
208+
},
166209
},
167210

168211
themeConfig: {
@@ -263,7 +306,10 @@ export default defineConfig({
263306
"/blog/": [
264307
{
265308
text: "What's New",
266-
items: [{ text: "All releases", link: "/blog/" }, ...buildBlogSidebarItems()],
309+
items: [
310+
{ text: "All releases", link: "/blog/" },
311+
...buildBlogSidebarItems(),
312+
],
267313
},
268314
],
269315
"/architecture/": [
@@ -287,11 +333,14 @@ export default defineConfig({
287333
},
288334

289335
// ── Social ────────────────────────────────────────────────────────────────
290-
socialLinks: [{ icon: "github", link: "https://github.com/fulll/github-code-search" }],
336+
socialLinks: [
337+
{ icon: "github", link: "https://github.com/fulll/github-code-search" },
338+
],
291339

292340
// ── Edit link ─────────────────────────────────────────────────────────────
293341
editLink: {
294-
pattern: "https://github.com/fulll/github-code-search/edit/main/docs/:path",
342+
pattern:
343+
"https://github.com/fulll/github-code-search/edit/main/docs/:path",
295344
text: "Edit this page on GitHub",
296345
},
297346

@@ -305,13 +354,20 @@ export default defineConfig({
305354
// ── Markdown ──────────────────────────────────────────────────────────────
306355
markdown: {
307356
theme: {
308-
light: "github-light",
357+
// github-light-high-contrast fixes WCAG AA contrast for Shiki tokens
358+
// (github-light has #D73A49 4.24:1, #6A737D 4.46:1, #22863A 4.28:1 — all below 4.5:1)
359+
light: "github-light-high-contrast",
309360
dark: "github-dark",
310361
},
311362
},
312363

313364
// ── Sitemap ───────────────────────────────────────────────────────────────
365+
// VITEPRESS_HOSTNAME overrides the default for local/CI a11y audits:
366+
// VITEPRESS_HOSTNAME=http://localhost:4173 vitepress build docs
367+
// → sitemap.xml contains localhost URLs that pa11y-ci can reach directly.
314368
sitemap: {
315-
hostname: "https://fulll.github.io/github-code-search/",
369+
hostname:
370+
(process.env.VITEPRESS_HOSTNAME ?? "https://fulll.github.io") +
371+
"/github-code-search/",
316372
},
317373
});

‎docs/.vitepress/theme/ComparisonTable.vue‎

Lines changed: 14 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -80,15 +80,18 @@ const ROWS: Row[] = [
8080
<strong>org-wide code audits and interactive triage</strong>.
8181
</p>
8282
<table class="ct-table">
83+
<caption class="sr-only">
84+
Feature comparison between gh search code and github-code-search
85+
</caption>
8386
<thead>
8487
<tr>
85-
<th class="ct-th-feature"></th>
86-
<th class="ct-th-tool">
88+
<th class="ct-th-feature" scope="col" aria-label="Feature"></th>
89+
<th class="ct-th-tool" scope="col">
8790
<div class="ct-tool-header">
8891
<span class="ct-tool-name ct-tool-alt">gh search code</span>
8992
</div>
9093
</th>
91-
<th class="ct-th-tool">
94+
<th class="ct-th-tool" scope="col">
9295
<div class="ct-tool-header">
9396
<span class="ct-tool-name ct-tool-brand">github-code-search</span>
9497
<span class="ct-badge">Purpose-built</span>
@@ -132,12 +135,12 @@ const ROWS: Row[] = [
132135
</span>
133136
</td>
134137
<td class="ct-cell">
135-
<span v-if="row.gh" class="ct-check">✓</span>
136-
<span v-else class="ct-cross">✗</span>
138+
<span v-if="row.gh" class="ct-check" aria-label="Yes">✓</span>
139+
<span v-else class="ct-cross" aria-label="No">✗</span>
137140
</td>
138141
<td class="ct-cell">
139-
<span v-if="row.gcs" class="ct-check">✓</span>
140-
<span v-else class="ct-cross">✗</span>
142+
<span v-if="row.gcs" class="ct-check" aria-label="Yes">✓</span>
143+
<span v-else class="ct-cross" aria-label="No">✗</span>
141144
</td>
142145
</tr>
143146
</tbody>
@@ -248,7 +251,8 @@ thead tr {
248251
}
249252
250253
.ct-tool-alt {
251-
color: var(--vp-c-text-3);
254+
/* Fix: var(--vp-c-text-3) = 2.87:1, below WCAG AA 4.5:1. text-2 ≥ 5.4:1. */
255+
color: var(--vp-c-text-2);
252256
}
253257
254258
.ct-tool-brand {
@@ -323,7 +327,8 @@ thead tr {
323327
.ct-feature-desc {
324328
font-size: 13px;
325329
font-weight: 400;
326-
color: var(--vp-c-text-3);
330+
/* Fix: var(--vp-c-text-3) ≈ 2.87:1, below WCAG AA. text-1 ensures ≥4.5:1. */
331+
color: var(--vp-c-text-1);
327332
line-height: 1.45;
328333
}
329334

0 commit comments

Comments
 (0)