fix(settings): govern the 外观 page structure, grouping, and copy by ARE404 · Pull Request #2343 · apache/maka

ARE404 · 2026-08-06T15:08:59Z

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.

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

Adversarial review — approve after rebase

Rebased onto current main and resolved conflicts:

settings-navigation-copy — kept PR copy (界面语言 on 通用, theme/palette on 外观) and preserved main's projects nav entries (zh + en).
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.

ARE404 · 2026-08-06T15:08:59Z

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.

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

Adversarial review — approve after rebase

Rebased onto current main and resolved conflicts:

settings-navigation-copy — kept PR copy (界面语言 on 通用, theme/palette on 外观) and preserved main's projects nav entries (zh + en).
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.

ARE404 · 2026-08-06T15:08:59Z

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.

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

Adversarial review — approve after rebase

Rebased onto current main and resolved conflicts:

settings-navigation-copy — kept PR copy (界面语言 on 通用, theme/palette on 外观) and preserved main's projects nav entries (zh + en).
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.

ARE404 · 2026-08-06T15:08:59Z

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.

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

Adversarial review — approve after rebase

Rebased onto current main and resolved conflicts:

settings-navigation-copy — kept PR copy (界面语言 on 通用, theme/palette on 外观) and preserved main's projects nav entries (zh + en).
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.

ARE404 · 2026-08-06T15:08:59Z

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.

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

Adversarial review — approve after rebase

Rebased onto current main and resolved conflicts:

settings-navigation-copy — kept PR copy (界面语言 on 通用, theme/palette on 外观) and preserved main's projects nav entries (zh + en).
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.

ARE404 · 2026-08-06T15:08:59Z

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.

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

Adversarial review — approve after rebase

Rebased onto current main and resolved conflicts:

settings-navigation-copy — kept PR copy (界面语言 on 通用, theme/palette on 外观) and preserved main's projects nav entries (zh + en).
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.

ARE404 · 2026-08-06T15:08:59Z

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.

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

Adversarial review — approve after rebase

Rebased onto current main and resolved conflicts:

settings-navigation-copy — kept PR copy (界面语言 on 通用, theme/palette on 外观) and preserved main's projects nav entries (zh + en).
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.

ARE404 · 2026-08-06T15:08:59Z

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.

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

Adversarial review — approve after rebase

Rebased onto current main and resolved conflicts:

settings-navigation-copy — kept PR copy (界面语言 on 通用, theme/palette on 外观) and preserved main's projects nav entries (zh + en).
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.

ARE404 force-pushed the are404/feat-appearance-settings-refresh branch 2 times, most recently from b2db810 to 13c598aCompare August 7, 2026 00:24

jackwener force-pushed the are404/feat-appearance-settings-refresh branch from 13c598a to 6bba54aCompare August 7, 2026 15:46

jackwener approved these changes Aug 7, 2026
View reviewed changes