# Add Accessibility Labels to a Flutter Cupertino App

Yes. An agent finds every icon button, toggle and field in your Flutter app that a screen reader cannot name, labels them, adds semantics tests, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-accessibility-labels/flutter/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads the widget tree the way VoiceOver would. In an app like `date_planner` in flutter/samples, `pubspec.yaml` takes `cupertino_icons`, `intl`, `provider` and `uuid` on an SDK of `^3.9.0-0` inside the repository's pub workspace, `analysis_options.yaml` includes the shared `analysis_defaults` with `flutter_lints` and strict casts and inference, and there is no `test/` directory. `main.dart` runs a `CupertinoApp` whose home is `EventList`, a `CupertinoSliverNavigationBar` with one trailing `CupertinoButton` whose child is `Icon(CupertinoIcons.plus)` and nothing else. That button adds an event, and a screen reader announces it as a button with no name. The agent lists every control like it before changing any.

The list is short and specific. In `event_row.dart`, the trailing widget is either `Icon(CupertinoIcons.check_mark)` for a finished event or a bare `Text` with the remaining task count, so a row reads as its title, its date, and then `3` with no unit. In `event_detail.dart`, the icon that opens the symbol editor is a `CupertinoButton` around an `Icon`, and the title field is a `CupertinoTextField` with `decoration: null` and no placeholder. In `task_row.dart`, the toggle is a `CupertinoButton` whose child switches between `checkmark_circle_fill` and `circle`, with no label and no checked state, and the task text field has no label either. In `symbol_editor.dart`, the ten colour buttons are each an `Icon(CupertinoIcons.circle_fill, color: ...)`, the twenty symbol buttons each an `Icon(icon, size: 32)` from the `eventSymbols` list in `event_symbol.dart`, which holds `IconData` values and no names, and a row of dots is a `Text` of periods that a reader would spell out.

Each control gets a label where the convention it already follows allows one. `Icon` takes `semanticLabel`, so the add button becomes `Add event`, the symbol button `Change symbol and colour`, the row's check mark `All tasks done`, and the count is wrapped in `Semantics(label: '3 tasks remaining')` with the number read from `event.remainingTaskCount`. The task toggle is wrapped in `Semantics` with `checked` and `toggled` state and a label of `Mark task complete` or `Mark task incomplete`, so a reader hears the state and the action. The two text fields get a `placeholder` of `Event title` and `Task`, which Cupertino exposes as the field's label. In the symbol editor, the colour buttons take `color.name` from the `ColorOptions` enum, the symbol list becomes a list of records pairing each `IconData` with a name such as `House` and `Ticket`, which the grid reads for both the icon and the label, the large preview icon gets the chosen name, and the dotted divider is wrapped in `ExcludeSemantics`. Decorative icons, the coloured event icon in each row, are excluded so a row does not announce its own glyph.

The agent then adds a `test/` directory the sample never had. `semantics_test.dart` calls `tester.ensureSemantics()`, pumps the app with a fresh `EventData`, and asserts with `find.bySemanticsLabel` and `matchesSemantics` that the add button is a labelled button with a tap action, that a task toggle reports `isChecked` after a tap in editing mode, and that the symbol grid exposes twenty labelled buttons. It also runs `meetsGuideline(labeledTapTargetGuideline)` on each screen and `iOSTapTargetGuideline` on the editor, where the colour buttons are drawn with `minimumSize: Size.zero`; a failure there is reported in the pull request as a question about target size rather than fixed by resizing the design. The README says the app runs against Flutter's `main` channel, so the sandbox installs that channel, and the agent runs `flutter pub get`, `dart analyze`, `dart format .` and `flutter test`, the same sequence `tool/ci_script.dart` runs for every package in CI.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add accessibility labels to this Flutter Cupertino app. Read pubspec.yaml, analysis_options.yaml, README.md and every file under lib/ first, and list every icon button, toggle, text field and decorative icon that has no semantic label. Give each control a label: semanticLabel on Icon for icon-only buttons, Semantics with checked and toggled state and an action label on the task toggle, a placeholder on the unlabelled CupertinoTextFields, a label built from remainingTaskCount on the task count, color.name on the colour buttons, and a name for every entry of eventSymbols by turning the list into records of icon and name. Exclude decorative icons and the dotted divider from semantics. Change no layout or colour. Add test/semantics_test.dart with ensureSemantics, bySemanticsLabel and matchesSemantics checks for the add button, the task toggle state and the symbol grid, plus the labeledTapTargetGuideline and iOSTapTargetGuideline checks; report a tap-target failure in the pull request rather than resizing the design. Install the Flutter channel the README names, run flutter pub get, dart analyze, dart format . and flutter test, and open a pull request listing every label added, by file and widget, with the test output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request touches `event_list.dart`, `event_row.dart`, `event_detail.dart`, `task_row.dart`, `symbol_editor.dart` and `event_symbol.dart`, adds `test/semantics_test.dart`, and changes no layout, colour or behaviour for a sighted user. Its description is a table of every label by file and widget, followed by the `dart analyze` and `flutter test` output and the channel the sandbox installed.

The symbol list change is the one that reaches beyond a wrapper: `eventSymbols` becomes a list of icon-and-name records so the grid can label each button, and `symbol_editor.dart` reads both fields. The description shows the before and after of that list so a reviewer can check the twenty names.

Before merging, a reviewer runs the app with VoiceOver or TalkBack on one screen to hear the labels in order, reads the tap-target result for the colour row and decides whether those buttons should grow, and checks that the names chosen for the symbols match the words the team uses for them.

## Run it on every app store accessibility review

A developer handed a store review or an internal accessibility audit starts this from the terminal with this body and the app's repository in `resources`, then goes on with the release. The run reads the real widgets and the real enum names, so the labels follow the app's own vocabulary, and the semantics test it adds keeps the next unlabelled button from reaching the store.

A team with several Flutter apps sends one `POST /o/{org}/sessions` per repository with a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started. A Material app gets `tooltip` on its `IconButton`s where the Cupertino app gets `semanticLabel`, and an app with existing widget tests gets the semantics checks added beside them.

## Why run it on Rush?

Missing labels are a finding spread across every file that draws an icon, and each one needs a judgement: is this icon a control, a status, or decoration, and what would a person call it. The agent reads the whole tree in one pass, takes the names the code already has, the enum's `name` and the task count, and writes the rest down in the pull request so each choice is reviewable.

The proof is a semantics test on the real widget tree, run on the Flutter channel the app targets, in a sandbox that installs that channel rather than whatever is on a laptop. The tap-target guideline runs in the same test and its result is reported rather than hidden, so the pull request shows what a screen reader will say and what the design still owes.

## Frequently asked questions

### Will it change what sighted users see?

No. `semanticLabel`, `Semantics`, `ExcludeSemantics` and a placeholder on an empty field affect the accessibility tree only, except that the placeholder shows as hint text in an empty title or task field, which the pull request points out. Colours, sizes and layout stay as they are.

### How does it name the twenty symbols?

The `eventSymbols` list holds `IconData` values, which carry no name, so the agent pairs each with a word taken from the icon's own identifier, `house_fill` becomes `House`, `gamecontroller_fill` becomes `Game controller`, and lists all twenty in the pull request for the team to adjust.

### What does the tap-target check do?

`iOSTapTargetGuideline` fails any tappable node smaller than 44 by 44 points. The colour buttons in the symbol editor are drawn with `minimumSize: Size.zero` around a default-size icon, so the check is likely to name them. The agent reports the result and leaves the size to the design owner, since enlarging them changes the row's layout.

### Why a Flutter channel other than stable?

The sample's README says it runs against the `main` channel only, and the sandbox installs what the README says so the analysis and tests run on the SDK the app targets. For an app on stable, the agent installs stable.

### Does it localise the labels?

The app has no localisation setup and its visible strings are literals, so the labels are literals in the same files. For an app with `flutter_localizations` and `.arb` files the labels go through those files as new keys, and the pull request adds them to every locale.

## More Flutter jobs

- [Generate App Icons for Every Platform of a Flutter App](https://getrush.ai/run/add-app-icons/flutter/)
- [Add Fingerprint and Face ID Login to a Flutter App](https://getrush.ai/run/add-biometric-auth/flutter/)
- [Add Dev and Production Build Flavors to a Flutter App](https://getrush.ai/run/add-build-flavors/flutter/)

## The same job on other stacks

- [Add Accessibility Labels to an Expo App's Screens and Components](https://getrush.ai/run/add-accessibility-labels/expo/)

## More jobs like this: Hand off a long task

- [Add Account Deletion to an AdonisJS API](https://getrush.ai/run/add-account-deletion/adonisjs/)
- [Add Account Deletion to a Next.js and Prisma App](https://getrush.ai/run/add-account-deletion/prisma/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
