Communitygithub.com

ComeOnOliver/skillshub

Orientação para criação de componentes Next.js seguindo padrões de servidor/cliente e estruturas de componentes existentes.

O que é skillshub?

Esta skill, denominada 'Habilidade de Componente Frontend', oferece um guia detalhado e prático para desenvolvedores criarem componentes em Next.js 16+ utilizando o App Router. Ela esclarece a distinção fundamental entre Server Components (padrão, para conteúdo estático e SEO) e Client Components (usados apenas quando é necessária interatividade, como hooks, event handlers e APIs do navegador). A habilidade fornece templates de código, padrões específicos (como ProtectedRoute, LoadingSpinner, ToastNotification e manipulação de formulários) e diretrizes para estilização com Tailwind CSS, acessibilidade WCAG 2.1 AA, nomenclatura de arquivos e requisitos de conformidade do projeto. É uma ferramenta essencial para desenvolvedores que trabalham com Next.js no repositório 'ComeOnOliver/skillshub', garantindo consistência, boas práticas e componentes de alta qualidade.

Funciona com~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/ComeOnOliver/skillshub/tree/HEAD/skills/aiskillstore/marketplace/asmayaseen/frontend-component

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Habilidade de Componente Frontend

Propósito: Orientação para criação de componentes Next.js seguindo padrões de servidor/cliente e estruturas de componentes existentes.

Visão Geral

Next.js 16+ usa App Router com Server Components por padrão. Client Components são usados apenas quando a interatividade é necessária (hooks, event handlers, APIs do navegador).

Componentes Servidor vs Cliente

Componentes Servidor (Padrão)

Quando Usar:

  • Páginas e layouts
  • Conteúdo estático
  • Busca de dados da API (quando possível)
  • Conteúdo otimizado para SEO

Padrão:

// Sem diretiva "use client"
import { Metadata } from "next";

export const metadata: Metadata = {
  title: "Título da Página",
};

export default function PageComponent() {
  return <div>Conteúdo estático</div>;
}

Exemplo: frontend/app/layout.tsx, frontend/app/page.tsx

Componentes Cliente (Quando Necessário)

Quando Usar:

  • Elementos interativos (botões, formulários, inputs)
  • Event handlers (onClick, onChange, etc.)
  • React hooks (useState, useEffect, useRouter, etc.)
  • APIs do navegador (localStorage, window, document, etc.)
  • Atualizações em tempo real
  • Funcionalidade de arrastar e soltar

Padrão:

"use client"; // DEVE ser a primeira linha

import { useState, useEffect } from "react";
import { useRouter } from "next/navigation";

interface ComponentProps {
  prop1: string;
  prop2?: number;
}

export default function ComponentName({ prop1, prop2 }: ComponentProps) {
  const router = useRouter();
  const [state, setState] = useState("");

  useEffect(() => {
    // Efeitos colaterais
  }, []);

  return <div>{/* JSX do componente */}</div>;
}

Exemplo: frontend/components/ProtectedRoute.tsx, frontend/app/signup/page.tsx

Modelo de Estrutura de Componente

"use client"; // Apenas se for componente cliente

/**
 * Nome do Componente
 *
 * Breve descrição do que este componente faz
 */

import { useState, useEffect } from "react";
import { ComponentType } from "@/types";
import { cn } from "@/lib/utils";

interface ComponentProps {
  prop1: string;
  prop2?: number;
  className?: string;
}

export default function ComponentName({ prop1, prop2, className }: ComponentProps) {
  // Estado
  const [state, setState] = useState("");

  // Efeitos
  useEffect(() => {
    // Efeitos colaterais
  }, []);

  // Handlers
  const handleClick = () => {
    // Lógica do handler
  };

  // Renderização
  return (
    <div className={cn("classes-base", className)}>
      {/* Conteúdo do componente */}
    </div>
  );
}

Padrões Específicos de Componente

1. Padrão ProtectedRoute

De: frontend/components/ProtectedRoute.tsx

"use client";

import { useEffect, useState } from "react";
import { useRouter } from "next/navigation";
import { isAuthenticated } from "@/lib/auth";
import LoadingSpinner from "./LoadingSpinner";

interface ProtectedRouteProps {
  children: React.ReactNode;
}

export default function ProtectedRoute({ children }: ProtectedRouteProps) {
  const router = useRouter();
  const [isAuthorized, setIsAuthorized] = useState(false);
  const [isChecking, setIsChecking] = useState(true);

  useEffect(() => {
    async function checkAuth() {
      try {
        const authenticated = await isAuthenticated();

        if (!authenticated) {
          const currentPath = window.location.pathname;
          if (currentPath !== "/signin") {
            sessionStorage.setItem("redirectAfterLogin", currentPath);
          }
          router.push("/signin");
        } else {
          setIsAuthorized(true);
        }
      } catch (error) {
        console.error("Falha na verificação de autenticação:", error);
        router.push("/signin");
      } finally {
        setIsChecking(false);
      }
    }

    checkAuth();
  }, [router]);

  if (isChecking) {
    return (
      <div className="min-h-screen flex items-center justify-center">
        <LoadingSpinner size="large" />
      </div>
    );
  }

  if (!isAuthorized) {
    return null;
  }

  return <>{children}</>;
}

Padrão:

  • Verificar autenticação na montagem
  • Mostrar spinner de carregamento durante a verificação
  • Armazenar destino pretendido no sessionStorage
  • Redirecionar para /signin se não autenticado
  • Renderizar filhos apenas se autorizado

2. Padrão LoadingSpinner

De: frontend/components/LoadingSpinner.tsx

interface LoadingSpinnerProps {
  size?: "small" | "medium" | "large";
  color?: string;
  label?: string;
}

export default function LoadingSpinner({
  size = "medium",
  color = "blue",
  label = "Carregando...",
}: LoadingSpinnerProps) {
  const sizeClasses = {
    small: "w-4 h-4 border-2",
    medium: "w-8 h-8 border-3",
    large: "w-12 h-12 border-4",
  };

  const colorClasses = {
    blue: "border-blue-600 border-t-transparent",
    gray: "border-gray-600 border-t-transparent",
    white: "border-white border-t-transparent",
  };

  const spinnerClass = `${sizeClasses[size]} ${
    colorClasses[color as keyof typeof colorClasses] || colorClasses.blue
  } rounded-full animate-spin`;

  return (
    <div
      className="flex items-center justify-center"
      role="status"
      aria-label={label}
      aria-live="polite"
    >
      <div className={spinnerClass}></div>
      <span className="sr-only">{label}</span>
    </div>
  );
}

Padrão:

  • Múltiplos tamanhos (pequeno, médio, grande)
  • Múltiplas cores (azul, cinza, branco)
  • Rótulos de acessibilidade (role="status", aria-label, aria-live)
  • Texto para leitores de tela com classe sr-only

3. Padrão de Manipulação de Formulário

De: frontend/app/signup/page.tsx

"use client";

import { useState } from "react";
import { useRouter } from "next/navigation";
import { api } from "@/lib/api";
import { isValidEmail, getPasswordStrength } from "@/lib/utils";

export default function SignupPage() {
  const router = useRouter();
  const [formData, setFormData] = useState({
    name: "",
    email: "",
    password: "",
  });
  const [errors, setErrors] = useState<Record<string, string>>({});
  const [isLoading, setIsLoading] = useState(false);
  const [apiError, setApiError] = useState("");

  const validateForm = (): boolean => {
    const newErrors: Record<string, string> = {};

    if (!formData.name.trim()) {
      newErrors.name = "Nome é obrigatório";
    }

    if (!formData.email.trim()) {
      newErrors.email = "Email é obrigatório";
    } else if (!isValidEmail(formData.email)) {
      newErrors.email = "Por favor, insira um endereço de email válido";
    }

    // Mais validações...

    setErrors(newErrors);
    return Object.keys(newErrors).length === 0;
  };

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setApiError("");

    if (!validateForm()) {
      return;
    }

    setIsLoading(true);

    try {
      const response = await api.signup(formData);
      if (response.success) {
        router.push("/dashboard");
      } else {
        setApiError(response.message || "Cadastro falhou");
      }
    } catch (error: any) {
      setApiError(error.message || "Ocorreu um erro");
    } finally {
      setIsLoading(false);
    }
  };

  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    const { name, value } = e.target;
    setFormData((prev) => ({ ...prev, [name]: value }));
    // Limpar erro para este campo quando o usuário começar a digitar
    if (errors[name]) {
      setErrors((prev) => ({ ...prev, [name]: "" }));
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      {/* Campos do formulário */}
    </form>
  );
}

Padrão:

  • Estado separado para dados do formulário, erros, carregamento, erros de API
  • Função de validação que retorna booleano
  • Limpar erros na alteração do input
  • Estado de carregamento durante o envio
  • Try-catch para tratamento de erros
  • Redirecionar em caso de sucesso

4. Padrão ToastNotification

De: frontend/components/ToastNotification.tsx

"use client";

import { useEffect, useState } from "react";
import { ToastMessage, ToastType } from "@/types";

export function useToast() {
  const [toasts, setToasts] = useState<ToastMessage[]>([]);

  const showToast = (type: ToastType, message: string, duration?: number) => {
    const id = `toast-${Date.now()}-${Math.random()}`;
    const newToast: ToastMessage = {
      id,
      type,
      message,
      duration,
    };
    setToasts((prev) => [...prev, newToast]);
  };

  const dismissToast = (id: string) => {
    setToasts((prev) => prev.filter((toast) => toast.id !== id));
  };

  return {
    toasts,
    showToast,
    dismissToast,
    success: (message: string, duration?: number) => showToast("success", message, duration),
    error: (message: string, duration?: number) => showToast("error", message, duration),
    // ...
  };
}

Padrão:

  • Hook personalizado para gerenciamento de toasts
  • Auto-dispensar com duração
  • Empilhar múltiplos toasts
  • Métodos auxiliares (success, error, warning, info)

Padrões Tailwind CSS

1. Apenas Classes Utilitárias

<div className="flex items-center justify-center gap-4 p-6 bg-white rounded-lg shadow-md">

Padrão: Usar classes utilitárias do Tailwind, sem estilos inline

2. Classes Condicionais com a Função cn()

import { cn } from "@/lib/utils";

<div className={cn(
  "classes-base",
  condition && "classes-condicionais",
  className // Permitir sobrescrita prop
)}>

Padrão: Usar cn() de @/lib/utils para classes condicionais

3. Suporte a Modo Escuro

<div className="bg-white dark:bg-gray-800 text-gray-900 dark:text-white">

Padrão: Usar prefixo dark: para estilos de modo escuro

4. Design Responsivo

<div className="w-full sm:w-1/2 md:w-1/3 lg:w-1/4">

Padrão: Usar prefixos de breakpoint (sm:, md:, lg:, xl:)

Padrões de Acessibilidade (WCAG 2.1 AA)

1. Rótulos ARIA

<button aria-label="Fechar diálogo">×</button>
<div role="status" aria-live="polite" aria-label="Carregando...">

Padrão: Sempre fornecer aria-label para botões com apenas ícone

2. HTML Semântico

<nav>
  <ul>
    <li><a href="/">Início</a></li>
  </ul>
</nav>

Padrão: Usar elementos HTML semânticos (nav, main, section, article, etc.)

3. Navegação por Teclado

<button
  onClick={handleClick}
  onKeyDown={(e) => {
    if (e.key === "Enter" || e.key === " ") {
      handleClick();
    }
  }}
>

Padrão: Garantir acessibilidade por teclado para todos os elementos interativos

4. Texto para Leitores de Tela

<span className="sr-only">Carregando conteúdo</span>

Padrão: Usar classe sr-only para texto exclusivo de leitores de tela

5. Gerenciamento de Foco

<input
  autoFocus
  className="focus:outline-none focus:ring-2 focus:ring-blue-500"
/>

Padrão: Sempre fornecer indicadores de foco visíveis

Convenções de Nomenclatura de Arquivos

  • Páginas: kebab-case (ex.: signup.tsx, signin.tsx)
  • Componentes: PascalCase (ex.: TaskList.tsx, TaskItem.tsx)
  • Layouts: layout.tsx
  • Páginas de Erro: error.tsx, not-found.tsx

Requisitos da Constituição

  • FR-033: Estrutura App Router Next.js 16+ ✅
  • FR-034: Componentes servidor padrão, cliente quando necessário ✅
  • FR-035: Limites de erro ✅
  • FR-036: Conformidade WCAG 2.1 AA ✅
  • FR-037: Modo estrito TypeScript ✅
  • FR-038: Formatação Prettier ✅
  • FR-039: Regras ESLint ✅

Referências

  • Especificação: specs/002-frontend-todo-app/spec.md - Especificações de componentes
  • Componentes Existentes: frontend/components/*.tsx - Exemplos de componentes
  • Páginas Existentes: frontend/app/*.tsx - Exemplos de páginas

Padrões Avançados de Componente

1. Padrão de Arrastar e Soltar (Fase 7 - T065)

Biblioteca: @dnd-kit/core

"use client";

import { DndContext, closestCenter, KeyboardSensor, PointerSensor, useSensor, useSensors } from "@dnd-kit/core";
import { SortableContext, sortableKeyboardCoordinates, useSortable, verticalListSortingStrategy } from "@dnd-kit/sortable";

export default function SortableTaskList({ tasks, onReorder }: Props) {
  const sensors = useSensors(
    useSensor(PointerSensor),
    useSensor(KeyboardSensor, {
      coordinateGetter: sortableKeyboardCoordinates,
    })
  );

  const handleDragEnd = (event: DragEndEvent) => {
    const { active, over } = event;
    if (over && active.id !== over.id) {
      onReorder(active.id, over.id);
    }
  };

  return (
    <DndContext sensors={sensors} collisionDetection={closestCenter} onDragEnd={handleDragEnd}>
      <SortableContext items={tasks.map(t => t.id)} strategy={verticalListSortingStrategy}>
        {tasks.map(task => (
          <SortableTaskItem key={task.id} task={task} />
        ))}
      </SortableContext>
    </DndContext>
  );
}

Padrão: Usar @dnd-kit/core para arrastar e soltar, manipular reordenação no final do arrasto

2. Padrão de Desfazer/Refazer (Fase 7 - T066)

"use client";

import { useReducer } from "react";

interface HistoryState<T> {
  past: T[];
  present: T;
  future: T[];
}

function historyReducer<T>(state: HistoryState<T>, action: { type: string; newPresent?: T }): HistoryState<T> {
  const { past, present, future } = state;

  switch (action.type) {
    case "UNDO":
      if (past.length === 0) return state;
      return {
        past: past.slice(0, past.length - 1),
        present: past[past.length - 1],
        future: [present, ...future],
      };
    case "REDO":
      if (future.length === 0) return state;
      return {
        past: [...past, present],
        present: future[0],
        future: future.slice(1),
      };
    case "SET":
      if (action.newPresent === present) return state;
      return {
        past: [...past, present],
        present: action.newPresent!,
        future: [],
      };
    default:
      return state;
  }
}

export function useHistory<T>(initialPresent: T) {
  const [state, dispatch] = useReducer(historyReducer, {
    past: [],
    present: initialPresent,
    future: [],
  });

  const undo = () => dispatch({ type: "UNDO" });
  const redo = () => dispatch({ type: "REDO" });
  const set = (newPresent: T) => dispatch({ typ

…

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ComeOnOliver/skillshub

Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Use when the user wants to build a presentation, convert a PPT/PPTX to web, or create slides for a talk/pitch. Helps non-designers discover their aesthetic through visual exploration rather than abstract choices.

ComeOnOliver/skillshub

Next.js 16+ 和 Turbopack — 增量打包、文件系统缓存、开发速度,以及何时使用 Turbopack 与 webpack。

ComeOnOliver/skillshub

SwiftUI architecture patterns, state management with @Observable, view composition, navigation, performance optimization, and modern iOS/macOS UI best practices.

ComeOnOliver/skillshub

See, Understand, Act on video and audio. See- ingest from local files, URLs, RTSP/live feeds, or live record desktop; return realtime context and playable stream links. Understand- extract frames, build visual/semantic/temporal indexes, and search moments with timestamps and auto-clips. Act- transcode and normalize (codec, fps, resolution, aspect ratio), perform timeline edits (subtitles, text/image overlays, branding, audio overlays, dubbing, translation), generate media assets (image, audio, video), and create real time alerts for events from live streams or desktop capture.

ComeOnOliver/skillshub

AI-assisted video editing workflows for cutting, structuring, and augmenting real footage. Covers the full pipeline from raw capture through FFmpeg, Remotion, ElevenLabs, fal.ai, and final polish in Descript or CapCut. Use when the user wants to edit video, cut footage, create vlogs, or build video content.

ComeOnOliver/skillshub

Next.js 15 애플리케이션을 위한 프론트엔드 개발 가이드라인. React 19, TypeScript, Shadcn/ui, Tailwind CSS를 사용한 모던 패턴. Server Components, Client Components, App Router, 파일 구조, Shadcn/ui 컴포넌트, 성능 최적화, TypeScript 모범 사례 포함. 컴포넌트, 페이지, 기능 생성, 데이터 페칭, 스타일링, 라우팅, 프론트엔드 코드 작업 시 사용.

ComeOnOliver/skillshub

Provides Tamagui patterns for config v4, compiler optimization, styled context, and cross-platform styling. Must use when working with Tamagui projects (tamagui.config.ts, @tamagui imports).

ComeOnOliver/skillshub

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

ComeOnOliver/skillshub

Create high-converting, visually distinctive landing pages. Use when building marketing pages, product launches, SaaS homepages, or any single-page conversion-focused website. Guides section-by-section composition with anti-AI-slop principles.

ComeOnOliver/skillshub

Auto-loaded context for Portfolio Buddy 2 development. Use for ANY task involving: React 19 development, TypeScript, portfolio analysis features, metrics calculations, trading strategy comparison, or working with the Portfolio Buddy 2 codebase. Contains tech stack, known issues, and architectural constraints.

ComeOnOliver/skillshub

Next.js development tooling via MCP. Inspect routes, components, build info, and debug Next.js apps. Use when working on Next.js applications, debugging routing, or inspecting app structure. NOT for general React or non-Next.js projects.

ComeOnOliver/skillshub

Implement UI using Shadcn MCP (atoms/theme) and 21st.dev MCP (complex sections). Use when adding buttons, layouts, or generating landing pages.

ComeOnOliver/skillshub

A conceptual skill for building an API client in Next.js that handles JWT tokens

ComeOnOliver/skillshub

Best practices and patterns for Next.js App Router, Server Actions, and Routing in this project.

ComeOnOliver/skillshub

The Design System, Theme, and UX rules for the Physical AI Hub.

ComeOnOliver/skillshub

Comprehensive frontend development skill for building modern, performant web applications using ReactJS, NextJS, TypeScript, Tailwind CSS. Includes component scaffolding, performance optimization, bundle analysis, and UI best practices. Use when developing frontend features, optimizing performance, implementing UI/UX designs, managing state, or reviewing frontend code.

ComeOnOliver/skillshub

This document captures learnings from fixing keyboard navigation issues when floating components (Select, DropdownMenu, Popover) have CSS open/close animations.

ComeOnOliver/skillshub

Build Next.js 16 applications with correct patterns and distinctive design. Use when creating pages, layouts, dynamic routes, upgrading from Next.js 15, or implementing proxy.ts. Covers breaking changes (async params/searchParams, Turbopack, cacheComponents) and frontend aesthetics. NOT when building non-React or backend-only applications.

ComeOnOliver/skillshub

Comprehensive Framer Motion animation library for React. Covers motion components, variants, gestures, page transitions, and scroll animations. Use when adding animations to React/Next.js applications.

ComeOnOliver/skillshub

Build interfaces that resonate, not just render. This skill enforces bold, intentional

Habilidades Relacionadas