Merge remote-tracking branch 'origin/master' into jb/ref/migrate-personal-tokens-form

# Conflicts:
#	static/app/utils/useMutateApiToken.tsx
#	static/app/views/settings/account/apiNewToken.spec.tsx
#	static/app/views/settings/account/apiNewToken.tsx
#	static/app/views/settings/account/apiTokenDetails.tsx

Author: priscilawebdev

.agents/skills/cell-architecture/SKILL.md

@@ -51,7 +51,7 @@ import {Container} from '@sentry/scraps/layout';
 
 // ❌ Don't create styled components
 const Component = styled('div')`
-  padding: ${space(2)};
+  padding: ${p => p.theme.space.md};
   border: 1px solid ${p => p.theme.tokens.border.primary};
 `;
 
@@ -119,7 +119,7 @@ import {Grid} from '@sentry/scraps/layout';
 const Component = styled('div')`
   display: grid;
   grid-template-columns: repeat(3, 1fr);
-  gap: ${space(2)};
+  gap: ${p => p.theme.space.md};
 `;
 
 // ✅ Use Grid primitive
@@ -147,7 +147,7 @@ import {Stack} from '@sentry/scraps/layout';
 const Component = styled('div')`
   display: flex;
   flex-direction: column;
-  gap: ${space(2)};
+  gap: ${p => p.theme.space.md};
 `;
 
 // ✅ Use Stack primitive (automatically column direction)
@@ -204,7 +204,7 @@ import {Text} from '@sentry/scraps/text';
 // ❌ Don't create styled text components
 const Label = styled('span')`
   color: ${p => p.theme.tokens.content.secondary};
-  font-size: ${p => p.theme.fontSizes.small};
+  font-size: ${p => p.theme.font.size.sm};
 `;
 
 // ❌ Don't use raw elements
@@ -242,7 +242,7 @@ import {Heading} from '@sentry/scraps/text';
 
 // ❌ Don't style heading elements
 const Title = styled('h2')`
-  font-size: ${p => p.theme.fontSize.md};
+  font-size: ${p => p.theme.font.size.md};
   font-weight: bold;
 `;
 
@@ -401,7 +401,7 @@ Container supports `margin` props but they are deprecated. Use `gap` on parent c
 ```tsx
 // ❌ Don't use margin between children
 const Child = styled('div')`
-  margin-right: ${p => p.theme.spacing.lg};
+  margin-right: ${p => p.theme.space.lg};
 `;
 
 // ✅ Use gap on parent container
@@ -421,7 +421,7 @@ const Component = styled('div')`
   display: flex;
   flex-direction: column;
   color: ${p => p.theme.tokens.content.secondary};
-  font-size: ${p => p.theme.fontSize.lg};
+  font-size: ${p => p.theme.font.size.lg};
 `;
 
 // ✅ Split into layout and typography primitives

.agents/skills/design-system/SKILL.md

@@ -9,7 +9,7 @@ This skill provides patterns for building forms using Sentry's new form system b
 
 ## Core Principle
 
-- Always use the new form system (`useScrapsForm`, `AutoSaveField`) for new forms. Never create new forms with the legacy JsonForm or Reflux-based systems.
+- Always use the new form system (`useScrapsForm`, `AutoSaveForm`) for new forms. Never create new forms with the legacy JsonForm or Reflux-based systems.
 
 - All forms should be schema based. DO NOT create a form without schema validation.
 
@@ -21,7 +21,7 @@ All form components are exported from `@sentry/scraps/form`:
 import {z} from 'zod';
 
 import {
-  AutoSaveField,
+  AutoSaveForm,
   defaultFormOptions,
   setFieldErrors,
   useScrapsForm,
@@ -439,6 +439,44 @@ const userSchema = z.object({
 });
 ```
 
+### Nullable Fields with Refine
+
+When a field starts as `null` (e.g., a required select with no initial selection), use `.nullable().refine()` in the schema. This creates a difference between the schema's _input_ type (which accepts `null`) and its _output_ type (which does not). To handle this correctly:
+
+1. Type `defaultValues` explicitly as `z.input<typeof schema>` — this allows `null` as an initial value.
+2. Call `schema.parse(value)` inside `onSubmit` to narrow from `z.input` to `z.output`, stripping the `null` before passing to your mutation.
+
+```tsx
+const schema = z.object({
+  provider: z
+    .enum(['GitHub', 'LaunchDarkly'])
+    .nullable()
+    .refine(v => v !== null, 'Provider is required'),
+  name: z.string().min(1, 'Name is required'),
+});
+
+// z.input allows null for the provider field
+const defaultValues: z.input<typeof schema> = {
+  provider: null,
+  name: '',
+};
+
+// z.output<typeof schema> has provider as non-null after refine
+type FormOutput = z.output<typeof schema>;
+
+const form = useScrapsForm({
+  ...defaultFormOptions,
+  defaultValues,
+  validators: {onDynamic: schema},
+  onSubmit: ({value}) => {
+    // schema.parse narrows null away — mutation receives z.output
+    return mutation.mutateAsync(schema.parse(value)).catch(() => {});
+  },
+});
+```
+
+> **Important**: Do NOT use non-null assertions (`value.provider!`) or type casts to work around nullable fields. The `schema.parse()` approach is both type-safe and validates at runtime.
+
 ### Conditional Validation
 
 Use `.refine()` for cross-field validation:
@@ -532,14 +570,14 @@ Validation errors automatically show as a warning icon with tooltip in the field
 
 ## Auto-Save Pattern
 
-For settings pages where each field saves independently, use `AutoSaveField`.
+For settings pages where each field saves independently, use `AutoSaveForm`.
 
-### Basic Auto-Save Field
+### Basic Auto-Save Form
 
 ```tsx
 import {z} from 'zod';
 
-import {AutoSaveField} from '@sentry/scraps/form';
+import {AutoSaveForm} from '@sentry/scraps/form';
 
 import {fetchMutation} from 'sentry/utils/queryClient';
 
@@ -549,7 +587,7 @@ const schema = z.object({
 
 function SettingsForm() {
   return (
-    <AutoSaveField
+    <AutoSaveForm
       name="displayName"
       schema={schema}
       initialValue={user.displayName}
@@ -572,7 +610,7 @@ function SettingsForm() {
           <field.Input value={field.state.value} onChange={field.handleChange} />
         </field.Layout.Row>
       )}
-    </AutoSaveField>
+    </AutoSaveForm>
   );
 }
 ```
@@ -603,7 +641,7 @@ The form system automatically shows:
 For dangerous operations (security settings, permissions), use the `confirm` prop to show a confirmation modal before saving. The `confirm` prop accepts either a string or a function.
 
 ```tsx
-<AutoSaveField
+<AutoSaveForm
   name="require2FA"
   schema={schema}
   initialValue={false}
@@ -619,7 +657,7 @@ For dangerous operations (security settings, permissions), use the `confirm` pro
       <field.Switch checked={field.state.value} onChange={field.handleChange} />
     </field.Layout.Row>
   )}
-</AutoSaveField>
+</AutoSaveForm>
 ```
 
 **Confirm Config Options:**
@@ -694,6 +732,20 @@ function MyForm() {
 }
 ```
 
+### Resetting After Save
+
+When a form stays on the page after submission (e.g., settings pages), call `form.reset()` after a successful mutation. This re-syncs the form with updated `defaultValues` so it becomes pristine again — any UI that depends on the form being dirty (like conditionally shown Save/Cancel buttons) will update correctly.
+
+```tsx
+onSubmit: ({value}) =>
+  mutation
+    .mutateAsync(value)
+    .then(() => form.reset())
+    .catch(() => {}),
+```
+
+> **Note**: `AutoSaveForm` handles this automatically. You only need to add this when using `useScrapsForm`.
+
 ### Submit Button
 
 ```tsx
@@ -741,6 +793,33 @@ const form = useScrapsForm({
 });
 ```
 
+### Nullable Default Values
+
+```tsx
+// ❌ Don't use non-null assertions or type casts
+onSubmit: ({value}) => {
+  return mutation.mutateAsync({...value, provider: value.provider!});
+};
+
+// ❌ Don't skip typing defaultValues when the schema has refine
+const form = useScrapsForm({
+  ...defaultFormOptions,
+  defaultValues: {provider: null, name: ''}, // type is inferred but imprecise
+});
+
+// ✅ Use z.input for defaultValues and schema.parse in onSubmit
+const defaultValues: z.input<typeof schema> = {provider: null, name: ''};
+
+const form = useScrapsForm({
+  ...defaultFormOptions,
+  defaultValues,
+  validators: {onDynamic: schema},
+  onSubmit: ({value}) => {
+    return mutation.mutateAsync(schema.parse(value)).catch(() => {});
+  },
+});
+```
+
 ### Form Submissions
 
 ```tsx
@@ -763,7 +842,11 @@ onSubmit: ({value}) => {
   // Return the promise to keep form.isSubmitting working
   // Add .catch(() => {}) to avoid unhandled rejection - error handling
   // is done by TanStack Query (onError callback, mutation.isError state)
-  return mutation.mutateAsync(value).catch(() => {});
+  // Add .then(() => form.reset()) if the form stays on the page after save
+  return mutation
+    .mutateAsync(value)
+    .then(() => form.reset())
+    .catch(() => {});
 };
 ```
 
@@ -803,7 +886,7 @@ mutationOptions={{
   mutationFn: (data) => fetchMutation({url: '/user/', method: 'PUT', data}),
   onSuccess: (data) => {
     queryClient.setQueryData(['user'], old => ({...old, ...data}));
-    // No toast needed - AutoSaveField shows a checkmark automatically
+    // No toast needed - AutoSaveForm shows a checkmark automatically
   },
 }}
 ```
@@ -850,6 +933,23 @@ const opts = mutationOptions({
 
 Make sure the zod schema's types are compatible with the API type. For example, if the API expects a string union like `'off' | 'low' | 'high'`, use `z.enum(['off', 'low', 'high'])` instead of `z.string()`.
 
+### Form Reset After Save
+
+```tsx
+// ❌ Don't forget to reset forms that stay on the page after save
+onSubmit: ({value}) => {
+  return mutation.mutateAsync(value).catch(() => {});
+};
+
+// ✅ Call form.reset() after successful save to sync with updated defaultValues
+onSubmit: ({value}) => {
+  return mutation
+    .mutateAsync(value)
+    .then(() => form.reset())
+    .catch(() => {});
+};
+```
+
 ### Layout Choice
 
 ```tsx
@@ -869,17 +969,18 @@ When creating a new form:
 - [ ] Import from `@sentry/scraps/form` and `zod`
 - [ ] Define Zod schema with helpful error messages
 - [ ] Use `useScrapsForm` with `...defaultFormOptions`
-- [ ] Set `defaultValues` matching schema shape
+- [ ] Set `defaultValues` matching schema shape (use `z.input<typeof schema>` if schema has `.refine()`)
 - [ ] Set `validators: {onDynamic: schema}`
 - [ ] Wrap with `<form.AppForm form={form}>`
 - [ ] Use `<form.AppField>` for each field
 - [ ] Choose appropriate layout (Stack or Row)
 - [ ] Handle server errors with `setFieldErrors`
 - [ ] Add `<form.SubmitButton>` for submission
+- [ ] Call `form.reset()` after successful mutation if the form stays on the page
 
 When creating auto-save fields:
 
-- [ ] Use `<AutoSaveField>` component
+- [ ] Use `<AutoSaveForm>` component
 - [ ] Pass `schema` for validation
 - [ ] Pass `initialValue` from current data
 - [ ] Configure `mutationOptions` with `mutationFn`
@@ -889,10 +990,10 @@ When creating auto-save fields:
 
 ## File References
 
-| File                                                      | Purpose                     |
-| --------------------------------------------------------- | --------------------------- |
-| `static/app/components/core/form/scrapsForm.tsx`          | Main form hook              |
-| `static/app/components/core/form/field/autoSaveField.tsx` | Auto-save wrapper           |
-| `static/app/components/core/form/field/*.tsx`             | Individual field components |
-| `static/app/components/core/form/layout/index.tsx`        | Layout components           |
-| `static/app/components/core/form/form.stories.tsx`        | Usage examples              |
+| File                                               | Purpose                     |
+| -------------------------------------------------- | --------------------------- |
+| `static/app/components/core/form/scrapsForm.tsx`   | Main form hook              |
+| `static/app/components/core/form/autoSaveForm.tsx` | Auto-save wrapper           |
+| `static/app/components/core/form/field/*.tsx`      | Individual field components |
+| `static/app/components/core/form/layout/index.tsx` | Layout components           |
+| `static/app/components/core/form/form.stories.tsx` | Usage examples              |