Archived on 2026-07-13. This reverse-engineering snapshot is provenance, not the current Settings contract.
Cross-checked by 4 parallel Explore agents on the extracted bundle at /tmp/qoder-asar/out/renderer/assets/.
This note captures the reference's Settings module so future Maka PRs can align without re-doing the dig. Naming hygiene applies: do not surface the reference product name in code, commits, or end-user copy.
Settings is a full-pane modal that takes over the workspace area. It is NOT a small overlay sheet.
role="dialog" + aria-modal="true"data-modal="agents-settings", data-canvas-dialog="true", data-settings-layout="page"flex h-full min-h-0 w-full flex-col overflow-hidden bg-background select-none
| Region | Width / sizing | Notes |
|---|---|---|
| Nav rail | w-[256px] shrink-0 | Left side, bg-transparent, full height |
| Content | flex-1 min-w-0 overflow-hidden | Right side, scrolls on the inner column |
| Gap | var(--agents-content-area-gap) 4px | Margin between rail and content plate |
Content pane class: agents-settings-wide-content:
.agents-settings-wide-content { background: var(--agents-content-area-bg); margin: var(--agents-content-area-gap) var(--agents-content-area-gap) var(--agents-content-area-gap) 0; border-radius: var(--agents-content-area-radius); /* 6px */ }
Content body inner wrapper (where the page lives):
mx-auto min-h-[200px] max-w-3xl pb-16 pt-10
max-w-3xl = 48rem / 768px. That's the optical reading column for any settings page body.
| Breakpoint | Behavior |
|---|---|
| ≥ 1200px | Two-rail (256px rail + content) |
| 900–1199 | Two-rail, tightened |
| < 900px | Compact: rail collapses; header shows back-arrow + title |
The rail is a flat vertical list (no group headings — purely flat).
preferences — Preferences (the big aggregator)profile — Profile / accountsystem — System (intentionally near-empty placeholder)keyboard — Keyboard shortcutsvm — Secure workspace / VM modeexperimental — Experimental flagspermissions — System capability togglesconnector — Integrations / connectorsappshot — App snapshot (macOS only, gated by platforms: ["darwin"])appearance (handled via the Preferences page itself), privacy, debug, hiddenConnector, awareness, appUpdate, models, customModels, commands, agents, worktrees, quickpick, voiceInput, wechat, beta, channels, legokit, archived — all exposed: false.
Tab registry lives in index-C02cm0ok.js around offset ~213400 (look for Su=[]).
<!-- inactive --> <button class="squircle-md text-text-secondary/80 hover:bg-[var(--settings-nav-row-selected-bg)] hover:text-text/80"> <Icon size=… /> <span>Label</span> </button> <!-- active --> <button class="squircle-md bg-[var(--settings-nav-row-selected-bg)] text-text/80"> … </button>
--settings-nav-row-selected-bg = var(--color-fill-secondary)px-4 py-3gap-3squircle-md (custom corner, not pure rounded-md)Globals offset ~76380–80000. This single tab carries the bulk of the end-user controls:
| Control | Type | Notes |
|---|---|---|
| Language | select | UI locale |
| Extended Thinking | switch | Bigger reasoning budget, disables streaming |
| Launch at Login (autoLaunch) | switch | Auto-start |
| Close Window Behavior | radio / select | Ask / Minimize-to-tray / Quit |
| Desktop Notifications | switch | Native OS notifications |
| Sound Notifications | switch | Audio on task completion |
| Include Co-Authored-By | switch | Adds Co-authored-by: trailer to git commits |
| Quick Switch (Ctrl/Cmd+Tab) | radio | Workspaces vs Agents |
| Auto-advance after archive | radio | Next / Prev / Close |
| Default Mode (new agent) | radio | Agent / Plan |
| Preview Mode (artifactPreview) | radio | New window / Right sidebar |
| Expand tool calls by default | switch | Tool-block collapsed vs expanded |
| Show tool steps in IM channels | switch | Whether bot-reply surfaces include tool-call sub-steps |
| Tool execution limit | number input | Soft pause when one turn exceeds N tool calls |
| Keep System Awake (preventSleep) | switch | While Agent works |
| Network Proxy | proxy block | System / Manual; URL input + test button + scheme validation |
| Chat Settings (sub-section) | composite | Theme brightness, interface style, glass effects, font face, font size, chat width |
Key insight: reference does NOT split “system-level” toggles (autoLaunch / preventSleep / notifications / proxy / closeWindowAction) into a separate System tab. They live alongside chat/agent toggles in ONE long Preferences page.
Title only. No fields. Placeholder for future use. The page exists in the nav but its body is intentionally empty / “to be defined.” Confirmed by walking the bundle.
Two sections:
appearance i18n key — actually rendered insidePreferences in production)
| Control | Type | Options |
|---|---|---|
| Interface theme | select | System pref / Light / Dark / Light Glass / Light Clear (win) / Dark Glass / Dark Clear (win) / Classic Dark / Parchment Light / Parchment Dark / From editors |
| Light variant | select | Per-mode theme |
| Dark variant | select | Per-mode theme |
| Workspace icon in sidebar | switch | Project glyph in the sidebar workspace list |
| Always expand to-do list | switch | Full vs compact to-do view |
Brief description: “dedicated space on your computer for running tasks — faster, more reliable, on-device.” Enable/disable toggle.
Beta feature toggles. Per-flag rows; roster managed in the renderer component, not visible as a literal array in the bundle.
“System permissions QoderWork needs on this Mac.” Capability rows (filesystem / network / mic / screen recording / accessibility) with “granted / not granted” status and a “request” CTA.
Integrations with external apps. Builtin connectors / market connectors / custom connectors. Each row: brand glyph, status, enable toggle, “configure” button.
macOS-only. Frontmost-app screenshot capture for chat context. Needs Accessibility + Screen Recording perms. Permission status row + capture preview.
Reference does NOT use bordered card containers around groups of controls. The default presentation is a flat row list inside the max-w-3xl column.
2c810f2d 2026-06-23WAWQAQ called out the left/right whitespace as visibly wider in reference than in Maka. Concrete numbers from a second RE pass:
mx-auto max-w-3xl pt-10 pb-16 (= 768px wide, 40px top, 64px bottom). No explicit px-N is applied inside the column — the side whitespace comes from the column NOT filling the right pane.px-5 py-4 (20px / 16px). Rows do NOT carry their own border, background plate, or shadow — separation is pure spacing.Maka delta found 2026-06-23:
.settingsStructuredPage had gap: 16px but NO max-width / margin: 0 auto — rows stretched to fill the right pane. Fixed to max-width: 768px; margin: 0 auto; padding: 40px 24px 64px..settingsFormRow had border-bottom: 1px solid var(--border) and padding: 6px 0 — both wrong. Reference uses spacing-only and px-5 py-4. Fixed to padding: 16px 20px, no border-bottom..settingsRow was sharing .providerCard chrome (bordered, tinted, lifted). Provider cards keep their chrome (they ARE cards); .settingsRow flattened to a flex row.text-sm font-medium + text-xs text-text-quaternary.flex items-center gap-3 px-4 py-3 /* group */ ├── label column │ ├── truncate text-sm font-medium text-text (title) │ └── mt-0.5 truncate text-xs text-text-quaternary (hint) └── control (right-aligned)
.group (e.g., shows a kebab menu)text-sm font-semibold text-text mb-4
rounded-mdbg-primary/20 ring-1 ring-primary/40 scale-[0.97]bg-gray-100 dark:bg-neutral-600) with inset shadowtransition-all duration-200w-full px-3 py-2 text-sm bg-background border rounded-md border-border-tertiary/80 focus:outline-none focus:ring-2 focus:ring-primary/50
border-error-borderpr-9bg-primary text-primary-foregroundbg-muted text-foregroundborder border-border text-foreground hover:bg-mutedtext-error hover:bg-error-bgsize-7 rounded-md (28px square), size-8 rounded-full (32 round)rounded bg-fill-tertiary px-1.5 py-0.5 text-[10px] font-medium text-text-tertiary
The page body owns its scroll:
min-h-0 flex-1 overflow-y-auto scrollbar-none
Custom scrollbar is hidden. The inner content column has pb-16 bottom padding so the last row never hugs the modal edge.
| Token | Value |
|---|---|
--agents-content-area-bg | var(--color-bg-container) |
--agents-content-area-gap | 4px |
--agents-content-area-radius | 12px |
--agents-layout-bg | var(--surface-canvas) (flat neutral shell — DO NOT paint a 172deg gradient here, see warning below) |
--settings-nav-row-selected-bg | var(--color-fill-secondary) |
⚠️ DO NOT paint a 172deg gradient on the layout/shell background.
The RE notes here historically said
--agents-layout-bgislinear-gradient(172deg, var(--color-fill-tertiary) 19.61%, var(--color-bg-container) 81.35%). That value was an artifact of the bundle CSS we copied, not what the live reference product actually paints. WAWQAQ has called this out four times in a row (msgs1e693dee/5d3b10e5/486b5611/4a1b8c13) — “谁让你他妈的用渐变的啊？ 参考实现就没有啊”. Every time we re-added the gradient because some atlas/RE note claimed it was canon.Source-side enforcement:
apps/desktop/src/main/__tests__/chat-chrome-no-gradient-contract.test.tsfails if any of.appFrame,html[data-os="darwin"] .maka-session-panel, or the floating panel reintroduces a gradient / border-right / smaller-than-12px radius. If a future RE iteration finds a new place where the reference product genuinely does paint a gradient, please update the contract test with the new exception in the same PR, don't silently lift the assertion.Use a flat neutral shell (
var(--surface-canvas)) behind the white content surface. Do not collapse the shell to the same white as the content card: that removes the visible lower radius and lets the bug come back even without a border or gradient.Rendered-pixel enforcement: after capturing
sidebar-long-sessions/light-1280-motion, runnpm --workspace @maka/desktop run screenshots:chat-chrome:check. It verifies the actual PNG has a visible shell/content delta, no dark one-pixel seam, and readable bottom surface corners.Surface radius is 12px (was historically noted as 6px). 6px was geometrically there but optically invisible — bottom corners of the floating content card didn't read against a same-color shell.
Color tokens consumed inside settings:
--color-text (primary text)--color-text-secondary--color-text-tertiary (hints)--color-text-quaternary (de-emphasized)--color-border (strong divider)--color-border-tertiary (input borders)--color-fill-secondary (active row fill)--color-fill-tertiary (chip background)--color-bg-container (page surface)--color-primary, --color-primary/20, --color-primary/40 (focus, switch on, ring)?view=settings&tab=preferences. No localStorage for the active tab — round-tripping the URL restores the page.qoder-work://settings/preferences. Maka's equivalent could be maka://settings/<tab>.tab param: preferences.[role="dialog"].settings_tab_view fires when a tab is selected; settings_heartbeat ticks every 300s with a feature-flag snapshot.This RE matters because WAWQAQ's ask — “add a 系统设置 section” — is ALMOST CORRECT but the deeper truth from the reference is:
Reference does NOT scatter system-level toggles into their own narrow pages. It collapses them into ONE long Preferences page, and reserves a near-empty system tab for future expansion.
Maka today has 17 nav items in Settings (some of them — 网络, 健康, 开放网关, 语音模型, 每日回顾, 记忆 — are single-purpose pages that mirror exactly the “wasteful single-purpose page” pattern WAWQAQ flagged for 网络).
The closer-to-reference move is to consolidate, not add another section. Concrete proposal:
| Group | Item | Holds |
|---|---|---|
| 基础 | 通用 | Aggregator: 隐身模式, 启动行为, 新对话模式, 默认模型, 通知, 网络代理, 保持唤醒, 自动更新, 关闭窗口行为 |
| 基础 | 外观 | 个性化 + theme + palette + font (merge 主题 + 个性化) |
| AI | 模型 | Provider connections + OAuth + per-model config |
| AI | 记忆与回顾 | Merge 记忆 + 每日回顾 |
| AI | 语音与网关 | Merge 语音模型 + 开放网关 |
| 集成 | 机器人对话 | Telegram / WeChat / Slack bot config |
| 集成 | 联网搜索 | Tavily provider config |
| 数据/系统 | 数据 | Export / import / wipe |
| 数据/系统 | 权限与能力 | Capability toggles + filesystem allowlist |
| 其他 | 健康 | Diagnostic / status / logs |
| 其他 | 关于 | Version + license + acknowledgements |
Specifically: drop the standalone 网络 page; move proxy into 通用. That‘s the minimum WAWQAQ asked for, but ride the same PR to merge 主题 + 个性化 into 外观 per reference, since 外观 is reference’s canonical name for that grouping.
For ANY settings page body, switch to:
max-w-3xl mx-auto pt-10 pb-16 inner columnflex items-center gap-3 px-4 py-3 per row)text-sm font-medium title + text-xs text-text-quaternary hinttext-sm font-semibold mb-4This is the visual “reference 真好看” pattern WAWQAQ asked us to study — the page is uncluttered because rows have NO chrome, only spacing.
Two PRs, ship in sequence:
PR-SETTINGS-ALIGN-IA-0 — Information architecture consolidation
网络 page; fold proxy into a “网络代理” sub-section of 通用主题 + 个性化 → 外观记忆 + 每日回顾 → 记忆与回顾语音模型 + 开放网关 → 语音与网关maka://settings/...)PR-SETTINGS-PAGE-BODY-0 — Visual pattern conversion
settingsStructuredPage / SettingRow card chrome to the flat-row + max-w-3xl recipe.maka-settings-row, .maka-settings-page primitives in styles.cssTackle them in this order so the IA stops shifting while we're polishing the bodies.