AGENT SKILL

settings-and-preferences

Builds app settings - saved fields, defaults, rows, each setting's effect, resets that keep them. Use when adding a setting or toggle, or a setting is ignored or lost on restart. Not for theme tokens (design-system-structure).

License 许可
MIT
最近更新
2026-10-22
Stars
★ 13
Forks
2

01 前言 Front Matter

name
settings-and-preferences
description
Builds app settings - saved fields, defaults, rows, each setting's effect, resets that keep them. Use when adding a setting or toggle, or a setting is ignored or lost on restart. Not for theme tokens (design-system-structure).

02 资源文件 92

03 SKILL.md 正文

Settings and preferences

Every setting is saved in one place, changed by one action, shown by one row, and applied by code outside the settings screen, at once and without a Save button; data resets never touch it, and a checker proves the whole chain against the app's own settings contract on iOS and Android alike.

Rules that must hold

  1. One settings model, one owner. Every saved preference is a field of one strict valibot object (SETTINGS_SCHEMA in src/stores/settings/) and is listed in contracts/settings.json with its validator, first-launch value, action and effect; nothing else keeps a copy (no useState mirror, no side cache, no zustand persist, no second key-value write). Why: one place to read, change and decode, so a restart can never show an older value. (settings-schema, single-writer)
  2. Saved through one synchronous adapter, read before the first paint. Default: expo-sqlite/kv-store behind SettingsStoragePort, one JSON value under one key, read in the root layout's first-render initializer. Why: the first frame already has the saved theme and language, and one key is one atomic write. (hydrate-sync)
  3. Reduce, persist, then publish; a failed write publishes nothing. The screen never shows a value that is not saved, the failure is shown (settings.save-failed), and storage that cannot be read runs the session in memory without overwriting it. No Save button, no delayed write. (persist-then-publish)
  4. One pure reducer action per change; ranges clamped in the reducer. Imperative kebab-case (set-theme), a no-op returns the same object (nothing written), integer percent rounded and clamped with a property test. Why: every change is testable without React and replays the same. (reducer-action)
  5. Decode field by field; a stored field never changes shape in place. A missing field takes its default quietly, an unreadable one falls back alone and is recorded, a new meaning gets a new field name, and a frozen sample of every shipped shape keeps decoding. Why: the key-value store has no migrations, and one bad value must never reset every setting.
  6. First-launch values follow the phone; noise is opt-in. Settings that mirror a phone setting (language, theme, reduce motion, digits) start at 'system'/null; sound and anything that interrupts start off; every other value is a product decision written in the contract. (settings-default)
  7. Every setting has an effect outside the settings code, applied at once, through one of four mechanisms: a provider re-render (PreferencesRoot feeds I18nProvider, AppThemeProvider preference, the reduce-motion preference context the root stack's RootMotion hands to MotionConfig), a store subscription started at startup that returns its unsubscribe (sound), an adapter that reads the store at call time (the haptics gate: created before the services, connected once the store opens, silent until then), or a feature hook reading a selector. Why: a setting nothing reads is a bug people see. (setting-effect)
  8. Store canonical units; convert at the edge. The volume is integer percent; toSoundOutput divides by 100 for the 0..1 an audio API takes; a 0..1 slider dispatches only when the whole percent changes. (unit-scale)
  9. Every row dispatches its action; rows that do not apply are hidden, never greyed. Visibility is the pure settingsGroupsFor(context) over facts (haptics supported, Premium owned, a consent entry point needed), each rule unit-tested; testIDs and label keys come from one typed table. Why: a disabled control nobody can enable is noise for VoiceOver and TalkBack. (row-dispatch)
  10. A language change switches the text at once; only a layout-direction flip restarts, after the person confirms. planLanguageChange compares the new language's direction with the layout's and the choice is saved either way. Why: React Native applies a direction at the next start, and a needless restart throws away state. (restart-on-direction-only)
  11. Resets never touch the settings. "Delete all data" (createDataResets) deletes data through the data layer (persistence-and-migrations owns the SQL) and keeps settings and purchases (and first-run flags, unless the product decides otherwise); no code outside the storage adapter clears a whole key-value store (Storage.clearSync(), AsyncStorage.clear()); a failed delete is shown, never silent; "Reset settings" is its own action and confirmation; a save-document reset is one write inside updateAndPublish's callback. (reset-keeps-settings, reset-publish)
  12. A switch plays its feedback once, after the dispatch (the model input onToggled, which calls playUiFeedback(services, 'toggle'); never the press feedback); sliders and segments play none. Why: the feedback reads the settings at call time, so "sound off" is already silent. (toggle-feedback, when the contract sets it)
  13. Reduce motion is tri-state. The switch shows the resolved value (useReduceMotion()) and writes the opposite explicitly ('on'/'off'); accessibility-as-code owns the resolution and the ban on Reanimated's useReducedMotion, and design-system-structure owns the theme provider.

Workflow

  1. Read references/settings-model.md: where each piece lives, the fields and first-launch values, persistence, decoding, the effects table, iOS and Android, resets, the contract keys and every checker rule.

  2. New settings model. npx expo install expo-sqlite expo-localization, then npm install -E zustand@5.0.15 valibot@1.5.0 (stack table, verified 2026-10-03; re-verify with npm view zustand@5 version). Copy templates/src/stores/settings/ (schema, codec, reducer and its settings-reducer-cases.ts table, selectors, store), templates/src/services/settings-storage/, templates/src/data/open-device-settings.ts and templates/contracts/ to contracts/. Replace the Tasks fields with the app's own, in the contract first, then the schema, defaults, codec v.fallback lines, actions, reducer cases and selectors.

  3. Wire the startup (copy templates/src/features/settings-effects/): in the root layout's decideStartup create the gate (createHapticsGate()) before createDeviceServices, whose haptics adapter takes gate.isEnabled, and resolve the language from readSavedLanguage(...) (examples/root-layout.tsx); in AppRoot's startApp, after the data layer and the error sink, open the store (openDeviceSettings(errorLog)), then gate.connect(settings) and connectSoundSettings (audio-and-haptics-feedback owns both ports); render SettingsStoreProvider and PreferencesRoot in place of fixed provider values; the canonical root-stack.tsx stays as it is (its RootMotion reads the preference PreferencesRoot provides) (examples/app-root.tsx, examples/app-providers.tsx).

  4. The screen. Read references/rows-and-controls.md. Copy templates/src/features/settings/ and templates/src/config/external-links.ts, merge templates/src/i18n/catalogs/*.json into the app's catalogs (translate for every app language), add the route as examples/settings-route.tsx and the view as examples/settings-screen.tsx with the ui-component-library rows and the three confirm dialogs; gather the row facts (signed in, haptics, Premium, consent) and the dataResets wiring (updateAndPublish around the data layer's reset) as examples/use-settings-input.ts. Fill PRIVACY_POLICY_PAGE: its test fails while the placeholder is left in. The account rows hand off to auth-and-secure-storage.

  5. Adding or changing a setting: follow "Adding or changing a setting" in the model reference: contract, schema and defaults, codec line and a frozen sample, action (test first), selector, row, effect. A new setting is a product decision: ask the developer first.

  6. Save document instead of the key-value store (persistence-and-migrations' document mode): use examples/settings-contract-document-mode.json as the contract and read the model reference's appendix.

  7. Test, then npm run typecheck:

    npx jest src/stores/settings src/services/settings-storage src/features/settings \
      src/features/settings-effects src/config --ci --maxWorkers=2
    
  8. On devices, after a change to the storage or the startup: change the theme, kill and relaunch on a named iOS simulator and a named Android emulator (commands in the rows reference); the first frame must show the saved theme. Without devices, say in the report that this check is owed.

  9. Run the checker from the repo root: node ${CLAUDE_SKILL_DIR}/scripts/check-settings.mjs .; fix every FAIL line (file, rule and fix are printed) and rerun until it prints RESULT: PASS.

Definition of done

  • [ ] contracts/settings.json lists every field (validator, first-launch value, action, effect) and every action; schema and defaults match it, and the codec has a v.fallback line per field.
  • [ ] The store hydrates synchronously, persists before it publishes, publishes nothing on a failed write, and never writes when the saved settings could not be read; its tests pass.
  • [ ] Every action has a reducer case and a test; every range is clamped with a property test; the codec test holds a frozen sample of every shipped shape.
  • [ ] Every row dispatches its action; hidden rows follow settingsGroupsFor and its tests; row testIDs and labels come from the typed tables and every app catalog has the keys.
  • [ ] Every field's effect is wired and tested outside the settings code; percent values are converted at the edge.
  • [ ] A language of the other direction opens "Restart to apply"; the same direction switches at once.
  • [ ] Data resets keep the settings and purchases (first-run flags as the product decided), and a failed delete shows settings.delete-all-data.failed; "Reset settings" is its own confirmed action.
  • [ ] The Privacy policy row opens the app's real https page (PRIVACY_POLICY_PAGE filled in).
  • [ ] The restart check passed on a named iOS simulator and a named Android emulator, or the report says it is owed.
  • [ ] node ${CLAUDE_SKILL_DIR}/scripts/check-settings.mjs . prints RESULT: PASS (expected only before the data layer exists: SKIP src/data/reset-data.ts [reset-keeps-settings] not yet created (persistence-and-migrations creates it); an app with no settings prints NOT APPLICABLE).

Anti-patterns

  • A local useState copy of a setting in the screen. It drifts from the store and skips the save; read the store and dispatch.
  • A Save button or a debounced write. Every change is saved at once; the store already persists before it publishes.
  • Loading settings with an async API after the first render. The app flashes the default theme and language; read synchronously in the first-render initializer.
  • zustand's persist middleware or AsyncStorage for settings. A second, unversioned copy that publishes before it saves; use the storage port.
  • One storage key per field. A two-field change becomes two writes and can be half saved; one JSON value under one key.
  • Resetting every setting because one saved value is unreadable. Decode field by field.
  • Reading settings.reduceMotion or settings.theme directly in a component. 'system' must resolve against the phone; the providers and useReduceMotion() do that.
  • Passing the stored percent to a 0..1 API or a 0..1 slider value straight into the store. Convert at the edge; dispatch only whole-percent changes.
  • Greying out rows that do not apply. Hide them, from the pure visibility function.
  • Restarting for every language change, or opening the restart dialog after a failed save (the restart comes back in the old language).
  • Clearing the whole key-value store in "Delete all data" (Storage.clearSync(), AsyncStorage.clear()): the settings go with it. Delete through the data layer.
  • Playing the toggle sound in the row component, or before the dispatch. It sounds twice, and "sound off" still clicks.

Files in this skill

File What it is Read/run when
references/settings-model.md Homes, fields, defaults, persistence, decoding, actions, effects, iOS and Android, resets, adding a setting, document mode, multi-package, contract keys, checker rules Workflow steps 1, 5 and 6
references/rows-and-controls.md Route, model and view; each row kind with VoiceOver and TalkBack; slider pitfall; language list and restart; dialogs; copy keys; testIDs and device flows; tests; React Navigation appendix Workflow steps 4 and 8
templates/src/stores/settings/ Schema and defaults, codec, reducer and settings-reducer-cases.ts (the rules as data, also read by state-management-zustand's reducer checker), selectors, store, store context, each with its test (synced canonical copies: never edit here) Workflow step 2
templates/src/services/settings-storage/ SettingsStoragePort and its fake with a test (synced), and the expo-sqlite/kv-store adapter Workflow step 2
templates/src/data/open-device-settings.ts Creates the store over the key-value adapter (composition root) Workflow steps 2 and 3
templates/src/features/settings-effects/ PreferencesRoot (language, digits, theme, reduce motion), connectSoundSettings, createHapticsGate, readSavedLanguage (for rtl-and-direction's DirectionGate), with tests Workflow step 3
templates/src/features/settings/ Rows and visibility (with the account group), preference handlers, data-resets.ts ("Delete all data" after its confirmation), the model hook, the language-change plan, with tests Workflow step 4
templates/src/config/ external-links.ts (privacy policy page, store review page per platform, support mail) and its test Workflow step 4
templates/src/i18n/catalogs/ The settings copy keys in en and ar, merged into the app's catalogs Workflow step 4
templates/contracts/ settings.json (the Tasks contract) and settings.schema.json Workflow steps 2 and 5
examples/root-layout.tsx The canonical root layout with the haptics gate and the saved language in decideStartup Workflow step 3
examples/app-root.tsx The canonical AppRoot opening the store, connecting the effects and rendering PreferencesRoot Workflow step 3
examples/app-providers.tsx AppRoot's outer providers with SettingsStoreProvider after the data layer Workflow step 3
examples/settings-route.tsx Thin Expo Router route and its feature hook shape (row hand-offs, the three dialogs) Workflow step 4
examples/settings-screen.tsx The pure screen view over the model: rows, failure notes heard on both platforms, confirm dialogs Workflow step 4
examples/use-settings-input.ts Where the row facts, locales, layout direction and the data-reset wiring come from Workflow step 4
examples/settings-contract-document-mode.json The contract for settings kept in the save document Workflow step 6
scripts/check-settings.mjs Checker for the contract, schema, defaults, actions, store, writers, rows, effects, units, resets, restarts and feedback Workflow step 9, and at the end
scripts/selftest.mjs Proves the checker passes the templates and catches every planted bug After changing the checker
scripts/check-lib.mjs Shared script helpers, synced from the library (do not edit here) Never by hand
scripts/lib/object-literal.mjs Shared object-literal reader, synced (do not edit here) Never by hand
assets/shared.json Declares the synced files (check-lib, the object-literal reader, the canonical store and port files) When adding a shared file
assets/template-placeholders.json Sample values for the template placeholders (__PRIVACY_POLICY_URL__) used when the templates are verified When adding a placeholder
tests/ bases/app/ (a minimal app) and fixtures/ (overlay cases over the templates, including document mode and silent decoys) When adding a rule to the checker

Related skills

  • state-management-zustand - the store pattern, selectors and useShallow, updateAndPublish.
  • persistence-and-migrations - the key-value boundary, the save document, data resets.
  • design-system-structure - AppThemeProvider and its preference prop.
  • accessibility-as-code - MotionConfig, useReduceMotion(), roles and targets.
  • i18n-strings-and-catalogs - I18nProvider, language resolution, digits, catalogs.
  • rtl-and-direction - the layout direction and the restart that applies it.
  • audio-and-haptics-feedback - the audio and haptics ports the effects drive.
  • ui-component-library - the row, slider, segmented and dialog components.
  • auth-and-secure-storage - the Sign out and Delete account rows' flows.
  • navigation-and-routing - the settings routes and sub-screens.
  • in-app-purchases, admob-ads-and-consent - the Premium and privacy-choices rows.
  • local-notifications, permissions-and-system-prompts - reminder settings and system settings links.
  • e2e-maestro - the restart flow on named devices.

04 同仓库更多 Skills