Frontend Specialist - 前端开发专家

与 bensz-collect-bugs 的协作约定

• 因本 skill 设计缺陷导致的 bug，先用 bensz-collect-bugs 规范记录到 ~/.bensz-skills/bugs/，不要直接修改用户本地已安装的 skill 源码；若有 workaround，先记 bug，再继续完成任务。
• 只有用户明确要求“report bensz skills bugs”等公开上报时，才用本地 gh 上传新增 bug 到 huangwb8/bensz-bugs；不要 pull / clone 整个仓库。

核心理念

现代前端开发 的最佳实践：

┌─────────────────────────────────────────────────────────┐
│  视觉方向 → 组件化 → 状态管理 → 性能优化 → 用户体验    │
└─────────────────────────────────────────────────────────┘

核心原则：

• ✅ 设计先行
• ✅ 组件化设计
• ✅ 声明式编程
• ✅ 性能优先
• ✅ 渐进增强

何时使用本技能

在以下场景时激活：

• 开发前端应用或组件
• 提到 React、Vue、Next.js、Nuxt.js
• 需要 UI/UX 实现
• 需要视觉重设计、设计系统、仪表盘、落地页或品牌化界面
• 前端性能优化
• 状态管理问题
• 响应式布局

设计优先工作流

在开始编码前，先完成一个最小设计 brief：

1. Purpose：这个页面/组件解决什么业务问题，服务谁
2. Constraints：沿用什么技术栈、设计系统、性能与无障碍约束
3. Aesthetic Direction：从鲜明方向中选一个，例如 editorial、industrial、playful、luxury、retro-futuristic，而不是“现代简洁”这类空话
4. Memorable Differentiator：定义一个最值得被记住的视觉记忆点
5. Implementation Guardrails：把视觉判断翻译成字体、色彩 token、空间节奏、背景层次和动效策略

如果项目已经有设计系统，优先继承并增强它；不要为了“更好看”而推翻既有语言。

前端审美护栏

• Typography：选择有性格的标题字体与稳健的正文字体，建立清晰层级，避免默认系统字体堆叠
• Color System：使用 CSS variables 或 design tokens 管理颜色、层级、阴影和边框，不靠零散硬编码堆样式
• Motion：优先少量高影响动画；HTML/CSS 场景优先 CSS-only，React 只在真正有价值的时刻使用 Motion 类库
• Spatial Composition：允许非对称、重叠、密度变化和有意的留白，避免所有界面都退化成均匀卡片墙
• Background & Atmosphere：通过纹理、渐变网格、图形语言、边框或光影建立氛围，不用纯平底色兜底

反模式清单

• 避免 Inter、Arial、Roboto、system font 一把梭
• 避免紫白渐变、玻璃卡片、大圆角的模板化组合
• 避免无上下文地拼装 shadcn/ui 式组件陈列
• 避免所有页面都长成居中 hero + 三列卡片 + 底部 CTA
• 避免极简主题写成花哨实现，或高表现力主题只有普通卡片

框架选择指南

React 生态

适用场景：

• 需要灵活性和大型生态系统
• 复杂的单页应用（SPA）
• 需要服务端渲染（SSR）

推荐组合：

Vue 生态

适用场景：

• 快速开发和渐进增强
• 中小型应用
• 团队熟悉 Vue 生态

推荐组合：

组件化设计

组件设计原则

1. 单一职责

// ❌ 不好的做法：组件职责过多
function UserProfile() {
  // 获取数据
  const [user, setUser] = useState(null);
  useEffect(() => {
    fetch(`/api/users/${id}`).then(r => r.json()).then(setUser);
  }, []);

  // 格式化日期
  const formatDate = (date) => { /* ... */ };

  // UI 渲染
  return <div>...</div>;
}

// ✅ 好的做法：职责分离
// 数据层
function useUser(id: string) {
  const [user, setUser] = useState(null);
  useEffect(() => {
    fetch(`/api/users/${id}`).then(r => r.json()).then(setUser);
  }, [id]);
  return user;
}

// 工具函数
function formatDate(date: Date): string { /* ... */ }

// 组件：只负责渲染
function UserProfile({ userId }: { userId: string }) {
  const user = useUser(userId);
  if (!user) return <Loading />;
  return <ProfileCard user={user} />;
}

2. 组合优于继承

// ❌ 不好的做法：通过 props 控制多种模式
function Modal({ type, content }) {
  if (type === 'alert') return <AlertModal content={content} />;
  if (type === 'confirm') return <ConfirmModal content={content} />;
  if (type === 'prompt') return <PromptModal content={content} />;
}

// ✅ 好的做法：组合模式
function Modal({ children, footer }: ModalProps) {
  return (
    <Overlay>
      <Container>
        {children}
        {footer && <Footer>{footer}</Footer>}
      </Container>
    </Overlay>
  );
}

// 使用
<Modal footer={<Buttons><OK /><Cancel /></Buttons>}>
  <Alert>Are you sure?</Alert>
</Modal>

3. Props 接口设计

// ✅ 好的 Props 设计
interface ButtonProps {
  // 必需的
  children: React.ReactNode;

  // 可选的，有合理默认值
  variant?: 'primary' | 'secondary' | 'ghost';
  size?: 'sm' | 'md' | 'lg';

  // 事件处理
  onClick?: (e: React.MouseEvent) => void;

  // HTML 属性
  disabled?: boolean;
  type?: 'button' | 'submit';
}

function Button({ variant = 'primary', size = 'md', ...props }: ButtonProps) {
  return <button className={`btn btn-${variant} btn-${size}`} {...props} />;
}

状态管理

状态分类

// 1. Local State - 组件内部状态
const [isOpen, setIsOpen] = useState(false);

// 2. URL State - URL 中的状态
const searchParams = useSearchParams();
const page = searchParams.get('page') || '1';

// 3. Server State - 服务器数据
const { data, isLoading } = useQuery({
  queryKey: ['user', userId],
  queryFn: () => fetchUser(userId)
});

// 4. Global State - 全局共享状态
const { user, login, logout } = useAuthStore();

状态管理工具选择

// Zustand 示例
import create from 'zustand';

interface AuthStore {
  user: User | null;
  login: (credentials: Credentials) => Promise<void>;
  logout: () => void;
}

const useAuthStore = create<AuthStore>((set) => ({
  user: null,
  login: async (credentials) => {
    const user = await api.login(credentials);
    set({ user });
  },
  logout: () => set({ user: null }),
}));

性能优化

1. Code Splitting

// ❌ 不好的做法：一次性加载所有代码
import { HeavyComponent } from './HeavyComponent';

// ✅ 好的做法：动态导入
import { lazy } from 'react';

const HeavyComponent = lazy(() => import('./HeavyComponent'));

function App() {
  return (
    <Suspense fallback={<Loading />}>
      <HeavyComponent />
    </Suspense>
  );
}

2. Memoization

// ✅ 合理使用 memo
export const ExpensiveComponent = memo(function ExpensiveComponent({
  data,
}: {
  data: ComplexData;
}) {
  return <div>{/* 复杂渲染 */}</div>;
});

// ✅ 缓存计算结果
import { useMemo } from 'react';

function List({ items }: { items: Item[] }) {
  const sorted = useMemo(
    () => items.sort((a, b) => a.id - b.id),
    [items]
  );
  return <ul>{sorted.map(item => <li key={item.id}>{item.name}</li>)}</ul>;
}

3. 虚拟滚动

// ✅ 大列表使用虚拟滚动
import { useVirtualizer } from '@tanstack/react-virtual';

function VirtualList({ items }: { items: Item[] }) {
  const parentRef = useRef<HTMLDivElement>(null);

  const virtualizer = useVirtualizer({
    count: items.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 50,
  });

  return (
    <div ref={parentRef} style={{ height: '400px', overflow: 'auto' }}>
      <div style={{ height: `${virtualizer.getTotalSize()}px` }}>
        {virtualizer.getVirtualItems().map(virtualItem => (
          <div
            key={virtualItem.key}
            style={{
              position: 'absolute',
              top: 0,
              left: 0,
              width: '100%',
              height: `${virtualItem.size}px`,
              transform: `translateY(${virtualItem.start}px)`,
            }}
          >
            {items[virtualItem.index].name}
          </div>
        ))}
      </div>
    </div>
  );
}

响应式设计

Tailwind CSS 响应式断点

// ✅ 移动优先设计
function Card() {
  return (
    <div className="
      p-4           /* 移动端默认 */
      md:p-6        /* md (768px+) */
      lg:p-8        /* lg (1024px+) */
    ">
      <h1 className="
        text-xl     /* 移动端 */
        md:text-2xl /* md (768px+) */
        lg:text-3xl /* lg (1024px+) */
      ">
        响应式标题
      </h1>
    </div>
  );
}

容器查询

/* ✅ 使用容器查询 */
@container (min-width: 400px) {
  .card {
    display: grid;
    grid-template-columns: 1fr 1fr;
  }
}

表单处理

React Hook Form + Zod

import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';

// Schema 定义
const loginSchema = z.object({
  email: z.string().email('Invalid email'),
  password: z.string().min(8, 'Password too short'),
});

type LoginForm = z.infer<typeof loginSchema>;

function LoginForm() {
  const {
    register,
    handleSubmit,
    formState: { errors },
  } = useForm<Logi