Skip to content

fix(settings): govern the 外观 page structure, grouping, and copy - #2343

Merged
jackwener merged 1 commit into
apache:mainfrom
ARE404:are404/feat-appearance-settings-refresh
Aug 7, 2026
Merged

fix(settings): govern the 外观 page structure, grouping, and copy#2343
jackwener merged 1 commit into
apache:mainfrom
ARE404:are404/feat-appearance-settings-refresh

Conversation

@ARE404

@ARE404 ARE404 commented Aug 6, 2026

Copy link
Copy Markdown
Contributor

The 外观 page carries four leftovers from the moves that reshaped it — identity going to 通用 (P2-13), the Astryx open-group rebuild (#1972), and the settings-page kit (#1991). None of them change what the page looks like; all four change what it is.

Page root

AppearanceSettingsPage wrapped a ThemeSettingsPage that opened a SettingsPage of its own, so the page grid nested inside itself — two .settingsPageStack in the rendered DOM. The page IS the theme page (its own comment says so), so it is now one component with one root.

通用 had the same defect from the other side: the identity block was exported as PersonalizationSettingsPage from appearance-settings-page.tsx and rendered inside GeneralSettingsPage's own SettingsPage. It is one section of someone else's page, so it is now named, filed, and shaped as one — personalization-settings-section.tsx, returning a SettingsSection.

Grouping

The 14 option tiles were loose in the accessibility tree: the two <section>s were unnamed landmarks (SettingsSection takes a titleId for exactly this and the page passed none), and the visible 编辑器主题 / 产品色调 labels had no programmatic relationship to the grids they head. Sections now carry titleId; each grid is a role="group" named by the label above it.

Copy

The nav description still advertised 界面语言 on 外观 — a page that has not had it since P2-13 — while 通用, which does have it, never mentioned it. Both descriptions now say what their page holds, zh and en.

sections.paletteHelp was defined in both locales and read by nobody, while the palette section reached into appearance.persistenceHelp for its lede. The palette section now takes its lede from sections, the same namespace the theme section above it uses, and the unread key is gone.

AppearanceSettingsPage also stops taking a settings prop it only passed down one level to a component that never read it.

Contract

astryx-component-behavior.test.ts pins one page stack, the four aria-labelledby anchors, three named groups, no 界面语言 on 外观, and that the identity block opens no page stack of its own.

Verification

  • npm --workspace @maka/desktop run typecheck
  • npm run format:check
  • npm --workspace @maka/desktop run test:checks (console / a11y / copy)
  • node scripts/check-dead-css.mjs --check
  • 1754 desktop tests, 0 failures
  • Both pages re-rendered in a real Electron fixture window (settings-appearance / settings-general, light and dark): 外观 unchanged apart from the two copy lines, 通用 pixel identical, .settingsPageStack count 2 → 1 on each.

Not in this PR

The palette picker's visual weaknesses are real but need a design conversation, so they are deliberately left alone: the swatches hardcode light-mode accents (mono is inverted in dark — oklch(0.30 0 0) previewed against a live dark accent of oklch(0.92 0 0)), the tiles preview the accent but never the canvas, the theme mock is palette-blind, and columns={{minWidth:180}} leaves orphan rows at 5 and 6 items. Happy to take any of them as a follow-up.

@ARE404
ARE404 force-pushed the are404/feat-appearance-settings-refresh branch 2 times, most recently from b2db810 to 13c598a Compare August 7, 2026 00:24
The 外观 page carried four leftovers from the moves that reshaped it —
identity going to 通用 (P2-13), the Astryx open-group rebuild (apache#1972), and
the settings-page kit (apache#1991).

- Page root: `AppearanceSettingsPage` wrapped a `ThemeSettingsPage` that
  opened a `SettingsPage` of its own, so the page grid nested inside itself
  (two `.settingsPageStack` in the DOM). The page IS the theme page, as its
  own comment said, so it is now one component with one root. Same defect on
  通用, where the identity block was a `*Page` rendered inside another page:
  it is a section of someone else's page and is now named, filed, and shaped
  as one (`personalization-settings-section.tsx`).
- Grouping: the 14 option tiles were loose in the accessibility tree — the
  sections were unnamed landmarks and the visible 编辑器主题 / 产品色调
  labels had no programmatic relationship to the grids they head. Sections
  now carry `titleId`, and each grid is a `role="group"` named by its label.
- Copy: the nav description still advertised 界面语言 on 外观, a page that
  has not had it since P2-13; 通用, which does, never mentioned it. Both
  descriptions now say what their page holds.
- Dead copy: `sections.paletteHelp` was defined in both locales and read by
  nobody, while the palette section reached into `appearance.persistenceHelp`
  for its lede. The palette section now takes its lede from `sections`, the
  same namespace the theme section above it uses, and the unread key is gone.

`AppearanceSettingsPage` also stops taking a `settings` prop it only passed
down one level to a component that never read it.

Contract: `astryx-component-behavior` pins one page stack, the four
labelledby anchors, three named groups, no 界面语言 on 外观, and that the
identity block opens no page stack of its own.

Verified: desktop typecheck; format:check; console/a11y/copy checks;
dead-css; 1754 desktop tests; and both pages re-rendered in a real Electron
fixture window (外观 unchanged apart from the two copy lines, 通用 pixel
identical).
@jackwener
jackwener force-pushed the are404/feat-appearance-settings-refresh branch from 13c598a to 6bba54a Compare August 7, 2026 15:46

@jackwener jackwener left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adversarial review — approve after rebase

Rebased onto current main and resolved conflicts:

  1. settings-navigation-copy — kept PR copy (界面语言 on 通用, theme/palette on 外观) and preserved main's projects nav entries (zh + en).
  2. astryx-component-behavior — kept main's onboarding-hero.tsx path and PR's PersonalizationSettingsSection export.

Structure checks

  • Single page root for 外观 (no nested settingsPageStack)
  • Identity block is a SettingsSection on 通用, not its own page
  • Named groups + titleIds for theme/palette tiles
  • CustomPetSettingsSection still mounted on appearance after rebase

Validation

  • desktop typecheck pass (after core/ui rebuild)
  • astryx-component-behavior: 10/10 pass (incl. new appearance/identity contracts)

No blocking product issues. LGTM once CI is green.

@jackwener
jackwener merged commit 9f1b0ad into apache:main Aug 7, 2026
12 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants