[skyswordw]

Integrated validation

Merged into main in sequence #295–#300. Final main commit 7c5393672d028f31bc76f83911a02e1407a53cf7 has the same file tree as tested integration commit 8fb4dda. Full local validation passed 687 tests in 102 suites with zero failures/skips, 0/1,261 missing zh-Hans strings, unchanged generated plists and clean diff checks. Bounded native CUA/AX draft creation and Search Clear/Close checks passed, including independent ZIP byte verification; this is not VoiceOver testing. See the review comment for scope and remaining native checks. Final main CI and the integrated #300 snapshot run supersede cancelled intermediate reruns.

Claude Code's visual design for #291 (Welcome hierarchy) and the secondary-entry presentation for #292 (sample download). Functional foundation: #295.

Ownership per AGENTS.md: Claude Code owns this layout, hierarchy, copy presentation and motion. Codex / Grok Bot own the routing, draft guards, packaging and tests underneath, which this PR does not change. No functional or native acceptance is claimed here.

Welcome (#291)

• Create Archive… is the prominent glass button, trailing, beside Open Archive…. Both buttons are the same width (English and zh-Hans), inside the drop zone, under the text that says what dropping does. Their tooltips give the shortcuts (⌘O, ⌘N).
• Settings is an icon-only gear in the window's top-trailing corner. It mirrors the traffic lights: same vertical centre, and its glyph's trailing inset equals the close button's leading inset.
  • The position comes from the window's own close button, so it follows the system's metrics. Measured in the capture: 14 pt glyph against 14 pt lights, 9.0 pt inset on both sides, same centre line.
  • It is secondary and borderless, with a faint 22 pt hover circle. Under Increase Contrast it is full strength with a hairline ring.
  • Its accessibility name is "Settings…", its tooltip is "Open Stow's settings (⌘,)", and it shows a focus ring for keyboard navigation.
  • A raw mouse press on it (not an AX press) opened Settings in a development build, so clicks reach it inside the title-bar strip.
• With keyboard navigation on, the window starts with focus on Create Archive (defaultFocus).
• On a short window the format chips go first, then the icon; both actions always stay.
• Motion: while a drag is over the zone, both actions fade to 35 % in place, using the existing drop-target spring. Nothing moves.
• Recents (empty and populated), drop handling, the context menu and Clear are unchanged.

Revision after user feedback: the first version of this PR put "⚙ Settings…" in a bottom-leading footer. The user preferred the top-right corner and found a text label there uncoordinated, so the footer is gone (fc99348). Open Archive… and Create Archive… stay exactly as they were, as the user confirmed.

Sample entry (#292)

• Help › Download Sample Archive now sits beside Sample Credits and Licenses, below a divider under Welcome to Stow. The sample is a web download, so it lives with the app's other web pages rather than in File, which holds commands that act inside the app.
• Welcome to Stow: the same Download Sample Archive button, with a caption: "Your browser saves it; open the ZIP to try Stow." The tooltip says it opens in the browser.
• There's no ellipsis, because nothing is asked before the browser takes over. There's no in-app progress or error UI; the browser shows both.

Behaviour changes (please review)

1. The File menu no longer has the sample item, and ⇧⌘O no longer downloads it. The command keeps its route (AppState.downloadSample()) and its disable rule while a password prompt is up, now under Help. If you want the shortcut back, re-add .keyboardShortcut("o", modifiers: [.command, .shift]) to the Help item.
2. With Full Keyboard Access on, Welcome's initial focus is Create Archive.

Routing, packaging, beginNewArchive() (one draft on repeated clicks, no replacement of unsaved work), the Settings router (SettingsRouter.shared.show(.general)) and the Release sample exclusion are all unchanged. ArchiveDraftView/PackSheet, Tray settings and Browser search are untouched.

Strings and docs

• New strings, all with zh-Hans: Download Sample Archive (renamed in place from "Download Sample…"), the onboarding caption and tooltip, and three Welcome tooltips.
• README and the UI/motion handoff now use the new wording, and the old Try the Sample guidance is marked superseded.
• DESIGN.md has new Welcome's actions and The sample bullets. They supersede the Open Archive… / Try the Sample pair and this PR's first footer draft. The drop-target motion row now covers the action fade.

Screenshots

Welcome, no history

English light	English dark	zh-Hans light	zh-Hans dark

Welcome with Recent

English light	English dark	zh-Hans light	zh-Hans dark

Welcome to Stow (sample entry)

English light	English dark	zh-Hans light	zh-Hans dark

Increase Contrast + Reduce Transparency (Stow overrides)

light	dark

Captured with scripts/snapshot.sh from the Debug build (-AppleLanguages "(zh-Hans)", -StowIncreaseContrast YES -StowReduceTransparency YES). The onboarding window is unchanged by the gear revision and shows inactive in its capture.

Validation

• Full suite before the gear revision (derived data outside ~/Downloads): 685 tests in 102 suites passed.
• After the revision: Welcome/window suites ArchiveWindowModeTests, OpeningWindowTests and SourceReadAccessTests — 29 tests passed. The later glyph-size changes are presentation constants only.
• scripts/check-localizations.sh zh-Hans: 0 of 1,237 strings missing.
• Debug build succeeded. No project.yml change.

Not verified: a real drag-over (the fade is in code, not captured), Full Keyboard Access initial focus and tab order, the gear's hover state on screen, and a physically short window (Welcome is fixed at 640 × 600; the fallbacks are checked in the tightest populated-Recent state). System controls follow Increase Contrast / Reduce Transparency themselves. VoiceOver remains deferred under #93.

🤖 Generated with Claude Code

[skyswordw]

Functional review completed with no blocking findings. Welcome Create and the menu routes share one guarded draft; Settings uses the existing router and retains its accessible name. The Help sample action remains explicit browser routing with the password-prompt gate. Removing the old Shift-Command-O sample shortcut is accepted as the explicitly documented behavior change; Command-O/Command-N remain unchanged.

The integrated tree passed 687 tests and complete zh-Hans export. CUA/AX confirmed Welcome Create reaches the real draft, and the combined Welcome snapshot was inspected. Catalog conflict resolution retained the new entries from both draft and Welcome designs. Full Keyboard Access/system-display refinements and signed lifecycle integration remain tracked in #38/#104; no VoiceOver test is claimed. Claude Code owns design/motion, Codex the routing/integration review.