novalon-website/docs/superpowers/plans/2026-04-28-phase1-view-transitions-svg-container-queries.md

前沿技术升级 Phase 1 实现计划：View Transitions + SVG drawSVG + Container Queries

面向 AI 代理的工作者： 必需子技能：使用 superpowers:subagent-driven-development（推荐）或 superpowers:executing-plans 逐任务实现此计划。步骤使用复选框（- [ ]）语法来跟踪进度。

目标： 在不改变现有静态导出架构的前提下，引入 View Transitions API 实现跨页面流畅过渡、SVG 路径动画实现品牌标题毛笔书写效果、Container Queries 实现组件级响应式布局。

架构： 三项技术均为渐进增强——View Transitions 作为浏览器原生 API 零运行时依赖；SVG drawSVG 基于 GSAP 的 SVG 路径动画插件，仅在品牌标题组件中引入；Container Queries 为纯 CSS 特性，替换现有媒体查询驱动的组件布局。三项改动互不耦合，可独立交付。

技术栈： React 19.2 View Transitions API、GSAP 3 + DrawSVGPlugin、CSS Container Queries、Next.js 16 App Router

---

文件结构

新建文件

文件	职责
src/components/ui/view-transition.tsx	View Transition 封装组件，提供声明式 API
src/components/ui/calligraphy-title.tsx	品牌标题 SVG 书写动画组件
src/components/ui/calligraphy-title.test.tsx	品牌标题组件测试
src/components/ui/view-transition.test.tsx	View Transition 组件测试
public/brand/ruixin-zhiyuan.svg	"睿新致遠" SVG 路径数据

修改文件

文件	变更内容
src/app/(marketing)/layout.tsx	包裹 ViewTransition，实现跨页面过渡
src/components/sections/hero-section.tsx	替换 HeroTitle 为 CalligraphyTitle
src/components/sections/hero-section-atoms.tsx	移除旧 HeroTitle，改用 CalligraphyTitle
src/components/ui/animated-card.tsx	添加 Container Query 支持
src/components/sections/products-section.tsx	产品卡片容器添加 container-type
src/components/sections/services-section.tsx	服务卡片容器添加 container-type
src/app/globals.css	添加 View Transition 关键帧、Container Query 样式
package.json	添加 gsap 依赖

---

任务 1：View Transitions API 基础封装

文件：

• 创建：src/components/ui/view-transition.tsx

• 创建：src/components/ui/view-transition.test.tsx

• 步骤 1：编写失败的测试

// src/components/ui/view-transition.test.tsx
import { render, screen } from '@testing-library/react';
import { describe, it, expect, vi } from 'vitest';
import { ViewTransitionWrapper } from './view-transition';

describe('ViewTransitionWrapper', () => {
  it('renders children when View Transitions API is not supported', () => {
    const originalStartViewTransition = document.startViewTransition;
    // @ts-expect-error - testing fallback
    document.startViewTransition = undefined;

    render(
      <ViewTransitionWrapper name="hero-title">
        <h1>Test Content</h1>
      </ViewTransitionWrapper>
    );

    expect(screen.getByText('Test Content')).toBeInTheDocument();

    // @ts-expect-error - restore
    document.startViewTransition = originalStartViewTransition;
  });

  it('applies view-transition-name style when name prop is provided', () => {
    render(
      <ViewTransitionWrapper name="hero-title">
        <h1>Test Content</h1>
      </ViewTransitionWrapper>
    );

    const element = screen.getByText('Test Content').parentElement;
    expect(element?.style.viewTransitionName).toBe('hero-title');
  });

  it('renders without name prop (no view-transition-name)', () => {
    render(
      <ViewTransitionWrapper>
        <h1>Test Content</h1>
      </ViewTransitionWrapper>
    );

    const element = screen.getByText('Test Content').parentElement;
    expect(element?.style.viewTransitionName).toBe('');
  });
});

• 步骤 2：运行测试验证失败

运行：npx vitest run src/components/ui/view-transition.test.tsx 预期：FAIL — 模块 ./view-transition 不存在

• 步骤 3：编写最少实现代码

// src/components/ui/view-transition.tsx
'use client';

import { type ReactNode, type CSSProperties } from 'react';

interface ViewTransitionWrapperProps {
  children: ReactNode;
  name?: string;
  className?: string;
}

export function ViewTransitionWrapper({
  children,
  name,
  className = '',
}: ViewTransitionWrapperProps) {
  const style: CSSProperties = name
    ? { viewTransitionName: name }
    : {};

  return (
    <div style={style} className={className}>
      {children}
    </div>
  );
}

• 步骤 4：运行测试验证通过

运行：npx vitest run src/components/ui/view-transition.test.tsx 预期：PASS

• 步骤 5：Commit

git add src/components/ui/view-transition.tsx src/components/ui/view-transition.test.tsx
git commit -m "feat: add ViewTransitionWrapper component with progressive enhancement"

---

任务 2：View Transitions 跨页面过渡集成

文件：

• 修改：src/app/(marketing)/layout.tsx

• 修改：src/app/globals.css

• 步骤 1：在 globals.css 添加 View Transition 关键帧

在 src/app/globals.css 的 @layer base 块末尾添加：

/* View Transitions - 跨页面过渡动画 */
@keyframes vt-fade-in {
  from { opacity: 0; transform: translateY(8px); }
  to { opacity: 1; transform: translateY(0); }
}

@keyframes vt-fade-out {
  from { opacity: 1; transform: translateY(0); }
  to { opacity: 0; transform: translateY(-8px); }
}

@keyframes vt-hero-enter {
  from { opacity: 0; clip-path: circle(0% at 50% 50%); }
  to { opacity: 1; clip-path: circle(75% at 50% 50%); }
}

::view-transition-old(root) {
  animation: vt-fade-out 0.2s cubic-bezier(0.16, 1, 0.3, 1) both;
}

::view-transition-new(root) {
  animation: vt-fade-in 0.35s cubic-bezier(0.16, 1, 0.3, 1) both;
}

::view-transition-old(hero-title) {
  animation: none;
}

::view-transition-new(hero-title) {
  animation: vt-hero-enter 0.6s cubic-bezier(0.16, 1, 0.3, 1) both;
}

@media (prefers-reduced-motion: reduce) {
  ::view-transition-old(root),
  ::view-transition-new(root) {
    animation: none !important;
  }
  ::view-transition-old(hero-title),
  ::view-transition-new(hero-title) {
    animation: none !important;
  }
}

• 步骤 2：修改 MarketingLayout 集成 View Transitions

在 src/app/(marketing)/layout.tsx 中，将主内容区域包裹 ViewTransitionWrapper：

找到 export default function MarketingLayout 函数，在 children 外层添加 ViewTransitionWrapper：

// 在文件顶部添加导入
import { ViewTransitionWrapper } from '@/components/ui/view-transition';

// 在 return 的 children 包裹处，找到所有渲染 children 的位置
// 对主站布局的 children 添加 ViewTransitionWrapper：
<ViewTransitionWrapper name="page-content">
  {children}
</ViewTransitionWrapper>

// 对产品详情页布局的 children 添加：
<ViewTransitionWrapper name="product-content">
  {children}
</ViewTransitionWrapper>

• 步骤 3：在 HeroSection 中标记共享元素

修改 src/components/sections/hero-section.tsx，对品牌标题添加 view-transition-name：

找到 HeroTitle 的渲染位置，在其外层包裹：

<ViewTransitionWrapper name="hero-title">
  <HeroTitle isVisible={isVisible} />
</ViewTransitionWrapper>

• 步骤 4：验证 View Transitions 工作正常

运行：npm run dev 操作：在首页和各子页面之间导航，观察页面过渡动画 预期：页面切换时有淡入淡出效果，品牌标题有圆形展开动画

• 步骤 5：Commit

git add src/app/globals.css src/app/\(marketing\)/layout.tsx src/components/sections/hero-section.tsx
git commit -m "feat: integrate View Transitions API for cross-page transitions"

---

任务 3：GSAP 安装与 SVG 品牌标题路径准备

文件：

• 创建：public/brand/ruixin-zhiyuan.svg

• 步骤 1：安装 GSAP

运行：npm install gsap

• 步骤 2：创建"睿新致遠"SVG 路径文件

将品牌标题转为 SVG path 数据。由于青柳隷書字体已内嵌，需要用字体渲染后提取路径。

创建 public/brand/ruixin-zhiyuan.svg：

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 200" fill="none">
  <!-- 睿 -->
  <path class="stroke-1" d="M80,40 L80,160 M50,60 L110,60 M50,100 L110,100 M40,140 L120,140 M50,40 L50,160 M110,40 L110,160" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round" fill="none"/>
  <!-- 新 -->
  <path class="stroke-2" d="M200,40 L200,160 M170,60 L230,60 M170,100 L230,100 M160,140 L240,140 M170,40 L170,160 M230,40 L230,160 M200,100 L230,140" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round" fill="none"/>
  <!-- 致 -->
  <path class="stroke-3" d="M320,40 L320,160 M290,60 L350,60 M290,100 L350,100 M280,140 L360,140 M290,40 L290,160 M350,40 L350,160" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round" fill="none"/>
  <!-- 遠 -->
  <path class="stroke-4" d="M440,40 L440,160 M410,60 L470,60 M410,100 L470,100 M400,140 L480,140 M410,40 L410,160 M470,40 L470,160 M440,100 L470,140 M400,80 L440,120" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round" fill="none"/>
</svg>

注意：上述 SVG 为占位骨架。实际生产需使用字体转 SVG 工具（如 opentype.js 或在线工具 text-to-svg）从青柳隷書字体提取精确路径。此步骤在实现时需用脚本从 src/app/fonts/AoyagiReisho.ttf 提取。

• 步骤 3：验证 SVG 可访问

运行：npm run dev 访问：http://localhost:3000/brand/ruixin-zhiyuan.svg 预期：SVG 文件可正常加载

• 步骤 4：Commit

git add package.json package-lock.json public/brand/ruixin-zhiyuan.svg
git commit -m "feat: add GSAP dependency and brand title SVG path data"

---

任务 4：CalligraphyTitle 组件实现

文件：

• 创建：src/components/ui/calligraphy-title.tsx

• 创建：src/components/ui/calligraphy-title.test.tsx

• 步骤 1：编写失败的测试

// src/components/ui/calligraphy-title.test.tsx
import { render, screen, act } from '@testing-library/react';
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { CalligraphyTitle } from './calligraphy-title';

describe('CalligraphyTitle', () => {
  beforeEach(() => {
    vi.useFakeTimers();
  });

  it('renders the title text as fallback', () => {
    render(<CalligraphyTitle text="睿新致遠" />);
    expect(screen.getByText('睿新致遠')).toBeInTheDocument();
  });

  it('applies brand font family', () => {
    render(<CalligraphyTitle text="睿新致遠" />);
    const element = screen.getByText('睿新致遠');
    expect(element.style.fontFamily).toContain('Aoyagi Reisho');
  });

  it('respects reduced motion preference', () => {
    const matchMediaSpy = vi.spyOn(window, 'matchMedia').mockImplementation(
      (query: string) => ({
        matches: query === '(prefers-reduced-motion: reduce)',
        media: query,
        onchange: null,
        addListener: vi.fn(),
        removeListener: vi.fn(),
        addEventListener: vi.fn(),
        removeEventListener: vi.fn(),
        dispatchEvent: vi.fn(),
      })
    );

    render(<CalligraphyTitle text="睿新致遠" />);
    const element = screen.getByText('睿新致遠');
    expect(element).toHaveStyle({ opacity: '1' });

    matchMediaSpy.mockRestore();
  });

  it('applies custom className', () => {
    render(<CalligraphyTitle text="睿新致遠" className="custom-class" />);
    const element = screen.getByText('睿新致遠').closest('.custom-class');
    expect(element).toBeInTheDocument();
  });
});

• 步骤 2：运行测试验证失败

运行：npx vitest run src/components/ui/calligraphy-title.test.tsx 预期：FAIL — 模块 ./calligraphy-title 不存在

• 步骤 3：编写最少实现代码

// src/components/ui/calligraphy-title.tsx
'use client';

import { useRef, useEffect, useState } from 'react';
import { gsap } from 'gsap';
import { DrawSVGPlugin } from 'gsap/DrawSVGPlugin';

gsap.registerPlugin(DrawSVGPlugin);

interface CalligraphyTitleProps {
  text: string;
  className?: string;
  duration?: number;
  stagger?: number;
  delay?: number;
}

export function CalligraphyTitle({
  text,
  className = '',
  duration = 2.5,
  stagger = 0.4,
  delay = 0.3,
}: CalligraphyTitleProps) {
  const svgRef = useRef<SVGSVGElement>(null);
  const containerRef = useRef<HTMLDivElement>(null);
  const [prefersReducedMotion, setPrefersReducedMotion] = useState(false);

  useEffect(() => {
    const mq = window.matchMedia('(prefers-reduced-motion: reduce)');
    setPrefersReducedMotion(mq.matches);

    const handler = (e: MediaQueryListEvent) => setPrefersReducedMotion(e.matches);
    mq.addEventListener('change', handler);
    return () => mq.removeEventListener('change', handler);
  }, []);

  useEffect(() => {
    if (prefersReducedMotion || !svgRef.current) return;

    const paths = svgRef.current.querySelectorAll('path');
    if (paths.length === 0) return;

    gsap.set(paths, { drawSVG: '0%' });

    const ctx = gsap.context(() => {
      gsap.fromTo(
        paths,
        { drawSVG: '0%' },
        {
          drawSVG: '100%',
          duration,
          stagger,
          delay,
          ease: 'power2.inOut',
        }
      );
    }, svgRef);

    return () => ctx.revert();
  }, [prefersReducedMotion, duration, stagger, delay]);

  return (
    <div ref={containerRef} className={`calligraphy-title ${className}`}>
      <svg
        ref={svgRef}
        viewBox="0 0 800 200"
        className="w-full h-auto"
        aria-hidden="true"
        style={{ display: prefersReducedMotion ? 'none' : 'block' }}
      >
        <use href="/brand/ruixin-zhiyuan.svg#strokes" />
      </svg>
      <span
        className={prefersReducedMotion ? '' : 'sr-only'}
        style={{
          fontFamily: "var(--font-aoyagi-reisho), 'Aoyagi Reisho', 'Ma Shan Zheng', serif",
          fontWeight: 'normal',
        }}
      >
        {text}
      </span>
    </div>
  );
}

• 步骤 4：运行测试验证通过

运行：npx vitest run src/components/ui/calligraphy-title.test.tsx 预期：PASS

• 步骤 5：Commit

git add src/components/ui/calligraphy-title.tsx src/components/ui/calligraphy-title.test.tsx
git commit -m "feat: add CalligraphyTitle component with GSAP DrawSVG animation"

---

任务 5：集成 CalligraphyTitle 到 Hero 区域

文件：

• 修改：src/components/sections/hero-section-atoms.tsx

• 修改：src/components/sections/hero-section.tsx

• 步骤 1：替换 HeroTitle 组件

在 src/components/sections/hero-section-atoms.tsx 中，修改 HeroTitle 函数：

// 替换现有 HeroTitle 实现
import { CalligraphyTitle } from '@/components/ui/calligraphy-title';

export function HeroTitle(_props: HeroContentProps) {
  const shouldReduceMotion = useReducedMotion();

  if (shouldReduceMotion) {
    return (
      <h1
        id="hero-heading"
        className="text-5xl sm:text-6xl lg:text-7xl tracking-tight mb-6"
        style={{
          fontFamily: "var(--font-aoyagi-reisho), 'Ma Shan Zheng', 'ZCOOL XiaoWei', 'STKaiti', 'KaiTi', serif",
          fontWeight: 'normal',
          WebkitFontSmoothing: 'antialiased',
          MozOsxFontSmoothing: 'grayscale',
          textRendering: 'optimizeLegibility',
        }}
      >
        {COMPANY_INFO.shortName}
      </h1>
    );
  }

  return (
    <CalligraphyTitle
      text={COMPANY_INFO.shortName}
      className="text-5xl sm:text-6xl lg:text-7xl tracking-tight mb-6"
      duration={2.5}
      stagger={0.4}
      delay={0.3}
    />
  );
}

• 步骤 2：移除旧的 InkReveal 包裹

在 src/components/sections/hero-section-atoms.tsx 中，移除 HeroTitle 中的 InkReveal 包裹（因为 CalligraphyTitle 自带动画），确保 h1 标签和 id="hero-heading" 保留。

• 步骤 3：验证 Hero 标题动画效果

运行：npm run dev 访问：http://localhost:3000 预期：品牌标题"睿新致遠"以毛笔书写动画逐笔呈现

• 步骤 4：Commit

git add src/components/sections/hero-section-atoms.tsx src/components/sections/hero-section.tsx
git commit -m "feat: replace HeroTitle with CalligraphyTitle for brush writing animation"

---

任务 6：Container Queries 实现

文件：

• 修改：src/components/ui/animated-card.tsx

• 修改：src/components/sections/products-section.tsx

• 修改：src/components/sections/services-section.tsx

• 修改：src/app/globals.css

• 步骤 1：在 globals.css 添加 Container Query 工具类

在 src/app/globals.css 的 @layer utilities 块中添加：

/* Container Queries */
@utility cq-container {
  container-type: inline-size;
  container-name: card;
}

@utility cq-container-section {
  container-type: inline-size;
  container-name: section;
}

在 @layer base 块之后添加：

/* Container Query 响应式卡片布局 */
@container card (min-width: 350px) {
  .cq-card-horizontal {
    display: grid;
    grid-template-columns: 120px 1fr;
    gap: 1rem;
  }
}

@container card (min-width: 500px) {
  .cq-card-horizontal {
    grid-template-columns: 180px 1fr;
    gap: 1.5rem;
  }
}

@container section (min-width: 768px) {
  .cq-section-grid {
    grid-template-columns: repeat(2, 1fr);
  }
}

@container section (min-width: 1024px) {
  .cq-section-grid {
    grid-template-columns: repeat(3, 1fr);
  }
}

• 步骤 2：修改 AnimatedCard 添加 container-type

在 src/components/ui/animated-card.tsx 中，找到 motion.div 的 className，添加 cq-container：

// 修改前
className={cn('ink-card', className)}

// 修改后
className={cn('ink-card cq-container', className)}

• 步骤 3：修改 ProductsSection 添加容器查询

在 src/components/sections/products-section.tsx 中，找到产品卡片的 grid 容器 div，添加 cq-container-section：

// 修改前
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-8 items-stretch">

// 修改后
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-8 items-stretch cq-container-section">

• 步骤 4：修改 ServicesSection 添加容器查询

在 src/components/sections/services-section.tsx 中做同样的修改。

• 步骤 5：验证 Container Queries 工作

运行：npm run dev 操作：调整浏览器窗口大小，观察卡片在不同容器宽度下的布局变化 预期：卡片在窄容器中单列显示，宽容器中自动切换为多列

• 步骤 6：运行全量单元测试

运行：npx vitest run 预期：所有测试通过

• 步骤 7：Commit

git add src/app/globals.css src/components/ui/animated-card.tsx src/components/sections/products-section.tsx src/components/sections/services-section.tsx
git commit -m "feat: add Container Queries for component-level responsive layouts"

---

任务 7：Phase 1 集成验证与收尾

文件：

• 无新增/修改

• 步骤 1：运行完整构建

运行：npm run build 预期：构建成功，无错误

• 步骤 2：运行全量测试

运行：npx vitest run 预期：所有测试通过

• 步骤 3：运行类型检查

运行：npm run type-check 预期：无类型错误

• 步骤 4：运行 Lighthouse 审计

运行：npm run lighthouse:mobile 预期：Performance ≥ 90, Accessibility ≥ 95

• 步骤 5：验证渐进增强降级

操作：

1. 在不支持 View Transitions 的浏览器（如 Firefox < 126）中访问 → 页面正常显示，无过渡动画
2. 在不支持 Container Queries 的浏览器中 → 卡片使用原有媒体查询布局
3. 开启 prefers-reduced-motion → 品牌标题直接显示，无书写动画

预期：所有降级场景均正常工作

• 步骤 6：最终 Commit

git add -A
git commit -m "chore: Phase 1 integration verification complete"