Ember: A Native, Accessibility-First Hacker News Client

Ember is a bespoke Hacker News reader designed for the Apple ecosystem (iPhone, iPad, and Mac). It prioritizes a calm user experience, high performance, and universal accessibility. Built entirely in SwiftUI, it avoids third-party libraries entirely, relying solely on native frameworks.

"Ember treats accessibility not as a checklist item, but as a core feature, ensuring that the Hacker News experience is inclusive for everyone."

---

🌟 Key Highlights

Ember transforms the HN experience into a native app flow. Here is what it brings to the table:

• Comprehensive Feeds: Quick access to Top, New, Best, Ask HN, Show HN, and Jobs via a pinned navigation bar.
• Native Threading: HTML comments are parsed into native SwiftUI views, supporting code blocks, italics, bold text, and blockquotes.
• Efficient Loading: Entire comment trees are fetched in a single request and feature collapsible nesting with depth indicators.
• Intelligent Onboarding: A first-run sequence that detects system accessibility and appearance settings to pre-configure the app.
• Powerful Search: Full-text search capabilities powered by Algolia, sortable by recency or relevance.
• Offline Capabilities:
  • Local storage for bookmarked stories.
  • A robust disk cache for feeds and threads, allowing the app to function without an internet connection.
• Read Tracking: Visited content is visually dimmed to help users track their progress.
• Adaptive Layout: The UI shifts based on the device:
  • $iPhone \rightarrow \text{TabView}$
  • $iPad/Mac \rightarrow \text{Three-pane NavigationSplitView}$
• Premium Typography: Utilizes the Inter variable font with optimized leading and line length for maximum readability.
• Integrated Browsing: Links open in an in-app Safari view (with Reader mode support) or the system browser.
• User Insights: Full access to user profiles, including karma, join dates, and submission history.
• Polished Aesthetics: A hand-crafted color palette, six distinct accent themes, haptic feedback, and smooth transitions.

---

♿ Accessibility as a Priority

Ember is engineered to be usable by everyone, with a heavy emphasis on color-blind friendliness and screen-reader optimization.

Visual & System Adaptations

System Setting	Ember's Implementation
Color Vision	Status is never indicated by color alone; SF Symbols, shapes, and text are always paired with colors.
Differentiate Without Color	When enabled, explicit non-color indicators are activated throughout the UI.
VoiceOver	Custom labels, traits, and hints ensure stories are read as single, coherent elements.
Dynamic Type	Typography and layouts (including comment indentation) scale fluidly with system text size.
Reduce Motion	Loading shimmers and animations are minimized or disabled.
Link Visibility	Links in comments can be underlined to ensure they are identifiable without color.

Proactive Setup: Upon the first launch, Ember scans for VoiceOver, Bold Text, and Reduce Motion settings, automatically enabling corresponding app features and notifying the user of the changes.

---

🛠 Technical Architecture

Ember is a "pure" SwiftUI project. The architecture is designed for modularity and speed.

The Tech Stack

• UI Framework: SwiftUI (targeting iOS 18) with Mac Catalyst for desktop support.
• State Management: Utilizes the @Observable framework for streamlined view models.
• Concurrency: Leverages async/await and TaskGroup for concurrent feed fetching.
• Persistence:
  • UserDefaults $\rightarrow$ Settings & Read State.
  • JSON $\rightarrow$ Bookmarks.
  • DiskCache (Actor-based) $\rightarrow$ Bounded cache for API responses.

Data Flow

Project Organization

Sources/
├── App/            # Entry point, Root Layout, Environment
├── Models/         # HNItem, HNUser, Feed, Algolia schemas
├── Networking/     # HNService protocol & API clients
├── Stores/         # Bookmarks, Settings, ReadState
├── DesignSystem/   # Theme, Typography, Haptics, Components
└── Utilities/      # HTML Renderer, Time formatting

Performance Note

The app ensures a smooth experience by utilizing a bounded cache. The mathematical logic for the cache fallback is: $\text{Data Source} = \begin{cases} \text{Network}, & \text{if connected} \\ \text{DiskCache}, & \text{if offline} \end{cases}$