obsidian-vault/work/wiki/apple-browsers/general.md

source, confidence, namespace, last_synced, alwaysApply

source	confidence	namespace	last_synced	alwaysApply
~/DuckDuckGo/apple-browsers.git/main/.cursor/rules/general.mdc	0.9	work	2026-04-28	true

DuckDuckGo Browser Development Rules Overview

Project Context

This is the DuckDuckGo browser for iOS and macOS, built with privacy-first principles, modern Swift patterns, and cross-platform architecture.

Key Directories:

• iOS/ - iOS browser app (UIKit + SwiftUI hybrid)
• macOS/ - macOS browser app (AppKit + SwiftUI hybrid)
• SharedPackages/ - Cross-platform Swift packages

Architecture Summary

• Pattern: MVVM + Coordinators + Dependency Injection
• UI: SwiftUI preferred, UIKit/AppKit for legacy
• Storage: Core Data + GRDB + Keychain for sensitive data
• Design: DesignResourcesKit for colors/icons (MANDATORY)
• Testing: >80% coverage required

Available Rules (.cursor/rules/)

Development rules are stored in .cursor/rules/. You MUST list all the available rules and you MUST consult the appropriate rule file before starting any work!

Core (Always Apply)

• anti-patterns.mdc - What NOT to do; use with ViewModels, testing, WebView work
• code-style.mdc - Swift style guide
• privacy-security.mdc - Privacy requirements; use with network calls, analytics, credentials
• import-hygiene.mdc - Import management and SwiftUI preview scoping
• logging-guidelines.mdc - Logger usage (never print())

Architecture & Patterns

• architecture.mdc - MVVM, DI patterns; use for new ViewModels
• project-structure.mdc - Directory layout
• browserserviceskit-integration.mdc - BSK integration; use for cross-platform code
• shared-packages.mdc - Cross-platform packages; use for cross-platform code
• subscription-architecture.mdc - Privacy Pro subscription

Feature Development

• feature-flags.mdc + feature-flags-addition.mdc - Feature flags
• abn-experiment-framework.mdc - A/B testing
• user-defaults-storage.mdc - UserDefaults, @UserDefaultsWrapper; use for settings/preferences

UI Development

• swiftui-style.mdc - SwiftUI + DesignResourcesKit; use for new ViewModels, UI work
• swiftui-advanced.mdc - Advanced SwiftUI patterns
• design-system-designresourceskit.mdc - Colors, typography, icons (MANDATORY)
• webkit-browser.mdc - WebView patterns

Platform-Specific

• ios-architecture.mdc - iOS AppDependencyProvider, MainCoordinator, UIKit
• ios-tracker-blocking-implementation.mdc - iOS content blocking
• macos-window-management.mdc - macOS windows
• macos-system-integration.mdc - macOS system services
• macos-singletons-removal.mdc - Removing singletons from macOS

Feature-Specific

• duckplayer.mdc + duckplayer-userscript-integration.mdc - DuckPlayer
• securevault-guidelines.mdc - Credentials/vault storage
• app-lifecycle-state-machine.mdc - App state management
• network-quality-*.mdc (4 files) - Network quality assessment

Testing & Quality

• testing.mdc - Testing patterns, xcodebuild commands
• ui-testing.mdc - UI testing for macOS browser
• maestro-device-selection.mdc - Maestro test device config
• performance-optimization.mdc - Performance; use with network calls

Workflow & Process

• development-commands.mdc - Build commands
• pull-request.mdc + branch-naming-conventions.mdc - PRs and git workflow
• analytics-patterns.mdc - Pixel analytics

Quick Start Checklist

Before Writing Any Code:

1. ✅ Read privacy-security.mdc - Privacy is non-negotiable
2. ✅ Check platform rules (ios-architecture.mdc or macos-system-integration.mdc)
3. ✅ Review anti-patterns.mdc - Avoid common mistakes
4. ✅ REMEMBER: NEVER commit, push, or run tests without explicit user permission or unless explicitly asked to

For UI Development:

1. ✅ Use swiftui-style.mdc for SwiftUI components
2. ✅ MUST use DesignResourcesKit colors: Color(designSystemColor: .textPrimary)
3. ✅ MUST use DesignResourcesKit icons: DesignSystemImages.Glyphs.Size16.add

For New Features:

1. ✅ Follow architecture.mdc for MVVM + DI patterns
2. ✅ Use AppDependencyProvider (iOS) or equivalent (macOS)
3. ✅ Write tests per testing.mdc requirements

Critical Don'ts (from anti-patterns.mdc)

• ❌ NEVER commit, push changes, create or delete branches on git or trigger github actions without EXPLICIT user permission
• ❌ NEVER run tests without EXPLICIT user permission or if user explicitly asked to in their prompt
• ❌ NEVER use .shared singletons - use dependency injection instead
• ❌ NEVER hardcode colors/icons (use DesignResourcesKit)
• ❌ NEVER update UI without @MainActor
• ❌ NEVER ignore privacy implications
• ❌ NEVER force unwrap without justification
• ❌ NEVER use print() statements - use appropriate Logger extensions instead

Logging Guidelines

NEVER use print() in production code. ALWAYS use appropriate Logger extensions:

Example: See logging-guidelines.swift

Available Logger categories:

• Logger.general - General app functionality
• Logger.network - Network requests and responses
• Logger.ui - UI updates and user interactions
• Logger.tests - Test-specific logging (import os.log in tests)

Benefits of Logger extensions:

• Structured logging with categories and levels
• Better performance than print() statements
• Automatic log collection and filtering
• Integration with system logging infrastructure

Dependency Injection Pattern (iOS)

Example: See dependency-injection-pattern.swift

Design System Usage (MANDATORY)

Example: See design-system-usage.swift

Code Review Checklist

1. Privacy implications assessed (privacy-security.mdc)
2. Design system properly used (design-system-designresourceskit.mdc)
3. Architecture patterns followed (platform-specific rules)
4. Anti-patterns avoided (anti-patterns.mdc)
5. Tests written and passing (testing.mdc)
6. Performance considered (performance-optimization.mdc)
7. PR template followed (pull-request.mdc)

Git & Testing Workflow Rules

🚨 MANDATORY: Never Auto-Execute Commands

NEVER commit, push, or run tests without EXPLICIT user permission.

Git Workflow:

1. Make file changes as requested
2. STOP before any git add, git commit, or git push commands
3. ASK the user: "Should I commit/push these changes?"
4. WAIT for explicit permission (e.g., "yes", "commit it", "push it", "go ahead")
5. Only then execute git commands

Testing Workflow:

1. Write or modify code as requested
2. STOP before running any tests (swift test, npm test, xcodebuild test, etc.)
3. ASK the user: "Should I run the tests?"
4. WAIT for explicit permission (e.g., "yes", "run tests", "test it")
5. Only then execute test commands

What NOT to Do:

Example: See git-workflow-wrong.sh

What TO Do:

Example: See git-workflow-correct.sh

These rules have NO exceptions. Always ask before executing git or test commands.

Communication Style

• Keep responses concise and focused on the task
• Avoid enthusiastic language like "Perfect!", "You are absolutely right!", "Excellent!"
• Keep work summaries brief - focus on what was changed, not how great it is
• Let the code quality speak for itself rather than using excessive praise

---

This overview ensures you understand the project context and know which specific rules to consult for your development task.