T-14: Error-handling UX matrix (design + code contract)

[kirich1409]

Description

Create MacApp/Packages/GitHubIntegration/Sources/GitHubIntegrationFeature/ErrorPresentation.swift — design artifact + code contract.

(1) Docstring — mandatory mapping table

error × surface → UX response:

Error	Badge	Popover	Preferences
.unauthorized	grey triangle ⚠	banner «Session expired — sign in again» + Sign-in button	red card «Your token was revoked — please Sign in again»
.forbidden(.saml)	grey triangle	banner «SSO authorization required» + deep link to https://github.com/orgs/<org>/sso?authorization_request=...	red card with SSO deep link
.forbidden(.scope)	grey triangle	banner «Insufficient permissions — re-authorize with updated scope» + Sign-in	red card «Scope mismatch» + Sign-in
.forbidden(.rateLimit) / .rateLimited(resetAt:)	.stale overlay + tooltip «Rate limited — retries at Xm:Ys»	banner «GitHub rate limit reached — retrying in …»	rate limit remaining = 0 with countdown
.notFound	hidden	banner «Repository or branch not found»	N/A
.networkError	.stale	banner «Network error — check connection» + Retry	red card
.serverError / .decodingFailed	grey triangle	banner «GitHub returned an unexpected response — retry later» + Retry	red card with error code
.forbidden(.other)	grey triangle	generic banner	generic red card

(2) Public helpers (single source of truth)

public struct BadgeVisual {
    public let symbol: String
    public let color: Color
    public let pulse: Bool
}
public func badgeIcon(for status: CIStatusView) -> BadgeVisual

public struct ErrorBannerConfig {
    public enum Action { case signIn, retry, ssoLink(URL), none }
    public let title: String
    public let message: String
    public let action: Action
}
public func bannerConfig(for error: GitHubAPIError) -> ErrorBannerConfig

public struct ErrorCardConfig {
    public let title: String
    public let message: String
    public let primaryAction: ErrorBannerConfig.Action
}
public func preferencesErrorState(for error: GitHubAuthError) -> ErrorCardConfig

T-9, T-10, T-11 consume these helpers exclusively.

(3) Unit tests

At least one test per error row — asserts helpers return the documented config.

Spec reference

See swarm-report/github-integration-decomposition.md#t-14 (BA review M-1 addition).

Relationships

• Parent issue: EPIC: GitHub Integration MVP (read-only CI status + popover + OAuth) #214
• Blocked by: T-5
• Blocks: T-8a, T-9, T-10, T-11, T-12
• Related: none

Acceptance criteria

• ErrorPresentation.swift exists; docstring contains the full mapping table verbatim
• Three helpers implemented
• Unit tests — at least one test per error case (8 rows)
• T-9, T-10, T-11 explicitly call these helpers (validated by code review)

Complexity

S

Suggested agent

developer-workflow:swift-engineer

Module / Layer

GitHubIntegrationFeature / UX contract