Ethos #

Measure accessibility coverage in Flutter apps using WCAG 2.2 specifications with Spec-Driven Development.

What is Ethos? #

Ethos measures what percentage of your Flutter widgets comply with WCAG 2.2 accessibility standards.

Unlike tools that detect individual issues, Ethos calculates coverage metrics for each rule, giving you a clear picture of your app's overall accessibility maturity.

📊 Overall Coverage: 75.5%
✅ Compliance Level: AA

📋 Coverage by Rule:
  ✅ Semantic Labels:  85% (17/20)
  ⚠️  Color Contrast:  60% (6/10)  — CRITICAL
  ✅ Touch Targets:   100% (12/12)
  ✅ Keyboard Nav:     90% (9/10)
  ✅ Focus Order:      95% (19/20)
     ⓘ 6 indeterminate (color from theme — not counted)

Features #

• ✅ WCAG 2.2 alignment — coverage metrics, not one-off issue lists.
• ✅ Honest AST analysis with package:analyzer — no regex, no guessing.
• ✅ Indeterminate accounting — values from themes or runtime variables are reported separately and never inflate pass/fail ratios.
• ✅ Built-in spec, zero setup — the WCAG 2.2 rules ship inside the package. You don't copy any YAML file.
• ✅ Optional ethos.yaml — teach Ethos about your own design-system widgets and colors in five minutes.
• ✅ Theme-aware contrast — resolves theme.textTheme.X automatically from your ThemeData, and accepts explicit color_aliases for custom style variables.
• ✅ Pluggable detector registry — add or replace rules without touching the core engine.
• ✅ CI/CD ready — JSON, Markdown, and human-readable outputs; exits with code 1 on critical failures.

Installation #

As a CLI #

dart pub global activate ethos
ethos -p ./my_flutter_app

As a library #

dependencies:
  ethos: ^0.3.1

import 'package:ethos/ethos.dart';

void main() async {
  final analyzer = await CoverageAnalyzer.forProject('./my_flutter_app');
  final report  = await analyzer.analyze();
  print('Coverage:   ${report.overallCoverage}%');
  print('Compliance: ${report.complianceLevel}');
}

You do not copy any spec file. The built-in WCAG 2.2 spec lives inside the package.

Quick start (local development) #

git clone https://github.com/gearscrafter/ethos.git
cd ethos
dart pub get

# Run against the bundled fixtures
dart run example/main.dart

# Run against your own Flutter project
dart run bin/analyze.dart -p ./my_flutter_app

# Install locally as a global command
dart pub global activate --source path .
ethos -p ./my_flutter_app

Configuration (optional): ethos.yaml #

Ethos works out of the box — the built-in spec already covers Flutter's standard widgets (GestureDetector, InkWell, IconButton, TextField, etc.).

Most real apps wrap controls in their own design-system components and define colors in a custom style object. Drop an ethos.yaml next to your pubspec.yaml to teach Ethos about them:

# ethos.yaml — OPTIONAL. Ethos auto-detects it; no flag needed.

widget_aliases:
  # Key = your widget's class name exactly as written in code.
  CircleIconBtn:
    role: button             # button | text | input
    label_arg: semanticLabel # which arg carries the accessible label
    size_guaranteed: true    # already wraps a >= 48×48 target internally?
    keyboard_ready: true     # keyboard-operable out of the box?

  AppButton:
    role: button
    label_arg: a11yLabel

color_aliases:
  # Teach Ethos about your design-system color expressions so the contrast
  # rule can compute real WCAG ratios instead of reporting "indeterminate".
  # Key = exact source expression as written in code.
  "$styles.text.body":
    foreground: "#212121"   # required — the text color
    background: "#FFFFFF"   # optional — the default background color

  "$styles.colors.primary":
    foreground: "#1565C0"

# Optional: tighten a threshold without rewriting the spec.
# rule_overrides:
#   wcag_1_4_3_contrast_minimum:
#     critical_threshold: 95

What each section teaches:

widget_aliases

color_aliases

Maps a design-system style expression to concrete hex colors. Both #RRGGBB and #AARRGGBB formats are accepted. When background is omitted, Ethos cannot compute a ratio and the element remains indeterminate.

No ethos.yaml? Ethos still runs on the built-in spec. Custom widgets and colors appear as indeterminate. For a vanilla Flutter project that's already useful; for a project with a design system, the aliases make all the difference.

Supported rules #

Five built-in rules, all backed by a RecursiveAstVisitor on real Dart AST.

1. Semantic Labels — wcag_1_3_1_semantics_label (WCAG 1.3.1 · Level A) #

Custom interactive widgets must have an accessible label.

• In scope: GestureDetector, InkWell, InkResponse with tap-like gestures, plus any role: button alias from ethos.yaml.
• Pass: wrapped in Semantics(label: '<non-empty literal>') as ancestor or descendant; or the alias label_arg is a non-empty literal.
• Indeterminate: label is a variable, interpolation, or runtime call.
• Excluded automatically: excludeFromSemantics: true, drag/pan-only gestures, onTap: () {} (block-parent), tap-to-dismiss patterns.

// ✅ PASS — Semantics as ancestor
Semantics(
  label: 'Open profile',
  child: GestureDetector(onTap: () {}, child: Icon(Icons.person)),
)

// ✅ PASS — Semantics as descendant also works
GestureDetector(
  onTap: () => navigate(),
  child: Semantics(label: 'Go to settings', child: Icon(Icons.settings)),
)

// ❌ FAIL
GestureDetector(onTap: () => navigate(), child: Icon(Icons.settings))

2. Minimum Color Contrast — wcag_1_4_3_contrast_minimum (WCAG 1.4.3 · Level AA) #

Text must have at least 4.5:1 contrast (3:1 for large text ≥ 18 pt) using the real WCAG luminance formula. Resolution is attempted in three layers:

1. Inline literals — TextStyle(color: Color(0xFF...), backgroundColor: ...).
2. ThemeData extraction — resolves theme.textTheme.bodyLarge etc. automatically from your MaterialApp(theme: ThemeData(...)).
3. color_aliases — resolves design-system expressions like $styles.text.body from your ethos.yaml.

// ✅ PASS — ratio 21:1
Text('Hello', style: TextStyle(
  color: Colors.black,
  backgroundColor: Colors.white,
))

// ❌ FAIL — ratio ~1.6:1
Text('Hello', style: TextStyle(
  color: Color(0xFFCCCCCC),
  backgroundColor: Colors.white,
))

Text('Hello', style: theme.textTheme.bodyLarge)

// ✅ PASS via color_aliases (if declared in ethos.yaml)
// Text('Hello', style: $styles.text.body)

3. Touch Target Size — wcag_2_5_5_target_size_enhanced (WCAG 2.5.5 · Level AAA) #

Interactive elements must be at least 48×48 logical pixels.

• Auto-pass: IconButton, FloatingActionButton (Flutter guarantees 48×48); aliases with size_guaranteed: true.
• Verifiable: custom interactive widget inside a SizedBox or Container with literal width/height — pass if both ≥ 48, fail otherwise.
• Indeterminate: size from a variable, intrinsic content, or tapTargetSize: shrinkWrap.

4. Keyboard Accessibility — wcag_2_1_1_keyboard (WCAG 2.1.1 · Level A) #

All interactive functionality must be reachable by keyboard.

• Pass: Material controls (ElevatedButton, TextField, InkWell, etc.); GestureDetector under a Focus, FocusScope, Shortcuts, or KeyboardListener ancestor; aliases with keyboard_ready: true.
• Fail: GestureDetector.onTap with no keyboard path in its ancestor chain.
• Excluded: widgets with excludeFromSemantics: true (visual-only wrappers).

5. Focus Order — wcag_2_4_3_focus_order (WCAG 2.4.3 · Level A) #

Multi-input layouts must declare explicit focus management.

• In scope: Form widgets, or any layout with 2+ focusable inputs (TextField, Checkbox, Radio, etc.).
• Pass: declares FocusNode, FocusScope, FocusTraversalGroup, or autofocus: true.

CLI reference #

ethos -p <project-path> [options]

Options:
  -p, --project-path   Path to the Flutter project to analyze (required)
  -c, --config         Path to a custom ethos.yaml (default: auto-detect)
  -r, --report-type    Output format: human | json | markdown | coverage
                       (default: human)
  -o, --output         Write report to this file instead of stdout
  -v, --verbose        Show progress details (written to stderr)
  -h, --help           Show this help

Examples:
  ethos -p ./my_app
  ethos -p ./my_app -c path/to/ethos.yaml
  ethos -p ./my_app -r json -o report.json
  ethos -p ./my_app -r markdown -o report.md
  ethos -p ./my_app -v

Verbose logs go to stderr so ethos -p . -r json | jq works cleanly. Exit code 1 when any rule is below its critical threshold — useful as a CI gate.

Compliance levels #

Library API reference #

// Standard entry point — built-in spec + optional ethos.yaml auto-merge
final analyzer = await CoverageAnalyzer.forProject('./my_app');

// With explicit config file
final analyzer = await CoverageAnalyzer.forProject(
  './my_app',
  configPath: 'path/to/ethos.yaml',
);

// Run analysis
final report = await analyzer.analyze();

// Output options
print(report.overallCoverage);   // double 0–100
print(report.complianceLevel);   // 'A' | 'AA' | 'AAA' | 'NONE'
print(report.toJsonString());    // JSON for CI pipelines

Advanced: CoverageAnalyzer.loadFromFile(specPath, projectPath: ...) and .fromString(yaml, projectPath: ...) load a fully custom spec instead of the built-in.

Architecture #

ethos/
├── bin/
│   └── analyze.dart               # CLI entry point
├── lib/
│   ├── ethos.dart                 # Public barrel export
│   └── src/
│       ├── models/
│       │   ├── spec.dart          # Spec, Rule, WidgetAlias, WidgetRole
│       │   ├── ethos_config.dart  # EthosConfig, ColorAlias, RuleOverride
│       │   └── coverage_report.dart  # CoverageReport, RuleCoverage, Finding
│       ├── specs/v1/
│       │   ├── wcag_2_2.yaml          # Source spec — edit this
│       │   └── wcag_2_2_embedded.dart # Generated constant — do not edit
│       └── analyzer/
│           ├── coverage_analyzer.dart  # Engine (forProject / analyze)
│           ├── spec_loader.dart        # Built-in + ethos.yaml merge
│           ├── detector_registry.dart
│           ├── rule_detector.dart      # RuleDetector interface
│           ├── ast/widget_visitor.dart
│           ├── utils/
│           │   ├── color_resolver.dart  # WCAG luminance + Colors.* map
│           │   └── theme_extractor.dart # ThemeData color extraction
│           └── detectors/
│               ├── semantic_labels_detector.dart
│               ├── contrast_detector.dart
│               ├── touch_target_detector.dart
│               ├── keyboard_detector.dart
│               └── focus_order_detector.dart
├── example/
│   ├── main.dart
│   └── fixtures/
│       ├── ethos.yaml             # Sample widget + color aliases
│       └── lib/                   # Sample Dart files (analysis input only)
├── test/
└── tool/
    └── embed_spec.dart            # Regenerates wcag_2_2_embedded.dart

When editing the built-in spec (lib/src/specs/v1/wcag_2_2.yaml), regenerate the embedded constant:

dart run tool/embed_spec.dart

Roadmap #

v1.0.0 #

• Widget alias inheritance — alias a widget once and child widgets inherit its traits automatically.
• Cross-method/cross-file resolution so a Semantics wrapper in a parent widget connects to a custom button in a child.
• More built-in detectors: text scaling, alternative text on images, animation preferences.
• Configurable rule subset — run only the rules you care about.

Contributing #

Contributions are welcome. High-value areas:

• Additional WCAG 2.2 detectors.
• Improved theme/$styles resolution for the contrast rule.
• CI/CD integration examples (GitHub Actions, GitLab CI).

License #

Apache-2.0 — see LICENSE.

Author #

@gearscrafter — Mobile Developer.

Resources #

• WCAG 2.2 Quick Reference
• Flutter Accessibility Docs
• Material Design 3 — Accessibility
• WebAIM Contrast Checker

Made with ❤️ for inclusive Flutter apps.