diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md
index d1b8299ea..1b006a9a3 100644
--- a/docs/project-memory/shared-memory/pitfalls.md
+++ b/docs/project-memory/shared-memory/pitfalls.md
@@ -3181,3 +3181,11 @@
 - 处理：在调用 `try_with_tx` 前通过 `let caller = ctx.sender()` 捕获真实调用者，再把 `caller` 显式传入事务函数；迁移、后台账号、runtime profile、外部生成等现有 procedure 已采用这一模式。`npm run check:spacetime-runtime-access` 禁止编辑器 runtime writer 鉴权重新直接读取事务 `ctx.sender()`。运行环境升级到 2.6.1 后继续保留显式 caller，避免鉴权依赖 SDK 版本细节。
 - 验证：运行 `npm run check:spacetime-runtime-access`、`cargo test -p spacetime-module --manifest-path server-rs/Cargo.toml`、`npm run check:spacetime-schema`；发布使用 SpacetimeDB 2.6.1 构建的新模块后，以 runtime writer identity 重试 `POST /api/editor/icon-spritesheets/slices`，确认来源查询、分片素材写入与 cohort 完成不再返回 identity 403。
 - 关联：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`、`scripts/check-spacetime-runtime-access.mjs`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
+
+## Portal 弹窗必须在遮罩根节点携带平台主题
+
+- 现象：项目库点击“重命名”后，标题、输入框和按钮仍显示，但弹窗面板及遮罩背景变透明，看起来像“改名界面的背景没了”。
+- 原因：`UnifiedModal` 默认 portal 到 `document.body`；若业务入口只在页面内层继承 `platform-theme`，portal 根节点不会继承该容器的 CSS 变量。此时 `.platform-modal-shell` 的 `background: var(--platform-modal-fill)` 和 `.platform-overlay` 的背景声明都会失效。
+- 处理：平台白底工具弹窗优先复用 `PlatformToolModalShell`，由共享壳读取当前 `AuthUiContext.platformTheme`，并把 `platform-theme platform-theme--<light|dark>` 挂到 portal overlay；不要用硬编码白底掩盖主题变量缺失。必须直接使用 `UnifiedModal` 的特殊场景，也要在 `overlayClassName` 显式传递当前平台主题。
+- 验证：在 light / dark 主题下打开 portal 弹窗，断言 dialog 的 overlay 携带对应主题类，并在真实浏览器核对 panel 与遮罩的 computed background 均非透明。
+- 关联：`src/components/project/ProjectGalleryView.tsx`、`src/components/common/PlatformToolModalShell.tsx`、`src/components/common/UnifiedModal.tsx`。
diff --git a/src/components/project/ProjectGalleryView.test.tsx b/src/components/project/ProjectGalleryView.test.tsx
index a118a2c76..aea2521e7 100644
--- a/src/components/project/ProjectGalleryView.test.tsx
+++ b/src/components/project/ProjectGalleryView.test.tsx
@@ -387,6 +387,29 @@ describe('ProjectGalleryView', () => {
     });
   });
 
+  it('keeps the project rename modal inside the active platform theme', async () => {
+    listEditorProjectsMock.mockResolvedValueOnce(projectItems);
+    const user = userEvent.setup();
+
+    render(
+      <AuthUiContext.Provider
+        value={createAuthValue({ platformTheme: 'dark' })}
+      >
+        <ProjectGalleryView onOpenProject={vi.fn()} />
+      </AuthUiContext.Provider>,
+    );
+
+    await screen.findByText('角色设定板');
+    await user.click(
+      screen.getByRole('button', { name: '打开项目角色设定板菜单' }),
+    );
+    await user.click(screen.getByRole('menuitem', { name: /重命名/u }));
+
+    const dialog = screen.getByRole('dialog', { name: '重命名' });
+    expect(dialog.closest('.platform-theme--dark')).toBeTruthy();
+    expect(dialog.className).toContain('platform-remap-surface');
+  });
+
   it('supports batch selection actions from the bottom toolbar', async () => {
     listEditorProjectsMock.mockResolvedValueOnce(projectItems);
     deleteEditorProjectMock.mockResolvedValue('deleted');
diff --git a/src/components/project/ProjectGalleryView.tsx b/src/components/project/ProjectGalleryView.tsx
index 4d8286020..a6629c366 100644
--- a/src/components/project/ProjectGalleryView.tsx
+++ b/src/components/project/ProjectGalleryView.tsx
@@ -30,7 +30,7 @@ import { PlatformIconButton } from '../common/PlatformIconButton';
 import { PlatformMediaFrame } from '../common/PlatformMediaFrame';
 import { PlatformStatusMessage } from '../common/PlatformStatusMessage';
 import { PlatformTextField } from '../common/PlatformTextField';
-import { UnifiedModal } from '../common/UnifiedModal';
+import { PlatformToolModalShell } from '../common/PlatformToolModalShell';
 import {
   LOCAL_PROJECT_COVER_CACHE_ASSET_KIND,
   resolveProjectCoverResource,
@@ -436,7 +436,7 @@ export function ProjectGalleryView({ onOpenProject }: ProjectGalleryViewProps) {
         <section className="project-gallery__grid">{projectCards}</section>
       )}
 
-      <UnifiedModal
+      <PlatformToolModalShell
         open={Boolean(renameDraft)}
         title="重命名"
         size="sm"
@@ -482,7 +482,7 @@ export function ProjectGalleryView({ onOpenProject }: ProjectGalleryViewProps) {
             />
           </form>
         ) : null}
-      </UnifiedModal>
+      </PlatformToolModalShell>
 
       {isSelectionMode ? (
         <PlatformBatchActionToolbar>