Skip to content

Make OpenStation settings easier to understand - #581

Open
nickhamze wants to merge 2 commits into
WordPress:trunkfrom
nickhamze:codex/settings-clarity-copy
Open

Make OpenStation settings easier to understand#581
nickhamze wants to merge 2 commits into
WordPress:trunkfrom
nickhamze:codex/settings-clarity-copy

Conversation

@nickhamze

@nickhamze nickhamze commented Aug 12, 2026

Copy link
Copy Markdown
Collaborator

Why this change

We reviewed every setting surfaced by the Settings Clarity run and found a recurring problem: the controls often say what they change, but not who the change affects, when it takes effect, what else it changes, or how to reverse it.

That makes ordinary choices feel riskier than they should. A person should not need to inspect the code—or learn by surprise—that a preference follows their WordPress account, a theme changes other preferences the first time it is selected, a native-window choice applies only when the app is opened again, or a reset reaches every Preferences tab.

The audit covered 137 settings. Of those, 129 are real OpenStation product settings and 8 are deliberately planted test-lab canaries. The canaries remain in the lab; this PR updates the product language only.

What changes

This pass focuses on the shared language problems that made otherwise straightforward settings hard to predict:

  • Account and site scope are stated plainly. Appearance and shortcut choices now say they are saved to the current WordPress account. Site-wide options say “for everyone.” Theme uploads say they install a theme for the whole site.
  • Timing is honest. Native Posts, Pages, Users, Plugins, and Comments choices now say they apply the next time the app opens and do not replace a window that is already open.
  • Reset is no longer vague. “Reset to defaults” becomes “Reset all OpenStation preferences,” with an explanation that it reaches every Preferences tab, clears the saved custom-wallpaper choice, keeps the Media Library file, and cannot be undone.
  • Theme side effects are disclosed. The Themes tab explains that the first selection applies the theme’s recommended preferences. The reapply action no longer promises “layout and effects” when a theme may recommend a different set of preferences.
  • Shortcut placement is easier to understand. “On both” and “Hidden” become “Desktop and dock” and “Nowhere,” and each picker is named for the shortcut it controls.
  • File Associations describe the actual decision. Every row now reads “Default app for …,” including the accessible control name, and explains that the choice belongs to the account and is used the next time a file opens.
  • Mio’s abstract controls use visible outcomes. “Hue spread,” “Iridescence,” “Spin the gradient,” and “Restore Mio” become “Colour range,” “Holographic strength,” “Move gradient around ring,” and “Reset Mio’s look.” Zero-value controls say when zero means off.
  • Shared Posts and Pages column choices are disclosed. The menu identifies whether it belongs to Posts or Pages, while Author and Date say they are shared by both.

Representative examples:

Before After Why
“saved to this browser” “saved to your WordPress account” The preference follows the signed-in user across browsers.
“Reset to defaults” “Reset all OpenStation preferences” The action reaches far beyond the visible Appearance tab.
“Use the native Posts window” “Open Posts in the native window” This is a routing choice used on the next open, not a live conversion of the current window.
“Apply recommended layout and effects” “Apply recommended preferences” Themes can recommend keys outside those two categories.
“Show in” “Where to show [app]” Each repeated picker now has a clear, distinct question.

What this PR does not claim to fix

This is intentionally a language-focused PR. The audit also found behavior bugs—failed-save rollback, rapid-toggle races, Spatial-layout placement, live opener refresh, ribbons that remain visible, and similar problems. Those need code fixes and are being tracked separately. The copy here does not disguise or close them.

The 16 findings from the audit

Every finding has its own destination now, so this PR does not become a catch-all bug report.

This PR fully resolves the wording or accessible-name problem in:

It improves the explanation, while leaving the remaining interaction decision open, in:

The behavior bugs remain separate:

Checks run

  • npm run lint
  • npm run typecheck
  • npm run test:js — 4,260 tests passed
  • npm run build
Open WordPress Playground Preview

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment