CleanMM/Docs/Execution/UI-Audit-2026-03-08.md

# UI Audit — 2026-03-08

## Scope

This audit reviews the current Atlas for Mac frozen-MVP shell after the post-MVP polish and bilingual localization work.

Audited surfaces:

- `Overview`
- `Smart Clean`
- `Apps`
- `History`
- `Permissions`
- `Settings`
- `Task Center`
- app shell navigation, toolbar, keyboard shortcuts, and shared design system

## Audit Method

The review combines:

- current product IA and copy guidance
- the shared SwiftUI design-system implementation
- screen-by-screen source review
- SwiftUI-focused UI guidance for hierarchy, keyboard flow, and accessibility

Evidence anchors:

- `Docs/IA.md`
- `Docs/COPY_GUIDELINES.md`
- `Packages/AtlasDesignSystem/Sources/AtlasDesignSystem/AtlasDesignSystem.swift`
- `Apps/AtlasApp/Sources/AtlasApp/AppShellView.swift`
- `Apps/AtlasApp/Sources/AtlasApp/AtlasAppCommands.swift`
- feature screen implementations under `Packages/AtlasFeatures*/Sources/*`

## Executive Summary

Atlas for Mac has moved beyond MVP-shell quality and now reads as a real product. The UX is coherent, trust-aware, keyboard-aware, and bilingual. The strongest improvements are in information clarity, reversibility cues, and consistency of shared surfaces.

The current gap is no longer “is this usable?” but “does this feel premium and native enough for a polished Mac utility?”

### Current Assessment

- Information architecture: `Strong`
- Trust and safety framing: `Strong`
- State coverage: `Strong`
- Accessibility and keyboard support: `Strong`
- Visual hierarchy depth: `Moderate`
- Density and reading rhythm: `Moderate`
- Secondary-surface polish: `Moderate`
- Premium native feel: `Moderate`

## What Is Working Well

### Product Clarity

- The app shell presents a stable frozen-MVP navigation model.
- `Overview`, `Smart Clean`, and `Apps` now tell a coherent story rather than reading like disconnected feature demos.
- Trust-sensitive actions are consistently framed as preview-first and recovery-aware.

### Interaction Model

- Main routes are keyboard reachable.
- Core task triggers are available from both screen UI and command menus.
- Task Center behaves like a real secondary control surface, not just a debug panel.

### Accessibility and Localization Foundations

- Shared UI primitives now expose meaningful accessibility labels and hints.
- Stable identifiers make UI automation resilient even when visible text changes by language.
- Chinese-first localization with English switching is now structurally correct, not just cosmetic.

## Primary Issues

### P0 — Highest Priority

#### 1. Card Hierarchy Is Still Too Flat

Most major pages rely on the same card weight and spacing rhythm. This keeps the product tidy, but it reduces scan efficiency because too many sections feel equally important.

Impact:

- Users need more effort to identify the single most important panel on a page.
- High-signal guidance competes visually with secondary detail.

Best-practice direction:

- Establish one dominant “hero” block per screen.
- Reduce visual competition among secondary sections.
- Reserve stronger elevation/tone for the first action-worthy surface.

Recommended changes:

- `Overview`: promote the top health / reclaimable / next-step zone into a more dominant summary block.
- `Smart Clean`: make the scan / execute area the unmistakable primary zone.
- `Apps`: make uninstall preview or inventory summary visually dominant depending on state.

#### 2. Reading Width Is Too Loose on Large Windows

Pages currently stretch very comfortably, but on wide desktop windows the reading path becomes longer than necessary.

Impact:

- Long explanatory copy becomes harder to scan.
- Secondary cards feel visually disconnected.

Best-practice direction:

- Introduce a content-width ceiling for main reading regions.
- Let metric clusters stretch, but keep explanatory sections tighter.

Recommended changes:

- Add a constrained content container inside `AtlasScreen`.
- Allow dense metric rows to use more width than narrative sections.

#### 3. Smart Clean Still Feels Like Two Primary CTA Zones

The `Run Scan` and `Execute Preview` actions are logically distinct, but visually they still compete for primary importance.

Impact:

- The next best action is not always instantly obvious.
- The page feels more tool-like than guided.

Best-practice direction:

- Only one dominant primary action should exist at a time.
- The primary CTA should depend on state:
  - no preview → `Run Scan`
  - actionable preview → `Execute Preview`

Recommended changes:

- Downgrade the non-primary action to bordered / secondary treatment in each state.
- Keep `Refresh Preview` secondary at all times.

#### 4. Settings Is Correct but Too Heavy

The screen is comprehensive, but it reads as a long structured form rather than a calm preference center.

Impact:

- Lower discoverability of the most important controls.
- Legal / trust text visually outweighs active preferences.

Best-practice direction:

- Split into clearer subsections or collapsible regions.
- Keep active settings short and above long-form informational content.

Recommended changes:

- Separate into `General`, `Language`, `Trust`, and `Notices` visual groups.
- Move long acknowledgement text behind expansion or a deeper detail view.

### P1 — Important Next Improvements

#### 5. Sidebar Density Is Slightly Too High for Daily Use

The two-line route treatment helps onboarding, but the constant subtitle presence adds noise once the user already understands the product.

Recommended changes:

- Reduce subtitle prominence.
- Consider showing subtitle only on selection, hover, or in onboarding mode.

#### 6. Secondary Surfaces Trail the Primary Routes

`Task Center` and some lower-priority sections now work well, but still feel more functional than premium.

Recommended changes:

- Tighten spacing and emphasis rules for popovers and secondary panels.
- Add a stronger visual relationship between summary text and follow-up action.

#### 7. Typography Scale Could Be More Intentional

The type hierarchy is good, but still somewhat conservative for a desktop utility with a lot of summary-driven UX.

Recommended changes:

- Slightly enlarge the primary summary tier.
- Slightly quiet secondary captions and helper text.
- Keep a more visible difference between page title, section title, and row title.

#### 8. Cross-Screen Density Rules Need One More Pass

Some screens are comfortably airy, others slightly dense.

Recommended changes:

- Standardize vertical rhythm for:
  - card header to body spacing
  - row spacing inside cards
  - gap between stacked cards

### P2 — Valuable but Not Immediate

#### 9. Native Delight Layer

The app is stable and clear, but not yet especially memorable.

Potential upgrades:

- more refined hover transitions
- better selected-state polish in the sidebar
- subtle page-entry choreography
- richer system-native empty-state illustration language

#### 10. Progressive Disclosure for Advanced Users

Future polish can separate mainstream users from power users without expanding scope.

Potential upgrades:

- compact vs comfortable density mode
- “advanced detail” toggles in `Smart Clean` and `Apps`
- richer developer-specific explanations where relevant

## Screen-by-Screen Notes

### Overview

Strengths:

- Clear high-level summary
- Good trust framing
- Useful activity surface

Main issue:

- Too many blocks feel equally important

Priority:

- `P0`

### Smart Clean

Strengths:

- Strong preview-first structure
- Good risk grouping
- Good recoverability language

Main issue:

- CTA hierarchy still needs stronger state-based dominance

Priority:

- `P0`

### Apps

Strengths:

- Good trust framing for uninstall
- Good leftover visibility
- Good preview-before-execute structure

Main issue:

- Preview state and inventory state should diverge more visually

Priority:

- `P0`

### History

Strengths:

- Good audit and recovery framing
- Rows are readable and trustworthy

Main issue:

- Could feel more timeline-like and less card-list-like

Priority:

- `P1`

### Permissions
n
Strengths:

- Limited-mode messaging is strong
- Permission rationale now feels respectful and clear

Main issue:

- Still somewhat uniform visually; could use stronger “what to do now” emphasis

Priority:

- `P1`

### Settings

Strengths:

- Good scope coverage
- Language switching is correctly placed
- Trust information is discoverable

Main issue:

- Too long and text-heavy for a premium settings surface

Priority:

- `P0`

### Task Center

Strengths:

- Useful and keyboard friendly
- Clear bridge into History

Main issue:

- Still visually closer to a utility panel than a polished product surface

Priority:

- `P1`

## Recommended Execution Order

### Wave 1

- Reduce card hierarchy flatness
- Introduce content-width ceiling
- Make `Smart Clean` a single-primary-action screen per state
- Reduce `Settings` reading burden

### Wave 2

- Refine sidebar density
- Upgrade `Task Center` and other secondary surfaces
- Tighten typography and spacing rules

### Wave 3

- Add native delight polish
- Add advanced progressive disclosure where it improves clarity

## Done When

This UI audit is considered addressed when:

- each major screen has an obvious primary focus region
- each state has one clearly dominant next action
- reading width feels intentionally controlled on large windows
- `Settings` no longer feels like a long documentation page
- secondary surfaces feel visually consistent with the main shell
- the product feels recognizably “Mac-native polished,” not just “well-organized SwiftUI”