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=<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

4. 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)

2. 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