feat(ios): comprehensive iPhone+iPad UX polish — refined-native design system

Freeze a shared design system (DesignSystem/{Tokens,Typography,StatusStyle, Primitives}.swift): indigo #7C8CFF accent (root .tint), semantic status colors, 2-4-8-12-16-20-24 spacing + sm8/md12/lg16 radii scale, SF Mono tabular numbers, reduce-motion-gated animations, haptics, reusable StatusBadge/TelemetryChip/Card/ SectionHeader/DSButtonStyle/ContinueLastBanner. Every changed view consumes tokens — no hardcoded colors/spacing. Applied across all surfaces (visual only — zero behavior/logic change, all suites green): session list rows + status system (shape+color, not color-alone) + telemetry chips + thumbnail placeholders; terminal gate card (≥44pt approve/reject) + keybar + reconnect + quick-reply + digest + SwiftTerm accent theme; pairing hero + warning tiers + Projects cards + Timeline/Diff; nav chrome + iPad split placeholder + privacy shade + motion. Chinese gate copy. UX finding fixed: timeline class colors now via DS.Palette (+timelineTool/timelineUser tokens). Design review 8.5/10. Verified: iPhone 16 290 + iPad Pro 11 290 tests green; packages + integration green; consistency audit ~clean; zero changes under ios/Packages, src/, public/.
2026-07-05 22:00:31 +02:00
parent 823432b1c8
commit 660a40491a
25 changed files with 1742 additions and 650 deletions
--- a/ios/App/WebTerm/Wiring/PrivacyShade.swift
+++ b/ios/App/WebTerm/Wiring/PrivacyShade.swift
@@ -20,6 +20,14 @@ enum PrivacyShadePolicy {
 /// Opaque cover rendered ABOVE the whole navigation tree (RootView ZStack) —
 /// deliberately no animation: the snapshot moment must never race a fade.
 ///
+/// Security invariant (do NOT weaken): the FULL-SCREEN base is `DS.Palette.surface`
+/// (`.systemBackground`, fully OPAQUE) + `.ignoresSafeArea()`, so no terminal
+/// byte can leak into the on-disk switcher snapshot. The branded lockup is a
+/// `.regularMaterial` card layered ON TOP of that opaque base (never over the
+/// terminal), so the material's translucency is purely decorative — it blurs
+/// the opaque surface below it, not the PTY content. Accent lock + app name +
+/// hint give the shade a refined-native identity instead of a flat cover.
+///
 /// Scope note (documented): sheets present in a separate presentation layer a
 /// root overlay cannot cover — but no terminal bytes are ever rendered in a
 /// sheet (pairing / plan-gate only), so the root-level shade covers every
@@ -27,21 +35,36 @@ enum PrivacyShadePolicy {
 struct PrivacyShadeView: View {
    var body: some View {
        ZStack {
-            Color(.systemBackground)
+            // OPAQUE full-screen occlusion — the security base. Must stay opaque
+            // and edge-to-edge; the material card below only decorates it.
+            DS.Palette.surface
                .ignoresSafeArea()
-            VStack(spacing: ShadeMetrics.spacing) {
-                Image(systemName: "terminal.fill")
-                    .font(.largeTitle)
-                    .foregroundStyle(.secondary)
-                Text("WebTerm")
-                    .font(.headline)
-                    .foregroundStyle(.secondary)
+
+            VStack(spacing: DS.Space.md12) {
+                Image(systemName: "lock.fill")
+                    .font(DS.Typography.largeTitle)
+                    .foregroundStyle(DS.Palette.accent)
+                Text(ShadeCopy.appName)
+                    .font(DS.Typography.headline)
+                    .foregroundStyle(DS.Palette.textPrimary)
+                Text(ShadeCopy.hint)
+                    .font(DS.Typography.caption)
+                    .foregroundStyle(DS.Palette.textSecondary)
            }
+            .padding(.horizontal, DS.Space.xxl24)
+            .padding(.vertical, DS.Space.xl20)
+            .background(.regularMaterial, in: RoundedRectangle(cornerRadius: DS.Radius.lg16))
+            .overlay(
+                RoundedRectangle(cornerRadius: DS.Radius.lg16)
+                    .strokeBorder(DS.Palette.hairline, lineWidth: DS.Stroke.hairline)
+            )
        }
        .accessibilityHidden(true)
    }
-
-    private enum ShadeMetrics {
-        static let spacing: CGFloat = 12
-    }
+}
+
+/// 遮罩内用户可见文案（Chinese, named constants）。
+private enum ShadeCopy {
+    static let appName = "WebTerm"
+    static let hint = "内容已隐藏"
 }
--- a/ios/App/WebTerm/Wiring/RootView.swift
+++ b/ios/App/WebTerm/Wiring/RootView.swift
@@ -5,19 +5,25 @@ import SwiftUI
 /// 隐私遮罩 + sheets/scenePhase/deepLink 的全部布线；iPad 自适应（T-iPad-2）
 /// 把它拆成两层：
 /// - `RootView`（本 struct）保持 `@main` 的唯一实例化点不变（WebTermApp 仍
-///   `RootView(coordinator:)`），内部只委托给 `AdaptiveRootView`。
+///   `RootView(coordinator:)`），内部委托给 `AdaptiveRootView` 并在这唯一处
+///   注入设计系统的 accent tint（`DS.Palette.accent`，DS 建议的「根注入一次」）
+///   —— 全 App 的系统控件/工具栏/`.borderedProminent` 由此统一到靛紫强调色。
 /// - `AdaptiveRootView` 按 `horizontalSizeClass` 选 `StackRootView`（compact，
 ///   现有路径，字节级不变）或 `SplitRootView`（regular，iPad 分栏），并把
 ///   隐私遮罩 / scenePhase / deepLink / sheets 这些**设备无关的横切布线**
 ///   上提到唯一一处，两分支共享（遮罩因此仍是两分支共同的 ZStack 顶层）。
 ///
 /// `StackRootView` 是原 `RootView` 的 body **原样搬迁** —— compact 分支复用它
-/// 不改一行，故 iPhone 逐屏渲染与适配前一致（零回归硬性要求）。
+/// 不改一行逻辑，故 iPhone 逐屏渲染与适配前一致（零回归硬性要求）。视觉层
+/// 只按冻结的 `DS.*` token 重塑（横幅/占位/遮罩），行为不动。
 struct RootView: View {
    @Bindable var coordinator: AppCoordinator

    var body: some View {
        AdaptiveRootView(coordinator: coordinator)
+            // DS：唯一的根 tint 注入点（Tokens.swift 头注约定）。子树若需别的
+            // 语义色（gate 的 amber、终端的 orange）在各自局部 `.tint` 覆盖。
+            .tint(DS.Palette.accent)
    }
 }

@@ -26,6 +32,7 @@ struct RootView: View {
 /// （遮罩/scenePhase/deepLink/sheets）不在这里，已上提到 `AdaptiveRootView`。
 struct StackRootView: View {
    @Bindable var coordinator: AppCoordinator
+    @Environment(\.accessibilityReduceMotion) private var reduceMotion

    var body: some View {
        NavigationStack {
@@ -66,38 +73,23 @@ struct StackRootView: View {
            onAddHost: { coordinator.presentAddHost() }
        )
        .safeAreaInset(edge: .bottom) { continueLastBanner }
+        // 横幅出现/消失走 DS 动效（reduceMotion 时塌成瞬切，无位移）。
+        .animation(
+            DS.Motion.gated(DS.Motion.base, reduceMotion: reduceMotion),
+            value: coordinator.continueLastSessionId
+        )
        // T-iOS-26 · Projects 入口挂在 RootView 层（SessionListScreen 是
        // T-iOS-23 的 W7 独占文件 —— 列表侧入口整合移交给它）。leading 位，
        // 避开列表自己的 topBarTrailing hostMenu。
-        .toolbar { projectsToolbarItem }
-    }
-
-    @ToolbarContentBuilder private var projectsToolbarItem: some ToolbarContent {
-        ToolbarItem(placement: .topBarLeading) {
-            Button {
-                coordinator.presentProjects()
-            } label: {
-                Label(RootCopy.projects, systemImage: "folder")
-            }
-            .disabled(coordinator.sessionList.activeHost == nil)
-            .accessibilityIdentifier("sessions.projectsButton")
-        }
+        .toolbar { ProjectsToolbarItem(coordinator: coordinator) }
    }

    // MARK: - "继续上次" highlight (cold start step 5)

    @ViewBuilder private var continueLastBanner: some View {
        if coordinator.continueLastSessionId != nil {
-            Button {
-                coordinator.openContinueLast()
-            } label: {
-                Label(RootCopy.continueLast, systemImage: "arrow.uturn.forward.circle.fill")
-                    .frame(maxWidth: .infinity)
-            }
-            .buttonStyle(.borderedProminent)
-            .padding(.horizontal, RootMetrics.bannerHorizontalPadding)
-            .padding(.vertical, RootMetrics.bannerVerticalPadding)
-            .background(.thinMaterial)
+            ContinueLastBanner { coordinator.openContinueLast() }
+                .transition(.move(edge: .bottom).combined(with: .opacity))
        }
    }

@@ -131,12 +123,54 @@ struct StackRootView: View {
    }
 }

-enum RootMetrics {
-    static let bannerHorizontalPadding: CGFloat = 16
-    static let bannerVerticalPadding: CGFloat = 8
+// MARK: - Continue-last banner (shared stack + split, DRY)
+
+/// 冷启动第 5 步的「继续上次会话」再入 CTA —— stack 底栏与 split sidebar 底栏
+/// 共用同一个组件（DRY）。设计：`.regularMaterial` 底 + 顶部发丝分隔 +
+/// 全宽 accent 主按钮（`DSButtonStyle(.primary)`），克制而不喧宾夺主。行为仅
+/// 一条 `action`（= `coordinator.openContinueLast()`），出现条件由调用点把关。
+struct ContinueLastBanner: View {
+    let action: () -> Void
+
+    var body: some View {
+        Button(action: action) {
+            Label(RootCopy.continueLast, systemImage: "arrow.uturn.forward.circle.fill")
+        }
+        .buttonStyle(DSButtonStyle(kind: .primary))
+        .accessibilityIdentifier("root.continueLastButton")
+        .padding(.horizontal, DS.Space.lg16)
+        .padding(.top, DS.Space.md12)
+        .padding(.bottom, DS.Space.sm8)
+        .background(.regularMaterial)
+        .overlay(alignment: .top) {
+            Rectangle()
+                .fill(DS.Palette.hairline)
+                .frame(height: DS.Stroke.hairline)
+        }
+    }
 }

-/// 根层用户可见文案（internal —— `SplitRootView` 复用同一「项目」标签，DRY）。
+// MARK: - Projects toolbar item (shared stack + split, DRY)
+
+/// 「项目」leading 工具栏入口 —— stack 与 split 共用（同 disabled 条件、同
+/// `presentProjects` 动作、同 a11y id）。根 tint 令其 label 呈 accent。
+struct ProjectsToolbarItem: ToolbarContent {
+    @Bindable var coordinator: AppCoordinator
+
+    var body: some ToolbarContent {
+        ToolbarItem(placement: .topBarLeading) {
+            Button {
+                coordinator.presentProjects()
+            } label: {
+                Label(RootCopy.projects, systemImage: "folder")
+            }
+            .disabled(coordinator.sessionList.activeHost == nil)
+            .accessibilityIdentifier("sessions.projectsButton")
+        }
+    }
+}
+
+/// 根层用户可见文案（internal —— `SplitRootView` 复用同一「项目」/「继续」标签，DRY）。
 enum RootCopy {
    static let continueLast = "继续上次会话"
    static let projects = "项目"
--- a/ios/App/WebTerm/Wiring/SplitRootView.swift
+++ b/ios/App/WebTerm/Wiring/SplitRootView.swift
@@ -10,12 +10,17 @@ import SwiftUI
 ///   split detail 无关，只换外层容器、内容零改（PLAN_IOS_IPAD §1）。
 /// - **选中态经 `AppCoordinator` 单一真值**：sidebar 触发面全部走
 ///   `selectSidebarItem` / `open`（同 stack 的既有路由），不新开会话生命周期。
+///   `coordinator.sidebarSelection` 提供二向绑定；行 highlight 需 sidebar List
+///   采纳 `selection:`（`SessionListScreen` 的 List，属列表组 Owns），见文末注。
 /// - **detail 终端仍带 `.id(controller.id)`**：换会话时新 controller → 新
 ///   SwiftTerm 视图（回放 ring buffer），identity 稳定复用 T-iOS-29 语义。
 /// - **隐私遮罩不在这里**：它在 `AdaptiveRootView` 的 ZStack 顶层，两分支共享，
 ///   故 detail 终端字节同样在 `scenePhase != .active` 时被遮（安全不变式）。
+/// - **视觉层**：横幅/占位/工具栏全部走冻结 `DS.*` token 与共享 Primitive，
+///   与 stack 分支像素级一致（继续横幅、项目入口都是同一组件）。
 struct SplitRootView: View {
    @Bindable var coordinator: AppCoordinator
+    @Environment(\.accessibilityReduceMotion) private var reduceMotion

    var body: some View {
        NavigationSplitView {
@@ -37,23 +42,19 @@ struct SplitRootView: View {
            onAddHost: { coordinator.presentAddHost() }
        )
        .safeAreaInset(edge: .bottom) { continueLastBanner }
-        .toolbar { projectsToolbarItem }
+        .animation(
+            DS.Motion.gated(DS.Motion.base, reduceMotion: reduceMotion),
+            value: coordinator.continueLastSessionId
+        )
+        .toolbar { ProjectsToolbarItem(coordinator: coordinator) }
    }

-    /// 与 `StackRootView.continueLastBanner` 同款「继续上次会话」（冷启动第 5 步）
-    /// —— 分栏 sidebar 也提供，iPad 用户不丢该入口（T-iPad-5 finding）。
+    /// 与 stack 底栏同款「继续上次会话」（冷启动第 5 步）—— 复用共享
+    /// `ContinueLastBanner`，iPad 用户不丢该入口（T-iPad-5 finding）。
    @ViewBuilder private var continueLastBanner: some View {
        if coordinator.continueLastSessionId != nil {
-            Button {
-                coordinator.openContinueLast()
-            } label: {
-                Label(RootCopy.continueLast, systemImage: "arrow.uturn.forward.circle.fill")
-                    .frame(maxWidth: .infinity)
-            }
-            .buttonStyle(.borderedProminent)
-            .padding(.horizontal, RootMetrics.bannerHorizontalPadding)
-            .padding(.vertical, RootMetrics.bannerVerticalPadding)
-            .background(.thinMaterial)
+            ContinueLastBanner { coordinator.openContinueLast() }
+                .transition(.move(edge: .bottom).combined(with: .opacity))
        }
    }

@@ -62,21 +63,6 @@ struct SplitRootView: View {
        request.sessionId.map(SidebarItem.session) ?? .newSession
    }

-    /// 与 `StackRootView.projectsToolbarItem` 同款（leading 位、同 disabled 条件、
-    /// 复用 `presentProjects`）—— iPad 上 Projects 本期仍走既有 sheet（大屏化留
-    /// 给 T-iPad-4）。
-    @ToolbarContentBuilder private var projectsToolbarItem: some ToolbarContent {
-        ToolbarItem(placement: .topBarLeading) {
-            Button {
-                coordinator.presentProjects()
-            } label: {
-                Label(RootCopy.projects, systemImage: "folder")
-            }
-            .disabled(coordinator.sessionList.activeHost == nil)
-            .accessibilityIdentifier("sessions.projectsButton")
-        }
-    }
-
    // MARK: - Detail（终端或占位）

    @ViewBuilder private var detail: some View {
@@ -91,19 +77,27 @@ struct SplitRootView: View {
            }
        } else {
            placeholder
+                .transition(.opacity)
        }
    }

+    /// 空 detail 占位 —— accent 图标 + 邀约式文案（DS 方向：ContentUnavailableView
+    /// + 好符号 + 友好中文）。图标着 accent 靛紫，与全 App 强调色呼应。
    private var placeholder: some View {
        ContentUnavailableView {
-            Label(SplitCopy.placeholderTitle, systemImage: "sidebar.left")
+            Label {
+                Text(SplitCopy.placeholderTitle)
+            } icon: {
+                Image(systemName: "terminal")
+                    .foregroundStyle(DS.Palette.accent)
+            }
        } description: {
            Text(SplitCopy.placeholderHint)
        }
    }
 }

-/// split 专属用户可见文案（「项目」标签复用 `RootCopy.projects`，DRY）。
+/// split 专属用户可见文案（「项目」/「继续」标签复用 `RootCopy`，DRY）。
 private enum SplitCopy {
    static let placeholderTitle = "选择或新建会话"
    static let placeholderHint = "从左侧选择一个运行中的会话，或新建一个开始工作。"
--- a/ios/App/WebTerm/Wiring/TerminalContainerView.swift
+++ b/ios/App/WebTerm/Wiring/TerminalContainerView.swift
@@ -35,18 +35,20 @@ struct TerminalContainerView: View {
    /// T-iOS-25 (additive) · Quick-reply palette store — per-container over
    /// `.standard` defaults (non-secret UI prefs, plan §5.3 split).
    @State private var quickReplyStore = QuickReplyStore()
+    /// 无障碍：减弱动态效果时，overlay 进出塌成即时切换（DS.Motion.gated）。
+    @Environment(\.accessibilityReduceMotion) private var reduceMotion

    private enum Metrics {
-        static let overlaySpacing: CGFloat = 8
-        static let overlayHorizontalPadding: CGFloat = 12
-        /// Clears TerminalScreen's own top-aligned ReconnectBanner zone.
-        static let overlayTopPadding: CGFloat = 52
-        /// Breathing room between the chip row and the keyboard/key-bar edge.
-        static let quickReplyBottomPadding: CGFloat = 8
+        /// Clears TerminalScreen's own top-aligned ReconnectBanner zone: a
+        /// hit-target-tall pill plus a gap. (They rarely co-exist — the banner
+        /// hides on `.connected` while gates/digests only arrive connected.)
+        static let overlayTopPadding: CGFloat = DS.Layout.minHitTarget + DS.Space.sm8
    }

    private enum Copy {
-        static let planGatePending = "⚠ 计划待批准"
+        /// The re-entry chip's own amber StatusBadge carries the "needs me"
+        /// warning shape, so the copy itself stays plain (no emoji).
+        static let planGatePending = "计划待批准"
    }

    var body: some View {
@@ -75,16 +77,19 @@ struct TerminalContainerView: View {
            gateViewModel: controller.gateViewModel,
            store: quickReplyStore
        )
-        .padding(.horizontal, Metrics.overlayHorizontalPadding)
-        .padding(.bottom, Metrics.quickReplyBottomPadding)
-        .animation(.default, value: controller.gateViewModel.currentGate)
+        .padding(.horizontal, DS.Space.md12)
+        .padding(.bottom, DS.Space.sm8)
+        .animation(
+            DS.Motion.gated(DS.Motion.base, reduceMotion: reduceMotion),
+            value: controller.gateViewModel.currentGate
+        )
    }

    // MARK: - Digest + tool gate (top stack)

    @ViewBuilder private var topOverlays: some View {
        let gateViewModel = controller.gateViewModel
-        VStack(spacing: Metrics.overlaySpacing) {
+        VStack(spacing: DS.Space.sm8) {
            if let digest = gateViewModel.digest {
                AwayDigestView(
                    digest: digest,
@@ -99,16 +104,38 @@ struct TerminalContainerView: View {
                }
            }
            if hasDismissedPendingPlanGate {
-                Button(Copy.planGatePending) { dismissedPlanGateEpoch = nil }
-                    .buttonStyle(.borderedProminent)
-                    .tint(.orange)
-                    .controlSize(.small)
+                planGatePendingChip
            }
        }
-        .padding(.horizontal, Metrics.overlayHorizontalPadding)
+        .padding(.horizontal, DS.Space.md12)
        .padding(.top, Metrics.overlayTopPadding)
-        .animation(.default, value: gateViewModel.toolGate)
-        .animation(.default, value: gateViewModel.digest)
+        .animation(DS.Motion.gated(DS.Motion.base, reduceMotion: reduceMotion),
+                   value: gateViewModel.toolGate)
+        .animation(DS.Motion.gated(DS.Motion.base, reduceMotion: reduceMotion),
+                   value: gateViewModel.digest)
+    }
+
+    /// The "plan still pending" re-entry chip shown after the user swiped the
+    /// plan sheet away — an amber pending-approval pill that re-presents the
+    /// sheet on tap.
+    private var planGatePendingChip: some View {
+        Button {
+            dismissedPlanGateEpoch = nil
+        } label: {
+            HStack(spacing: DS.Space.xs4) {
+                StatusBadge(status: .pendingApproval)
+                Text(Copy.planGatePending)
+                    .font(DS.Typography.callout.weight(.medium))
+                    .foregroundStyle(DS.Palette.textPrimary)
+            }
+            .padding(.horizontal, DS.Space.md12)
+            .frame(minHeight: DS.Layout.minHitTarget)
+            .background(.regularMaterial, in: Capsule())
+            .overlay(
+                Capsule().strokeBorder(DS.Palette.statusWaiting, lineWidth: DS.Stroke.hairline)
+            )
+        }
+        .buttonStyle(.plain)
    }

    // MARK: - Timeline drill-down (T-iOS-24, additive)