{"id":"66a19190-f2d4-45a6-96e8-de62925638b1","shortId":"3speJW","kind":"skill","title":"swift-api-design-guidelines","tagline":"Apply Swift API Design Guidelines to name, label, and document Swift APIs. Covers argument label rules (prepositional phrase rule, grammatical phrase rule, first-label omission), mutating/nonmutating pair naming (-ed/-ing participle pattern, form- prefix, sort/sorted, formUnion/u","description":"# Swift API Design Guidelines\n\nApply the Swift API Design Guidelines when naming types, methods, properties, parameters, and argument labels. Targets Swift 6.3. For language features and syntax, see `swift-language`. For concurrency patterns, see `swift-concurrency`.\n\n## Contents\n\n- [Argument Label Rules](#argument-label-rules)\n- [Side-Effect Naming](#side-effect-naming)\n- [Mutating and Nonmutating Pairs](#mutating-and-nonmutating-pairs)\n- [Documentation Comments](#documentation-comments)\n- [Clarity and Naming](#clarity-and-naming)\n- [Fluent Usage and Protocols](#fluent-usage-and-protocols)\n- [General Conventions](#general-conventions)\n- [Common Mistakes](#common-mistakes)\n- [Review Checklist](#review-checklist)\n- [References](#references)\n\n## Argument Label Rules\n\nArgument labels determine how a call site reads. Apply these rules in order.\n\n### When to omit the first argument label\n\n**Grammatical phrase rule.** When the first argument forms a grammatical phrase with the base name, omit the label. Move any leading words from what would be the label into the base name instead.\n\n```swift\n// GOOD — reads as \"add subview y\"\nview.addSubview(y)\n\n// BAD — redundant label breaks the phrase\nview.add(subview: y)\n```\n\n**Value-preserving type conversions.** When an initializer performs a value-preserving (widening) conversion, omit the first argument label.\n\n```swift\n// GOOD — widening conversion, no label\nlet value = Int64(someUInt32)\nlet str = String(someCharacter)\n\n// Narrowing or lossy conversions keep a label\nlet approx = Int64(truncating: someDecimal)\nlet str = String(describing: someObject)\n```\n\n**Indistinguishable arguments.** When all arguments cannot be usefully distinguished, omit all labels.\n\n```swift\n// GOOD — arguments are peers\nlet smaller = min(x, y)\nzip(sequence1, sequence2)\n```\n\n### When to use a prepositional label\n\n**Prepositional phrase rule.** When the first argument completes a prepositional phrase with the base name, label it with the preposition.\n\n```swift\n// GOOD — \"remove boxes having length 12\"\nx.removeBoxes(havingLength: 12)\n\n// GOOD — \"fade from red\"\nview.fade(from: red)\n\n// GOOD — \"relative path from root\"\npath.relativePath(from: root)\n```\n\n**Exception — abstraction boundary.** When the first two arguments represent parts of a single abstraction, fold the preposition into the base name so each component gets its own label.\n\n```swift\n// GOOD — x and y are parts of a single abstraction (a point)\na.moveTo(x: b, y: c)\n\n// BAD — preposition attaches to first arg, leaving y unlabeled\na.move(toX: b, y: c)\n```\n\n### Default: label everything else\n\nWhen no special rule above applies, label the argument.\n\n```swift\n// GOOD\narray.split(maxSplits: 2)\nbutton.setTitle(\"OK\", for: .normal)\ncontroller.dismiss(animated: true)\narray.sorted(by: >)\n```\n\n### Argument label decision table\n\n| Situation | Rule | Example |\n|-----------|------|---------|\n| First arg completes grammatical phrase | Omit label, merge words into base name | `addSubview(y)` |\n| Value-preserving init conversion | Omit first label | `Int64(someUInt32)` |\n| Arguments are indistinguishable peers | Omit all labels | `min(x, y)` |\n| First arg completes prepositional phrase | Label with preposition | `fade(from: red)` |\n| First two args form a single abstraction | Fold preposition into base name | `moveTo(x: b, y: c)` |\n| Everything else | Label it | `split(maxSplits: 2)` |\n\nFor extended examples and edge cases, see [references/argument-labels-and-parameters.md](references/argument-labels-and-parameters.md).\n\n## Side-Effect Naming\n\nName functions and methods by their side effects.\n\n### Functions with side effects — imperative verbs\n\nWhen a function mutates state, name it as an imperative verb phrase.\n\n```swift\n// Mutates — imperative verb\narray.sort()\narray.append(newElement)\nlist.remove(at: index)\ntimer.invalidate()\n```\n\n### Functions without side effects — nouns or adjective phrases\n\nWhen a function returns a result without mutating anything, name it as a noun phrase, adjective phrase, or read as a description of what it returns.\n\n```swift\n// Pure — noun/description\nlet d = point.distance(to: origin)\nlet area = rect.intersection(other)\nlet line = text.trimmingCharacters(in: .whitespaces)\n```\n\n### Boolean properties and methods\n\nBoolean properties and methods read as assertions about the receiver.\n\n```swift\n// GOOD — reads as \"line is empty\"\nline.isEmpty\nset.contains(element)\nurl.isFileURL\n\n// BAD — not an assertion\nline.empty       // verb? adjective?\nset.includes     // incomplete phrase\n```\n\nFor more examples, see [references/side-effects-and-mutating-pairs.md](references/side-effects-and-mutating-pairs.md).\n\n## Mutating and Nonmutating Pairs\n\nWhen an operation has both mutating and nonmutating variants, name them as a pair.\n\n### Verb-described operations — -ed/-ing suffix\n\nWhen the operation is naturally described by a verb:\n- **Mutating:** imperative verb (`sort`, `append`, `reverse`)\n- **Nonmutating:** past participle `-ed` or present participle `-ing`\n\nDefault to `-ed` (past participle). When `-ed` is ungrammatical — typically when the verb does not form a natural past participle, or when adding `-ed` produces an awkward phrase — use `-ing` (present participle) instead.\n\n| Mutating | Nonmutating | Why |\n|----------|-------------|-----|\n| `sort()` | `sorted()` | `-ed` — \"a sorted array\" |\n| `reverse()` | `reversed()` | `-ed` — \"a reversed collection\" |\n| `append(y)` | `appending(y)` | `-ing` — \"appended\" is ungrammatical here |\n| `stripNewlines()` | `strippingNewlines()` | `-ing` — \"stripped newlines\" is awkward |\n\n### Noun-described operations — form- prefix\n\nWhen the operation is naturally described by a noun:\n- **Nonmutating:** the noun itself (`union`, `intersection`)\n- **Mutating:** `form` prefix (`formUnion`, `formIntersection`)\n\n```swift\n// Nonmutating — returns new value\nlet combined = a.union(b)\n\n// Mutating — modifies in place\na.formUnion(b)\n```\n\n### Factory methods — make- prefix\n\nFactory methods that create a new value start with `make`.\n\n```swift\nlet iterator = collection.makeIterator()\nlet buffer = parser.makeBuffer()\n```\n\n### Pair decision table\n\n| Operation described by | Mutating name | Nonmutating name | Example pair |\n|------------------------|---------------|-------------------|-------------|\n| Verb (default) | verb | verb + `-ed` | `sort()` / `sorted()` |\n| Verb (`-ed` is ungrammatical) | verb | verb + `-ing` | `stripNewlines()` / `strippingNewlines()` |\n| Noun | `form` + Noun | noun | `formUnion(b)` / `union(b)` |\n\nFor the full -ed/-ing decision tree and stdlib examples, see [references/side-effects-and-mutating-pairs.md](references/side-effects-and-mutating-pairs.md).\n\n## Documentation Comments\n\nEvery public declaration must have a documentation comment.\n\n### Summary rules by declaration kind\n\n| Declaration | Summary describes |\n|-------------|-------------------|\n| Function / method | What it does and what it returns |\n| Subscript | What it accesses |\n| Initializer | What it creates |\n| Type / property / variable | What it **is** |\n\nWrite summaries as a single sentence fragment, beginning with a verb (for actions) or a noun phrase (for entities), ending in a period.\n\n```swift\n/// Returns the element at the specified index.\nfunc element(at index: Int) -> Element { ... }\n\n/// The number of elements in the collection.\nvar count: Int { ... }\n\n/// Creates a new array with the given elements.\ninit(_ elements: some Sequence<Element>) { ... }\n\n/// Accesses the element at the specified position.\nsubscript(index: Int) -> Element { ... }\n```\n\n### Symbol markup\n\nUse standard symbol markup after the summary when relevant:\n\n- `- Parameter name:` for individual parameters\n- `- Parameters:` block for multiple parameters\n- `- Returns:` for the return value\n- `- Throws:` for errors thrown\n- `- Complexity:` for algorithmic complexity\n\n```swift\n/// Removes and returns the element at the specified position.\n///\n/// - Parameter index: The position of the element to remove.\n/// - Returns: The removed element.\n/// - Complexity: O(*n*), where *n* is the length of the collection.\nmutating func remove(at index: Int) -> Element { ... }\n```\n\n### O(1) complexity rule\n\nDocument the complexity of any computed property that is not O(1). Callers assume properties are O(1) by default. If a property does more than constant-time work, state the complexity explicitly.\n\n```swift\n/// The total weight of all items.\n///\n/// - Complexity: O(*n*), where *n* is the number of items.\nvar totalWeight: Double {\n    items.reduce(0) { $0 + $1.weight }\n}\n```\n\nFor documentation patterns and examples, see [references/conventions-and-special-rules.md](references/conventions-and-special-rules.md).\n\n## Clarity and Naming\n\nClarity at the point of use is the most important goal. Every design decision serves the person reading a call site.\n\n**Clarity over brevity.** Longer names are acceptable when they remove ambiguity. Do not abbreviate.\n\n```swift\n// GOOD\nemployees.remove(at: position)\n\n// BAD — ambiguous: remove the element? remove at position?\nemployees.remove(position)\n```\n\n**Include words needed to avoid ambiguity.** If omitting a word makes the call site unclear, keep it.\n\n```swift\n// GOOD — \"at\" clarifies the argument's role\nfriends.remove(at: index)\n\n// BAD — is \"index\" the element to remove or the position?\nfriends.remove(index)\n```\n\n**Omit needless words.** Do not repeat type information already available from the context.\n\n```swift\n// GOOD\nallViews.remove(cancelButton)\n\n// BAD — \"Element\" repeats the type\nallViews.removeElement(cancelButton)\n```\n\n**Name variables and parameters by role, not type.** Use the entity's role in the current context, not its type name.\n\n```swift\n// GOOD — describes the role\nvar greeting: String\nfunc add(_ observer: NSObject, for keyPath: String)\n\n// BAD — names the type\nvar string: String\nfunc add(_ object: NSObject, for string: String)\n```\n\n**Compensate for weak type information.** When a parameter type is `Any`, `AnyObject`, or a fundamental type like `Int` or `String`, add role-clarifying words to the name.\n\n```swift\n// GOOD — role is clear despite weak types\nfunc addObserver(_ observer: NSObject, forKeyPath path: String)\n\n// BAD — what does \"string\" mean here?\nfunc add(_ object: NSObject, for string: String)\n```\n\nFor extended naming examples and patterns, see [references/naming-and-clarity.md](references/naming-and-clarity.md).\n\n## Fluent Usage and Protocols\n\n**Call sites read as grammatical English.** Prefer names that form grammatical phrases at the point of use.\n\n```swift\n// GOOD — reads fluently\nx.insert(y, at: z)          // \"x, insert y at z\"\nx.subviews.remove(at: i)    // \"x's subviews, remove at i\"\nx.makeIterator()             // \"x, make iterator\"\n\n// BAD — ungrammatical\nx.insert(y, position: z)\nx.subviews.remove(i)\n```\n\n**Initializer first argument.** The first argument to an initializer should not form a phrase continuing the type name.\n\n```swift\n// GOOD\nlet foreground = Color(red: 32, green: 64, blue: 128)\n\n// BAD — \"Color with red\" reads awkwardly\nlet foreground = Color(havingRGBValuesRed: 32, green: 64, blue: 128)\n```\n\n**Protocol naming conventions:**\n\n| Protocol describes | Naming pattern | Examples |\n|--------------------|----------------|----------|\n| What something **is** | Noun | `Collection`, `IteratorProtocol` |\n| A **capability** | `-able`, `-ible`, or `-ing` suffix | `Equatable`, `Hashable`, `Sendable` |\n\n## General Conventions\n\n**Casing.** Types and protocols use `UpperCamelCase`. Everything else uses `lowerCamelCase`. Acronyms that are commonly all-caps in American English appear uniformly upper- or lower-cased based on position.\n\n```swift\nvar utf8Bytes: [UTF8.CodeUnit]\nvar isRepresentableAsASCII = true\nvar userSMTPServer: SMTPServer\n```\n\n**Methods and properties over free functions.** Prefer methods and properties. Use free functions only when:\n1. There is no obvious `self` — `min(x, y)`\n2. The function is an unconstrained generic — `print(value)`\n3. The function syntax is established domain notation — `sin(x)`\n\n**Default arguments over method families.** Prefer a single method with default parameters over a family of methods that differ only in which parameters they accept. Place defaulted parameters at the end. Parameters with default values should always have argument labels — defaulted parameters are usually omitted at call sites, so their labels must be clear when they do appear.\n\n```swift\n// GOOD — labeled with defaults\nfunc decode(_ data: Data, encoding: String.Encoding = .utf8) -> String?\n\n// BAD — method family\nfunc decode(_ data: Data) -> String?\nfunc decode(_ data: Data, encoding: String.Encoding) -> String?\n```\n\n**Overload safety.** Methods may share a base name when they operate in different type domains or when their meaning is clear from context. Avoid return-type-only overloads that cause ambiguity at the call site.\n\nFor casing edge cases, overload patterns, and tuple/closure naming, see [references/conventions-and-special-rules.md](references/conventions-and-special-rules.md).\n\n## Common Mistakes\n\n1. **Omitting needed argument labels.** Using `remove(position)` instead of `remove(at: position)` when the role of the argument is ambiguous without the label.\n\n2. **Using -ed when -ing is correct.** Applying `stripped()` when the past participle is ungrammatical — use `stripping()` instead. Test: does \"a [verb]-ed [noun]\" read naturally?\n\n3. **Using verb names for side-effect-free operations.** Naming a nonmutating method `sort()` that returns a new collection — use `sorted()` to signal no mutation.\n\n4. **Naming by type instead of role.** Using `string` instead of `greeting`, or `array` instead of `elements`, when the role would be more informative.\n\n5. **Missing documentation comments.** Leaving public declarations undocumented, or writing summaries that describe the implementation rather than the purpose.\n\n6. **Not documenting non-O(1) computed properties.** Exposing a linear-time computed property without a `Complexity:` note, causing callers to assume O(1) and use it in loops.\n\n7. **Applying form- prefix to verb-based operations.** Writing `formSort()` instead of just `sort()` — the `form` prefix is only for noun-based operations (`formUnion`).\n\n8. **Factory methods without make- prefix.** Naming factory methods as `createIterator()` or `buildBuffer()` instead of `makeIterator()` and `makeBuffer()`.\n\n9. **Repeating type information in names.** Writing `removeElement(cancelButton)` or `stringValue: String` when the type is already evident from context.\n\n10. **Return-type-only overloads.** Defining overloads that differ only in return type, creating ambiguity when the compiler cannot infer the expected type.\n\n11. **Unlabeled tuple members and closure parameters.** Exposing tuples or closures in public API without naming their components, forcing callers to use positional access.\n\n## Review Checklist\n\n### Argument Labels\n- [ ] First argument follows the correct label rule (grammatical phrase, prepositional, conversion, or labeled)\n- [ ] Prepositional labels do not incorrectly group independent arguments\n- [ ] Value-preserving conversion initializers omit the first label\n- [ ] All non-special-case arguments have labels\n\n### Naming Semantics\n- [ ] Mutating methods use imperative verb form\n- [ ] Nonmutating methods use -ed/-ing or noun form\n- [ ] Mutating/nonmutating pairs follow the correct pattern (verb pair or noun/form-noun pair)\n- [ ] Boolean properties read as assertions (`isEmpty`, `isValid`, `contains`)\n- [ ] Variables and parameters are named by role, not type\n\n### Documentation\n- [ ] Every public declaration has a doc comment\n- [ ] Summaries are single sentence fragments ending in a period\n- [ ] Summaries describe the correct thing per declaration kind (action, access, creation, entity)\n- [ ] Non-O(1) computed properties document their complexity\n- [ ] Parameters, return values, and thrown errors are documented with symbol markup\n\n### Conventions\n- [ ] Types and protocols use UpperCamelCase; everything else uses lowerCamelCase\n- [ ] Acronyms are uniformly cased based on position\n- [ ] Default arguments are preferred over method families\n- [ ] Overloads do not differ only in return type\n- [ ] Protocol names follow the noun (is-a) or suffix (capability) convention\n\n## References\n\n- Naming clarity, role-based naming, weak-type compensation, and terminology: [references/naming-and-clarity.md](references/naming-and-clarity.md)\n- Argument label edge cases, parameter naming, and default argument strategy: [references/argument-labels-and-parameters.md](references/argument-labels-and-parameters.md)\n- Side-effect naming examples, -ed/-ing decision tree, form- prefix patterns, and factory methods: [references/side-effects-and-mutating-pairs.md](references/side-effects-and-mutating-pairs.md)\n- Casing edge cases, complexity documentation, overload safety, tuple/closure naming, and free function exceptions: [references/conventions-and-special-rules.md](references/conventions-and-special-rules.md)","tags":["swift","api","design","guidelines","ios","skills","dpearson2699","accessibility","agent-skills","ai-coding","apple","claude-code"],"capabilities":["skill","source-dpearson2699","skill-swift-api-design-guidelines","topic-accessibility","topic-agent-skills","topic-ai-coding","topic-apple","topic-claude-code","topic-codex-skills","topic-cursor-skills","topic-ios","topic-ios-development","topic-liquid-glass","topic-localization","topic-mapkit"],"categories":["swift-ios-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/dpearson2699/swift-ios-skills/swift-api-design-guidelines","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add dpearson2699/swift-ios-skills","source_repo":"https://github.com/dpearson2699/swift-ios-skills","install_from":"skills.sh"}},"qualityScore":"0.700","qualityRationale":"deterministic score 0.70 from registry signals: · indexed on github topic:agent-skills · 599 github stars · SKILL.md body (17,032 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-18T18:53:44.492Z","embedding":null,"createdAt":"2026-04-22T12:53:47.434Z","updatedAt":"2026-05-18T18:53:44.492Z","lastSeenAt":"2026-05-18T18:53:44.492Z","tsv":"'0':1118,1119 '1':1060,1074,1080,1541,1705,1830,1849,2085 '1.weight':1120 '10':1919 '11':1943 '12':326,329 '128':1444,1459 '2':422,507,1550,1729 '3':1559,1755 '32':1440,1455 '4':1781 '5':1805 '6':1824 '6.3':64 '64':1442,1457 '7':1855 '8':1881 '9':1899 'a.formunion':801 'a.move':400 'a.moveto':386 'a.union':795 'abbrevi':1166 'abl':1476 'abstract':346,358,383,490 'accept':1159,1593 'access':903,973,1966,2079 'acronym':1496,2112 'action':926,2078 'ad':720 'add':204,1276,1290,1316,1346 'addobserv':1333 'addsubview':451 'adject':564,581,640 'algorithm':1016 'all-cap':1500 'allviews.remove':1237 'allviews.removeelement':1244 'alreadi':1230,1915 'alway':1605 'ambigu':1163,1173,1187,1686,1725,1934 'american':1504 'anim':428 'anyobject':1307 'anyth':574 'api':3,8,17,44,50,1956 'appear':1506,1626 'append':688,746,748,751 'appli':6,47,155,414,1736,1856 'approx':260 'area':601 'arg':396,440,474,486 'argument':19,60,82,86,144,147,165,173,236,270,273,283,306,352,417,432,463,1204,1418,1421,1570,1607,1708,1723,1969,1972,1991,2006,2120,2161,2169 'argument-label-rul':85 'array':739,964,1794 'array.append':552 'array.sort':551 'array.sorted':430 'array.split':420 'assert':619,637,2040 'assum':1076,1847 'attach':393 'avail':1231 'avoid':1186,1678 'awkward':724,761,1450 'b':388,402,498,796,802,857,859 'bad':209,391,634,1172,1210,1239,1282,1339,1408,1445,1640 'base':180,197,313,364,449,494,1513,1661,1862,1878,2116,2151 'begin':921 'block':1001 'blue':1443,1458 'boolean':609,613,2036 'boundari':347 'box':323 'break':212 'breviti':1155 'buffer':822 'buildbuff':1893 'button.settitle':423 'c':390,404,500 'call':152,1151,1194,1365,1615,1689 'caller':1075,1845,1962 'cancelbutton':1238,1245,1907 'cannot':274,1938 'cap':1502 'capabl':1475,2144 'case':513,1486,1512,1692,1694,2005,2115,2164,2190,2192 'caus':1685,1844 'checklist':138,141,1968 'clarifi':1202,1319 'clariti':111,115,1129,1132,1153,2148 'clarity-and-nam':114 'clear':1328,1622,1675 'closur':1948,1953 'collect':745,957,1051,1472,1774 'collection.makeiterator':820 'color':1438,1446,1453 'combin':794 'comment':107,110,874,882,1808,2060 'common':132,135,1499,1703 'common-mistak':134 'compens':1296,2156 'compil':1937 'complet':307,441,475 'complex':1014,1017,1041,1061,1065,1095,1104,1842,2090,2193 'compon':368,1960 'comput':1068,1831,1838,2086 'concurr':75,80 'constant':1090 'constant-tim':1089 'contain':2043 'content':81 'context':1234,1262,1677,1918 'continu':1430 'controller.dismiss':427 'convent':128,131,1462,1485,2102,2145 'convers':222,232,241,255,457,1981,1995 'correct':1735,1975,2029,2073 'count':959 'cover':18 'creat':810,907,961,1933 'createiter':1891 'creation':2080 'current':1261 'd':596 'data':1634,1635,1645,1646,1650,1651 'decis':434,825,865,1145,2180 'declar':877,886,888,1811,2056,2076 'decod':1633,1644,1649 'default':405,698,837,1082,1569,1579,1595,1602,1609,1631,2119,2168 'defin':1925 'describ':267,670,680,764,773,828,890,1269,1464,1817,2071 'descript':587 'design':4,9,45,51,1144 'despit':1329 'determin':149 'differ':1587,1667,1928,2129 'distinguish':277 'doc':2059 'document':15,106,109,873,881,1063,1122,1807,1826,2053,2088,2098,2194 'documentation-com':108 'domain':1565,1669 'doubl':1116 'ed':35,672,693,700,704,721,736,742,840,844,863,1731,1751,2020,2178 'edg':512,1693,2163,2191 'effect':91,95,519,528,532,561,1762,2175 'element':632,940,946,950,954,968,970,975,983,1023,1034,1040,1058,1176,1214,1240,1797 'els':408,502,1493,2109 'employees.remove':1169,1180 'empti':629 'encod':1636,1652 'end':933,1599,2066 'english':1370,1505 'entiti':932,1256,2081 'equat':1481 'error':1012,2096 'establish':1564 'everi':875,1143,2054 'everyth':407,501,1492,2108 'evid':1916 'exampl':438,510,646,834,869,1125,1355,1467,2177 'except':345,2202 'expect':1941 'explicit':1096 'expos':1833,1950 'extend':509,1353 'factori':803,807,1882,1888,2186 'fade':331,481 'famili':1573,1583,1642,2125 'featur':67 'first':29,164,172,235,305,350,395,439,459,473,484,1417,1420,1971,1999 'first-label':28 'fluent':118,123,1361 'fluent-usage-and-protocol':122 'fluentli':1385 'fold':359,491 'follow':1973,2027,2136 'forc':1961 'foreground':1437,1452 'forkeypath':1336 'form':39,174,487,713,766,784,853,1374,1427,1857,1871,2016,2024,2182 'formintersect':787 'formsort':1865 'formunion':786,856,1880 'formunion/u':42 'fragment':920,2065 'free':1530,1537,1763,2200 'friends.remove':1207,1220 'full':862 'func':945,1053,1275,1289,1332,1345,1632,1643,1648 'function':522,529,537,558,568,891,1531,1538,1552,1561,2201 'fundament':1310 'general':127,130,1484 'general-convent':129 'generic':1556 'get':369 'given':967 'goal':1142 'good':201,239,282,321,330,337,374,419,624,1168,1200,1236,1268,1325,1383,1435,1628 'grammat':25,167,176,442,1369,1375,1978 'green':1441,1456 'greet':1273,1792 'group':1989 'guidelin':5,10,46,52 'hashabl':1482 'havinglength':328 'havingrgbvaluesr':1454 'ibl':1477 'imper':533,544,549,685,2014 'implement':1819 'import':1141 'includ':1182 'incomplet':642 'incorrect':1988 'independ':1990 'index':556,944,948,981,1029,1056,1209,1212,1221 'indistinguish':269,465 'individu':998 'infer':1939 'inform':1229,1300,1804,1902 'ing':36,673,697,727,750,757,849,864,1479,1733,2021,2179 'init':456,969 'initi':225,904,1416,1424,1996 'insert':1391 'instead':199,730,1713,1746,1785,1790,1795,1866,1894 'int':949,960,982,1057,1313 'int64':246,261,461 'intersect':782 'is-a':2139 'isempti':2041 'isrepresentableasascii':1521 'isvalid':2042 'item':1103,1113 'items.reduce':1117 'iter':819,1407 'iteratorprotocol':1473 'keep':256,1197 'keypath':1280 'kind':887,2077 'label':13,20,30,61,83,87,145,148,166,184,194,211,237,243,258,280,299,315,372,406,415,433,445,460,469,478,503,1608,1619,1629,1709,1728,1970,1976,1983,1985,2000,2008,2162 'languag':66,73 'lead':187 'leav':397,1809 'length':325,1048 'let':244,248,259,264,286,595,600,604,793,818,821,1436,1451 'like':1312 'line':605,627 'line.empty':638 'line.isempty':630 'linear':1836 'linear-tim':1835 'list.remove':554 'longer':1156 'loop':1854 'lossi':254 'lower':1511 'lower-cas':1510 'lowercamelcas':1495,2111 'make':805,816,1192,1406,1885 'makebuff':1898 'makeiter':1896 'markup':985,989,2101 'maxsplit':421,506 'may':1658 'mean':1343,1673 'member':1946 'merg':446 'method':56,524,612,616,804,808,892,1526,1533,1572,1577,1585,1641,1657,1768,1883,1889,2012,2018,2124,2187 'min':288,470,1547 'miss':1806 'mistak':133,136,1704 'modifi':798 'move':185 'moveto':496 'multipl':1003 'must':878,1620 'mutat':97,102,538,548,573,650,659,684,731,783,797,830,1052,1780,2011 'mutating-and-nonmutating-pair':101 'mutating/nonmutating':32,2025 'n':1043,1045,1106,1108 'name':12,34,54,92,96,113,117,181,198,314,365,450,495,520,521,540,575,663,831,833,996,1131,1157,1246,1266,1283,1323,1354,1372,1433,1461,1465,1662,1699,1758,1765,1782,1887,1904,1958,2009,2048,2135,2147,2152,2166,2176,2198 'narrow':252 'natur':679,715,772,1754 'need':1184,1707 'needless':1223 'new':791,812,963,1773 'newel':553 'newlin':759 'non':1828,2003,2083 'non-o':1827,2082 'non-special-cas':2002 'nonmut':99,104,652,661,690,732,777,789,832,1767,2017 'normal':426 'notat':1566 'note':1843 'noun':562,579,763,776,779,852,854,855,929,1471,1752,1877,2023,2138 'noun-bas':1876 'noun-describ':762 'noun/description':594 'noun/form-noun':2034 'nsobject':1278,1292,1335,1348 'number':952,1111 'o':1042,1059,1073,1079,1105,1829,1848,2084 'object':1291,1347 'observ':1277,1334 'obvious':1545 'ok':424 'omiss':31 'omit':162,182,233,278,444,458,467,1189,1222,1613,1706,1997 'oper':656,671,677,765,770,827,1665,1764,1863,1879 'order':159 'origin':599 'overload':1655,1683,1695,1924,1926,2126,2195 'pair':33,100,105,653,667,824,835,2026,2032,2035 'paramet':58,995,999,1000,1004,1028,1249,1303,1580,1591,1596,1600,1610,1949,2046,2091,2165 'parser.makebuffer':823 'part':354,379 'participl':37,692,696,702,717,729,1741 'past':691,701,716,1740 'path':339,1337 'path.relativepath':342 'pattern':38,76,1123,1357,1466,1696,2030,2184 'peer':285,466 'per':2075 'perform':226 'period':936,2069 'person':1148 'phrase':23,26,168,177,214,301,310,443,477,546,565,580,582,643,725,930,1376,1429,1979 'place':800,1594 'point':385,1135,1379 'point.distance':597 'posit':979,1027,1031,1171,1179,1181,1219,1412,1515,1712,1717,1965,2118 'prefer':1371,1532,1574,2122 'prefix':40,767,785,806,1858,1872,1886,2183 'preposit':22,298,300,309,319,361,392,476,480,492,1980,1984 'present':695,728 'preserv':220,230,455,1994 'print':1557 'produc':722 'properti':57,610,614,909,1069,1077,1085,1528,1535,1832,1839,2037,2087 'protocol':121,126,1364,1460,1463,1489,2105,2134 'public':876,1810,1955,2055 'pure':593 'purpos':1823 'rather':1820 'read':154,202,584,617,625,1149,1367,1384,1449,1753,2038 'receiv':622 'rect.intersection':602 'red':333,336,483,1439,1448 'redund':210 'refer':142,143,2146 'references/argument-labels-and-parameters.md':515,516,2171,2172 'references/conventions-and-special-rules.md':1127,1128,1701,1702,2203,2204 'references/naming-and-clarity.md':1359,1360,2159,2160 'references/side-effects-and-mutating-pairs.md':648,649,871,872,2188,2189 'relat':338 'relev':994 'remov':322,1019,1036,1039,1054,1162,1174,1177,1216,1401,1711,1715 'removeel':1906 'repeat':1227,1241,1900 'repres':353 'result':571 'return':569,591,790,899,938,1005,1008,1021,1037,1680,1771,1921,1931,2092,2132 'return-type-on':1679,1920 'revers':689,740,741,744 'review':137,140,1967 'review-checklist':139 'role':1206,1251,1258,1271,1318,1326,1720,1787,1800,2050,2150 'role-bas':2149 'role-clarifi':1317 'root':341,344 'rule':21,24,27,84,88,146,157,169,302,412,437,884,1062,1977 'safeti':1656,2196 'see':70,77,514,647,870,1126,1358,1700 'self':1546 'semant':2010 'sendabl':1483 'sentenc':919,2064 'sequenc':972 'sequence1':292 'sequence2':293 'serv':1146 'set.contains':631 'set.includes':641 'share':1659 'side':90,94,518,527,531,560,1761,2174 'side-effect':89,517,2173 'side-effect-fre':1760 'side-effect-nam':93 'signal':1778 'sin':1567 'singl':357,382,489,918,1576,2063 'site':153,1152,1195,1366,1616,1690 'situat':436 'skill' 'skill-swift-api-design-guidelines' 'smaller':287 'smtpserver':1525 'somecharact':251 'somedecim':263 'someobject':268 'someth':1469 'someuint32':247,462 'sort':687,734,735,738,841,842,1769,1776,1869 'sort/sorted':41 'source-dpearson2699' 'special':411,2004 'specifi':943,978,1026 'split':505 'standard':987 'start':814 'state':539,1093 'stdlib':868 'str':249,265 'strategi':2170 'string':250,266,1274,1281,1287,1288,1294,1295,1315,1338,1342,1350,1351,1639,1647,1654,1789,1910 'string.encoding':1637,1653 'stringvalu':1909 'strip':758,1737,1745 'stripnewlin':755,850 'strippingnewlin':756,851 'subscript':900,980 'subview':205,216,1400 'suffix':674,1480,2143 'summari':883,889,915,992,1815,2061,2070 'swift':2,7,16,43,49,63,72,79,200,238,281,320,373,418,547,592,623,788,817,937,1018,1097,1167,1199,1235,1267,1324,1382,1434,1516,1627 'swift-api-design-guidelin':1 'swift-concurr':78 'swift-languag':71 'symbol':984,988,2100 'syntax':69,1562 'tabl':435,826 'target':62 'terminolog':2158 'test':1747 'text.trimmingcharacters':606 'thing':2074 'throw':1010 'thrown':1013,2095 'time':1091,1837 'timer.invalidate':557 'topic-accessibility' 'topic-agent-skills' 'topic-ai-coding' 'topic-apple' 'topic-claude-code' 'topic-codex-skills' 'topic-cursor-skills' 'topic-ios' 'topic-ios-development' 'topic-liquid-glass' 'topic-localization' 'topic-mapkit' 'total':1099 'totalweight':1115 'tox':401 'tree':866,2181 'true':429,1522 'truncat':262 'tupl':1945,1951 'tuple/closure':1698,2197 'two':351,485 'type':55,221,908,1228,1243,1253,1265,1285,1299,1304,1311,1331,1432,1487,1668,1681,1784,1901,1913,1922,1932,1942,2052,2103,2133,2155 'typic':707 'unclear':1196 'unconstrain':1555 'undocu':1812 'ungrammat':706,753,846,1409,1743 'uniform':1507,2114 'union':781,858 'unlabel':399,1944 'upper':1508 'uppercamelcas':1491,2107 'url.isfileurl':633 'usag':119,124,1362 'use':276,296,726,986,1137,1254,1381,1490,1494,1536,1710,1730,1744,1756,1775,1788,1851,1964,2013,2019,2106,2110 'usersmtpserv':1524 'usual':1612 'utf8':1638 'utf8.codeunit':1519 'utf8bytes':1518 'valu':219,229,245,454,792,813,1009,1558,1603,1993,2093 'value-preserv':218,228,453,1992 'var':958,1114,1272,1286,1517,1520,1523 'variabl':910,1247,2044 'variant':662 'verb':534,545,550,639,669,683,686,710,836,838,839,843,847,848,924,1750,1757,1861,2015,2031 'verb-bas':1860 'verb-describ':668 'view.add':215 'view.addsubview':207 'view.fade':334 'weak':1298,1330,2154 'weak-typ':2153 'weight':1100 'whitespac':608 'widen':231,240 'without':559,572,1726,1840,1884,1957 'word':188,447,1183,1191,1224,1320 'work':1092 'would':191,1801 'write':914,1814,1864,1905 'x':289,375,387,471,497,1390,1398,1405,1548,1568 'x.insert':1386,1410 'x.makeiterator':1404 'x.removeboxes':327 'x.subviews.remove':1395,1414 'y':206,208,217,290,377,389,398,403,452,472,499,747,749,1387,1392,1411,1549 'z':1389,1394,1413 'zip':291","prices":[{"id":"4dddf006-76b0-4775-982c-acbf018cbe56","listingId":"66a19190-f2d4-45a6-96e8-de62925638b1","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"dpearson2699","category":"swift-ios-skills","install_from":"skills.sh"},"createdAt":"2026-04-22T12:53:47.434Z"}],"sources":[{"listingId":"66a19190-f2d4-45a6-96e8-de62925638b1","source":"github","sourceId":"dpearson2699/swift-ios-skills/swift-api-design-guidelines","sourceUrl":"https://github.com/dpearson2699/swift-ios-skills/tree/main/skills/swift-api-design-guidelines","isPrimary":false,"firstSeenAt":"2026-04-22T12:53:47.434Z","lastSeenAt":"2026-05-18T18:53:44.492Z"},{"listingId":"66a19190-f2d4-45a6-96e8-de62925638b1","source":"skills_sh","sourceId":"dpearson2699/swift-ios-skills/swift-api-design-guidelines","sourceUrl":"https://skills.sh/dpearson2699/swift-ios-skills/swift-api-design-guidelines","isPrimary":true,"firstSeenAt":"2026-05-07T20:41:55.112Z","lastSeenAt":"2026-05-07T22:41:17.308Z"}],"details":{"listingId":"66a19190-f2d4-45a6-96e8-de62925638b1","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"dpearson2699","slug":"swift-api-design-guidelines","github":{"repo":"dpearson2699/swift-ios-skills","stars":599,"topics":["accessibility","agent-skills","ai-coding","apple","claude-code","codex-skills","cursor-skills","ios","ios-development","liquid-glass","localization","mapkit","networking","storekit","swift","swift-concurrency","swiftdata","swiftui","widgetkit","xcode"],"license":"other","html_url":"https://github.com/dpearson2699/swift-ios-skills","pushed_at":"2026-04-26T21:04:17Z","description":"Agent Skills for iOS 26+, Swift 6.3, SwiftUI, and modern Apple frameworks","skill_md_sha":"29169bc5123f11ff6cd14a5b8b81b338dd5a8e59","skill_md_path":"skills/swift-api-design-guidelines/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/dpearson2699/swift-ios-skills/tree/main/skills/swift-api-design-guidelines"},"layout":"multi","source":"github","category":"swift-ios-skills","frontmatter":{"name":"swift-api-design-guidelines","description":"Apply Swift API Design Guidelines to name, label, and document Swift APIs. Covers argument label rules (prepositional phrase rule, grammatical phrase rule, first-label omission), mutating/nonmutating pair naming (-ed/-ing participle pattern, form- prefix, sort/sorted, formUnion/union), side-effect naming (noun for pure, verb for mutating), documentation comment structure (summary by declaration kind, O(1) complexity rule), clarity at call site, role-based naming, protocol naming (-able/-ible/-ing), default arguments over method families, casing conventions, and terminology. Use when designing new Swift APIs, reviewing naming and argument labels, writing documentation comments, or refactoring for call site clarity."},"skills_sh_url":"https://skills.sh/dpearson2699/swift-ios-skills/swift-api-design-guidelines"},"updatedAt":"2026-05-18T18:53:44.492Z"}}