reis-mobile 0.4.0 → 0.6.0

package/agents/mobile-accessibility-auditor.md

@@ -0,0 +1,63 @@
+---
+name: mobile-accessibility-auditor
+description: Use this agent to audit mobile UI code for accessibility on any stack (Flutter, Jetpack Compose and Android Views, SwiftUI and UIKit, React Native) — missing or misleading screen reader labels, roles and states, decorative elements read aloud, rows split into many elements, touch targets below the minimum, text that does not scale, contrast risks, focus in dialogs and unannounced dynamic changes. It returns a severity-ranked report with file:line evidence and the fix in the platform's own API. Typical triggers are "is this screen accessible?", "TalkBack reads this button as unlabeled", an accessibility audit before release and a WCAG compliance request.
+model: inherit
+color: purple
+tools: ["Read", "Grep", "Glob", "Bash"]
+intents: [accessibility]
+stacks: ["*"]
+---
+
+You are a senior mobile accessibility engineer. You know how TalkBack and VoiceOver build their view of a screen from Flutter semantics, Compose semantics, Android Views, SwiftUI modifiers, UIKit properties and React Native props, and you judge UI by whether a person using a screen reader, large text, switch access or reduced motion can complete the flow.
+
+## When to act
+
+- **Screen or component audit.** The user points at files, a screen or a flow.
+- **Change review.** A diff touches UI; audit only the changed UI, reading the whole widget, composable or view when the hunk is not enough.
+- **Pre-release audit.** No target given: start from the main flows (onboarding, login, the primary task, checkout or payment, settings) and shared components (buttons, list rows, inputs, dialogs), since one broken shared component breaks every screen.
+
+The `mobile-accessibility` skill holds the checks and a reference per platform (`references/flutter.md`, `android.md`, `ios.md`, `react-native.md`); read the one for the project's stack, and the native references for native screens inside cross-platform apps.
+
+## Process
+
+1. Detect the stack (`node "${CLAUDE_PLUGIN_ROOT}/bin/reis-mobile.mjs" detect`, or the router result when available) and the UI toolkit: Compose or Views, SwiftUI or UIKit.
+2. Find the shared components first (`Grep` for custom buttons, icon buttons, list items, text fields, dialogs) and audit them once.
+3. For each screen, walk the accessibility tree in reading order as the screen reader would: name, role, state, grouping, then touch targets, text scaling, focus and announcements.
+4. **Confirm every finding in the code.** A label passed through a parameter, a theme that sets minimum sizes or a wrapper component that adds semantics can make a suspicion false. Follow the call to where the semantics are actually set.
+5. Rank by who is blocked: a user who cannot complete the flow comes before a user who needs an extra swipe.
+6. Give the minimal fix in the project's language, conventions and component library.
+
+## Rules
+
+- Use only APIs that exist in the versions the project uses. Check `pubspec.lock`, the Compose BOM or `build.gradle`, the iOS deployment target or `package.json` before recommending an API added recently (for example, iOS 17-only announcement APIs).
+- Labels describe the action or content in the app's language, and include context in lists ("Delete *Buy milk*", not "Delete" repeated twenty times). Do not add "button" or "image" to labels: the role already says it.
+- Do not ask for hints, custom actions or sort orders where the default is already correct; extra semantics are noise too.
+- Contrast and real screen reader behavior cannot be proven from code alone. Mark those findings as risks and name the tool that confirms them (Accessibility Scanner, Accessibility Inspector, `performAccessibilityAudit`, Flutter's `textContrastGuideline`).
+- Do not edit files unless the user asks for fixes. When they do, keep each fix scoped and suggest the automated check that prevents the regression.
+- Answer in the user's language; keep code, API names and labels' original language as they are in the project.
+
+## Report format
+
+```markdown
+## Accessibility audit
+Stack and UI toolkit, scope (files, screens or diff), verdict: accessible | needs work | blocks screen reader users.
+
+## Critical
+## High
+## Medium
+## Low
+
+For each finding:
+- **Element** — `path:line`
+- **Problem** — what the user hears or cannot do
+- **Guideline** — the WCAG 2.2 criterion or platform guideline (for example, 1.1.1 Non-text Content, 4.1.2 Name, Role, Value)
+- **Fix** — code in the platform's API
+
+## Needs device verification
+Contrast, reading order across complex layouts, custom controls — what to check and with which tool.
+
+## Prevent regressions
+Automated checks to add to the test suite for this stack.
+```
+
+If a severity has no findings, write "No findings."

package/agents/mobile-code-reviewer.md

@@ -16,6 +16,8 @@ You are a senior mobile engineer doing code review. Your job is to find what bre
 - **Project audit.** There are no changes. Prioritize the entry points (`main.dart`, `Application`/`MainActivity`, `AppDelegate`/`@main`, `App.tsx`), the data layer, authentication and the most complex screens.
 - **Called via /reis-mobile:review.** The command has already detected the stack and loaded the skills. Follow their checklists; do not redo the detection.
 
+The `mobile-code-review` skill holds the review process and a checklist per platform (`references/flutter.md`, `android.md`, `ios.md`, `react-native.md`); read the one for the project's stack.
+
 ## Process
 
 1. Confirm the stack and the target platforms (use the router result when available).

package/agents/mobile-release-engineer.md

@@ -0,0 +1,58 @@
+---
+name: mobile-release-engineer
+description: Use this agent to get a mobile app version out safely on any stack (Flutter, native Android, native iOS, React Native and Expo) — release readiness audits with a go/no-go verdict, version and build number checks, signing and crash symbol setup (R8 mappings, dSYMs, Dart debug info, source maps), store requirements, staged rollout and rollback plans, release notes and store listing text written from the git history, and CI/CD pipelines with GitHub Actions, fastlane, EAS or Codemagic. Typical triggers are "are we ready to ship 2.3?", "write the release notes since the last tag", "set up a pipeline that uploads to TestFlight and the Play internal track" and a rejected or broken store submission.
+model: inherit
+color: green
+tools: ["Read", "Grep", "Glob", "Bash"]
+intents: [release, deployment]
+stacks: ["*"]
+---
+
+You are a senior mobile release engineer. You have shipped apps to Google Play and the App Store through staged rollouts, broken builds, rejected submissions and hotfixes, and you know that a store release cannot be rolled back: what matters is catching the problem before the upload and limiting the blast radius after it.
+
+## When to act
+
+- **Readiness audit.** "Can we ship?" Check the project against the release checklist and return GO, GO WITH RISKS or NO-GO.
+- **Release notes and store copy.** Turn the commits since the last release into store notes, a developer changelog and QA focus areas.
+- **Pipeline.** Design, write or review a CI/CD pipeline that builds, signs, uploads and archives symbols.
+- **Failed release.** An upload rejected by the store, a signing or provisioning error in CI, a build number conflict, a rollout with rising crashes. Build failures in Gradle or Xcode themselves belong to the `mobile-debug` skill; use it for the compiler and toolchain side.
+
+The `mobile-release` skill holds the process: `SKILL.md` has the readiness checklist and report, `references/flutter.md`, `android.md`, `ios.md` and `react-native.md` the platform details, `references/store-copy.md` the release notes method and store limits, `references/ci-cd.md` the pipelines. Flutter and React Native releases also need the Android and iOS references.
+
+## Process
+
+1. Detect the stack (`node "${CLAUDE_PLUGIN_ROOT}/bin/reis-mobile.mjs" detect`, or the router result when available) and which platforms ship.
+2. Establish the release range: the last release tag (`git describe --tags --abbrev=0`), the current version and build numbers in every manifest, and the branch being released.
+3. Read the files that decide the release: `build.gradle(.kts)`, signing config, `Info.plist` and build settings, entitlements, `PrivacyInfo.xcprivacy`, `pubspec.yaml`, `app.json`/`eas.json`, `Fastfile`, CI workflows, `.gitignore`.
+4. Apply the checklist and the platform references. Every item is pass, fail with evidence, or unknown with who can confirm it.
+5. Deliver the report, notes or pipeline in the formats the skill defines.
+
+## Rules
+
+- **Read-only by default.** Do not bump versions, create tags, push, run uploads, change store settings or run commands that publish (`fastlane` lanes, `eas submit`, `eas update`) unless the user explicitly asks. Propose the exact commands instead.
+- **Never expose secrets.** Do not print keystore passwords, API keys, service account JSON or `.p8` contents, even when you find them. Report where a secret is committed and how to rotate it.
+- **Store rules change every year.** Target API level, minimum Xcode and SDK versions, tester requirements and privacy obligations must be confirmed in the Play Console and Apple's current requirements; do not state deadlines or version numbers from memory as facts.
+- **Evidence for release notes.** A change goes into the notes only when a commit, pull request or issue supports it. Unclear commits go under "needs description" for the team.
+- Do not invent tool flags or action inputs. Check the installed CLI (`fastlane --version`, `eas --version`, `--help`) or the action's documented inputs before writing them into a pipeline.
+- Answer in the user's language. Store notes are written in the languages the app's listing uses; say which translations are missing.
+
+## Output
+
+Readiness audit:
+
+```markdown
+## Release readiness — <app> <version> (<build>)
+Verdict: GO | GO WITH RISKS | NO-GO
+Platforms: Android | iOS | both
+
+### Blockers
+### Risks
+### Unknown
+### Rollout plan
+### Commands
+The exact commands to tag, build and upload once the blockers are fixed.
+```
+
+Release notes: the store, changelog and QA sections from `references/store-copy.md`, with character counts for the store section of each platform.
+
+Pipeline: the workflow files, the list of secrets to create (names only), and what the user must configure in the store consoles.

package/agents/mobile-staff-engineer.md

@@ -4,13 +4,13 @@ description: Use this agent for senior-level guidance across Flutter/Dart, Andro
 model: inherit
 color: blue
 tools: ["Read", "Grep", "Glob", "Bash"]
-intents: [debug, architecture, performance, test, security, release, migration, dependency, build, deployment, accessibility]
+intents: [debug, architecture, performance, test, security, migration, dependency, build]
 stacks: ["*"]
 ---
 
 You are a **Staff Mobile Engineer** with long experience shipping production mobile apps at scale. You are an expert in Flutter/Dart, Android (Kotlin) and iOS (Swift), with deep knowledge of architecture, performance, CI/CD and native SDK integration.
 
-The reis-mobile router sends you work that no stack-specific specialist covers: native Android and iOS projects, debugging and build problems on any stack, migrations, releases and pipelines.
+The reis-mobile router sends you work that no stack-specific specialist covers: native Android and iOS projects, debugging and build problems on any stack and migrations. Release readiness and pipelines go to `mobile-release-engineer`, accessibility audits to `mobile-accessibility-auditor`.
 
 ## When to invoke
 

package/agents/rn-architect.md

@@ -62,7 +62,7 @@ src/
 - Native modules called directly from many places instead of one wrapper
 
 **Configuration**
-- Secrets in `.env` files bundled into the app (see `mobile-security-audit`)
+- Secrets in `.env` files bundled into the app (see `mobile-security`)
 - Missing or loose TypeScript settings (`strict` off) in a codebase that relies on types
 
 ## Process

package/commands/debug.md

@@ -37,7 +37,7 @@ The CLI output has a `Language` line. Write everything the user reads in that la
 Read with the Read tool, in this order:
 
 1. `${CLAUDE_PLUGIN_ROOT}/agents/<Agent>.md`;
-2. `${CLAUDE_PLUGIN_ROOT}/skills/<skill>/SKILL.md` for each listed skill. The first skills are the most specific to the stack and area; read them all, since a failure often crosses layers (a Flutter build that fails inside Gradle).
+2. `${CLAUDE_PLUGIN_ROOT}/skills/<skill>/SKILL.md` for each listed skill. `mobile-debug` maps the stack and the `area` from step 1 to its platform references; read the reference for each layer the failure crosses (a Flutter build that fails inside Gradle needs the Flutter and the Android references).
 
 ## 3. Diagnose
 

package/core/registry/registry.mjs

@@ -8,14 +8,15 @@ import { parseFrontmatter } from './frontmatter.mjs';
 
 export const ANY_STACK = '*';
 
-/** Every skill name starts with the prefix of the first stack it declares. */
-export const SKILL_PREFIXES = {
-  [ANY_STACK]: ['mobile-'],
-  flutter: ['flutter-'],
-  android: ['android-'],
-  ios: ['ios-'],
-  'react-native': ['rn-'],
-  'kotlin-multiplatform': ['kmp-'],
+/**
+ * Every skill starts with `mobile-`. A topic skill covers every stack (`stacks: ["*"]`) with a
+ * reference per platform; a platform skill is named after the one stack it covers.
+ */
+export const PLATFORM_SKILLS = {
+  'mobile-flutter': 'flutter',
+  'mobile-android': 'android',
+  'mobile-ios': 'ios',
+  'mobile-rn': 'react-native',
 };
 
 /**
@@ -119,9 +120,15 @@ export function validateRegistry({ stacks, agents, skills }) {
 
     if (component.source && !component.license) errors.push(`${label}: "source" requires "license"`);
 
-    const prefixes = component.kind === 'skill' ? SKILL_PREFIXES[component.stacks[0]] : undefined;
-    if (prefixes && component.name && !prefixes.some((prefix) => component.name.startsWith(prefix))) {
-      errors.push(`${label}: skill name must start with "${prefixes.join('" or "')}" for stack "${component.stacks[0]}"`);
+    if (component.kind === 'skill' && component.name) {
+      const platform = PLATFORM_SKILLS[component.name];
+      if (!component.name.startsWith('mobile-')) {
+        errors.push(`${label}: skill name must start with "mobile-"`);
+      } else if (platform && !(component.stacks.length === 1 && component.stacks[0] === platform)) {
+        errors.push(`${label}: platform skill ${component.name} must declare stacks: [${platform}]`);
+      } else if (!platform && !(component.stacks.length === 1 && component.stacks[0] === ANY_STACK)) {
+        errors.push(`${label}: topic skill must declare stacks: ["*"], or be one of ${Object.keys(PLATFORM_SKILLS).join(', ')}`);
+      }
     }
 
     for (const intent of component.intents) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "reis-mobile",
-  "version": "0.4.0",
-  "description": "AI agents, skills and workflows for Flutter, Android, iOS and React Native development.",
+  "version": "0.6.0",
+  "description": "AI agents and skills for mobile development — Flutter, Android, iOS and React Native — as a plugin for Claude Code and Codex: code review, debugging, tests, architecture, security and Firebase.",
   "type": "module",
   "license": "MIT",
   "author": "Warleson Reis",
@@ -31,5 +31,26 @@
     "validate": "node bin/reis-mobile.mjs validate",
     "check": "npm run validate && npm test"
   },
-  "keywords": ["mobile", "flutter", "android", "ios", "react-native", "claude-code", "plugin", "agents"]
+  "keywords": [
+    "flutter",
+    "android",
+    "ios",
+    "react-native",
+    "expo",
+    "swift",
+    "swiftui",
+    "kotlin",
+    "jetpack-compose",
+    "dart",
+    "firebase",
+    "mobile",
+    "mobile-development",
+    "claude-code",
+    "claude-code-plugin",
+    "codex",
+    "agent-skills",
+    "skills",
+    "ai-agents",
+    "code-review"
+  ]
 }

package/skills/mobile-accessibility/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: mobile-accessibility
+description: Audits and fixes accessibility in mobile apps on every stack — screen reader labels, roles, states and reading order for TalkBack and VoiceOver, decorative elements, grouping, touch target size, text scaling and Dynamic Type, color contrast, focus in dialogs and announcements for dynamic content — with the exact APIs for Flutter (Semantics), native Android (Jetpack Compose semantics and Views), native iOS (SwiftUI and UIKit) and React Native, plus automated checks in tests. Use when building or reviewing UI for accessibility, preparing an accessibility audit, fixing TalkBack or VoiceOver issues, or when the user mentions a11y, WCAG, screen readers, font scaling or contrast, even if they only point at one screen.
+intents: [accessibility]
+stacks: ["*"]
+---
+
+# Mobile Accessibility
+
+One accessibility process for every mobile stack. This file holds what is true everywhere; each platform's APIs, tools and pitfalls live in its reference.
+
+## 1. Pick the reference
+
+| Project | Read |
+|---|---|
+| Flutter | [references/flutter.md](references/flutter.md) |
+| Native Android: Jetpack Compose or Views | [references/android.md](references/android.md) |
+| Native iOS: SwiftUI or UIKit | [references/ios.md](references/ios.md) |
+| React Native or Expo | [references/react-native.md](references/react-native.md) |
+
+In Flutter and React Native apps, the native reference applies only to screens or components written natively (platform views, native modules with UI).
+
+## 2. What a screen reader user needs
+
+Every interactive element exposes four things to the accessibility tree. Check them in this order:
+
+1. **Name.** What it is or does, in words: "Delete task", not "trash icon" or nothing. Text children usually provide it; icon-only controls, images that carry meaning and custom-drawn controls need an explicit label.
+2. **Role.** Button, checkbox, switch, slider, link, header, image. A tappable container without a role is read as plain text, and the user does not know it can be activated.
+3. **State and value.** Checked, selected, expanded, disabled, the slider's value. When the state changes, the new state is read.
+4. **Order and grouping.** Reading order follows the visual order. Related pieces (an avatar, a name and a timestamp in a list row) are one element, not three swipes.
+
+And the tree must not contain noise: decorative images, dividers and duplicated text are hidden from assistive technology.
+
+## 3. Checks (all stacks)
+
+**Perceivable**
+- [ ] Icon-only buttons, image buttons and meaningful images have a label that describes the action or content.
+- [ ] Decorative images and icons next to text that already says the same are excluded from the accessibility tree.
+- [ ] Text contrast is at least 4.5:1, or 3:1 for large text; icons and control borders that carry meaning reach 3:1 (WCAG 1.4.3 and 1.4.11). Contrast cannot be proven from code alone when colors come from themes or images: say so and name the tool that measures it.
+- [ ] Information is not conveyed by color only (an error shown only as a red border).
+
+**Operable**
+- [ ] Touch targets are at least 48×48 dp on Android and 44×44 pt on iOS, even when the visible icon is smaller. The layout extends the tappable area instead of the icon.
+- [ ] Gestures (swipe to delete, long press, drag) have an alternative: a visible button or a custom accessibility action.
+- [ ] Modal dialogs and bottom sheets move focus inside when they open and return it when they close; content behind them is not reachable.
+- [ ] Timeouts, auto-advancing carousels and animations can be paused or respect the system's reduce motion setting.
+
+**Understandable**
+- [ ] Form fields have a persistent label, not only a placeholder; errors are announced and say how to fix the input.
+- [ ] Screen titles and section headers are marked as headers, so users can jump between them.
+- [ ] Dynamic changes the user did not trigger by moving focus — a snackbar, a validation error, "3 results", loading finished — are announced.
+
+**Robust**
+- [ ] Text scales with the system font size setting up to the largest accessibility sizes without truncation, overlap or clipped containers. Fixed heights on text containers are the usual cause.
+- [ ] Custom-drawn controls (canvas, custom painters, gesture detectors) expose name, role, state and actions explicitly.
+- [ ] The layout works in landscape and with the display size (screen zoom) setting increased.
+
+## 4. Evidence and severity
+
+Point to `file:line` for every finding and give the fix in the platform's own API, not pseudocode.
+
+- **Critical:** a screen reader user cannot complete the flow — an unlabeled primary action, a control that cannot be activated with the screen reader, focus trapped or lost, a custom control invisible to the tree.
+- **High:** the flow is possible but misleading or very hard — wrong role, missing state, targets far below the minimum, text that clips at larger sizes, unannounced errors.
+- **Medium:** noise and friction — decorative elements read aloud, rows split into many swipes, missing headers.
+- **Low:** polish — hints, custom action names, reading order inside a well-labeled group.
+
+## 5. Verify on a device
+
+Code review finds most problems; only assistive technology confirms the experience. Recommend the automated checks listed in the reference for the test suite, then a manual pass: TalkBack on Android and VoiceOver on iOS through the flow, the largest font size, and the platform's scanner (Accessibility Scanner on Android, Accessibility Inspector in Xcode). Say which findings came from code only.

package/skills/mobile-accessibility/references/android.md

@@ -0,0 +1,54 @@
+# Accessibility on native Android
+
+TalkBack reads the accessibility tree built from Compose semantics or from View properties. Material components fill in roles and states; custom composables with `Modifier.clickable`, `pointerInput` or `Canvas`, and custom Views, need them explicitly.
+
+## Jetpack Compose
+
+| Need | API |
+|---|---|
+| Label an icon-only control | `Icon(Icons.Default.Delete, contentDescription = "Delete task")` inside `IconButton` |
+| Hide a decorative icon or image | `contentDescription = null` |
+| Role for a custom clickable | `Modifier.clickable(role = Role.Button, onClickLabel = "Open details") { }` |
+| Toggle with role and state | `Modifier.toggleable(value = checked, role = Role.Checkbox, onValueChange = ...)` on the whole row |
+| Merge a row into one element | `Modifier.semantics(mergeDescendants = true) {}` |
+| Replace children's semantics | `Modifier.clearAndSetSemantics { contentDescription = "..." }` |
+| Header | `Modifier.semantics { heading() }` |
+| Custom state text | `Modifier.semantics { stateDescription = "Expanded" }` |
+| Live updates | `Modifier.semantics { liveRegion = LiveRegionMode.Polite }` |
+| Gesture alternative | `Modifier.semantics { customActions = listOf(CustomAccessibilityAction("Archive") { archive(); true }) }` |
+| Dialog or pane title | `Modifier.semantics { paneTitle = "Filters" }` |
+| Reading order | `Modifier.semantics { traversalIndex = 1f }` with `isTraversalGroup = true` on the container |
+
+Pitfalls:
+
+- A `Checkbox` or `Switch` next to a `Text` in a `Row` produces two elements and a checkbox without a name. Make the `Row` `toggleable` and pass `onCheckedChange = null` to the inner control.
+- `Modifier.size(24.dp)` on an `IconButton` shrinks the touch target. Material components apply `Modifier.minimumInteractiveComponentSize()` (48 dp); keep the icon small, not the button.
+- `Modifier.pointerInput` and `detectTapGestures` add no semantics at all; prefer `clickable`, or add `onClick` in `semantics`.
+- Text sizes in `dp` instead of `sp` do not scale with the font size setting.
+
+## Views
+
+| Need | API |
+|---|---|
+| Label | `android:contentDescription`, or `android:labelFor` on the `TextView` that labels an input |
+| Hide decorative | `android:importantForAccessibility="no"` (or `contentDescription="@null"` on `ImageView`) |
+| Group | `android:focusable="true"` on the container with `android:screenReaderFocusable="true"` |
+| Header | `android:accessibilityHeading="true"` / `ViewCompat.setAccessibilityHeading` |
+| Live updates | `android:accessibilityLiveRegion="polite"` |
+| Role, state, actions | `ViewCompat.setAccessibilityDelegate` with `onInitializeAccessibilityNodeInfo`, or `ViewCompat.addAccessibilityAction` |
+| Text field hint and error | `TextInputLayout` with `hint` and `error` |
+
+`View.announceForAccessibility` is discouraged in recent Android releases in favor of live regions and pane titles; check the `compileSdk` and the method's documentation before recommending it.
+
+## Touch targets and text
+
+- 48×48 dp minimum. For small icons use padding or `TouchDelegate` in Views.
+- Text in `sp`; containers with `wrap_content` or minimum heights, not fixed heights.
+- Test at the largest font size and display size in Settings, including the nonlinear font scaling of Android 14 and later.
+
+## Automated checks
+
+- Espresso: `AccessibilityChecks.enable()` from `androidx.test.espresso:espresso-accessibility` runs the Accessibility Test Framework on every view action.
+- Compose UI tests can assert semantics: `onNodeWithContentDescription("Delete task").assertHasClickAction()`, `assert(hasStateDescription("Expanded"))`.
+- Lint flags missing `contentDescription` on `ImageView` and `ImageButton` (`ContentDescription`) and small touch targets in some layouts.
+- Manual: TalkBack, the Accessibility Scanner app, and Settings → Accessibility → font and display size.

package/skills/mobile-accessibility/references/flutter.md

@@ -0,0 +1,59 @@
+# Accessibility in Flutter
+
+Flutter builds its own semantics tree from widgets and hands it to TalkBack and VoiceOver. Material and Cupertino widgets already fill in most of it; custom widgets built from `GestureDetector`, `InkWell` without children text, `CustomPaint` and images do not. For the broader Flutter guide (including localization), see `mobile-flutter` → `references/accessibility-i18n.md`.
+
+## Labels, roles and states
+
+| Need | API |
+|---|---|
+| Label an icon button | `IconButton(tooltip: 'Delete task', ...)` — the tooltip becomes the label |
+| Label a meaningful image | `Image.asset(..., semanticLabel: 'Profile photo of Ana')` |
+| Hide a decorative image | `Image.asset(..., excludeFromSemantics: true)`, or wrap in `ExcludeSemantics` |
+| Custom tappable widget | `Semantics(button: true, label: '...', onTap: ..., child: ...)` |
+| Toggle state | `Semantics(toggled: value, ...)` or `checked:` for checkbox-like controls |
+| Header | `Semantics(header: true, child: Text('Settings'))` |
+| Replace children's semantics | `Semantics(label: '...', excludeSemantics: true, child: ...)` |
+| Merge a row into one element | `MergeSemantics(child: ListTile(...))` |
+| Extra actions for gestures | `Semantics(customSemanticsActions: {CustomSemanticsAction(label: 'Archive'): _archive})` |
+| Text field label | `TextField(decoration: InputDecoration(labelText: 'Email', errorText: ...))` |
+
+Pitfalls:
+
+- `GestureDetector` and `InkWell` around an `Icon` expose a tap action but no label. Prefer `IconButton`, or add `Semantics`.
+- `Icon(semanticLabel: ...)` labels the icon, but it is still not a button. Put the label on the tappable widget.
+- `Semantics` without `container: true` may merge into an ancestor; set it when a widget must be its own node.
+- `CustomPaint` is invisible to screen readers unless its painter implements `semanticsBuilder` or it is wrapped in `Semantics`.
+
+## Announcements and focus
+
+- Mark text that changes on its own (a counter, a status) with `Semantics(liveRegion: true, ...)`.
+- For one-off messages, `SemanticsService.announce(message, textDirection)` exists in `package:flutter/semantics.dart`; check its status in the Flutter version in `pubspec.lock`'s SDK constraint before recommending it, since the announcement APIs have been evolving for multi-view support.
+- `SnackBar`s shown through `ScaffoldMessenger` are announced by the framework.
+- Dialogs opened with `showDialog` and routes block the semantics of what is behind them; custom overlays built with `Stack` and `Positioned` do not — use `BlockSemantics` or a route.
+- Control reading order with `Semantics(sortKey: OrdinalSortKey(n))` only when the visual order and the widget order genuinely differ.
+
+## Touch targets and text scaling
+
+- Material's minimum is `kMinInteractiveDimension` (48). `ThemeData.materialTapTargetSize: MaterialTapTargetSize.shrinkWrap` shrinks it — flag it on interactive components.
+- Small icons: keep the visual size and give the tappable widget `constraints: BoxConstraints(minWidth: 48, minHeight: 48)` or padding.
+- Text scaling comes from `MediaQuery.textScalerOf(context)`. Flag code that overrides it for the whole app (`MediaQuery(data: ...copyWith(textScaler: TextScaler.noScaling))`) and fixed-height containers around text.
+- Respect reduced motion with `MediaQuery.disableAnimationsOf(context)`.
+
+## Automated checks
+
+Widget tests can assert the guidelines that `flutter_test` ships:
+
+```dart
+testWidgets('login screen meets accessibility guidelines', (tester) async {
+  final handle = tester.ensureSemantics();
+  await tester.pumpWidget(const MaterialApp(home: LoginScreen()));
+
+  await expectLater(tester, meetsGuideline(androidTapTargetGuideline));
+  await expectLater(tester, meetsGuideline(iOSTapTargetGuideline));
+  await expectLater(tester, meetsGuideline(labeledTapTargetGuideline));
+  await expectLater(tester, meetsGuideline(textContrastGuideline));
+  handle.dispose();
+});
+```
+
+Find semantics nodes in tests with `find.bySemanticsLabel('Delete task')`. On a device, use TalkBack and VoiceOver, and the `showSemanticsDebugger: true` flag of `MaterialApp` to see the tree.

package/skills/mobile-accessibility/references/ios.md

@@ -0,0 +1,50 @@
+# Accessibility on native iOS
+
+VoiceOver reads accessibility elements built from SwiftUI modifiers or UIKit properties. Standard controls come with traits and values; custom views, gesture recognizers and drawn content need them explicitly. For the broader iOS UI guide, see `mobile-ios` → `references/ui-navigation.md`.
+
+## SwiftUI
+
+| Need | API |
+|---|---|
+| Label an icon-only button | `Button { } label: { Image(systemName: "trash") }.accessibilityLabel("Delete task")`, or `Label("Delete task", systemImage: "trash").labelStyle(.iconOnly)` |
+| Hide a decorative image | `Image(decorative: "divider")` or `.accessibilityHidden(true)` |
+| Trait for a custom tappable view | Use `Button` instead of `.onTapGesture`; otherwise `.accessibilityAddTraits(.isButton)` |
+| Header | `.accessibilityAddTraits(.isHeader)` |
+| Group a row | `.accessibilityElement(children: .combine)` |
+| Replace children | `.accessibilityElement(children: .ignore).accessibilityLabel("...")` |
+| Value | `.accessibilityValue("3 of 5")` |
+| Hint | `.accessibilityHint("Opens the order details")` — only when the label is not enough |
+| Gesture alternative | `.accessibilityAction(named: "Archive") { archive() }` |
+| Adjustable control | `.accessibilityAdjustableAction { direction in ... }` |
+| Reading order | `.accessibilitySortPriority(_:)` inside a container |
+| Announcement | `AccessibilityNotification.Announcement("Saved").post()` (iOS 17+) or `UIAccessibility.post(notification: .announcement, argument: "Saved")` |
+
+Pitfalls:
+
+- `.onTapGesture` on an `HStack` does not add the button trait, so VoiceOver does not say the row can be activated; `Button` with a custom style keeps the look and the trait.
+- `.font(.system(size: 17))` does not scale with Dynamic Type. Use text styles (`.font(.body)`) and `@ScaledMetric` for custom sizes and spacing.
+- `.frame(height:)` on text containers clips at accessibility sizes; use `minHeight`, and switch `HStack` to `VStack` with `@Environment(\.dynamicTypeSize)` when `dynamicTypeSize.isAccessibilitySize`.
+- Respect `@Environment(\.accessibilityReduceMotion)` for animations.
+
+## UIKit
+
+| Need | API |
+|---|---|
+| Element and label | `isAccessibilityElement = true`, `accessibilityLabel` |
+| Hide decorative | `isAccessibilityElement = false` or `accessibilityElementsHidden = true` on a container |
+| Traits | `accessibilityTraits = [.button]`, `.header`, `.selected`, `.notEnabled` |
+| Group a cell | set `isAccessibilityElement = true` and a combined label on the cell |
+| Custom actions | `accessibilityCustomActions = [UIAccessibilityCustomAction(name: "Archive") { _ in ... }]` |
+| Modal | `accessibilityViewIsModal = true` on the presented view |
+| Screen or layout change | `UIAccessibility.post(notification: .screenChanged, argument: firstElement)` / `.layoutChanged` |
+| Dynamic Type | `UIFont.preferredFont(forTextStyle:)`, `UIFontMetrics`, `adjustsFontForContentSizeCategory = true` |
+
+## Touch targets
+
+Apple's Human Interface Guidelines recommend at least 44×44 points. In SwiftUI, extend the hit area with `.frame(minWidth: 44, minHeight: 44)` and `.contentShape(Rectangle())`; in UIKit, override `point(inside:with:)` or enlarge the button's frame, not the image.
+
+## Automated checks
+
+- XCUITest: `try app.performAccessibilityAudit()` (Xcode 15, iOS 17 and later) checks contrast, hit regions, element descriptions, Dynamic Type clipping and traits; pass a set of audit types or a handler to ignore known issues.
+- Query by label in UI tests (`app.buttons["Delete task"]`): a test that finds elements by label breaks when a label disappears.
+- Manual: VoiceOver on a device, Accessibility Inspector in Xcode (audit and inspection), and Environment Overrides in the debug bar for Dynamic Type, contrast and reduce motion.

package/skills/mobile-accessibility/references/react-native.md

@@ -0,0 +1,38 @@
+# Accessibility in React Native
+
+React Native maps accessibility props to the native TalkBack and VoiceOver APIs. Core components such as `Button` and `Switch` fill in roles; `Pressable`, `TouchableOpacity` and `View` do not. Recent React Native versions also accept ARIA-style props (`role`, `aria-label`, `aria-checked`...) that map to the same native properties; follow whichever style the project already uses. For the broader guide, see `mobile-rn` → `references/ui-navigation.md`.
+
+## Labels, roles and states
+
+| Need | API |
+|---|---|
+| Label an icon-only control | `<Pressable accessibilityRole="button" accessibilityLabel="Delete task">` |
+| Hide decorative content | `accessible={false}` on images; for subtrees `accessibilityElementsHidden` (iOS) **and** `importantForAccessibility="no-hide-descendants"` (Android) |
+| Group a row | `accessible` on the container, with a combined `accessibilityLabel` when children's text is not enough |
+| State | `accessibilityState={{ checked, selected, disabled, expanded, busy }}` |
+| Value | `accessibilityValue={{ min: 0, max: 100, now: 40 }}` or `{{ text: '3 of 5' }}` |
+| Header | `accessibilityRole="header"` |
+| Hint | `accessibilityHint="Opens the order details"` |
+| Gesture alternative | `accessibilityActions={[{ name: 'archive', label: 'Archive' }]}` with `onAccessibilityAction` |
+| Live updates | `accessibilityLiveRegion="polite"` (Android); `AccessibilityInfo.announceForAccessibility('Saved')` for both |
+| Modal | `<Modal>` handles focus; custom overlays need `accessibilityViewIsModal` (iOS) and `importantForAccessibility="no-hide-descendants"` on the content behind (Android) |
+| Move focus | `AccessibilityInfo.setAccessibilityFocus(findNodeHandle(ref.current))` |
+
+Pitfalls:
+
+- A `Pressable` without `accessibilityRole` is read as plain text: the user does not know it is tappable.
+- A checkbox built from `Pressable` and an icon needs `accessibilityRole="checkbox"` and `accessibilityState={{ checked }}`.
+- The iOS-only and Android-only props are silently ignored on the other platform; hiding and modal behavior need both.
+- `TextInput` without a visible label: add `accessibilityLabel`; placeholders are not labels.
+
+## Touch targets and text scaling
+
+- Keep interactive elements at 44×44 pt / 48×48 dp. Use `hitSlop` or padding to extend the area of small icons; `hitSlop` does not extend beyond the parent's bounds on Android.
+- Text scales with the system font size by default. Flag `allowFontScaling={false}` on body text; prefer `maxFontSizeMultiplier` when a layout has a real limit. Avoid fixed `height` on text containers.
+- Respect reduced motion with `AccessibilityInfo.isReduceMotionEnabled()` or Reanimated's `useReducedMotion()`.
+
+## Automated checks
+
+- React Native Testing Library queries by role and label (`screen.getByRole('button', { name: 'Delete task' })`), so tests fail when a role or label disappears. `toBeChecked`, `toBeDisabled` and `toBeExpanded` matchers read the accessibility state.
+- ESLint: `eslint-plugin-react-native-a11y` flags missing roles and labels, when the project uses ESLint.
+- Manual: TalkBack and VoiceOver on devices, the Accessibility Scanner app on Android and Accessibility Inspector in Xcode on the iOS build.

package/skills/mobile-android/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: mobile-android
+description: Builds native Android apps with the Android team's guides — Jetpack Compose UI, adaptive layouts, edge-to-edge, Compose styles, migrating XML views to Compose, Navigation 3 and predictive back; Android Gradle Plugin 9 upgrades, R8 keep rule analysis, profiling with Android Studio and Perfetto, and the Android CLI; Google Play policy compliance, Play Billing upgrades and the Engage SDK; Credential Manager restore and verified email; CameraX and Media3 Cast; App Functions and the ML Kit GenAI Prompt API; Wear OS, Android TV and display glasses. Use when writing, upgrading or auditing native Android (Kotlin) code for any of these topics, even if the user does not name the library.
+intents: [performance, release, migration, build, dependency]
+stacks: [android]
+---
+
+# Mobile Android
+
+Guides for building native Android apps, most of them from the Android team (`android/skills`). Cross-platform topics live in their own skills and have Android references there: architecture in `mobile-architecture`, tests in `mobile-test`, debugging (Gradle, crashes, ANRs) in `mobile-debug`, code review in `mobile-code-review`, security in `mobile-security` and Firebase in `mobile-firebase`.
+
+## Pick the topic
+
+| Topic | Read |
+|---|---|
+| UI and navigation | [references/ui.md](references/ui.md) |
+| Build, performance and tooling | [references/build-and-performance.md](references/build-and-performance.md) |
+| Google Play | [references/play.md](references/play.md) |
+| Identity | [references/identity.md](references/identity.md) |
+| Camera and media | [references/media.md](references/media.md) |
+| On-device AI | [references/on-device-ai.md](references/on-device-ai.md) |
+| Other form factors | [references/devices.md](references/devices.md) |
+
+Each topic file lists its guides; open only the ones the task needs.
+
+## Before writing code
+
+- Check the AGP, Kotlin, Compose BOM and `compileSdk`/`targetSdk` versions in the build files and version catalog; several guides depend on minimum versions.
+- Several guides prescribe running specific tools or scripts and following steps strictly; run what writes files only with the user's agreement.

package/skills/{android-agp-9-upgrade/SKILL.md → mobile-android/references/build-and-performance/agp-9-upgrade/GUIDE.md}

@@ -1,23 +1,4 @@
----
-name: android-agp-9-upgrade
-description: Upgrades, or migrates, an Android project to use Android Gradle Plugin
-  (AGP) version 9. Do not use this skill for migrating Kotlin Multiplatform (KMP)
-  projects.
-license: Apache-2.0
-source: https://github.com/android/skills
-intents: [migration, build, dependency]
-stacks: [android]
-metadata:
-  author: Google LLC
-  last-updated: '2026-08-18'
-  keywords:
-  - Android Gradle Plugin 9
-  - AGP 9
-  - AGP Upgrade
-  - AGP Migration
-  - New AGP DSL
-  - Migrate to built-in Kotlin
----
+> Adapted from the `agp-9-upgrade` skill in [android/skills](https://github.com/android/skills) (Apache-2.0). See `THIRD_PARTY_NOTICES.md`.
 
 ## Migration guide
 

package/skills/{android-cli/SKILL.md → mobile-android/references/build-and-performance/android-cli/GUIDE.md}

@@ -1,28 +1,4 @@
----
-name: android-cli
-description: Provides instructions for installing and using the `android` CLI. The
-  `android` command-line tool is a critical tool for Android development and helps
-  you create new Android projects, run Android apps on devices, manage and interact
-  with Android virtual devices (including screenshots and UI inspection), manage Android
-  SDK components, look up official Android documentation, and discover and install
-  official Android skills.
-license: Apache-2.0
-source: https://github.com/android/skills
-routing: manual
-stacks: [android]
-metadata:
-  author: Google LLC
-  last-updated: '2026-09-12'
-  keywords:
-  - android-cli
-  - sdk
-  - emulator
-  - skills
-  - docs
-  - knowledge base
-  - project creation
-  - screenshots
----
+> Adapted from the `android-cli` skill in [android/skills](https://github.com/android/skills) (Apache-2.0). See `THIRD_PARTY_NOTICES.md`.
 
 This skill provides instructions for using the `android` CLI tool. The tool
 includes various commands for creating projects, running applications,