WAYFINDER Codex UX Review
Overview
Use this skill to audit or revise the WAYFINDER native macOS experience so it feels closer to the OpenAI Codex product where that analogy is useful: quiet, thread-centered, dense but readable, tool-aware, and reviewable. Keep WAYFINDER's own architecture and accepted design contracts authoritative.
Core Workflow
- Confirm the target surface:
- Native Swift app:
macos/WayfinderMac.
- Legacy web/Tauri client:
clients/desktop, only when the task explicitly references it.
- Product docs/design contracts:
macos/README.md, decisions/WF-ADR-0042-desktop-menu-bar-client.md, designs/WF-DESIGN-0012-desktop-popover-design.md, and designs/WF-DESIGN-0014-flat-list-popover.md.
- Read
references/codex-ux-reference.md before making UX judgments.
- Inspect the current Swift implementation before prescribing changes. Start with:
macos/WayfinderMac/Package.swiftmacos/WayfinderMac/Sources/WayfinderMacApp/WayfinderMacMain.swiftmacos/WayfinderMac/Sources/WayfinderMac/WayfinderMacApp.swift
- Make UX changes in the smallest native surface that owns the behavior. Prefer SwiftUI/AppKit-native structure over web-era assumptions.
- Verify with the strongest available check:
- Run
swift test for behavior that can be tested.
- Run
swift run WayfinderMac for visual/manual review when feasible.
- Use screenshots or Computer Use for native macOS visual inspection when available.
- Use the Browser plugin only for local web previews, docs, or browser-rendered prototypes; do not treat it as the primary inspection tool for native Swift UI.
UX Priorities
- Preserve the menu-bar utility shape: fast glance, transient popover, native calm, no decorative landing-page energy.
- Make the routing decision legible first. The product is the decision, not a generic chat wrapper.
- Favor flat native menu grammar: rows, hairlines, compact labels, restrained icons, clear status, and no card grids unless an accepted design doc calls for one.
- Mirror Codex at the interaction level: persistent thread context, clear task state, tool/action affordances, reviewability, precise feedback loops, and compact controls.
- Avoid copying Codex visual details that conflict with WAYFINDER's accepted tokens, route colors, privacy claims, or menu-bar constraints.
- Keep privacy language exact: offline mode is the only mode that guarantees nothing leaves the machine.
- Prefer native accessibility: keyboard reachability, VoiceOver labels, reduced motion, visible focus, and no hidden action behind hover-only UI.
Codex Product Source
Use references/codex-ux-reference.md for the stable review lens. When the task needs current Codex product facts, first use the OpenAI docs/Codex manual workflow rather than relying on memory.
Relevant public source anchors:
Browser Plugin Guidance
For native Swift work, do not lead with the Browser plugin. Use it when:
- The task includes a local web preview, rendered documentation, or prototype route.
- A legacy
clients/desktop Vite/Tauri page needs inspection.
- The user explicitly asks to use
@Browser or the in-app browser.
When using Browser, keep the task scoped to a concrete URL, viewport, state, and visible issue. For native macOS UI, ask for or capture screenshots instead.
Output Shape
For UX review, lead with prioritized findings grounded in the visible UI or source files. For implementation, summarize the changed surfaces and the verification performed.
For design direction, separate "Codex-like" from "WAYFINDER-specific" so future changes do not flatten the product into a copy.
1---2name: wayfinder-codex-ux-review3description: Review and improve WAYFINDER's native macOS UX against OpenAI Codex app patterns and the repo's accepted menu-bar design contracts. Use when working on the Swift macOS app, menu-bar popover, chat window, settings window, native app screenshots, Codex-like interaction design, or UX review tasks that mention WAYFINDER, Codex, Codex app, Browser plugin, in-app browser, or OpenAI product reference.4---56# WAYFINDER Codex UX Review78## Overview910Use this skill to audit or revise the WAYFINDER native macOS experience so it feels closer to the OpenAI Codex product where that analogy is useful: quiet, thread-centered, dense but readable, tool-aware, and reviewable. Keep WAYFINDER's own architecture and accepted design contracts authoritative.1112## Core Workflow13141. Confirm the target surface:15 - Native Swift app: `macos/WayfinderMac`.16 - Legacy web/Tauri client: `clients/desktop`, only when the task explicitly references it.17 - Product docs/design contracts: `macos/README.md`, `decisions/WF-ADR-0042-desktop-menu-bar-client.md`, `designs/WF-DESIGN-0012-desktop-popover-design.md`, and `designs/WF-DESIGN-0014-flat-list-popover.md`.182. Read `references/codex-ux-reference.md` before making UX judgments.193. Inspect the current Swift implementation before prescribing changes. Start with:20 - `macos/WayfinderMac/Package.swift`21 - `macos/WayfinderMac/Sources/WayfinderMacApp/WayfinderMacMain.swift`22 - `macos/WayfinderMac/Sources/WayfinderMac/WayfinderMacApp.swift`234. Make UX changes in the smallest native surface that owns the behavior. Prefer SwiftUI/AppKit-native structure over web-era assumptions.245. Verify with the strongest available check:25 - Run `swift test` for behavior that can be tested.26 - Run `swift run WayfinderMac` for visual/manual review when feasible.27 - Use screenshots or Computer Use for native macOS visual inspection when available.28 - Use the Browser plugin only for local web previews, docs, or browser-rendered prototypes; do not treat it as the primary inspection tool for native Swift UI.2930## UX Priorities3132- Preserve the menu-bar utility shape: fast glance, transient popover, native calm, no decorative landing-page energy.33- Make the routing decision legible first. The product is the decision, not a generic chat wrapper.34- Favor flat native menu grammar: rows, hairlines, compact labels, restrained icons, clear status, and no card grids unless an accepted design doc calls for one.35- Mirror Codex at the interaction level: persistent thread context, clear task state, tool/action affordances, reviewability, precise feedback loops, and compact controls.36- Avoid copying Codex visual details that conflict with WAYFINDER's accepted tokens, route colors, privacy claims, or menu-bar constraints.37- Keep privacy language exact: offline mode is the only mode that guarantees nothing leaves the machine.38- Prefer native accessibility: keyboard reachability, VoiceOver labels, reduced motion, visible focus, and no hidden action behind hover-only UI.3940## Codex Product Source4142Use `references/codex-ux-reference.md` for the stable review lens. When the task needs current Codex product facts, first use the OpenAI docs/Codex manual workflow rather than relying on memory.4344Relevant public source anchors:4546- https://developers.openai.com/codex/app/features47- https://developers.openai.com/codex/app/browser48- https://developers.openai.com/codex/skills49- https://developers.openai.com/codex/plugins5051## Browser Plugin Guidance5253For native Swift work, do not lead with the Browser plugin. Use it when:5455- The task includes a local web preview, rendered documentation, or prototype route.56- A legacy `clients/desktop` Vite/Tauri page needs inspection.57- The user explicitly asks to use `@Browser` or the in-app browser.5859When using Browser, keep the task scoped to a concrete URL, viewport, state, and visible issue. For native macOS UI, ask for or capture screenshots instead.6061## Output Shape6263For UX review, lead with prioritized findings grounded in the visible UI or source files. For implementation, summarize the changed surfaces and the verification performed.6465For design direction, separate "Codex-like" from "WAYFINDER-specific" so future changes do not flatten the product into a copy.
asdecided