OpenSpec 项目实战（四） | 布局改造：给长列表装上导航骨架

Explore  →  Propose  →  Apply  →  Verify  →  Archive
   ↓           ↓          ↓         ↓          ↓
  澄清       生成       按任务      验证       归档
  需求       5 工件      执行       检查      change

export default function Home() {
  const tools = getTools();

  const grouped = tools.reduce<Record<string, typeof tools>>((acc, tool) => {
    if (!acc[tool.category]) {
      acc[tool.category] = [];
    }
    acc[tool.category].push(tool);
    return acc;
  }, {});

  const sortedCategories = Object.keys(grouped).sort();

  return (
    <div className="space-y-12 px-6 py-8">
      <div className="text-center py-12">
        <h1 className="text-3xl font-bold mb-3"
          style={{ color: 'var(--color-neutral-900)' }}>
          shuge AI Toolbox
        </h1>
        <p style={{ color: 'var(--color-neutral-500)' }}>
          探索 AI 工具，提升工作效率
        </p>
      </div>

      {sortedCategories.map((category) => {
        const categoryTools = grouped[category].sort((a, b) => {
          const priorityDiff = stagePriority[a.stage] - stagePriority[b.stage];
          if (priorityDiff !== 0) return priorityDiff;
          return a.name.localeCompare(b.name);
        });

        return (
          <section key={category}>
            <h2 className="text-xl font-semibold mb-4"
              style={{ color: 'var(--color-neutral-800)' }}>
              {category}
            </h2>
            {/* 卡片网格 — 每张卡片显示工具名称、状态标签、描述 */}
          </section>
        );
      })}
    </div>
  );
}

<div className="flex gap-4">
  <Link
    to="/"
    className={`px-3 py-1 rounded-md transition-colors ${
      isHome ? 'font-bold' : 'hover:opacity-80'
    }`}
    style={{
      color: isHome ? 'var(--color-primary-500)' : 'var(--color-neutral-600)',
    }}
  >
    首页
  </Link>
</div>

const tools: ToolManifest[] = [
  {
    id: 'text-summary',
    name: '文本摘要',
    route: '/tools/text-summary',
    category: '文本处理',
    description: '快速提取长文本的核心观点',
    stage: 'active',
  },
  {
    id: 'json-formatter',
    name: 'JSON 格式化',
    route: '/tools/json-formatter',
    category: '数据转换',
    description: '美化 JSON 数据结构',
    stage: 'active',
  },
  {
    id: 'code-explainer',
    name: '代码解释',
    route: '/tools/code-explainer',
    category: '开发工具',
    description: '解释代码片段的功能和逻辑',
    stage: 'beta',
  },
  {
    id: 'image-generator',
    name: '图片生成',
    route: '/tools/image-generator',
    category: '内容创作',
    description: '根据描述生成图片',
    stage: 'planned',
  },
  {
    id: 'markdown-table',
    name: 'Markdown 表格',
    route: '/tools/markdown-table',
    category: '文本处理',
    description: '将数据转换为 Markdown 表格',
    stage: 'planned',
  },
];

┌─────────────────────────────────────────────────────────┐
│  方案 A: 粘性顶部 Tab 导航                               │
│  ┌──────────────────────────────────────────────────┐   │
│  │ [全部] [分类A] [分类B] [分类C] [分类D] ...      │   │
│  └──────────────────────────────────────────────────┘   │
│  内容区域（滚动时导航栏固定）                             │
│                                                         │
│  优点：直观，点击即达                                    │
│  缺点：分类多时拥挤，侵占垂直空间                         │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│  方案 B: 左侧迷你导航（桌面端）/ 抽屉式（移动端）          │
│                                                         │
│  ┌────┐ ┌──────────────────────────────────────────┐    │
│  │ A  │ │                                          │    │
│  │ B  │ │              内容区                      │    │
│  │ C  │ │                                          │    │
│  │ D  │ │                                          │    │
│  └────┘ └──────────────────────────────────────────┘    │
│                                                         │
│  优点：不占内容区空间                                    │
│  缺点：移动端交互成本高                                  │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│  方案 C: 锚点式快速跳转                                  │
│                                                         │
│  页面内滚动时出现浮动导航：                               │
│                                                         │
│      ●                                              [🔝]│
│      ●                                              [🔝]│
│                                                         │
│  点击跳转，滚动时淡入淡出                                │
│                                                         │
│  优点：侵入性最小                                       │
│  缺点：需要内容区有清晰锚点                              │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│  方案 D: 分类标题吸顶 + 滚动进度                          │
│                                                         │
│  滚动时当前分类标题固定在顶部：                           │
│  ┌──────────────────────────────────────────────────┐   │
│  │ 当前分类：████████                               │   │
│  └──────────────────────────────────────────────────┘   │
│                                                         │
│  优点：上下文感强，不占额外空间                           │
│  缺点：失去全局概览                                     │
└─────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────┐
│                    TopNav (全局)                    │
├──────────────────────────────────────────────────────┤
│                                                      │
│  ┌─ Content Area ─────────────────────────────────┐  │
│  │  [全部] [文本处理] [数据转换] [开发工具] [内容创作] │  │
│  │  ─────────────────────────────────────────────  │  │
│  │                                                │  │
│  │  ┌─────┐  ┌─────┐  ┌─────┐                    │  │
│  │  │卡片1 │  │卡片2 │  │卡片3 │                    │  │
│  │  └─────┘  └─────┘  └─────┘                    │  │
│  │                                                │  │
│  │  ...                                           │  │
│  └────────────────────────────────────────────────┘  │
│                                                      │
└──────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────┐
│  TopNav (全局导航)                                   │
├──────────────────────────────────────────────────────┤
│                                                      │
│  Content Area:                                       │
│  [全部] [文本处理] [数据转换] [开发工具] [内容创作]     │
│  ─────────────────────────────────────────────────   │
│  ┌─────┐  ┌─────┐  ┌─────┐                          │
│  │卡片1 │  │卡片2 │  │卡片3 │   (过滤显示)           │
│  └─────┘  └─────┘  └─────┘                          │
│                                                      │
│  切换 Tab → 回到顶部                                 │
│  Tab 栏跟随内容滚动，不吸顶                           │
│                                                      │
└──────────────────────────────────────────────────────┘

/opsx:apply

## Implementation Complete

**Change:** layout-restructure
**Schema:** with-review
**Progress:** 12/12 tasks complete ✓

### Commits This Session
- `132cb45` test: add Tab navigation tests to Home
- `de953b9` feat: add Tab navigation to Home page
- `49f533a` feat: complete Tab navigation for Home page

### What Was Built
- Tab 导航栏位于内容区顶部（全部 + 4 个分类 Tab）
- 点击分类 Tab 过滤显示该分类工具卡片
- 「全部」Tab 显示全部分类分组
- Tab 切换时 smooth scroll 到顶部
- 活跃 Tab 使用 `border-b-2 border-accent-500` 高亮
- 提取 `ToolCard` 组件复用

### Test Results
Test Files  6 passed (6)
     Tests  30 passed (30)

All tasks complete! You can archive this change with `/opsx:archive`.

function ToolCard({ tool }: { tool: ReturnType<typeof getTools>[number] }) {
  return (
    <Link
      to={`/tools/${tool.id}`}
      className={`block p-5 rounded-xl border transition-all ${
        tool.stage === 'planned' ? 'opacity-60' : 'hover:shadow-md'
      }`}
      style={{
        backgroundColor: 'var(--color-neutral-50)',
        borderColor: 'var(--color-neutral-200)',
      }}
    >
      <div className="flex items-start justify-between mb-2">
        <h3 className="font-medium" style={{ color: 'var(--color-neutral-900)' }}>
          {tool.name}
        </h3>
        {tool.stage === 'planned' && (
          <span className="text-xs px-2 py-0.5 rounded"
            style={{ backgroundColor: 'var(--color-neutral-200)', color: 'var(--color-neutral-600)' }}>
            Planned
          </span>
        )}
        {tool.stage === 'beta' && (
          <span className="text-xs px-2 py-0.5 rounded"
            style={{ backgroundColor: 'var(--color-accent-100)', color: 'var(--color-accent-600)' }}>
            Beta
          </span>
        )}
      </div>
      <p className="text-sm" style={{ color: 'var(--color-neutral-500)' }}>
        {tool.description}
      </p>
    </Link>
  );
}

const tools = getTools();
const categories = [...new Set(tools.map((t) => t.category))].sort();
const [activeTab, setActiveTab] = useState<string>('全部');

const handleTabClick = (tab: string) => {
  setActiveTab(tab);
  window.scrollTo({ top: 0, behavior: 'smooth' });
};

const filteredTools =
  activeTab === '全部' ? tools : tools.filter((t) => t.category === activeTab);

<nav className="flex gap-2 border-b border-neutral-200">
  <button onClick={() => handleTabClick('全部')}
    className={`px-4 py-2 text-sm font-medium transition-colors ${
      activeTab === '全部' ? 'border-b-2 border-accent-500 text-accent-600' : 'text-neutral-500 hover:text-neutral-900'
    }`}>全部</button>
  {categories.map((cat) => (
    <button key={cat} onClick={() => handleTabClick(cat)}
      className={`px-4 py-2 text-sm font-medium transition-colors ${
        activeTab === cat ? 'border-b-2 border-accent-500 text-accent-600' : 'text-neutral-500 hover:text-neutral-900'
      }`}>{cat}</button>
  ))}
</nav>

{activeTab === '全部' ? (
  categories.map((category) => {
    const categoryTools = filteredTools.filter((t) => t.category === category).sort((a, b) => {
      const priorityDiff = stagePriority[a.stage] - stagePriority[b.stage];
      if (priorityDiff !== 0) return priorityDiff;
      return a.name.localeCompare(b.name);
    });
    return (
      <section key={category}>
        <h2 className="text-xl font-semibold mb-4" style={{ color: 'var(--color-neutral-800)' }}>{category}</h2>
        <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
          {categoryTools.map((tool) => (<ToolCard key={tool.id} tool={tool} />))}
        </div>
      </section>
    );
  })
) : (
  <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
    {filteredTools.sort((a, b) => {
      const priorityDiff = stagePriority[a.stage] - stagePriority[b.stage];
      if (priorityDiff !== 0) return priorityDiff;
      return a.name.localeCompare(b.name);
    }).map((tool) => (<ToolCard key={tool.id} tool={tool} />))}
  </div>
)}

/opsx:verify

## Verification Report: layout-restructure

### Summary
| Dimension    | Status                      |
|--------------|------------------------------|
| Completeness | ✅ All 12 tasks committed    |
| Correctness  | ✅ All 7 spec scenarios covered |
| Coherence    | ✅ Design decisions followed |

npm run build

> shuge-ai-toolbox@0.0.0 build
> tsc -b && vite build

vite v8.0.12 building client environment for production...
✓ 31 modules transformed.
rendering chunks...
computing gzip size...
dist/index.html                   0.46 kB │ gzip:  0.30 kB
dist/assets/index-HNIv7IuC.css   17.34 kB │ gzip:  4.22 kB
dist/assets/index-D0MO6XrT.js   290.38 kB │ gzip: 92.34 kB

✓ built in 105ms

/opsx:archive

## Archive Complete

**Change:** layout-restructure
**Schema:** with-review
**Archived to:** `openspec/changes/archive/2026-05-16-layout-restructure/`
**Specs:** No delta specs (new capability, no existing main spec to sync)

All artifacts complete. All tasks complete.

ls openspec/changes/