implementing-ios-code

name	implementing-ios-code
description	Implement, write code, add a new screen, create a feature, new view, new processor, or wire up a new service in Bitwarden iOS. Use when asked to "implement", "write code", "add screen", "create feature", "new view", "new processor", "add service", or when translating a design doc into actual Swift code.

Implementing iOS Code

Use this skill to implement Bitwarden iOS features following established patterns.

Prerequisites

• A plan should exist in .claude/outputs/plans/<ticket-id>.md. If not, invoke planning-ios-implementation first.
• Read Docs/Architecture.md — it is the authoritative source for all patterns. This skill references it, not replaces it.

Step 1: Determine Scope

From the plan, identify:

• Is this a new feature (full file-set) or modification of existing code?
• Which framework: BitwardenShared, AuthenticatorShared, or BitwardenKit?
• Which domain: Auth/, Autofill/, Platform/, Tools/, Vault/?

See templates.md for file-set skeletons.

Step 2: Core Layer First

Implement from the bottom up:

Data Models (if needed)

• Request/Response types in Core/<Domain>/Models/Request/ and Response/
  • Alphabetize stored properties and initializer parameters (parameters with default values go last). When you add one to an existing type, insert it at its alphabetical position and update the synthesized initializer and every call site to match — don't append.
• Enum types in Core/<Domain>/Models/Enum/
  • Keep cases alphabetical. When you add a case to an existing enum, insert it at its alphabetical position in every switch over that enum (across all layers) rather than appending it — match the surrounding order.

Persistence (if needed)

• Vault sync data → CoreData via DataStore (add entities to Bitwarden.xcdatamodeld)
• Non-sensitive settings → AppSettingsStore (backed by UserDefaults)
• Credentials/keys → KeychainRepository
• All three are exposed through StateService. Prefer adding a separate protocol over extending StateService, AppSettingsStore, or KeychainRepository directly, to maintain interface segregation.

Services / Repositories

• Define protocol with // sourcery: AutoMockable
• Implement Default<Name>Service / Default<Name>Repository
• Add Has<Name> protocol
• See templates.md for service skeleton

Step 3: UI Layer (File-Set Pattern)

For new screens, create all required files together (see templates.md):

1. Route — Add case to the parent Coordinator's route enum
2. Coordinator — Navigation logic, screen instantiation, Services typealias
3. State — Value type (struct) holding all view-observable data
4. Action — Enum of user interactions handled synchronously in receive(_:)
5. Effect — Enum of async work handled in perform(_:)
6. Processor — StateProcessor subclass, business logic only
7. View — SwiftUI view using store.binding, store.perform, @ObservedObject

SwiftUI previews:

• Use #Preview macros for new views — the modern default across the codebase. Do not add new PreviewProvider structs. Because the snapshot harness cannot enumerate #Preview macros, such a view's snapshot coverage comes from a test that instantiates the view directly; see the testing-ios-code skill for how to choose between that and iterating PreviewProvider._allPreviews when a view exposes both.

New localization keys (BitwardenResources/.../Localizable.strings):

• Key name mirrors the English string: Archive for "Archive", not MoveToArchive or ArchiveTitle.
  • Exception: long descriptive strings (~70-80+ chars) use a DescriptionLong suffix on a shortened opening phrase. Example: PassphrasesAreOftenEasierToRememberDescriptionLong.
• Translator-facing /* … */ comments describe meaning, placement, or constraints that affect translation — translators are the audience, not internal engineers.

Step 4: Wire Dependency Injection

After creating a new service/repository:

• Add Has<Name> conformance to ServiceContainer via extension
• Add Has<Name> to the Services typealias of any processor that needs it

Step 5: Security Check

Before finishing:

• Vault data? → Must use BitwardenSdk for all encryption/decryption
• Storing credentials? → Must use KeychainRepository, not AppSettingsStore
• User input? → Must validate via InputValidator
• Surfacing errors? → Sensitive errors must implement NonLoggableError
• Running in an extension? → Check Argon2id memory if KDF is involved

Step 6: Documentation

All new public types and methods require DocC (///) documentation. Exceptions: protocol property/function implementations (docs live in the protocol), mock classes. Use pragma marks to organize code. // MARK: - is used to denote different objects in the same file; // MARK: is used to denote different sections within an object.

Step 7: Verify — Lint, Format, and Regenerate

Run these checks after all code and tests are written, before handing back. Fix every violation found — do not leave warnings for the commit phase.

If new localization strings were added, regenerate first so SwiftGen picks them up:

mint run swiftgen config run --config swiftgen-bwr.yml   # BitwardenResources (most common)
# Run the appropriate swiftgen-*.yml if strings landed in a different target

Then run the pre-commit checks:

./Scripts/pre-commit

This runs spell-check, SwiftFormat, and SwiftLint on changed files — the same checks that run at commit time. If violations are reported, fix them and re-run until it passes cleanly.

For SwiftLint violations that require manual fixes, prefer fixing the root cause over suppressing with // swiftlint:disable comments. Suppression is appropriate when the violation is structural and fixing it would require an artificial or non-idiomatic refactor. Common cases:

• line_length — wrap long lines using Xcode's ⌃M style (each argument on its own indented line); fix rather than suppress
• file_length — if a #if DEBUG preview section pushed a file over the limit, add // swiftlint:disable file_length at the top of the file (this is the established pattern — do NOT move previews to a separate file)
• type_body_length — split large types using // MARK: extensions in separate files if needed; suppress only if the type is inherently large and splitting would hurt readability

Only hand back once ./Scripts/pre-commit passes cleanly for files touched in this session.

Conventions

• Member ordering — within a // MARK: section, keep members in a single alphabetical order (stored properties, computed properties, methods, and static members share that order), and alphabetize function and initializer parameters the same way (default-valued, variadic, then trailing-closure parameters last). Insert new members and parameters at their alphabetical position rather than appending. Exceptions: UI objects (views, view modifiers) follow visual layout order, not alphabetical; and protocol conformance ordering is not enforced.
• No file-scope globals — prefer a static member on the relevant type or extension over a file-scope global function or property, even a private one.
• Prefer typed over stringly-typed — model values with their natural types (enums, Date, etc.) rather than raw strings, unless deliberately mirroring an external contract (e.g. an SDK model that stores ISO date strings) where typed conversion is intentionally deferred.