diff --git a/apps/web/components/settings/prompts-settings.tsx b/apps/web/components/settings/prompts-settings.tsx
index bb824e60ea..0703f092c4 100644
--- a/apps/web/components/settings/prompts-settings.tsx
+++ b/apps/web/components/settings/prompts-settings.tsx
@@ -502,56 +502,58 @@ export function PromptsSettings() {
onSave={showCreate ? handleCreate : handleUpdate}
onDiscard={resetForm}
>
-
-
- Use {PROMPT_MENTION_TOKEN} in the
- chat input to insert a prompt’s content. Prompts are matched by name and expanded in
- place.
-
-
-
- {t("settings:promptAdd")}
-
- }
- >
- {showCreate && (
- setFormState((prev) => ({ ...prev, ...patch }))}
- onCancel={resetForm}
- isBusy={isBusy}
- />
- )}
-
-
-
setFormState((prev) => ({ ...prev, ...patch }))}
- onStartEditing={startEditing}
- onOpenDelete={openDeleteDialog}
- onDeleteCancel={closeDeleteDialog}
- onDeleteConfirm={confirmDelete}
- onCancel={resetForm}
- isBusy={isBusy}
- showCreate={showCreate}
- isFinePointer={isFinePointer}
- deleteTargetId={deleteTarget?.id ?? null}
- />
+
+
+
+ Use {PROMPT_MENTION_TOKEN} in the
+ chat input to insert a prompt’s content. Prompts are matched by name and expanded in
+ place.
+
-
+
+ {t("settings:promptAdd")}
+
+ }
+ >
+ {showCreate && (
+ setFormState((prev) => ({ ...prev, ...patch }))}
+ onCancel={resetForm}
+ isBusy={isBusy}
+ />
+ )}
+
+
+
setFormState((prev) => ({ ...prev, ...patch }))}
+ onStartEditing={startEditing}
+ onOpenDelete={openDeleteDialog}
+ onDeleteCancel={closeDeleteDialog}
+ onDeleteConfirm={confirmDelete}
+ onCancel={resetForm}
+ isBusy={isBusy}
+ showCreate={showCreate}
+ isFinePointer={isFinePointer}
+ deleteTargetId={deleteTarget?.id ?? null}
+ />
+
+
+
);
}
diff --git a/docs/plans/settings-composition/plan.md b/docs/plans/settings-composition/plan.md
index ed73048bbb..c8518ec32a 100644
--- a/docs/plans/settings-composition/plan.md
+++ b/docs/plans/settings-composition/plan.md
@@ -169,6 +169,37 @@ Required structure: three visible tabs, expanded sections, concise row descripti
Copy and ASCII spacing are illustrative. The work-order copy table is the English starting point.
Maps to AC-UI-SETTINGS-COMPOSITION-002.1 through .6, -003.1 through .6, -004.1 through .5, and -005.1 through .7.
+### UI-08: Prompt usage help spacing, desktop and phone
+
+Entry: `/settings/prompts`, page loaded with custom prompts.
+
+```text
+Before, desktop:
+[ @name usage hint ]
+Custom prompts [Add prompt]
+
+After, desktop:
+[ @name usage hint ]
+
+Custom prompts [Add prompt]
+[ prompt list ]
+
+Before, phone:
+[ @name usage hint ]
+Custom prompts
+[Add prompt]
+
+After, phone:
+[ @name usage hint ]
+
+Custom prompts
+[Add prompt]
+[ prompt list ]
+```
+
+The page remains the single scroll owner. The 24px separation is required by the existing settings spacing contract. Phone keeps the existing stacked group action.
+This preview describes the affected region; other page content is omitted. Maps to AC-UI-SETTINGS-COMPOSITION-001.1.
+
## Tests and E2E
Task 06 owns the exact commands and scenarios for the refinement.
@@ -186,8 +217,9 @@ The work order also requires every modified existing E2E consumer to run and rec
- [x] [Task 05: System, account, and plugin settings](task-05-system-account.md)
- [x] [Task 06: Concise help and header tabs](task-06-concise-help-and-tabs.md)
+- [x] [Task 07: Prompt usage help spacing](task-07-prompt-usage-spacing.md)
-Tasks 01 through 05 are complete. Task 06 follows them sequentially. No delegation is authorized.
+Tasks 01 through 06 are complete. Task 07 records the completed prompt-spacing follow-up.
## Verification results
@@ -284,3 +316,7 @@ Do not overlap these E2E commands or use worker overrides.
- Shared spacing can affect specialized editors. Retain and document their inner geometry.
- Brief descriptions can omit decision-critical exclusions. Keep those visible and move only secondary detail.
- Existing E2E selectors reference card structure. Preserve semantic assertions and migrate affected selectors together.
+
+## Task 07 results
+
+The prompts page now applies the established 24px settings-group gap between its `@name` usage hint and Custom prompts group. A temporary capture produced desktop and phone screenshots; the capture spec was removed afterward. Commit hooks passed, and the PR body publishes the compressed screenshots from its orphan media ref.
diff --git a/docs/plans/settings-composition/task-07-prompt-usage-spacing.md b/docs/plans/settings-composition/task-07-prompt-usage-spacing.md
new file mode 100644
index 0000000000..b184d79de8
--- /dev/null
+++ b/docs/plans/settings-composition/task-07-prompt-usage-spacing.md
@@ -0,0 +1,77 @@
+---
+id: "07-prompt-usage-spacing"
+title: "Separate prompt usage help"
+status: complete
+wave: 7
+depends_on:
+ - 06-concise-help-and-tabs
+plan: "plan.md"
+requirements:
+ - REQ-UI-SETTINGS-COMPOSITION-001
+acceptance_criteria:
+ - AC-UI-SETTINGS-COMPOSITION-001.1
+system_design:
+ - ../../specs/ui/system-design/settings-composition.md
+---
+
+# Task 07: Separate prompt usage help
+
+## Summary
+
+Add the settings group's standard 24px gap between the prompt-reference hint and the Custom prompts heading and action.
+
+## In scope
+
+- Keep the hint and prompt group in their existing page order.
+- Apply the shared group spacing on desktop and phone.
+- Preserve prompt list, editor, save, and delete behavior.
+
+## Out of scope
+
+- Changing prompt-reference behavior, prompt content, localization, or persistence.
+- Rearranging other content on the Prompts settings page.
+
+## Acceptance
+
+- The `@name` hint has the existing 24px settings-group separation from the Custom prompts heading and Add prompt action.
+- Desktop and phone retain the existing inline page flow, with the phone group action stacked below its heading.
+
+## ASCII UI preview
+
+UI-08 is the affected region of `/settings/prompts`. The before view is supported by the user-provided desktop screenshot and source; the after views were captured at desktop and phone sizes.
+
+```text
+Before, desktop:
+[ @name usage hint ]
+Custom prompts [Add prompt]
+
+Before, phone:
+[ @name usage hint ]
+Custom prompts
+[Add prompt]
+
+After, desktop:
+[ @name usage hint ]
+
+Custom prompts [Add prompt]
+[ prompt list ]
+
+After, phone:
+[ @name usage hint ]
+
+Custom prompts
+[Add prompt]
+[ prompt list ]
+```
+
+The page remains the scroll owner. The gap uses the existing `space-y-6` settings spacing token. No new surface, control, or navigation is added. Maps to AC-UI-SETTINGS-COMPOSITION-001.1.
+
+## Verification
+
+- `CAPTURE_PR_ASSETS=1 pnpm e2e:run --host tests/settings/prompt-spacing-capture.spec.ts`: passed, one disposable capture scenario; desktop and phone screenshots were inspected and published in PR #3891. The temporary spec was removed after capture.
+- Commit hooks: passed formatting, changed-file lint, i18n guards, and commit-message validation.
+- `git diff --check`: passed.
+
+## Results
+
+The usage hint and prompt group now have the 24px separation defined by the existing Settings Composition system design. Prompt behavior and persistence are unchanged.