| Query | Expected source | Actual top-1 | Expected source in top-10? |
|---|---|---|---|
App icon | hig (0.5) | apple-docs://swiftui/scene/dialogicon | NO |
Touch targets | hig (0.5) | apple-docs://webkitjs/touchevent | NO |
Dark mode | hig (0.5) | apple-docs://appintents/defining-your-app-s-focus-filter | NO |
Quartz 2D | apple-archive (0.5) | apple-docs://coreimage/ciimage/init(cgimage:) | NO |
Cocoa Bindings | apple-archive (0.5) | apple-docs://appkit/cocoa-bindings | NO |
Key Value Observing | apple-archive (0.5) | apple-docs://swift/using-key-value-observing-in-swift | NO |
For each of these queries, the HIG or apple-archive corpus does have a relevant page (verified via cupertino search "<query>" --source hig and --source apple-archive):
| Query | Verified HIG page | Verified apple-archive page |
|---|---|---|
App icon | hig://general/appicons-appledeveloperdocumentation | — |
Dark mode | hig://general/darkmode-appledeveloperdocumentation | — |
Cocoa Bindings | — | apple-archive://TP40001075/CocoaBindings |
Key Value Observing | — | apple-archive://10000177i/KeyValueObserving |
Quartz 2D | — | apple-archive://TP30001066/dq_data_mgr |
Touch targets | (no exact-title page; HIG covers under "Gestures" / "Editing menus") | — |
The pages exist. The ranker doesn't surface them because the apple-docs RRF contribution dominates.
Why this happens, mechanically
RRF fuses per-source rank-1 contributions weighted by source authority:
fused(d) = Σ_{s ∈ sources(d)} weight(s) / (k + rank_s(d))For rank-1 in each source (k = 60):
| Source | Weight | Rank-1 fused contribution |
|---|---|---|
| apple-docs | 3.0 | 3.0 / 61 = 0.0492 |
| swift-evolution / packages | 1.5 | 1.5 / 61 = 0.0246 |
| swift-book / swift-org / samples | 1.0 | 1.0 / 61 = 0.0164 |
| hig / apple-archive | 0.5 | 0.5 / 61 = 0.0082 |
Even when HIG has a perfect rank-1 hit and apple-docs has a tangential rank-1 hit, the apple-docs contribution wins by 6:1 in fused score. HIG can never surface at top-1 in the default unfiltered query unless apple-docs has nothing in its corpus to return — which essentially never happens (351K rows).
Is this a bug?
No, it is the design. The source weights were tuned in Search.SmartQuery.sourceWeights (#254 Option B) specifically to bias toward apple-docs because that is the canonical reference for code-generating AI agents (cupertino's stated purpose per README.md and docs/design/cupertino.md §1.1). For an LLM grounding a Swift code-generation task, getting apple-docs at top-1 is the right answer even when HIG might be more conceptually relevant — the agent is writing code, not designing UX.
But it has a knowable cost. Designers, UX writers, and humans using cupertino to look up Apple's design guidance get apple-docs answers when HIG answers exist. The current workaround is the explicit --source hig flag. Documenting the cost here so it isn't a surprise the next time the question comes up.
Possible future directions (out of scope for this audit)
- Intent routing for design-vocabulary queries. Augment
Search.SmartQuery.symbolPreferredSources(#254) with adesignPreferredSourcesanalogue: when a query matches design vocabulary (app icon,dark mode,accessibility,typography,gestures,navigation pattern), route to HIG/apple-docs only. - Source-weight reconfiguration as a setting. Expose source weights as user-settable so a designer can
cupertino config set source-weight hig 3.0. - Composite top-3 rather than top-1. If the consumer reads top-3, the HIG hit may appear at rank 2 or 3, mitigating the issue without weight changes. Worth measuring.
None of these is proposed as immediate work; each is a candidate per the feedback_code_changes_as_ideas_for_future rule.