菜单
Audits Spectra accessibility: WCAG contrast, colorblind palettes, keyboard nav, high-contrast theme. Use when changing theme colors, legend/series colors, or new interactive UI controls.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Serena MCP Tools — Semantic code analysis and editing with clangd for C++20 and Python
Use for any question about a codebase, its architecture, file relationships, or project content — especially when graphify-out/ exists, where the question should be treated as a graphify query first. Turns any input (code, docs, papers, images, videos) into a persistent knowledge graph with god nodes, community detection, and query/path/explain tools.
Drives a live Spectra instance via the embedded MCP automation server (default http://127.0.0.1:8765/mcp). Use for smoke tests, screenshots, UI commands, figure/series setup, and visual debugging after builds — whenever validating rendering without writing a harness.
Spectra Agent Skill Set
Plan, design, and implement Spectra C++/GLSL/Python changes. Use when breaking down a feature, making architecture decisions before coding, or writing/fixing source in src/, include/spectra/, shaders, tests, or python/.
Spectra git and release workflows: conventional commits, branches, PRs, version bumps, release tags, merge conflicts, changelog. Use for commit, branch, PR, release, version.txt, squash merge, cherry-pick, or git status/diff questions.
| name | qa-accessibility-agent |
| description | Audits Spectra accessibility: WCAG contrast, colorblind palettes, keyboard nav, high-contrast theme. Use when changing theme colors, legend/series colors, or new interactive UI controls. |
Ensure Spectra meets accessibility requirements: WCAG AA contrast ratios, colorblind-safe default palettes, full keyboard navigation, and a working high-contrast theme. This agent owns the inclusivity layer of QA.
Before starting any task, read:
plans/QA_design_review.md — open accessibility items (contrast, colorblind palettes)src/ui/theme/design_tokens.hpp — spacing, font sizes, opacity constantssrc/ui/theme/theme.cpp — initialize_default_themes() — all color valuescmake -B build -G Ninja -DSPECTRA_BUILD_QA_AGENT=ON
cmake --build build -j$(nproc)
./build/tests/spectra_qa_agent --seed 42 --design-review --no-fuzz --no-scenarios \
--output-dir /tmp/spectra_qa_a11y_$(date +%Y%m%d)
Key screenshots to analyze for accessibility:
11_dark_theme.png — dark theme contrast12_light_theme.png — light theme contrast07_inspector_panel_open.png — text on panels08_command_palette_open.png — command palette text legibility34_multi_series_full_chrome.png — series colors in legend/plot (colorblind check)19_3d_surface.png — colormap accessibility (Viridis is colorblind-safe; Jet is not)ctest --test-dir build --output-on-failure -R "test_theme_colorblind|test_theme"
Tests in tests/unit/test_theme_colorblind.cpp verify:
For each UI element in the screenshot set, calculate WCAG AA contrast ratio:
Key element pairs to check:
| Element | Foreground | Background | Required ratio |
|---|---|---|---|
| Plot title | theme.text_primary | plot background | 4.5:1 |
| Axis labels | theme.text_secondary | plot background | 4.5:1 |
| Status bar text | theme.text_secondary | status bar background | 4.5:1 |
| Inspector labels | theme.text_primary | panel background | 4.5:1 |
| Tab bar active | theme.accent | tab background | 3:1 |
| Button icons | icon color | button background | 3:1 |
| Grid lines | theme.grid_color | plot background | — (not text, aim for 1.5:1 minimum for visibility) |
Use the WCAG contrast formula: (L1 + 0.05) / (L2 + 0.05) where L = relative luminance.
Default categorical colors must be distinguishable under:
Test: tests/unit/test_theme_colorblind.cpp
For 3D surface plots — advise Viridis (default) over Jet:
Every interactive control must be reachable via keyboard. Check:
[ = step back; ] = step forwardseries.cycle_selectionVerify shortcuts in src/ui/commands/shortcut_manager.cpp and src/ui/app/register_commands.cpp.
The high-contrast theme (ui::ThemeId::HighContrast) must:
Test by capturing design review with high-contrast theme:
# Modify QA agent to use high-contrast theme, or test via theme toggle command
./build/tests/spectra_qa_agent --scenario mode_switching --no-fuzz \
--output-dir /tmp/spectra_qa_hc
Common accessibility fix patterns:
| Issue | Fix |
|---|---|
| Low contrast text | Increase lightness of text_secondary or darken background |
| Colorblind-unsafe palette | Replace similar-hue colors with perceptually distinct alternatives |
| Missing keyboard shortcut | Add to register_standard_commands() with appropriate key |
| Focus indicator not visible | Add ImGui::SetItemDefaultFocus() or highlight active control |
| Color-only state indicator | Add icon or shape alongside color |
cmake --build build -j$(nproc)
ctest --test-dir build --output-on-failure -R "test_theme"
./build/tests/spectra_qa_agent --seed 42 --design-review --no-fuzz --no-scenarios \
--output-dir /tmp/spectra_qa_a11y_after
Update plans/QA_design_review.md with accessibility findings (use A11Y- prefix for IDs).
| Standard | Requirement |
|---|---|
| WCAG 2.1 AA | Normal text ≥ 4.5:1 contrast |
| WCAG 2.1 AA | Large text ≥ 3:1 contrast |
| WCAG 2.1 AA | UI components ≥ 3:1 contrast |
| WCAG 2.1 AAA | Normal text ≥ 7:1 (high-contrast theme) |
| Colorblind | All state conveyed by shape/icon + color, not color alone |
| Keyboard | All functionality reachable without mouse |
| Issue type | Primary file |
|---|---|
| Theme color values | src/ui/theme/theme.cpp — initialize_default_themes() |
| Design tokens (spacing, font sizes) | src/ui/theme/design_tokens.hpp |
| Colorblind palette | src/ui/theme/theme.cpp — colorblind-safe categorical colors |
| Keyboard shortcuts | src/ui/app/register_commands.cpp |
| Shortcut manager config | src/ui/commands/shortcut_manager.cpp |
| Tab order / focus | src/ui/imgui/imgui_integration.cpp — panel draw functions |
| High-contrast theme | src/ui/theme/theme.cpp — ThemeId::HighContrast |
| Colorblind unit tests | tests/unit/test_theme_colorblind.cpp |
| 3D colormap accessibility | src/gpu/shaders/surface3d.frag — colormap order in UI |
| Command ID | Keyboard | Accessibility note |
|---|---|---|
series.cycle_selection | — | Needs keyboard shortcut (Tab or F6) |
series.copy | Ctrl+C | ✅ |
series.cut | Ctrl+X | ✅ |
series.paste | Ctrl+V | ✅ |
series.delete | Delete | ✅ |
view.toggle_grid | G | ✅ |
view.toggle_legend | L | ✅ |
view.home | H | ✅ |
anim.toggle_play | Space | ✅ |
edit.undo | Ctrl+Z | ✅ |
edit.redo | Ctrl+Shift+Z | ✅ |
| Metric | Target |
|---|---|
test_theme_colorblind | 100% pass |
| Normal text contrast (dark + light themes) | ≥ 4.5:1 |
| UI component contrast | ≥ 3:1 |
| High-contrast theme text | ≥ 7:1 |
| Series palette: deuteranopia distance | > 20 CIELAB units between any two colors |
| Keyboard coverage | 100% of primary actions reachable without mouse |
Update REPORT.md and plans/QA_*.md; extend references/ if you discover new patterns.
Update REPORT.md and plans/QA_*.md; extend references/ if you discover new patterns.
Improvement: <one sentence describing what was added/changed> Motivation: Change: <file(s) edited OR new check described in this SKILL.md> Next gap:
### How to pick an improvement
1. **If bugs were found:** Turn the most surprising finding into a new automated check or a new audit table row. Ask: "What would have caught this earlier?"
2. **If no bugs were found:** The detection is too weak. Pick from the Improvement Backlog below, implement it, and document the result.
### Improvement Backlog (consume one per session, add new ones as discovered)
| ID | Improvement | How to implement |
|---|---|---|
| A-I1 | Audit focus-indicator visibility for all interactive ImGui controls | grep `SetItemDefaultFocus` + `PushStyleColor` in `imgui_integration.cpp`; verify every focusable control has visible ring |
| A-I2 | Check tooltip text contrast (tooltips on hover use secondary text color on overlay background) | Add tooltip element pair to audit contrast table; compute ratio against overlay color in `theme.cpp` |
| A-I3 | Verify screen reader–compatible label pairing: every icon-only button has a tooltip | grep icon-button draws in `imgui_integration.cpp`, confirm each has `SetTooltip` or `BeginTooltip` |
| A-I4 | Add Tritanopia simulation to colorblind palette test | Extend `test_theme_colorblind.cpp` with tritanopia confusion matrix check (blue-yellow channel swap) |
| A-I5 | Audit animation state indicators (play/pause/record) — color-only or icon+color? | Inspect `timeline_editor.cpp` draw code; verify state change uses icon shape not just color change |
| A-I6 | Check status bar text-to-background contrast in light theme (often overlooked) | Compute ratio for `text_secondary` on `status_bar_bg` in light theme values |
| A-I7 | Verify zoom % label is readable at extreme zoom values (e.g. `10^15 %`) | Check `imgui_integration.cpp` zoom label formatting; test overflow/truncation |
| A-I8 | Check 3D axis arrow color distinguishability under deuteranopia (red X vs green Y) | Simulate X=red, Y=green under deuteranopia; if indistinguishable, add label suffix or shape difference |
---
## Live Report
Append findings to [REPORT.md](REPORT.md) at the end of every session.
### Report update procedure
After every run, open `REPORT.md` and:
1. Add a new `## Session YYYY-MM-DD HH:MM` block at the top (newest first).
2. Fill in: colorblind test results, contrast ratios measured (element + ratio + pass/fail), keyboard gaps found, fixes applied (file + change), goldens updated, self-updates made.
3. Update the `## Current Status` block at the very top.
4. Never delete old session blocks — they are the accessibility audit trail.
---
## MCP
[spectra-mcp](../spectra-mcp/SKILL.md).
## Guardrails
- Never change a theme color without computing the new contrast ratio first.
- Do not add color-only state indicators — always pair with an icon or shape.
- Jet colormap is not colorblind-safe — do not set it as the default for new surface plots.
- Accessibility fixes are non-negotiable for P0 issues — do not defer them.
- Run `test_theme_colorblind` after every palette change.
- Route rendering/visual bugs to `qa-designer-agent`; route crash/perf bugs to `qa-performance-agent`.
- Self-updates to this file require `test_theme_colorblind` passing — never update speculatively.