{"id":"fdc34134-c46b-42af-855b-ea0a31a2fcea","shortId":"7CGWY8","kind":"skill","title":"apple-ui-accessibility-workflow","tagline":"Guide Apple UI accessibility implementation and review for SwiftUI-first code, with UIKit and AppKit bridge guidance plus explicit verification expectations and testing handoffs. Use when the user wants help making Apple UI accessible, reviewing accessibility semantics, shaping t","description":"# Apple UI Accessibility Workflow\n\n## Purpose\n\nProvide a docs-first workflow for Apple UI accessibility implementation and review. Keep the first version SwiftUI-first while still covering the UIKit and AppKit bridge surface when SwiftUI code wraps platform-native views or when an accessibility behavior only makes sense in those underlying frameworks.\n\nIt is not the Apple-docs router, not the SwiftUI app-structure workflow, and not the Xcode execution workflow.\n\n## When To Use\n\n- Use this skill when the user wants help making a SwiftUI view, control, list, form, chart, or composite UI more accessible.\n- Use this skill when the user wants help reviewing Apple UI semantics such as labels, values, hints, roles, traits, actions, headings, or grouping behavior.\n- Use this skill when the user wants help deciding whether the default accessibility tree is sufficient or whether a view needs explicit accessibility modifiers.\n- Use this skill when the user wants help shaping the accessibility tree with `accessibilityElement(children:)`, `accessibilityChildren`, `accessibilityRepresentation`, hiding rules, or synthetic accessibility content.\n- Use this skill when the user wants help understanding where SwiftUI accessibility stops and UIKit or AppKit accessibility responsibilities begin.\n- Use this skill when the user wants accessibility-specific verification expectations for VoiceOver, focus order, Dynamic Type, contrast, reduced motion, or related Apple platform settings.\n- Recommend `explore-apple-swift-docs` when the user primarily needs Apple or Swift documentation lookup rather than accessibility guidance.\n- Recommend `xcode-testing-workflow` when the work becomes XCUITest execution, simulator or device automation, `.xctestplan` configuration, or runtime UI verification.\n- Recommend `swiftui-app-architecture-workflow` when the question is really about SwiftUI app structure, scene ownership, command ownership, or general data flow rather than accessibility semantics.\n\n## Single-Path Workflow\n\n1. Classify the request:\n   - SwiftUI implementation\n   - SwiftUI review\n   - UIKit/AppKit bridge guidance\n   - accessibility verification planning\n2. Apply the Apple docs gate before recommending changes:\n   - read the relevant Apple accessibility documentation first\n   - state the documented behavior being relied on before giving accessibility guidance\n   - if Apple docs and the current code disagree, stop and surface that conflict\n   - if no relevant Apple docs can be found, say that explicitly before proceeding\n3. Choose the accessibility surface:\n   - default semantics are already sufficient\n   - explicit description is needed\n   - explicit traits or actions are needed\n   - accessibility tree reshaping is needed\n   - UIKit/AppKit bridge work is needed\n4. Check the anti-patterns before finalizing guidance:\n   - accessibility identifiers treated as if they solve user-facing accessibility\n   - labels that redundantly repeat surrounding visible context\n   - meaningful content hidden from accessibility without a replacement\n   - custom controls that look interactive but do not expose the right role or action\n   - visual order that does not produce a sane assistive-technology reading order\n   - verification claims made without a runtime or manual accessibility pass\n5. Return one recommendation path with:\n   - the documented Apple behavior being relied on\n   - the chosen accessibility surface\n   - any SwiftUI versus UIKit/AppKit bridge warning when relevant\n   - one verification expectation\n   - one handoff when the next honest step is docs lookup, Xcode testing, or broader SwiftUI architecture work\n\n## Inputs\n\n- `request`: optional free-text task description used to classify the accessibility question.\n- `scope`: optional explicit scope such as `swiftui-semantics`, `tree-shaping`, `bridge-guidance`, `review`, or `verification`.\n- `platform_context`: optional platform emphasis such as `ios`, `ipados`, `macos`, `watchos`, `tvos`, or `mixed-apple`.\n- `framework_context`: optional explicit framework emphasis such as `swiftui`, `uikit`, `appkit`, or `swiftui-with-bridge`.\n- Defaults:\n  - docs-first guidance always applies\n  - SwiftUI is the primary path in the first version\n  - UIKit and AppKit stay in scope when they materially affect accessibility behavior or representable-wrapper correctness\n\n## Outputs\n\n- `status`\n  - `success`: the request belongs to this workflow and an accessibility recommendation is ready\n  - `handoff`: the request belongs to another skill after accessibility-aware classification\n  - `blocked`: the request lacks enough context to recommend an accessibility change honestly\n- `path_type`\n  - `primary`: the recommendation comes from a directly supported accessibility path\n  - `fallback`: the recommendation depends on limited framework or platform context because the request shape is underspecified\n- `output`\n  - resolved request class\n  - chosen accessibility surface\n  - documented Apple behavior relied on\n  - bridge findings when relevant\n  - verification expectation\n  - recommended skill when handing off\n  - one concise next step\n\n## Guards and Stop Conditions\n\n- Do not treat accessibility identifiers as the same thing as user-facing accessibility semantics.\n- Do not recommend accessibility modifiers that simply restate visible content unless the explicit semantic override is actually needed.\n- Do not hide meaningful content from accessibility without documenting what replaces that information.\n- Do not silently absorb XCUITest execution, simulator control, or `.xctestplan` work that belongs to `xcode-testing-workflow`.\n- Do not silently absorb broader SwiftUI app-structure work that belongs to `swiftui-app-architecture-workflow`.\n- Stop with `blocked` when the request is too vague to tell whether the problem is semantic content, tree shape, bridge behavior, or verification follow-through.\n\n## Fallbacks and Handoffs\n\n- Prefer explicit scope and framework context when the user provides them.\n- Fall back to request-text inference when the platform or framework shape is unclear.\n- Recommend `explore-apple-swift-docs` when the real need is broader Apple or Swift docs lookup.\n- Recommend `xcode-testing-workflow` when the next honest step is runtime UI verification, XCUITest mechanics, simulator or device flow, XCUI interruption handling, screenshots, or `.xctestplan` orchestration.\n- Recommend `swiftui-app-architecture-workflow` when the next honest step is app, scene, command, focus, environment, or dependency-flow architecture rather than accessibility semantics.\n\n## Customization\n\nUse `references/customization-flow.md`.\n\n`scripts/customization_config.py` exists to preserve the repo-wide customization-file contract, but the first version of this skill defines no runtime-enforced knobs.\n\nKeep the first release focused on the decision model, the documented accessibility boundary, and explicit verification expectations. If future iterations add a real deterministic need for runtime knobs, document them explicitly before letting runtime behavior depend on them.\n\n## References\n\n### Workflow References\n\n- `references/swiftui-accessibility-semantics.md`\n- `references/swiftui-accessibility-tree-shaping.md`\n- `references/framework-bridging-uikit-appkit.md`\n- `references/worked-swiftui-accessibility-examples.md`\n- `references/verification-expectations.md`\n- `references/common-accessibility-anti-patterns.md`\n- `references/customization-flow.md`\n\n### Support References\n\n- Recommend `explore-apple-swift-docs` when the user needs direct Apple-docs lookup instead of accessibility guidance.\n- Recommend `references/snippets/apple-xcode-project-core.md` when the user needs reusable Apple-project baseline policy rather than a one-off accessibility recommendation.\n\n### Script Inventory\n\n- `scripts/customization_config.py`","tags":["apple","accessibility","workflow","dev","skills","gaelic-ghost","agent-skills","apple-development","apple-docs","apple-docs-mcp","codex","codex-app"],"capabilities":["skill","source-gaelic-ghost","skill-apple-ui-accessibility-workflow","topic-agent-skills","topic-apple-development","topic-apple-docs","topic-apple-docs-mcp","topic-codex","topic-codex-app","topic-codex-cli","topic-codex-skills","topic-dash-docsets","topic-ios","topic-macos","topic-swift"],"categories":["apple-dev-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/gaelic-ghost/apple-dev-skills/apple-ui-accessibility-workflow","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add gaelic-ghost/apple-dev-skills","source_repo":"https://github.com/gaelic-ghost/apple-dev-skills","install_from":"skills.sh"}},"qualityScore":"0.453","qualityRationale":"deterministic score 0.45 from registry signals: · indexed on github topic:agent-skills · 7 github stars · SKILL.md body (7,846 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T19:13:58.067Z","embedding":null,"createdAt":"2026-05-18T13:21:10.009Z","updatedAt":"2026-05-18T19:13:58.067Z","lastSeenAt":"2026-05-18T19:13:58.067Z","tsv":"'1':334 '2':348 '3':401 '4':431 '5':503 'absorb':792,810 'access':4,9,40,42,48,60,91,144,181,191,203,214,227,233,244,280,328,345,361,373,404,421,440,450,462,501,518,560,638,656,669,681,694,717,746,756,761,782,948,989,1045,1065 'accessibility-awar':668 'accessibility-specif':243 'accessibilitychildren':208 'accessibilityel':206 'accessibilityrepresent':209 'action':164,418,479 'actual':774 'add':998 'affect':637 'alreadi':409 'alway':617 'anoth':665 'anti':435 'anti-pattern':434 'app':112,306,316,814,822,927,936 'app-structur':111,813 'appkit':21,77,232,606,630 'appl':2,7,38,46,58,105,154,259,265,273,351,360,376,391,511,595,720,883,892,1031,1040,1055 'apple-doc':104,1039 'apple-project':1054 'apple-ui-accessibility-workflow':1 'appli':349,618 'architectur':307,546,823,928,945 'assist':489 'assistive-technolog':488 'autom':296 'awar':670 'back':866 'baselin':1057 'becom':290 'begin':235 'behavior':92,168,367,512,639,721,845,1012 'belong':650,663,801,818 'block':672,827 'boundari':990 'bridg':22,78,343,427,524,575,611,724,844 'bridge-guid':574 'broader':544,811,891 'chang':356,682 'chart':139 'check':432 'children':207 'choos':402 'chosen':517,716 'claim':494 'class':715 'classif':671 'classifi':335,558 'code':17,82,381 'come':689 'command':320,938 'composit':141 'concis':736 'condit':742 'configur':298 'conflict':387 'content':215,459,767,780,841 'context':457,581,597,677,705,859 'contract':964 'contrast':254 'control':136,467,796 'correct':644 'cover':73 'current':380 'custom':466,950,962 'customization-fil':961 'data':324 'decid':177 'decis':985 'default':180,406,612 'defin':972 'depend':699,943,1013 'dependency-flow':942 'descript':412,555 'determinist':1001 'devic':295,915 'direct':692,1038 'disagre':382 'doc':54,106,267,352,377,392,539,614,885,895,1033,1041 'docs-first':53,613 'document':276,362,366,510,719,784,988,1006 'dynam':252 'emphasi':584,601 'enforc':976 'enough':676 'environ':940 'execut':119,292,794 'exist':954 'expect':27,247,530,729,994 'explicit':25,190,398,411,415,564,599,770,855,992,1008 'explor':264,882,1030 'explore-apple-swift-doc':263,881,1029 'expos':474 'face':449,755 'fall':865 'fallback':696,851 'file':963 'final':438 'find':725 'first':16,55,66,70,363,615,626,967,980 'flow':325,916,944 'focus':250,939,982 'follow':849 'follow-through':848 'form':138 'found':395 'framework':99,596,600,702,858,876 'free':552 'free-text':551 'futur':996 'gate':353 'general':323 'give':372 'group':167 'guard':739 'guid':6 'guidanc':23,281,344,374,439,576,616,1046 'hand':733 'handl':919 'handoff':30,532,660,853 'head':165 'help':36,131,152,176,200,223 'hidden':460 'hide':210,778 'hint':161 'honest':536,683,905,933 'identifi':441,747 'implement':10,61,339 'infer':871 'inform':788 'input':548 'instead':1043 'interact':470 'interrupt':918 'inventori':1068 'io':587 'ipado':588 'iter':997 'keep':64,978 'knob':977,1005 'label':159,451 'lack':675 'let':1010 'limit':701 'list':137 'look':469 'lookup':277,540,896,1042 'maco':589 'made':495 'make':37,94,132 'manual':500 'materi':636 'meaning':458,779 'mechan':912 'mix':594 'mixed-appl':593 'model':986 'modifi':192,762 'motion':256 'nativ':86 'need':189,272,414,420,425,430,775,889,1002,1037,1052 'next':535,737,904,932 'one':505,528,531,735,1063 'one-off':1062 'option':550,563,582,598 'orchestr':923 'order':251,481,492 'output':645,712 'overrid':772 'ownership':319,321 'pass':502 'path':332,507,623,684,695 'pattern':436 'plan':347 'platform':85,260,580,583,704,874 'platform-n':84 'plus':24 'polici':1058 'prefer':854 'preserv':956 'primari':622,686 'primarili':271 'problem':838 'proceed':400 'produc':485 'project':1056 'provid':51,863 'purpos':50 'question':311,561 'rather':278,326,946,1059 'read':357,491 'readi':659 'real':888,1000 'realli':313 'recommend':262,282,303,355,506,657,679,688,698,730,760,880,897,924,1028,1047,1066 'reduc':255 'redund':453 'refer':1016,1018,1027 'references/common-accessibility-anti-patterns.md':1024 'references/customization-flow.md':952,1025 'references/framework-bridging-uikit-appkit.md':1021 'references/snippets/apple-xcode-project-core.md':1048 'references/swiftui-accessibility-semantics.md':1019 'references/swiftui-accessibility-tree-shaping.md':1020 'references/verification-expectations.md':1023 'references/worked-swiftui-accessibility-examples.md':1022 'relat':258 'releas':981 'relev':359,390,527,727 'reli':369,514,722 'repeat':454 'replac':465,786 'repo':959 'repo-wid':958 'represent':642 'representable-wrapp':641 'request':337,549,649,662,674,708,714,830,869 'request-text':868 'reshap':423 'resolv':713 'respons':234 'restat':765 'return':504 'reusabl':1053 'review':12,41,63,153,341,577 'right':476 'role':162,477 'router':107 'rule':211 'runtim':300,498,908,975,1004,1011 'runtime-enforc':974 'sane':487 'say':396 'scene':318,937 'scope':562,565,633,856 'screenshot':920 'script':1067 'scripts/customization_config.py':953,1069 'semant':43,156,329,407,570,757,771,840,949 'sens':95 'set':261 'shape':44,201,573,709,843,877 'silent':791,809 'simpli':764 'simul':293,795,913 'singl':331 'single-path':330 'skill':126,147,171,195,218,238,666,731,971 'skill-apple-ui-accessibility-workflow' 'solv':446 'source-gaelic-ghost' 'specif':245 'state':364 'status':646 'stay':631 'step':537,738,906,934 'still':72 'stop':228,383,741,825 'structur':113,317,815 'success':647 'suffici':184,410 'support':693,1026 'surfac':79,385,405,519,718 'surround':455 'swift':266,275,884,894,1032 'swiftui':15,69,81,110,134,226,305,315,338,340,521,545,569,604,609,619,812,821,926 'swiftui-app-architecture-workflow':304,820,925 'swiftui-first':14,68 'swiftui-semant':568 'swiftui-with-bridg':608 'synthet':213 'task':554 'technolog':490 'tell':835 'test':29,285,542,805,900 'text':553,870 'thing':751 'topic-agent-skills' 'topic-apple-development' 'topic-apple-docs' 'topic-apple-docs-mcp' 'topic-codex' 'topic-codex-app' 'topic-codex-cli' 'topic-codex-skills' 'topic-dash-docsets' 'topic-ios' 'topic-macos' 'topic-swift' 'trait':163,416 'treat':442,745 'tree':182,204,422,572,842 'tree-shap':571 'tvos':591 'type':253,685 'ui':3,8,39,47,59,142,155,301,909 'uikit':19,75,230,605,628 'uikit/appkit':342,426,523 'unclear':879 'under':98 'underspecifi':711 'understand':224 'unless':768 'use':31,123,124,145,169,193,216,236,556,951 'user':34,129,150,174,198,221,241,270,448,754,862,1036,1051 'user-fac':447,753 'vagu':833 'valu':160 'verif':26,246,302,346,493,529,579,728,847,910,993 'version':67,627,968 'versus':522 'view':87,135,188 'visibl':456,766 'visual':480 'voiceov':249 'want':35,130,151,175,199,222,242 'warn':525 'watcho':590 'whether':178,186,836 'wide':960 'without':463,496,783 'work':289,428,547,799,816 'workflow':5,49,56,114,120,286,308,333,653,806,824,901,929,1017 'wrap':83 'wrapper':643 'xcode':118,284,541,804,899 'xcode-testing-workflow':283,803,898 'xctestplan':297,798,922 'xcui':917 'xcuitest':291,793,911","prices":[{"id":"fd5768fe-eb5a-4698-a021-77d35ccc3a95","listingId":"fdc34134-c46b-42af-855b-ea0a31a2fcea","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"gaelic-ghost","category":"apple-dev-skills","install_from":"skills.sh"},"createdAt":"2026-05-18T13:21:10.009Z"}],"sources":[{"listingId":"fdc34134-c46b-42af-855b-ea0a31a2fcea","source":"github","sourceId":"gaelic-ghost/apple-dev-skills/apple-ui-accessibility-workflow","sourceUrl":"https://github.com/gaelic-ghost/apple-dev-skills/tree/main/skills/apple-ui-accessibility-workflow","isPrimary":false,"firstSeenAt":"2026-05-18T13:21:10.009Z","lastSeenAt":"2026-05-18T19:13:58.067Z"}],"details":{"listingId":"fdc34134-c46b-42af-855b-ea0a31a2fcea","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"gaelic-ghost","slug":"apple-ui-accessibility-workflow","github":{"repo":"gaelic-ghost/apple-dev-skills","stars":7,"topics":["agent-skills","apple-development","apple-docs","apple-docs-mcp","codex","codex-app","codex-cli","codex-skills","dash-docsets","ios","macos","swift","swift-package-manager","swift-toolchain","swiftly","swiftpm","xcode","xcode-mcp","xcodebuild","xcrun"],"license":"apache-2.0","html_url":"https://github.com/gaelic-ghost/apple-dev-skills","pushed_at":"2026-05-13T01:26:51Z","description":"Apple Dev Workflows for Codex | Now Available in Socket Marketplace","skill_md_sha":"57ec6b7797e55957c0d3ca713f22f9bcf2f0499b","skill_md_path":"skills/apple-ui-accessibility-workflow/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/gaelic-ghost/apple-dev-skills/tree/main/skills/apple-ui-accessibility-workflow"},"layout":"multi","source":"github","category":"apple-dev-skills","frontmatter":{"name":"apple-ui-accessibility-workflow","description":"Guide Apple UI accessibility implementation and review for SwiftUI-first code, with UIKit and AppKit bridge guidance plus explicit verification expectations and testing handoffs. Use when the user wants help making Apple UI accessible, reviewing accessibility semantics, shaping the accessibility tree, or planning Apple-platform accessibility verification without collapsing the work into generic design review or Xcode test execution."},"skills_sh_url":"https://skills.sh/gaelic-ghost/apple-dev-skills/apple-ui-accessibility-workflow"},"updatedAt":"2026-05-18T19:13:58.067Z"}}