sitapix/txt-accessibility

Accessibility for Custom Text Editors

Authored against iOS 26.x / Swift 6.x / Xcode 26.x.

This skill covers the accessibility surface that text editors specifically need: keeping UITextView's built-in accessibility intact when wrapping it in SwiftUI, declaring traits and value on a from-scratch text view, adopting UIAccessibilityReadingContent so VoiceOver's text-navigation rotor works, choosing the right accessibilityTextualContext so prose vs code vs chat are read correctly, and posting announcements when programmatic changes happen. The patterns here are clues, not answers — before claiming any specific accessibility property exists or behaves a particular way, open the actual view code and verify the configuration, and fetch the current docs via Sosumi (sosumi.ai/documentation/uikit/uiaccessibility) for any signature you're not certain about.

For Dynamic Type — text scaling, UIFontMetrics, content-size category notifications, AX size testing — see txt-dynamic-type. The boundary is intentional: this skill is about VoiceOver and trait wiring; that one is about size scaling.

Contents

• What stock text views give you
• SwiftUI representable wrappers
• Custom text views from scratch
• UIAccessibilityReadingContent
• accessibilityTextualContext
• Announcing programmatic changes
• Accessibility Inspector checks
• Common Mistakes
• References

What stock text views give you

UITextView and NSTextView are accessible by default. They report as static text or as an editable text field depending on isEditable, expose their text content as the accessibility value, support the rotor's character/word/line/heading navigation, and announce typing through the text input system. If a stock text view is silent in VoiceOver, the cause is upstream — a parent isAccessibilityElement = false shadowing the subtree, an overlay view obscuring it, or accessibilityElementsHidden = true on an ancestor — not the view itself.

Programmatic changes (insertions from autocomplete, clipboard pastes you trigger, formatting commands) are not auto-announced. Stock views announce only what flows through the input system. See "Announcing programmatic changes" below.

SwiftUI representable wrappers

The most common failure is a UIViewRepresentable wrapper that accidentally replaces the UITextView's accessibility subtree. SwiftUI generates an accessibility element for the representable container; if you set .accessibilityLabel/.accessibilityValue on the SwiftUI side, the SwiftUI element shadows the UIKit view's dynamic accessibility behavior.

// WRONG — replaces UITextView's dynamic accessibility
EditorView()
    .accessibilityLabel("Editor")

// CORRECT — set on the UITextView itself
struct EditorView: UIViewRepresentable {
    func makeUIView(context: Context) -> UITextView {
        let tv = UITextView()
        tv.isEditable = true
        tv.accessibilityHint = "Double tap to edit"
        // Do NOT set accessibilityLabel/accessibilityValue here —
        // UITextView populates them dynamically from text and isEditable.
        return tv
    }
    func updateUIView(_ uiView: UITextView, context: Context) { }
}

The narrowest hint to add: a hint (not a label, not a value) on the UITextView itself. Hints supplement; labels and values replace. Letting UITextView continue to drive its label and value is what keeps the rotor and text navigation working.

If the SwiftUI side genuinely needs to expose its own label (because the editor is one element of a larger composite), apply .accessibilityElement(children: .contain) so the wrapper becomes a container that lets the UIKit subtree through, rather than .accessibilityElement() (no argument), which replaces the subtree with a single element.

Custom text views from scratch

A text view that doesn't inherit from UITextView/NSTextView is silent until you wire accessibility manually. The minimum surface is isAccessibilityElement = true, a label, a value, and traits matching the editing state.

class CustomTextView: UIView {
    override var isAccessibilityElement: Bool {
        get { true }
        set { }
    }

    override var accessibilityTraits: UIAccessibilityTraits {
        get { isEditable ? [] : .staticText }
        set { }
    }

    override var accessibilityValue: String? {
        get { textContent }
        set { }
    }

    override var accessibilityLabel: String? {
        get { placeholder ?? "Text editor" }
        set { }
    }
}

The trait set is empty for editable views and .staticText for read-only — VoiceOver derives "editable" handling from the absence of .staticText plus the input-system signals (focus state, first-responder status). Do not try to add a hypothetical .editable trait; the trait that exists is .staticText for the read-only case.

The accessibility value should reflect the current text content. If the editor stores text in a backing store that updates incrementally, ensure accessibilityValue reads the current state — caching a snapshot here is how "VoiceOver reads stale text" bugs originate.

UIAccessibilityReadingContent

For VoiceOver's rotor to navigate the editor by line, the view must declare its line geometry through UIAccessibilityReadingContent. Without this protocol, character and word rotors still work (they use the value string), but line navigation does not.

extension CustomTextView: UIAccessibilityReadingContent {
    func accessibilityLineNumber(for point: CGPoint) -> Int {
        lineNumber(at: point)
    }

    func accessibilityContent(forLineNumber lineNumber: Int) -> String? {
        textContent(forLine: lineNumber)
    }

    func accessibilityFrame(forLineNumber lineNumber: Int) -> CGRect {
        frameForLine(lineNumber)
    }

    func accessibilityPageContent() -> String? {
        textContent
    }
}

The frame returned by accessibilityFrame(forLineNumber:) is in screen coordinates — convert from your view's coordinate space via convert(rect, to: nil) if needed. VoiceOver uses this rect to position its highlight overlay; an incorrect coordinate space results in the focus indicator drawing in the wrong place.

accessibilityPageContent() returns the entire visible page of text; pagination is a concept VoiceOver uses to scope long documents. For editors that don't paginate, return the full content.

accessibilityTextualContext

UIAccessibilityTextualContext tells VoiceOver how to read the content. The default treats text as ordinary prose; that's wrong for code (where punctuation matters), spreadsheets (where layout structure matters), and chat (where utterances are short and discrete). The right context per editor type:

• .sourceCode — reads punctuation literally (braces, parens, colons, operators). The real differentiator for code editors; without it VoiceOver elides the symbols that carry meaning.
• .wordProcessing — rich-text editor cues. Right for a Notes-style editor with formatting and structural elements.
• .narrative — long-form prose readers (essays, articles, books). Reading cadence tuned for paragraphs.
• .console — terminals and log viewers. Treats lines as discrete records, reads control characters.
• .messaging — chat. Short discrete utterances, fast cadence.
• .spreadsheet — tabular cells. VoiceOver reads coordinates and structure.
• .fileSystem — paths and identifiers. Reads separators and segments rather than treating slashes as prose.

textView.accessibilityTextualContext = .sourceCode

Source-code context is the most consequential. In the default prose context, VoiceOver omits most punctuation — a comprehensible behavior for paragraphs, an incomprehensible one for code. A code editor that doesn't set .sourceCode is effectively unusable with VoiceOver.

The property is settable on any UIView that can be an accessibility element, not just UITextView. Set it on the wrapper view of a custom editor as well.

iOS 17 and iOS 18 rotor changes

iOS 17 added a "Change Rotor with Item" toggle in Settings → Accessibility → VoiceOver → Rotor. With it enabled, focusing an item that has custom actions auto-switches the rotor to Actions; with it disabled (and many users now disable it after the iOS 17 default change), the rotor stays where the user left it. For a custom editor that exposes accessibilityCustomActions, this means the user may not discover the actions unless they manually rotate to the Actions rotor. Surface critical actions through the standard text-edit menu or via gesture as a backup, not only through custom actions.

iOS 18 added a two-finger rotation gesture as an alternative to the rotor twist. It reaches the same rotor ring but can be performed with one hand. No code change is required for support — the gesture works on any view that participates in the rotor — but it's worth knowing when reproducing user reports of "I can't get to the rotor."

Announcing programmatic changes

VoiceOver is not aware of edits that happen outside the input system. Format commands, paste-and-clean operations, autocompletion expansions, AI rewrites — none of these emit accessibility events on their own. Post an announcement so the user knows what changed.

func applyFormatting(_ style: FormatStyle) {
    applyStyle(style, to: selectedRange)
    UIAccessibility.post(
        notification: .announcement,
        argument: "Applied \(style.name) formatting"
    )
}

For larger structural changes (content reloaded, document switched, view layout substantially changed), post .layoutChanged with the new focus argument so VoiceOver re-reads the focused element:

UIAccessibility.post(notification: .layoutChanged, argument: textView)

Don't over-announce. An announcement on every keystroke or every autocorrect is noise that makes the editor harder to use, not easier. Reserve announcements for user-initiated commands the user might not have heard the result of.

AccessibilityNotification on macOS uses NSAccessibility.post(...) with NSAccessibility.Notification.announcementRequested — the equivalent path with a slightly different argument shape.

Accessibility Inspector checks

The Xcode Accessibility Inspector exposes the live tree. Run it against the simulator while interacting with the editor; the relevant fields:

• The text view appears as an element (no shadowing parent).
• Traits show as expected: .staticText for read-only, empty trait set for editable.
• Value updates as text changes — typing in the editor should change the displayed value live.
• Label is non-empty (a placeholder, a header label, or an accessibility-only label).
• Hint, if set, supplements the label without duplicating it.

The interaction surface should also be tested with a screen reader, not just the inspector. Accessibility Inspector confirms the wiring is present; VoiceOver confirms the wiring is correct.

Common Mistakes

1. SwiftUI accessibility modifiers on a UIViewRepresentable wrapper. .accessibilityLabel("Editor") on the SwiftUI side replaces the UITextView's dynamic value with a static label, breaking text navigation. Set accessibility properties on the underlying UITextView, or use .accessibilityElement(children: .contain) to leave the subtree intact.

2. Caching text in accessibilityValue. A snapshot value stays stale as text changes. The getter should read current state from the backing store every call.

3. Missing UIAccessibilityReadingContent on a custom view. Without it, the line rotor doesn't function. Character and word navigation still work (they only need accessibilityValue), but line navigation requires the protocol.

4. .plain context on a code editor. VoiceOver skips most punctuation in prose context. Code becomes incomprehensible. Set .sourceCode on any text view whose content is code.

5. Programmatic edits without an announcement. A user invoking a "make this formal" rewrite hears nothing if the editor doesn't post an announcement. Post .announcement for command outcomes; post .layoutChanged for structural changes.

6. Custom fonts without the UIFontMetrics + adjustsFontForContentSizeCategory pair. Custom fonts re-scale only when both conditions are met: the font is wrapped via UIFontMetrics.scaledFont(for:) and the text view has adjustsFontForContentSizeCategory = true. Either alone is inert. This often surfaces during accessibility audits because reviewers test at AX sizes and the editor's text doesn't grow. See /skill txt-dynamic-type for the scaling pattern. Accessibility and Dynamic Type are separate but mutually reinforcing.

7. Testing only with VoiceOver. Switch Control, Voice Control, and Full Keyboard Access exercise different surfaces. A view that works with VoiceOver may still be unreachable by Switch Control if the trait set or focus order is wrong.

References

• /skill txt-dynamic-type — Dynamic Type scaling, content-size categories, UIFontMetrics
• /skill txt-wrap-textview — UIViewRepresentable wrapping patterns and the SwiftUI/UIKit boundary
• /skill txt-view-picker — picking an accessible text view in the first place
• /skill txt-colors — text contrast and semantic color pairing
• UIAccessibility
• UIAccessibilityReadingContent
• UIAccessibilityTextualContext