feat(web): 对齐 Alright 主题视觉规范（配色/字体/图标/背景/动效），并补充设计规范文档

2026-10-22 20:27:10 +08:00
parent e522a98f6f
commit 386c0f77c7
50 changed files with 6344 additions and 1094 deletions
@@ -1,22 +0,0 @@
-export function BackToTop() {
-  const handleClick = () => {
-    // 桌面端滚动的是内容容器，窄屏滚动的是窗口
-    document.getElementById('content-scroll')?.scrollTo({ top: 0, behavior: 'smooth' })
-    window.scrollTo({ top: 0, behavior: 'smooth' })
-  }
-
-  return (
-    <button
-      type="button"
-      className="back-to-top"
-      title="回到顶部"
-      aria-label="回到顶部"
-      onClick={handleClick}
-    >
-      <svg viewBox="0 0 24 24" aria-hidden="true">
-        <line x1="5" y1="4" x2="19" y2="4" />
-        <path d="M12 20V8M6 14l6-6 6 6" />
-      </svg>
-    </button>
-  )
-}
@@ -1,84 +0,0 @@
-import { useState } from 'react'
-import type { Project } from '../api'
-import { MOCK_NAV_GROUPS, MOCK_NAV_PRIMARY } from '../catalog'
-import { ProfileCard } from './ProfileCard'
-import { ServicePanel } from './ServicePanel'
-
-type SidebarProps = {
-  projects: Project[]
-  live: boolean
-  refreshing: boolean
-  onRefresh: () => void
-}
-
-export function Sidebar({ projects, live, refreshing, onRefresh }: SidebarProps) {
-  const [openGroups, setOpenGroups] = useState<string[]>([])
-  const [activeId, setActiveId] = useState('common')
-
-  const toggle = (id: string) => {
-    setOpenGroups((previous) =>
-      previous.includes(id) ? previous.filter((item) => item !== id) : [...previous, id],
-    )
-  }
-
-  const isOpen = (id: string) => openGroups.includes(id)
-
-  return (
-    <aside className="sidebar">
-      <ProfileCard />
-
-      <ServicePanel
-        projects={projects}
-        live={live}
-        refreshing={refreshing}
-        onRefresh={onRefresh}
-      />
-
-      <nav className="nav-card card-box" aria-label="站点分类">
-        <ul className="nav-group">
-          {MOCK_NAV_PRIMARY.map((link) => (
-            <li className="nav-item" key={link.id}>
-              <a
-                className={`nav-link${activeId === link.id ? ' active' : ''}`}
-                href={`#${link.id}`}
-                onClick={() => setActiveId(link.id)}
-              >
-                <span>{link.label}</span>
-              </a>
-            </li>
-          ))}
-
-          {MOCK_NAV_GROUPS.map((group) => (
-            <li className={`nav-item${isOpen(group.id) ? ' open' : ''}`} key={group.id}>
-              <button
-                type="button"
-                className="nav-link"
-                aria-expanded={isOpen(group.id)}
-                onClick={() => toggle(group.id)}
-              >
-                <span>{group.label}</span>
-                <span className="nav-arrow" aria-hidden="true">
-                  ›
-                </span>
-              </button>
-
-              <ul className="submenu">
-                {group.links.map((link) => (
-                  <li key={link.id}>
-                    <a
-                      className={`nav-link${activeId === link.id ? ' active' : ''}`}
-                      href={`#${link.id}`}
-                      onClick={() => setActiveId(link.id)}
-                    >
-                      <span>{link.label}</span>
-                    </a>
-                  </li>
-                ))}
-              </ul>
-            </li>
-          ))}
-        </ul>
-      </nav>
-    </aside>
-  )
-}
@@ -1,26 +0,0 @@
-import type { CatalogCard } from '../catalog'
-
-type SiteCardProps = {
-  card: CatalogCard
-  index: number
-}
-
-export function SiteCard({ card, index }: SiteCardProps) {
-  return (
-    <a
-      className="card"
-      href={card.href}
-      title={card.title}
-      // 轻微错峰入场，最多延迟 12 个卡片
-      style={{ animationDelay: `${Math.min(index, 12) * 24}ms` }}
-    >
-      <span className="card-icon" aria-hidden="true">
-        {card.initial}
-      </span>
-      <span className="card-body">
-        <span className="card-title">{card.title}</span>
-        <span className={`card-desc${card.mono ? ' is-mono' : ''}`}>{card.desc}</span>
-      </span>
-    </a>
-  )
-}
@@ -1,89 +0,0 @@
-import { useMemo } from 'react'
-import type { Project } from '../api'
-import { LoginIcon, SearchIcon } from './icons'
-
-type TopBarProps = {
-  projects: Project[]
-  live: boolean
-  onFocusSearch: () => void
-}
-
-type TickerItem = {
-  tag: string
-  text: string
-}
-
-export function TopBar({ projects, live, onFocusSearch }: TopBarProps) {
-  return (
-    <header className="topbar">
-      <div className="topbar-inner">
-        <a className="brand" href="/" aria-label="Stash 首页">
-          <span className="brand-mark" aria-hidden="true">
-            S
-          </span>
-          <span className="brand-name">STASH</span>
-        </a>
-
-        <Ticker projects={projects} live={live} />
-
-        <div className="top-actions">
-          <button
-            type="button"
-            className="icon-button"
-            title="搜索（Ctrl+K）"
-            aria-label="聚焦搜索框"
-            onClick={onFocusSearch}
-          >
-            <SearchIcon />
-          </button>
-          {/* TODO(auth): 后端登录接口就绪后接上，目前仅作入口占位 */}
-          <button type="button" className="icon-button" title="登录" aria-label="登录">
-            <LoginIcon />
-          </button>
-        </div>
-      </div>
-    </header>
-  )
-}
-
-/** 顶栏跑马灯：展示连接状态、项目数量与前几个项目名。 */
-function Ticker({ projects, live }: { projects: Project[]; live: boolean }) {
-  const items = useMemo(() => buildTickerItems(projects, live), [projects, live])
-
-  // 复制一份实现无缝循环，动画位移为 -50%
-  const loop = [...items, ...items]
-
-  return (
-    <div className="ticker" aria-hidden="true">
-      <div className="ticker-track">
-        {loop.map((item, index) => (
-          <span className="ticker-item" key={`${item.tag}-${item.text}-${index}`}>
-            <span className="ticker-tag">{item.tag}</span>
-            {item.text}
-          </span>
-        ))}
-      </div>
-    </div>
-  )
-}
-
-function buildTickerItems(projects: Project[], live: boolean): TickerItem[] {
-  const items: TickerItem[] = [
-    { tag: '状态', text: live ? '实时同步已连接' : '等待服务连接' },
-    { tag: '项目', text: `共 ${projects.length} 个本地应用` },
-  ]
-
-  if (projects.length === 0) {
-    items.push({
-      tag: '提示',
-      text: '把静态站点放进托管目录，并保留 index.html，就会出现在这里',
-    })
-    return items
-  }
-
-  for (const project of projects.slice(0, 6)) {
-    items.push({ tag: '本地', text: project.name })
-  }
-
-  return items
-}
@@ -0,0 +1,33 @@
+import { ArrowUpIcon } from './Icon'
+
+/**
+ * 回到顶部：复刻 Alright 主题的 .scroll-toolbar .totop-button。
+ *
+ * - 42px 圆形、浅灰底，固定在右侧（bottom: 50%）
+ * - 默认隐藏，只有内容区滚动后才淡入，回到顶部后再淡出
+ */
+type BackToTopProps = {
+  /** 内容区是否已滚动（由 App 传入） */
+  visible: boolean
+}
+
+export function BackToTop({ visible }: BackToTopProps) {
+  const handleClick = () => {
+    // 桌面端滚动的是内容容器，窄屏滚动的是窗口，两处都滚一遍
+    document.getElementById('content-scroll')?.scrollTo({ top: 0, behavior: 'smooth' })
+    window.scrollTo({ top: 0, behavior: 'smooth' })
+  }
+
+  return (
+    <button
+      type="button"
+      className={`back-to-top${visible ? ' is-visible' : ''}`}
+      title="回到顶部"
+      aria-label="回到顶部"
+      tabIndex={visible ? 0 : -1}
+      onClick={handleClick}
+    >
+      <ArrowUpIcon />
+    </button>
+  )
+}
@@ -0,0 +1,11 @@
+/**
+ * 数量角标：贴在分区标题右上角的小红标。
+ * 纯展示组件，只接收数字，宽度由内容撑开（两位数不会变形）。
+ */
+type CountBadgeProps = {
+  count: number
+}
+
+export function CountBadge({ count }: CountBadgeProps) {
+  return <span className="count-badge">{count}</span>
+}
@@ -0,0 +1,67 @@
+/**
+ * 通用图标组件。
+ *
+ * 全部使用 Alright 主题的 iconfont 线性图标（见 src/iconfont.css），
+ * 尺寸与颜色由使用处的 CSS 控制（font-size / color），
+ * 因此同一套图标可以复用在按钮、统计条、导航等不同位置。
+ */
+
+type IconProps = {
+  /** 附加类名，便于局部覆盖字号或颜色 */
+  className?: string
+}
+
+const base = (name: string, className?: string) =>
+  `iconfont icon-${name}${className !== undefined ? ` ${className}` : ''}`
+
+export function SearchIcon({ className }: IconProps) {
+  return <i className={base('search', className)} aria-hidden="true" />
+}
+
+export function UserIcon({ className }: IconProps) {
+  return <i className={base('user', className)} aria-hidden="true" />
+}
+
+export function RefreshIcon({ className }: IconProps) {
+  return <i className={base('refresh', className)} aria-hidden="true" />
+}
+
+export function LinkIcon({ className }: IconProps) {
+  return <i className={base('link', className)} aria-hidden="true" />
+}
+
+export function ExternalIcon({ className }: IconProps) {
+  return <i className={base('external', className)} aria-hidden="true" />
+}
+
+export function EyeIcon({ className }: IconProps) {
+  return <i className={base('eye', className)} aria-hidden="true" />
+}
+
+export function ThumbUpIcon({ className }: IconProps) {
+  return <i className={base('thumb-up', className)} aria-hidden="true" />
+}
+
+export function ShareIcon({ className }: IconProps) {
+  return <i className={base('share', className)} aria-hidden="true" />
+}
+
+export function CloseIcon({ className }: IconProps) {
+  return <i className={base('close', className)} aria-hidden="true" />
+}
+
+export function MoreIcon({ className }: IconProps) {
+  return <i className={base('more', className)} aria-hidden="true" />
+}
+
+export function ArrowUpIcon({ className }: IconProps) {
+  return <i className={base('arrow-up', className)} aria-hidden="true" />
+}
+
+export function ArrowLeftIcon({ className }: IconProps) {
+  return <i className={base('arrow-left', className)} aria-hidden="true" />
+}
+
+export function ArrowDownIcon({ className }: IconProps) {
+  return <i className={base('arrow-down', className)} aria-hidden="true" />
+}
@@ -0,0 +1,49 @@
+import type { AppItem } from '../../data/types'
+
+/**
+ * 应用卡片：逐项复刻 Alright 主题「推荐作者」条目的结构。
+ *
+ * 对应主题的：
+ *   .flex-avatar  > img.avatar-48 + span.avatar-badge.badge_5
+ *   .item-content > h3.font-title.text-md（名字 + span.item-badge.hot）
+ *                 + div.text-xs.text-muted.h-1x（单行描述）
+ *
+ * 热门条目才会同时出现头像角标和 HOT 徽标，普通条目两者都没有。
+ */
+type AppCardProps = {
+  item: AppItem
+  onOpen?: (itemId: string) => void
+}
+
+export function AppCard({ item, onOpen }: AppCardProps) {
+  return (
+    <a
+      className="app-card"
+      href={item.href}
+      title={item.name}
+      onClick={(event) => {
+        if (onOpen === undefined) return
+        if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return
+        event.preventDefault()
+        onOpen(item.id)
+      }}
+    >
+      <span className="app-card-avatar" aria-hidden="true">
+        {item.cover !== undefined ? (
+          <img src={item.cover} alt="" loading="lazy" />
+        ) : (
+          <span className="app-card-letter">{item.icon}</span>
+        )}
+        {item.hot === true && <span className="app-card-verify" />}
+      </span>
+
+      <span className="app-card-info">
+        <span className="app-card-title">
+          <span className="app-card-name">{item.name}</span>
+          {item.hot === true && <span className="app-card-badge" />}
+        </span>
+        <span className="app-card-desc">{item.desc}</span>
+      </span>
+    </a>
+  )
+}
@@ -0,0 +1,24 @@
+import type { AppItem } from '../../data/types'
+import { AppCard } from './AppCard'
+
+/**
+ * 应用网格：默认 4 列，窄屏退化为 2 列。
+ * 首页预览与明细页共用，靠 modifier 调整间距。
+ */
+type AppGridProps = {
+  items: AppItem[]
+  /** 明细页使用更宽松的间距 */
+  variant?: 'home' | 'detail'
+  /** 点击卡片打开条目详情 */
+  onOpen?: (itemId: string) => void
+}
+
+export function AppGrid({ items, variant = 'home', onOpen }: AppGridProps) {
+  return (
+    <div className={`app-grid${variant === 'detail' ? ' app-grid--detail' : ''}`}>
+      {items.map((item) => (
+        <AppCard key={item.id} item={item} onOpen={onOpen} />
+      ))}
+    </div>
+  )
+}
@@ -0,0 +1,36 @@
+import type { ArticleItem } from '../../data/types'
+
+/**
+ * 首页图文卡：4:3 封面 + 底部渐变条上的标题。
+ * 传入 onOpen 时整张卡变成按钮，点击进入文章详情。
+ */
+type ArticleCardProps = {
+  item: ArticleItem
+  onOpen?: (itemId: string) => void
+}
+
+export function ArticleCard({ item, onOpen }: ArticleCardProps) {
+  const content = (
+    <>
+      <img className="article-cover" src={item.cover} alt={item.title} loading="lazy" />
+      <span className="article-caption">
+        <span className="article-title">{item.title}</span>
+      </span>
+    </>
+  )
+
+  if (onOpen === undefined) {
+    return <figure className="article-card">{content}</figure>
+  }
+
+  return (
+    <button
+      type="button"
+      className="article-card"
+      title={item.title}
+      onClick={() => onOpen(item.id)}
+    >
+      {content}
+    </button>
+  )
+}
@@ -0,0 +1,79 @@
+import type { ArticleItem } from '../../data/types'
+import { ArrowLeftIcon } from '../common/Icon'
+
+/**
+ * 文章详情页（对应模板图二）：
+ * 大标题 + [编辑] + 元信息行 + 白色正文卡（段落 / 小标题 / 配图混排）。
+ *
+ * 正文是 block 数组，后端以后可以直接把富文本结构映射过来，
+ * 不用再改渲染层。
+ */
+type ArticleDetailViewProps = {
+  article: ArticleItem
+  categoryTitle: string
+  onBack: () => void
+}
+
+export function ArticleDetailView({ article, categoryTitle, onBack }: ArticleDetailViewProps) {
+  const meta = article.meta ?? ['2 年前', categoryTitle]
+
+  return (
+    <div className="detail-view article-view">
+      <div className="detail-nav card-box">
+        <button type="button" className="detail-back" onClick={onBack}>
+          <ArrowLeftIcon />
+          返回
+        </button>
+        <span className="detail-breadcrumb">{categoryTitle} / 文章</span>
+      </div>
+
+      <header className="article-head">
+        <h2 className="article-heading">
+          {article.title}
+          <button type="button" className="item-edit" disabled title="编辑功能待接入">
+            [编辑]
+          </button>
+        </h2>
+
+        <div className="article-meta">
+          {meta.map((text, index) => (
+            <span className="article-meta-item" key={text}>
+              {index > 0 && <i className="article-meta-dot" aria-hidden="true" />}
+              {text}
+            </span>
+          ))}
+        </div>
+      </header>
+
+      <article className="article-body card-box">
+        {(article.blocks ?? []).map((block, index) => {
+          if (block.type === 'heading') {
+            return (
+              <h3 className="article-body-heading" key={index}>
+                {block.text}
+              </h3>
+            )
+          }
+
+          if (block.type === 'image') {
+            return (
+              <img
+                className="article-body-image"
+                key={index}
+                src={block.src}
+                alt=""
+                loading="lazy"
+              />
+            )
+          }
+
+          return (
+            <p className="article-body-text" key={index}>
+              {block.text}
+            </p>
+          )
+        })}
+      </article>
+    </div>
+  )
+}
@@ -0,0 +1,19 @@
+import type { ArticleItem } from '../../data/types'
+import { ArticleCard } from './ArticleCard'
+
+/** 图文网格：首页 4 列，窄屏 2 列 */
+type ArticleGridProps = {
+  items: ArticleItem[]
+  /** 点击卡片打开文章详情 */
+  onOpen?: (itemId: string) => void
+}
+
+export function ArticleGrid({ items, onOpen }: ArticleGridProps) {
+  return (
+    <div className="article-grid">
+      {items.map((item) => (
+        <ArticleCard key={item.id} item={item} onOpen={onOpen} />
+      ))}
+    </div>
+  )
+}
@@ -0,0 +1,37 @@
+import type { ArticleItem } from '../../data/types'
+
+/**
+ * 明细页图文卡：上图下文的白卡。
+ * 传入 onOpen 时整张卡变成按钮，点击进入文章详情。
+ */
+type CesCardProps = {
+  item: ArticleItem
+  onOpen?: (itemId: string) => void
+}
+
+export function CesCard({ item, onOpen }: CesCardProps) {
+  const content = (
+    <>
+      <img className="ces-cover" src={item.cover} alt={item.title} loading="lazy" />
+      <span className="ces-body">
+        <span className="ces-title">{item.title}</span>
+        <span className="ces-desc">{item.desc}</span>
+      </span>
+    </>
+  )
+
+  if (onOpen === undefined) {
+    return <article className="ces-card">{content}</article>
+  }
+
+  return (
+    <button
+      type="button"
+      className="ces-card"
+      title={item.title}
+      onClick={() => onOpen(item.id)}
+    >
+      {content}
+    </button>
+  )
+}
@@ -0,0 +1,19 @@
+import type { ArticleItem } from '../../data/types'
+import { CesCard } from './CesCard'
+
+/** 明细页图文网格：4 列白卡，窄屏 2 列 */
+type CesCardGridProps = {
+  items: ArticleItem[]
+  /** 点击卡片打开文章详情 */
+  onOpen?: (itemId: string) => void
+}
+
+export function CesCardGrid({ items, onOpen }: CesCardGridProps) {
+  return (
+    <div className="ces-grid">
+      {items.map((item) => (
+        <CesCard key={item.id} item={item} onOpen={onOpen} />
+      ))}
+    </div>
+  )
+}
@@ -0,0 +1,88 @@
+import { categoryCount, type Category } from '../../data/types'
+import { ArrowLeftIcon } from '../common/Icon'
+import { AppGrid } from './AppGrid'
+import { CesCardGrid } from './CesCardGrid'
+import { GroupBlock } from './GroupBlock'
+import { PosterGrid } from './PosterGrid'
+
+/**
+ * 分类明细视图：返回条 + 面包屑 + hero（图标 / 标题 / 数量）+ 内容区。
+ *
+ * 内容区按分类类型切换：
+ * - apps：指定分组时只渲染该组，否则单组扁平渲染、多组带小标题分组渲染；
+ * - posters：6 列海报；
+ * - articles：上图下文白卡网格。
+ */
+type DetailViewProps = {
+  category: Category
+  /** 从侧栏子菜单进入时指定的分组 */
+  groupId?: string
+  onBack: () => void
+  /** 点击卡片 / 海报进入条目详情 */
+  onOpenItem: (itemId: string) => void
+}
+
+export function DetailView({ category, groupId, onBack, onOpenItem }: DetailViewProps) {
+  const groups = category.kind === 'apps' ? category.groups : []
+  const activeGroup =
+    groupId !== undefined ? groups.find((group) => group.id === groupId) : undefined
+
+  const title = activeGroup?.name ?? category.title
+  const count = activeGroup !== undefined ? activeGroup.items.length : categoryCount(category)
+  const breadcrumb =
+    activeGroup !== undefined
+      ? `首页 / ${category.title} / ${activeGroup.name}`
+      : `首页 / ${category.title}`
+
+  function renderBody() {
+    if (category.kind === 'posters') {
+      return <PosterGrid items={category.items} variant="detail" onOpen={onOpenItem} />
+    }
+
+    if (category.kind === 'articles') {
+      return <CesCardGrid items={category.items} onOpen={onOpenItem} />
+    }
+
+    if (activeGroup !== undefined) {
+      return <AppGrid items={activeGroup.items} variant="detail" onOpen={onOpenItem} />
+    }
+
+    if (category.groups.length === 1) {
+      return <AppGrid items={category.groups[0].items} variant="detail" onOpen={onOpenItem} />
+    }
+
+    if (category.groups.length === 0) {
+      return <p className="section-empty">{category.emptyText ?? '暂无内容'}</p>
+    }
+
+    return (
+      <>
+        {category.groups.map((group) => (
+          <GroupBlock key={group.id} group={group} onOpen={onOpenItem} />
+        ))}
+      </>
+    )
+  }
+
+  return (
+    <div className="detail-view">
+      <div className="detail-nav card-box">
+        <button type="button" className="detail-back" onClick={onBack}>
+          <ArrowLeftIcon />
+          返回首页
+        </button>
+        <span className="detail-breadcrumb">{breadcrumb}</span>
+      </div>
+
+      <div className="detail-hero">
+        <span className="detail-hero-icon" aria-hidden="true">
+          {category.icon}
+        </span>
+        <h2 className="detail-hero-title">{title}</h2>
+        <span className="detail-hero-count">[{count}]</span>
+      </div>
+
+      {renderBody()}
+    </div>
+  )
+}
@@ -0,0 +1,20 @@
+import type { AppGroup } from '../../data/types'
+import { AppGrid } from './AppGrid'
+
+/**
+ * 明细页的分组块：小标题 + 该组的应用网格。
+ * 分类被拆成多个分组时重复使用，单个分组时明细页不渲染标题。
+ */
+type GroupBlockProps = {
+  group: AppGroup
+  onOpen?: (itemId: string) => void
+}
+
+export function GroupBlock({ group, onOpen }: GroupBlockProps) {
+  return (
+    <section className="group-block">
+      <h3 className="group-title">{group.name}</h3>
+      <AppGrid items={group.items} variant="detail" onOpen={onOpen} />
+    </section>
+  )
+}
@@ -0,0 +1,67 @@
+import { categoryCount, flattenAppItems, type Category } from '../../data/types'
+import { AppGrid } from './AppGrid'
+import { ArticleGrid } from './ArticleGrid'
+import { PosterGrid } from './PosterGrid'
+import { SectionCard } from './SectionCard'
+
+/**
+ * 首页：把每个分类渲染成一张分区卡片。
+ *
+ * 每个分区只展示前若干条（由分类的 previewLimit 决定），
+ * 右上角 ••• 进入该分类明细，点击卡片 / 海报则进入该条目的详情。
+ */
+type HomeViewProps = {
+  categories: Category[]
+  onOpenDetail: (categoryId: string) => void
+  onOpenItem: (categoryId: string, itemId: string) => void
+}
+
+export function HomeView({ categories, onOpenDetail, onOpenItem }: HomeViewProps) {
+  return (
+    <div className="home-view">
+      {categories.map((category) => (
+        <SectionCard
+          key={category.id}
+          title={category.title}
+          count={categoryCount(category)}
+          barColor={category.barColor}
+          onMore={() => onOpenDetail(category.id)}
+        >
+          {renderPreview(category, onOpenItem)}
+        </SectionCard>
+      ))}
+    </div>
+  )
+}
+
+/** 按分类类型输出对应的预览网格；应用类为空时给出提示文案 */
+function renderPreview(
+  category: Category,
+  onOpenItem: (categoryId: string, itemId: string) => void,
+) {
+  if (category.kind === 'apps') {
+    const items = flattenAppItems(category).slice(0, category.previewLimit ?? 4)
+
+    if (items.length === 0) {
+      return <p className="section-empty">{category.emptyText ?? '暂无内容'}</p>
+    }
+
+    return <AppGrid items={items} onOpen={(itemId) => onOpenItem(category.id, itemId)} />
+  }
+
+  if (category.kind === 'posters') {
+    return (
+      <PosterGrid
+        items={category.items.slice(0, category.previewLimit ?? 6)}
+        onOpen={(itemId) => onOpenItem(category.id, itemId)}
+      />
+    )
+  }
+
+  return (
+    <ArticleGrid
+      items={category.items.slice(0, category.previewLimit ?? 4)}
+      onOpen={(itemId) => onOpenItem(category.id, itemId)}
+    />
+  )
+}
@@ -0,0 +1,122 @@
+import type { ItemDetailModel } from '../../data/detail'
+import type { RelatedItem } from '../../data/types'
+import { ExternalIcon, EyeIcon, ShareIcon, ThumbUpIcon } from '../common/Icon'
+import { ArrowLeftIcon } from '../common/Icon'
+import { RelatedList } from './RelatedList'
+
+/**
+ * 条目详情页：应用与电影共用。
+ *
+ * 版式：标题 + 主图（方形头像 / 竖版海报）+ 标签行 + 一句话评价 + 正文
+ * + 操作条（浏览 / 点赞 / 分享 / 跳转）+ 可选横幅 + 「推荐阅读」。
+ * 具体形态由 ItemDetailModel 决定，这里不判断条目类型。
+ */
+type ItemDetailViewProps = {
+  breadcrumb: string
+  model: ItemDetailModel
+  related: RelatedItem[]
+  onBack: () => void
+  onOpenItem: (itemId: string) => void
+}
+
+export function ItemDetailView({
+  breadcrumb,
+  model,
+  related,
+  onBack,
+  onOpenItem,
+}: ItemDetailViewProps) {
+  return (
+    <div className="detail-view item-view">
+      <div className="detail-nav card-box">
+        <button type="button" className="detail-back" onClick={onBack}>
+          <ArrowLeftIcon />
+          返回
+        </button>
+        <span className="detail-breadcrumb">{breadcrumb}</span>
+      </div>
+
+      <article className="item-card card-box">
+        <h2 className="item-title">
+          {model.title}
+          <button type="button" className="item-edit" disabled title="编辑功能待接入">
+            [编辑]
+          </button>
+        </h2>
+
+        <div className={`item-cover item-cover--${model.shape}`}>
+          {model.cover !== undefined ? (
+            <img src={model.cover} alt={model.title} loading="lazy" />
+          ) : (
+            <span className="item-cover-letter">{model.fallbackIcon ?? '•'}</span>
+          )}
+        </div>
+
+        {model.tags.length > 0 && (
+          <div className="item-tags">
+            {model.tags.map((tag) => (
+              <span className="item-tag" key={tag}>
+                {tag}
+              </span>
+            ))}
+          </div>
+        )}
+
+        {model.comment !== undefined && (
+          <div className="item-quote">
+            <span className="item-quote-mark" aria-hidden="true">
+              “
+            </span>
+            <p className="item-quote-text">{model.comment}</p>
+          </div>
+        )}
+
+        {model.paragraphs.map((paragraph, index) => (
+          <p className="item-desc" key={`${index}-${paragraph.slice(0, 8)}`}>
+            {paragraph}
+          </p>
+        ))}
+
+        <div className="item-actions">
+          <span className="item-stat" title="浏览量">
+            <EyeIcon />
+            <em>{model.views}</em>
+          </span>
+
+          <span className="item-stat" title="点赞数">
+            <ThumbUpIcon />
+            <em>{model.likes}</em>
+          </span>
+
+          <button
+            type="button"
+            className="item-stat item-stat--icon"
+            title="分享（待接入）"
+            aria-label="分享"
+          >
+            <ShareIcon />
+          </button>
+
+          {/* 占位数据没有真实地址时，按钮置灰而不是打开空白页 */}
+          {model.href === '#' ? (
+            <button type="button" className="item-jump" disabled title="暂无跳转地址">
+              跳转到
+              <ExternalIcon />
+            </button>
+          ) : (
+            <a className="item-jump" href={model.href} target="_blank" rel="noreferrer">
+              跳转到
+              <ExternalIcon />
+            </a>
+          )}
+        </div>
+
+        {model.banner !== undefined && (
+          <img className="item-banner" src={model.banner} alt="" loading="lazy" />
+        )}
+      </article>
+
+      <RelatedList items={related} onOpen={onOpenItem} />
+    </div>
+  )
+}
@@ -0,0 +1,36 @@
+import type { PosterItem } from '../../data/types'
+
+/**
+ * 竖版海报卡：2:3 封面 + 底部渐变遮罩上的标题。
+ * 传入 onOpen 时整张卡变成按钮，点击进入该电影的详情页。
+ */
+type PosterCardProps = {
+  item: PosterItem
+  onOpen?: (itemId: string) => void
+}
+
+export function PosterCard({ item, onOpen }: PosterCardProps) {
+  const content = (
+    <>
+      <img className="poster-cover" src={item.cover} alt={item.title} loading="lazy" />
+      <span className="poster-caption">
+        <span className="poster-title">{item.title}</span>
+      </span>
+    </>
+  )
+
+  if (onOpen === undefined) {
+    return <figure className="poster-card">{content}</figure>
+  }
+
+  return (
+    <button
+      type="button"
+      className="poster-card"
+      title={item.title}
+      onClick={() => onOpen(item.id)}
+    >
+      {content}
+    </button>
+  )
+}
@@ -0,0 +1,20 @@
+import type { PosterItem } from '../../data/types'
+import { PosterCard } from './PosterCard'
+
+/** 海报网格：首页 6 列，明细页同样 6 列但间距更大 */
+type PosterGridProps = {
+  items: PosterItem[]
+  variant?: 'home' | 'detail'
+  /** 点击海报打开条目详情 */
+  onOpen?: (itemId: string) => void
+}
+
+export function PosterGrid({ items, variant = 'home', onOpen }: PosterGridProps) {
+  return (
+    <div className={`poster-grid${variant === 'detail' ? ' poster-grid--detail' : ''}`}>
+      {items.map((item) => (
+        <PosterCard key={item.id} item={item} onOpen={onOpen} />
+      ))}
+    </div>
+  )
+}
@@ -0,0 +1,45 @@
+import type { RelatedItem } from '../../data/types'
+
+/**
+ * 详情页的「推荐阅读」：两列小卡片，头像 + 名称 + 截断描述。
+ * 点击任意一条会在同一视图内切换到对应条目的详情。
+ */
+type RelatedListProps = {
+  items: RelatedItem[]
+  onOpen: (itemId: string) => void
+}
+
+export function RelatedList({ items, onOpen }: RelatedListProps) {
+  if (items.length === 0) return null
+
+  return (
+    <section className="related-card card-box" aria-label="推荐阅读">
+      <h3 className="related-title">
+        <span className="related-title-icon" aria-hidden="true">
+          📚
+        </span>
+        推荐阅读
+      </h3>
+
+      <ul className="related-grid">
+        {items.map((item) => (
+          <li key={item.id}>
+            <button type="button" className="related-item" onClick={() => onOpen(item.id)}>
+              <span className="related-avatar" aria-hidden="true">
+                {item.cover !== undefined ? (
+                  <img src={item.cover} alt="" loading="lazy" />
+                ) : (
+                  (item.icon ?? '•')
+                )}
+              </span>
+              <span className="related-info">
+                <span className="related-name">{item.name}</span>
+                <span className="related-desc">{item.desc}</span>
+              </span>
+            </button>
+          </li>
+        ))}
+      </ul>
+    </section>
+  )
+}
@@ -0,0 +1,47 @@
+import type { ReactNode } from 'react'
+import { CountBadge } from '../common/CountBadge'
+import { MoreIcon } from '../common/Icon'
+
+/**
+ * 首页分区卡片：白底圆角容器，组成「色条 + 标题 + 角标 + 更多按钮 + 内容」。
+ * 内容由调用方传入，因此同一容器可以承载应用网格、海报网格或图文网格。
+ */
+type SectionCardProps = {
+  title: string
+  count: number
+  /** 标题左侧色条颜色，不同分类用不同颜色区分 */
+  barColor?: string
+  /** 点击右上角 ••• 进入该分类的明细视图 */
+  onMore?: () => void
+  children: ReactNode
+}
+
+export function SectionCard({ title, count, barColor, onMore, children }: SectionCardProps) {
+  return (
+    <section className="section-card">
+      <header className="section-header">
+        <div className="section-title-wrapper">
+          <span className="section-bar" style={{ backgroundColor: barColor }} aria-hidden="true" />
+          <span className="section-title-box">
+            <h2 className="section-title">{title}</h2>
+            <CountBadge count={count} />
+          </span>
+        </div>
+
+        {onMore !== undefined && (
+          <button
+            type="button"
+            className="section-more"
+            title={`查看${title}全部`}
+            aria-label={`查看${title}全部`}
+            onClick={onMore}
+          >
+            <MoreIcon />
+          </button>
+        )}
+      </header>
+
+      {children}
+    </section>
+  )
+}
@@ -0,0 +1,24 @@
+import type { ReactNode } from 'react'
+
+/**
+ * 顶栏中间的一条信息，形如「[标签] 文本」。
+ * 标签带浅色底，用于区分「本地 / 状态」这类类型前缀。
+ */
+type HeaderInfoItemProps = {
+  /** 可选的前缀标签 */
+  tag?: string
+  /** 标签配色：默认蓝色，状态类用绿色 */
+  tone?: 'blue' | 'green'
+  children: ReactNode
+}
+
+export function HeaderInfoItem({ tag, tone = 'blue', children }: HeaderInfoItemProps) {
+  return (
+    <div className="header-info-item">
+      {tag !== undefined && (
+        <span className={`header-info-tag${tone === 'green' ? ' is-green' : ''}`}>{tag}</span>
+      )}
+      <span className="header-info-text">{children}</span>
+    </div>
+  )
+}
@@ -0,0 +1,58 @@
+import { SearchIcon, UserIcon } from '../common/Icon'
+import { HeaderInfoItem } from './HeaderInfoItem'
+
+/**
+ * 顶部栏：左品牌、中间运行信息、右侧操作图标。
+ * 信息区展示「共 N 个本地应用 / 第一个项目 / 连接状态」，
+ * 对应模板里的 header-center-info。
+ */
+type SiteHeaderProps = {
+  projectCount: number
+  /** 用于展示的第一个项目名，没有项目时留空 */
+  sampleProject?: string
+  live: boolean
+  onFocusSearch: () => void
+}
+
+export function SiteHeader({ projectCount, sampleProject, live, onFocusSearch }: SiteHeaderProps) {
+  return (
+    <header className="site-header">
+      <div className="layout-container site-header-inner">
+        <a className="site-brand" href="/" aria-label="Stash 首页">
+          <span className="site-brand-mark" aria-hidden="true">
+            S
+          </span>
+          <span className="site-brand-name">STASH</span>
+        </a>
+
+        <div className="header-info">
+          <HeaderInfoItem>共 {projectCount} 个本地应用</HeaderInfoItem>
+
+          {sampleProject !== undefined && (
+            <HeaderInfoItem tag="本地">{sampleProject}</HeaderInfoItem>
+          )}
+
+          <HeaderInfoItem tag="状态" tone={live ? 'green' : 'blue'}>
+            {live ? '实时同步已连接' : '等待服务连接'}
+          </HeaderInfoItem>
+        </div>
+
+        <div className="header-actions">
+          <button
+            type="button"
+            className="header-icon-button"
+            title="搜索（Ctrl+K）"
+            aria-label="聚焦搜索框"
+            onClick={onFocusSearch}
+          >
+            <SearchIcon />
+          </button>
+          {/* TODO(auth): 后端登录接口就绪后接上，目前仅作入口占位 */}
+          <button type="button" className="header-icon-button" title="登录" aria-label="登录">
+            <UserIcon />
+          </button>
+        </div>
+      </div>
+    </header>
+  )
+}
@@ -1,37 +0,0 @@
-/** 统一的小图标集合：只负责路径，尺寸与颜色由使用处的 CSS 决定。 */
-
-export function RefreshIcon() {
-  return (
-    <svg viewBox="0 0 24 24" aria-hidden="true">
-      <path d="M21 12a9 9 0 1 1-2.64-6.36" />
-      <path d="M21 3v6h-6" />
-    </svg>
-  )
-}
-
-export function SearchIcon() {
-  return (
-    <svg viewBox="0 0 24 24" aria-hidden="true">
-      <circle cx="11" cy="11" r="8" />
-      <line x1="21" y1="21" x2="16.65" y2="16.65" />
-    </svg>
-  )
-}
-
-export function LinkIcon() {
-  return (
-    <svg viewBox="0 0 24 24" aria-hidden="true">
-      <path d="M10 13a5 5 0 0 0 7.07 0l3-3a5 5 0 0 0-7.07-7.07l-1.5 1.5" />
-      <path d="M14 11a5 5 0 0 0-7.07 0l-3 3a5 5 0 0 0 7.07 7.07l1.5-1.5" />
-    </svg>
-  )
-}
-
-export function LoginIcon() {
-  return (
-    <svg viewBox="0 0 24 24" aria-hidden="true">
-      <circle cx="12" cy="8" r="3.6" />
-      <path d="M4.8 20a7.2 7.2 0 0 1 14.4 0" />
-    </svg>
-  )
-}
@@ -1,5 +1,10 @@
 import { useEffect, type RefObject } from 'react'
+import { CloseIcon, SearchIcon } from '../common/Icon'

+/**
+ * 全局搜索框：固定悬浮在顶栏下方居中。
+ * 支持 Ctrl/Cmd+K 聚焦、Esc 清空，输入内容由父组件接管过滤逻辑。
+ */
 type SearchBarProps = {
  value: string
  onChange: (value: string) => void
@@ -22,10 +27,7 @@ export function SearchBar({ value, onChange, inputRef }: SearchBarProps) {

  return (
    <div className="search-bar card-box">
-      <svg className="search-icon" viewBox="0 0 24 24" aria-hidden="true">
-        <circle cx="11" cy="11" r="8" />
-        <line x1="21" y1="21" x2="16.65" y2="16.65" />
-      </svg>
+      <SearchIcon className="search-icon" />

      <input
        ref={inputRef}
@@ -48,9 +50,7 @@ export function SearchBar({ value, onChange, inputRef }: SearchBarProps) {
          aria-label="清空搜索"
          onClick={() => onChange('')}
        >
-          <svg viewBox="0 0 24 24" aria-hidden="true">
-            <path d="M18 6 6 18M6 6l12 12" />
-          </svg>
+          <CloseIcon />
        </button>
      )}
    </div>
@@ -0,0 +1,79 @@
+import { useState } from 'react'
+import { NAV_GROUPS, NAV_TOP_LEVEL, type NavTarget } from '../../data/nav'
+
+/**
+ * 分类导航树：顶层直达链接 + 可折叠分组。
+ * 点击叶子节点不跳转页面，而是把目标（分类 + 可选分组）交给父组件的 onNavigate，
+ * 由父组件切换右侧的明细视图。
+ */
+type CategoryNavProps = {
+  /** 当前明细视图的分类 / 分组，用于高亮 */
+  activeCategoryId?: string
+  activeGroupId?: string
+  onNavigate: (target: NavTarget) => void
+}
+
+export function CategoryNav({ activeCategoryId, activeGroupId, onNavigate }: CategoryNavProps) {
+  const [openGroups, setOpenGroups] = useState<string[]>([])
+
+  const toggle = (id: string) => {
+    setOpenGroups((previous) =>
+      previous.includes(id) ? previous.filter((item) => item !== id) : [...previous, id],
+    )
+  }
+
+  const isOpen = (id: string) => openGroups.includes(id)
+
+  return (
+    <nav className="nav-card card-box" aria-label="站点分类">
+      <ul className="nav-group">
+        {NAV_TOP_LEVEL.map((leaf) => (
+          <li className="nav-item" key={leaf.id}>
+            <button
+              type="button"
+              className={`nav-link${
+                activeCategoryId === leaf.target.categoryId && activeGroupId === undefined
+                  ? ' active'
+                  : ''
+              }`}
+              onClick={() => onNavigate(leaf.target)}
+            >
+              <span>{leaf.label}</span>
+            </button>
+          </li>
+        ))}
+
+        {NAV_GROUPS.map((group) => (
+          <li className={`nav-item${isOpen(group.id) ? ' open' : ''}`} key={group.id}>
+            <button
+              type="button"
+              className="nav-link has-children"
+              aria-expanded={isOpen(group.id)}
+              onClick={() => toggle(group.id)}
+            >
+              <span>{group.label}</span>
+            </button>
+
+            {/* 用 grid-template-rows 做高度动画：不需要猜 max-height，
+                也不会在过渡期间出现滚动条 */}
+            <div className={`submenu-wrap${isOpen(group.id) ? ' is-open' : ''}`}>
+              <ul className="submenu">
+                {group.leaves.map((leaf) => (
+                  <li key={leaf.id}>
+                    <button
+                      type="button"
+                      className={`nav-link${activeGroupId === leaf.target.groupId ? ' active' : ''}`}
+                      onClick={() => onNavigate(leaf.target)}
+                    >
+                      <span>{leaf.label}</span>
+                    </button>
+                  </li>
+                ))}
+              </ul>
+            </div>
+          </li>
+        ))}
+      </ul>
+    </nav>
+  )
+}
@@ -1,16 +1,17 @@
-import { PLACEHOLDER_PROFILE } from '../profile'
+import { PLACEHOLDER_PROFILE } from '../../profile'
+import { UserIcon } from '../common/Icon'

-/** 登录后展示的用户资料卡（数据为占位，见 profile.ts）。 */
+/**
+ * 用户资料卡：头像、认证徽标、昵称、角色、简介、IP 属地。
+ * 数据来自 profile.ts 的占位对象，后端接入鉴权后替换。
+ */
 export function ProfileCard() {
  const { name, role, bio, location } = PLACEHOLDER_PROFILE

  return (
    <section className="profile-card card-box" aria-label="用户信息">
      <div className="profile-avatar" aria-hidden="true">
-        <svg viewBox="0 0 24 24">
-          <circle cx="12" cy="9" r="3.4" />
-          <path d="M5.6 19.4a6.6 6.6 0 0 1 12.8 0" />
-        </svg>
+        <UserIcon />
        <span className="profile-badge">✓</span>
      </div>

@@ -1,6 +1,10 @@
-import type { Project } from '../api'
-import { LinkIcon, RefreshIcon } from './icons'
+import type { Project } from '../../api'
+import { LinkIcon, RefreshIcon } from '../common/Icon'

+/**
+ * 本地服务面板：连接状态、项目数、访问地址，以及两个操作入口。
+ * 只读展示 + 触发刷新，不负责导航。
+ */
 type ServicePanelProps = {
  projects: Project[]
  live: boolean
@@ -8,10 +12,6 @@ type ServicePanelProps = {
  onRefresh: () => void
 }

-/**
- * 本地服务面板：状态概览 + 操作入口。
- * 项目列表本身在右侧内容区以卡片呈现，这里不再展开。
- */
 export function ServicePanel({ projects, live, refreshing, onRefresh }: ServicePanelProps) {
  const host = typeof window === 'undefined' ? '-' : window.location.host

@@ -0,0 +1,48 @@
+import type { Project } from '../../api'
+import type { NavTarget } from '../../data/nav'
+import { CategoryNav } from './CategoryNav'
+import { ProfileCard } from './ProfileCard'
+import { ServicePanel } from './ServicePanel'
+
+/**
+ * 左侧栏容器：用户资料 + 本地服务面板 + 分类导航。
+ * 只负责布局与数据透传，具体内容由三个子组件分别渲染。
+ */
+type SidebarProps = {
+  projects: Project[]
+  live: boolean
+  refreshing: boolean
+  onRefresh: () => void
+  activeCategoryId?: string
+  activeGroupId?: string
+  onNavigate: (target: NavTarget) => void
+}
+
+export function Sidebar({
+  projects,
+  live,
+  refreshing,
+  onRefresh,
+  activeCategoryId,
+  activeGroupId,
+  onNavigate,
+}: SidebarProps) {
+  return (
+    <aside className="sidebar">
+      <ProfileCard />
+
+      <ServicePanel
+        projects={projects}
+        live={live}
+        refreshing={refreshing}
+        onRefresh={onRefresh}
+      />
+
+      <CategoryNav
+        activeCategoryId={activeCategoryId}
+        activeGroupId={activeGroupId}
+        onNavigate={onNavigate}
+      />
+    </aside>
+  )
+}