Add Accessibility

Add Accessibility Skill

Overview

Use this skill to scan all SwiftUI files in a project, find interactive elements missing accessibility identifiers, and add them using a consistent {screen}-{type}-{name} naming convention. Also flags Dynamic Type compatibility issues without auto-fixing them.

Options

• --dry-run: Don't modify files, only report what would be changed
• --path=: Scan only the specified directory (default: all SwiftUI files)
• --verbose: Log each identifier added in detail

Workflow

1) Scan & Analyze

1. Find all *.swift files in the project
2. Filter to files containing SwiftUI views (struct X: View, #Preview, etc.)
3. In each file, detect these interactive elements:

• Button — buttons
• TextField and SecureField — input fields
• Image — images
• Toggle — toggle switches
• Slider — sliders
• Picker — pickers
• DatePicker — date pickers
• NavigationLink — navigation links
• TabView tab items
• .onTapGesture views — tap gesture elements
• Link — external links

1. For each element, check existing accessibility state:

• Has .accessibilityIdentifier()? → SKIP
• Has .accessibilityLabel()? → SKIP
• If either exists, do not touch it

2) Generate Identifiers

Naming convention: {screen}-{type}-{name}

Screen name: derived from the filename

• LoginView.swift → login
• OnboardingStepView.swift → onboarding-step
• HomeTabView.swift → home-tab
• Remove View suffix, convert camelCase to kebab-case

Type: based on the element type

| SwiftUI Element | Type | |----------------|------| | Button | button | | TextField | textfield | | SecureField | securefield | | Image | image | | Toggle | toggle | | Slider | slider | | Picker | picker | | DatePicker | datepicker | | NavigationLink | navlink | | Link | link | | .onTapGesture view | tap | | TabView item | tab |

Name: derived from the element's content

• Button("Continue") → continue
• TextField("Email", ...) → email
• Image(systemName: "gear") → gear
• Image("hero-banner") → hero-banner
• Toggle("Notifications", ...) → notifications
• No content or too complex → number sequentially (button-1, button-2)

Example results:

login-button-continue
login-textfield-email
login-securefield-password
onboarding-image-hero-banner
settings-toggle-notifications
home-tab-profile

3) Apply Changes

Add .accessibilityIdentifier("generated-id") to each element missing one:

// BEFORE
Button("Continue") {
    viewModel.proceed()
}

// AFTER
Button("Continue") {
    viewModel.proceed()
}
.accessibilityIdentifier("login-button-continue")

For Images, also add accessibilityLabel (for VoiceOver):

// BEFORE
Image(systemName: "gear")

// AFTER
Image(systemName: "gear")
    .accessibilityIdentifier("settings-image-gear")
    .accessibilityLabel("Settings")

For onTapGesture views, mark as accessibility elements:

// BEFORE
HStack {
    Image("avatar")
    Text(user.name)
}
.onTapGesture { showProfile() }

// AFTER
HStack {
    Image("avatar")
    Text(user.name)
}
.onTapGesture { showProfile() }
.accessibilityElement(children: .combine)
.accessibilityIdentifier("profile-tap-user-row")
.accessibilityAddTraits(.isButton)

4) Dynamic Type Check

Check Text elements for Dynamic Type compatibility:

1. Flag (report as warnings, do NOT auto-fix):

• Text without .lineLimit() when the content could be long
• Text without .minimumScaleFactor() in constrained areas
• .font(.system(size: XX)) with hardcoded font sizes instead of dynamic fonts like .font(.title), .font(.body)

1. Report format:

⚠️ Dynamic Type Warnings:
  LoginView.swift:42 - Text("Welcome back...") → missing lineLimit or minimumScaleFactor
  LoginView.swift:58 - Text(...).font(.system(size: 14)) → consider using dynamic font (.body, .caption, etc.)
  SettingsView.swift:23 - Text(longString) → missing lineLimit, risk of overflow with large text

5) Summary Report

Show a summary when the scan is complete:

✅ Accessibility Scan Complete
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Files scanned:     24
Elements found:    87
Already present:   31 (skipped)
Newly added:       56
  - Button:        18
  - TextField:      8
  - Image:         12
  - Toggle:         6
  - Other:         12

⚠️ Dynamic Type Warnings: 7
  (details above)

Pattern: {screen}-{type}-{name}

Important Rules

1. NEVER modify or remove existing accessibility modifiers
2. NEVER change the view's functionality or appearance
3. Only add .accessibilityIdentifier(), .accessibilityLabel(), .accessibilityElement(), .accessibilityAddTraits()
4. Do NOT wrap in #if DEBUG — identifiers must be in production too (for real accessibility / VoiceOver)
5. If unsure about a name, use {screen}-{type}-{index} format and flag it in verbose mode
6. Dynamic Type warnings are REPORT ONLY — do not auto-fix, leave it to the user
7. In --dry-run mode, do not modify any files — only show the plan
8. After modifying each file, run a compile check — if a syntax error is introduced, revert

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yusufkaran
• Source: yusufkaran/swiftui-autotest-skill
• License: MIT

Install and usage instructions live in the source repository linked above.