Codex

How every settings page — a control panel of small, independent decisions — is built. The kit is src/components/settings-page/ (+ the form kit's FormFooter for save-gated cards); the living example is /labs/layout/settings. Same contract as data-view.md: the kit enforces what it can with defaults, this file records the rest.

Sibling boundary with form.md: a form is an interview — one record, one submit, dirty covers the whole page. A settings page is a control panel — many independent decisions, visited repeatedly, changed one at a time. Misclassifying costs real UX: an interview chopped into per-card saves nags; a control panel behind one giant Save loses edits from three sections up.

Every section is its own feature, so every section is its own Card — the inverse of the form's one-Card-of-sections, and the cross-class law's "a page with several features shows several cards" in its purest form. The stack sits on the same max-w-2xl measure as forms so the two classes read as kin.

<SettingsStack>
  <SettingsCard title="General" description="…"
    footer={<FormFooter dirty={isDirty}>…Reset · Save…</FormFooter>}>
    …identity fields (a miniature form per docs/form.md)…
  </SettingsCard>

  <SettingsCard title="Preferences" description="…">
    <SettingRow label="Language" description="…" htmlFor="lang">
      <Select … onValueChange={applyAndToast} />
    </SettingRow>
    <SettingRow label="Compact mode" description="…" htmlFor="compact">
      <Switch … onCheckedChange={applyAndToast} />
    </SettingRow>
  </SettingsCard>

  <SettingsCard danger title="Danger zone" description="…">
    <SettingRow label="Delete workspace" description="…">
      <AlertDialog>…destructive Button → typed confirm…</AlertDialog>
    </SettingRow>
  </SettingsCard>
</SettingsStack>

Each card commits to exactly one semantic; mixing them in one card is the class's central anti-pattern.

• Instant — toggles, selects, segmented choices. Applying is the interaction; every change toasts so the user knows it stuck. No Save button, no dirty state.
• Save-gated — free-text identity fields (names, slugs, URLs), anything where half-typed values must not go live. The card carries a dirty-gated FormFooter; dirty scope is THAT CARD only.
• Confirm-gated — destructive actions. Never instant, never dirty-gated: an AlertDialog is the gate, and truly irreversible actions (delete) require typing the resource name to arm the button.

Which semantic a control gets follows from the control type, not taste — that's what makes ten settings pages feel like one product.

• One card, one semantic. A Save button whose card also contains instant toggles teaches the user that Save is sometimes decorative — the worst possible lesson.
• Instant changes toast. A silent toggle flip is indistinguishable from a broken one.
• Dirty never crosses cards. Editing General must not arm a Save in Notifications; each save-gated card owns its own form state.
• The danger zone is last, ringed, and confirmed. Every action in it opens an AlertDialog; delete-grade actions arm only when the user types the resource name. The zone never uses dirty-gating — confirmation IS the gate.
• Consequences are written down. Every row's description states what the setting does, not what it is called.

1. Sort the decisions into sections; each section becomes a SettingsCard.
2. Classify each card: instant / save-gated / danger — by control type.
3. Instant rows: apply on change + toast. Save-gated cards: a zod schema + RHF per card, FormFooter gated on that card's isDirty.
4. Danger zone last: danger card, AlertDialog per action, typed confirm for irreversibles.
5. Register the route and extend the feature ledger.

• One page-wide Save button over many sections (that's a form pretending).
• Instant toggles and a Save footer in the same card.
• A toggle that applies silently, or a select that waits for a Save.
• A danger zone anywhere but last, or a destructive action without its dialog.
• Dirty state shared across cards.
• A row description that restates the label instead of the consequence.