frontend-integration

Skill do Frontend Developer para implementação com React/Next.js, Zustand, React Query, e Skeleton loading. Use quando precisar implementar componentes, páginas, integração com API, gerenciamento de estado, ou qualquer código frontend. Trigger em: "React", "Next.js", "componente", "página", "Zustand", "React Query", "TanStack Query", "skeleton", "loading", "hook", "frontend", "integração", "mobile responsive", "Tailwind", "formulário", "roteamento".

Quality

78%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/04-frontend-integration/SKILL.md

Frontend Developer - React/Next.js + Zustand + React Query

O Frontend transforma design em codigo, integrando com a API e garantindo UX fluida.

Governanca Global

Esta skill segue GLOBAL.md, policies/execution.md, policies/handoffs.md, policies/quality-gates.md, policies/token-efficiency.md, policies/stack-flexibility.md, policies/tool-safety.md e policies/evals.md.

Para snippets extensos e exemplos completos, consultar docs/skill-guides/frontend-integration.md apenas quando a tarefa exigir.

Para integracoes locais de MCP com bibliotecas visuais, consultar docs/skill-guides/ui-component-mcps.md.

Quando a tarefa exigir navegacao real, screenshots ou verificacao visual do app rodando, esta skill pode configurar ou reutilizar Playwright MCP localmente.

Quando Usar

implementar tela, componente, estado ou integracao com API
fechar comportamento de loading, erro, vazio e refresh

Quando Nao Usar

para definir regras de negocio sem apoio do Backend ou PO
para motion, SEO ou review final como atividade principal

Entradas Esperadas

spec do PO e direcao de UI/UX
contrato de API
restricoes de estado, auth e navegacao

Saidas Esperadas

interface funcional integrada
estados de UX tratados
handoff claro para QA

Para auth, o access token fica apenas em memoria. Persistencia local fica reservada a preferencias nao sensiveis, nunca a tokens.

Responsabilidades

Implementar interfaces conforme spec do UI/UX
Integrar com APIs usando React Query
Gerenciar estado global com Zustand
Implementar skeleton loading em toda tela com fetch
Garantir responsividade mobile-first
Código limpo, DRY, e tipado

Stack e Estrutura

Stack de referencia:

React ou Next.js
Zustand para estado global quando necessario
React Query para server state
Axios ou cliente HTTP equivalente
TypeScript strict mode

Para estrutura de pastas e exemplos completos de store, auth e API client, consultar docs/skill-guides/frontend-integration.md.

Padroes Principais

estado global pequeno e focado em UI ou sessao
accessToken apenas em memoria
server state separado do estado local
estados de loading, erro, vazio e retry definidos por tela

Storage Client-Side Reativo

Para persistir preferencia de UI, filtro de tela ou qualquer estado nao sensivel que precisa sobreviver a reload ou sincronizar entre abas, o default e o middleware persist do Zustand (zustand/middleware) quando o projeto ja usa Zustand para esse estado — nao adicionar dependencia nova so pra isso.

brownies (https://github.com/franciscop/brownies, MIT, npm brownies) e uma opcao pontual quando nao ha Zustand no caminho: cookie/local/session/db com interface unificada de getter/setter direto (nao .get()/.set()) e sincronizacao entre abas via subscribe().

import { cookies, local, session, db, subscribe, unsubscribe } from 'brownies';

local.token = 42;        // set
const t = local.token;   // get (sincrono para cookies/local/session)
delete local.token;      // remove

// db (IndexedDB) e assincrono
db.token = 42;
const dbVal = await db.token;

// subscribe reage a mudanca feita em outra aba ou via API nativa
const id = subscribe(local, 'points', (value) => setPoints(value));
unsubscribe(id); // ou unsubscribe(callback)

Quando usar: state simples fora de um store existente — ex. tela isolada sem Zustand, ou precisa de cookies/session/db (IndexedDB) alem de localStorage, o que persist do Zustand nao cobre nativamente.

Quando nao usar: projeto ja tem Zustand no estado que precisa persistir — nesse caso persist resolve sem dependencia nova. Tambem nao usar para dado sensivel (token, PII) — regra desta skill de token apenas em memoria continua valendo, brownies nao muda isso.

Gap de baixa prioridade: e o caso mais "commodity" entre as libs avaliadas para esta skill — a maior parte dos projetos ja resolve isso com persist, entao tratar como nota, nao como recomendacao forte.

MCPs de Componentes

Esta skill pode instalar ou configurar localmente MCPs de bibliotecas como Magic UI MCP e React Bits MCP quando isso acelerar a implementacao e o projeto nao tiver equivalente melhor.

Regras:

verificar se o MCP ja existe antes de configurar outro
adaptar componentes ao design system do app
nao introduzir visual ou motion que destoem do produto
registrar a instalacao/configuracao local no handoff quando houver mudanca no workspace

Biblioteca de Componentes para Apps Document-Heavy

Quando a feature envolve visualizar ou manipular documentos dentro do app (PDF, DOCX, XLSX, CSV, upload com preview, citação com bounding box sobre o documento, e-signing, schema builder), considerar extend-hq/ui (https://github.com/extend-hq/ui, MIT) em vez de construir viewer do zero ou improvisar com libs genéricas.

Componentes principais do kit: PDF viewer (baseado em react-pdf), DOCX viewer, XLSX viewer, file upload, file thumbnail, e-signature, layout blocks (inspeção de OCR com confidence score), bounding box citations (citação campo a campo com diff em JSON), file system/finder (visões ícone, lista, coluna, galeria).

Stack esperada: React + TypeScript, Tailwind CSS, primitivas shadcn/ui (Button, Select, Dialog, ScrollArea, Tooltip precisam existir no projeto). Next.js não é obrigatório para os componentes em si — é usado no site de docs do projeto original. Instalação é via shadcn CLI, componente por componente, como código-fonte copiado para o projeto (não é dependência de pacote fechada):

npx shadcn@latest add @extend/pdf-viewer

Quando usar: o produto já tem (ou vai ter) fluxo de revisão/anotação de documentos — contratos, notas fiscais, planilhas importadas, formulários assinados — e precisa de viewer com citação/bounding box ou e-signing nativo.

Quando não usar: telas sem documento nenhum (CRUD comum, dashboards, formulários simples) — nesse caso os componentes de MCPs de Componentes acima (Magic UI, React Bits) resolvem melhor. Também não usar se o projeto não tiver shadcn/ui configurado e não quiser adotar — nesse caso o custo de introduzir a dependência de primitivas supera o ganho.

MCP de Browser

Para validacao visual real, esta skill pode usar Playwright MCP para:

abrir o app localmente
navegar por telas e fluxos
verificar comportamento responsivo
capturar screenshots para confirmar detalhes de UI

Usar especialmente quando a mudanca visual nao puder ser validada com confianca apenas por leitura de codigo.

Para exemplos completos de store, authStore, uiStore e api client, consultar docs/skill-guides/frontend-integration.md.

React Query - Padrão de Hooks

src/lib/query-keys.ts

export const queryKeys = {
  users: {
    all: ['users'] as const,
    lists: () => [...queryKeys.users.all, 'list'] as const,
    list: (params: Record<string, unknown>) => [...queryKeys.users.lists(), params] as const,
    details: () => [...queryKeys.users.all, 'detail'] as const,
    detail: (id: string) => [...queryKeys.users.details(), id] as const,
  },
  posts: {
    all: ['posts'] as const,
    lists: () => [...queryKeys.posts.all, 'list'] as const,
    list: (params: Record<string, unknown>) => [...queryKeys.posts.lists(), params] as const,
    details: () => [...queryKeys.posts.all, 'detail'] as const,
    detail: (id: string) => [...queryKeys.posts.details(), id] as const,
  },
} as const;

src/hooks/useApi.ts

import { useQuery, useMutation, useQueryClient, UseQueryOptions } from '@tanstack/react-query';
import { api } from '@/lib/api-client';
import type { ApiResponse, PaginatedResponse } from '@/types/api';

export function usePaginatedQuery<T>(
  queryKey: readonly unknown[],
  url: string,
  params?: Record<string, unknown>,
  options?: Omit<UseQueryOptions, 'queryKey' | 'queryFn'>
) {
  return useQuery({
    queryKey: [...queryKey, params],
    queryFn: async () => {
      const { data } = await api.get<PaginatedResponse<T>>(url, { params });
      return data;
    },
    placeholderData: (prev) => prev,
    ...options,
  });
}

export function useDetailQuery<T>(
  queryKey: readonly unknown[],
  url: string,
  options?: Omit<UseQueryOptions, 'queryKey' | 'queryFn'>
) {
  return useQuery({
    queryKey,
    queryFn: async () => {
      const { data } = await api.get<ApiResponse<T>>(url);
      return data.data;
    },
    ...options,
  });
}

export function useApiMutation<TInput, TOutput = unknown>(
  method: 'post' | 'patch' | 'delete',
  url: string | ((variables: TInput) => string),
  options?: {
    invalidateKeys?: readonly unknown[][];
    onSuccess?: (data: TOutput) => void;
    optimistic?: {
      queryKey: readonly unknown[];
      updater: (old: any, variables: TInput) => any;
    };
  }
) {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: async (variables: TInput) => {
      const endpoint = typeof url === 'function' ? url(variables) : url;
      const { data } = await api[method]<ApiResponse<TOutput>>(endpoint, variables);
      return data.data;
    },

    onMutate: options?.optimistic
      ? async (variables) => {
          await queryClient.cancelQueries({ queryKey: options.optimistic!.queryKey });
          const previous = queryClient.getQueryData(options.optimistic!.queryKey);
          queryClient.setQueryData(
            options.optimistic!.queryKey,
            (old: any) => options.optimistic!.updater(old, variables)
          );
          return { previous };
        }
      : undefined,

    onError: options?.optimistic
      ? (err, variables, context: any) => {
          queryClient.setQueryData(options.optimistic!.queryKey, context?.previous);
        }
      : undefined,

    onSuccess: (data) => {
      options?.invalidateKeys?.forEach((key) => {
        queryClient.invalidateQueries({ queryKey: key });
      });
      options?.onSuccess?.(data);
    },
  });
}

Skeleton Loading - Implementação

src/components/ui/Skeleton.tsx

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

interface SkeletonProps {
  className?: string;
  variant?: 'text' | 'circular' | 'rectangular';
  width?: string | number;
  height?: string | number;
  lines?: number;
}

export function Skeleton({ className, variant = 'text', width, height, lines = 1 }: SkeletonProps) {
  const baseClass = 'animate-pulse bg-gray-200 rounded';

  if (variant === 'circular') {
    return (
      <div
        className={cn(baseClass, 'rounded-full', className)}
        style={{ width: width || 40, height: height || 40 }}
      />
    );
  }

  if (variant === 'rectangular') {
    return (
      <div
        className={cn(baseClass, className)}
        style={{ width: width || '100%', height: height || 200 }}
      />
    );
  }

  return (
    <div className="space-y-2">
      {Array.from({ length: lines }).map((_, i) => (
        <div
          key={i}
          className={cn(baseClass, 'h-4', className)}
          style={{
            width: i === lines - 1 ? '60%' : i % 2 === 0 ? '100%' : '80%',
          }}
        />
      ))}
    </div>
  );
}

export function withSkeleton<T>(
  Component: React.ComponentType<T>,
  SkeletonComponent: React.ComponentType
) {
  return function SkeletonWrapper({ isLoading, ...props }: T & { isLoading: boolean }) {
    if (isLoading) return <SkeletonComponent />;
    return <Component {...(props as T)} />;
  };
}

src/components/skeletons/UserListSkeleton.tsx

import { Skeleton } from '@/components/ui/Skeleton';

export function UserListSkeleton({ count = 5 }: { count?: number }) {
  return (
    <div className="space-y-4">
      {Array.from({ length: count }).map((_, i) => (
        <div key={i} className="flex items-center gap-4 p-4 border rounded-lg">
          <Skeleton variant="circular" width={48} height={48} />
          <div className="flex-1 space-y-2">
            <Skeleton className="h-4 w-1/3" />
            <Skeleton className="h-3 w-1/2" />
          </div>
          <Skeleton className="h-8 w-20" variant="rectangular" />
        </div>
      ))}
    </div>
  );
}

API Client - Axios com Interceptors

src/lib/api-client.ts

import axios from 'axios';
import { useAuthStore } from '@/stores/authStore';

export const api = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_URL,
  timeout: 10000,
  withCredentials: true,
  headers: { 'Content-Type': 'application/json' },
});

api.interceptors.request.use((config) => {
  const token = useAuthStore.getState().accessToken;
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }

  const csrfToken = getCookie('csrf-token');
  if (csrfToken) {
    config.headers['X-CSRF-Token'] = csrfToken;
  }

  return config;
});

let isRefreshing = false;
let failedQueue: Array<{ resolve: Function; reject: Function }> = [];

const processQueue = (error: any, token: string | null) => {
  failedQueue.forEach((prom) => {
    if (error) prom.reject(error);
    else prom.resolve(token);
  });
  failedQueue = [];
};

api.interceptors.response.use(
  (response) => response,
  async (error) => {
    const originalRequest = error.config;
    
    if (error.response?.status === 401 && !originalRequest._retry) {
      if (isRefreshing) {
        return new Promise((resolve, reject) => {
          failedQueue.push({ resolve, reject });
        }).then((token) => {
          originalRequest.headers.Authorization = `Bearer ${token}`;
          return api(originalRequest);
        });
      }
      
      originalRequest._retry = true;
      isRefreshing = true;
      
      try {
        const { data } = await axios.post(
          `${process.env.NEXT_PUBLIC_API_URL}/auth/refresh`,
          {},
          { withCredentials: true }
        );
        
        const { accessToken, user } = data.data;
        useAuthStore.getState().setAuth(user, accessToken);
        
        processQueue(null, accessToken);
        originalRequest.headers.Authorization = `Bearer ${accessToken}`;
        return api(originalRequest);
      } catch (refreshError) {
        processQueue(refreshError, null);
        useAuthStore.getState().clearAuth();
        if (typeof window !== 'undefined') window.location.href = '/login';
        return Promise.reject(refreshError);
      } finally {
        isRefreshing = false;
      }
    }
    
    return Promise.reject(error);
  }
);

function getCookie(name: string): string | null {
  if (typeof document === 'undefined') return null;
  const match = document.cookie.match(new RegExp(`(^| )${name}=([^;]+)`));
  return match ? match[2] : null;
}

Providers Setup

src/app/providers.tsx

'use client';

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
import { useState, type ReactNode } from 'react';

export function Providers({ children }: { children: ReactNode }) {
  const [queryClient] = useState(
    () =>
      new QueryClient({
        defaultOptions: {
          queries: {
            staleTime: 60 * 1000,
            gcTime: 5 * 60 * 1000,
            retry: 1,
            refetchOnWindowFocus: false,
          },
          mutations: {
            retry: 0,
          },
        },
      })
  );
  
  return (
    <QueryClientProvider client={queryClient}>
      {children}
      {process.env.NODE_ENV === 'development' && <ReactQueryDevtools />}
    </QueryClientProvider>
  );
}

Exemplo Completo - Listagem com Skeleton

src/app/(dashboard)/users/page.tsx

'use client';

import { useState } from 'react';
import { usePaginatedQuery } from '@/hooks/useApi';
import { queryKeys } from '@/lib/query-keys';
import { UserListSkeleton } from '@/components/skeletons/UserListSkeleton';
import { UserCard } from '@/components/features/UserCard';
import { Pagination } from '@/components/ui/Pagination';
import { SearchInput } from '@/components/ui/SearchInput';
import { useDebounce } from '@/hooks/useDebounce';
import type { User } from '@/types/user';

export default function UsersPage() {
  const [page, setPage] = useState(1);
  const [search, setSearch] = useState('');
  const debouncedSearch = useDebounce(search, 300);
  
  const params = { page, perPage: 20, search: debouncedSearch };
  
  const { data, isLoading, isError, error } = usePaginatedQuery<User>(
    queryKeys.users.list(params),
    '/api/v1/users',
    params
  );
  
  return (
    <div className="space-y-6">
      <div className="flex flex-col sm:flex-row justify-between gap-4">
        <h1 className="text-2xl font-bold">Usuários</h1>
        <SearchInput
          value={search}
          onChange={setSearch}
          placeholder="Buscar usuários..."
        />
      </div>
      
      {isLoading ? (
        <UserListSkeleton count={5} />
      ) : isError ? (
        <ErrorState message={error.message} onRetry={() => {}} />
      ) : data?.data.length === 0 ? (
        <EmptyState message="Nenhum usuário encontrado" />
      ) : (
        <>
          <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
            {data?.data.map((user) => (
              <UserCard key={user.id} user={user} />
            ))}
          </div>
          {data?.meta && (
            <Pagination
              page={data.meta.page}
              totalPages={data.meta.totalPages}
              onPageChange={setPage}
            />
          )}
        </>
      )}
    </div>
  );
}

Error States Robustos

Toda tela que faz fetch DEVE ter estes estados:

Loading (skeleton)
Sucesso (dados)
Erro (mensagem + botao retry)
Vazio (empty state com acao)
Timeout (mensagem especifica + retry)
Offline (detectar navigator.onLine)
Dados stale (indicador visual quando cache expirou)

Retry pattern no useApi:

const RETRY_CONFIG = {
  retries: 3,
  retryDelay: (attempt: number) => Math.min(1000 * 2 ** attempt, 10000),
};

Quando precisar de imagem (placeholder, avatar default, hero, ilustração)

Não use unsplash/lorem-picsum em prod. Despache skill 17 (image-generator) pra gerar asset alinhado ao projeto:

Tipo: placeholder | avatar-default | hero | illustration
Contexto: [componente onde entra], [paleta do app]
Output path: public/images/ ou assets/
Restrições: [dimensão], [transparência se PNG], [formato preferido]

Skill 17 aplica regra default (grok-imagine $0.020 t2i / gemini-25-flash $0.039 edit). Em runtime do app (não em build): usar templates/stack-default/apps/web/src/lib/image.ts se template está sendo consumido.

Evidencia de Conclusao

interface implementada conforme fluxo esperado
loading, erro, vazio e auth tratados
pontos criticos para QA e Motion destacados

Handoff para QA

Entregar:

App rodando em ambiente de staging
Lista de features implementadas com rotas
Componentes interativos documentados (Storybook se houver)
Variáveis de ambiente documentadas
Como rodar localmente (README)

Código Limpo

Codigo deve priorizar clareza. Comentarios so fazem sentido quando explicam contexto nao obvio, restricoes externas ou workarounds temporarios.

Fontes

Seção "Biblioteca de Componentes para Apps Document-Heavy" curada a partir de extend-hq/ui (MIT, ~1.5k stars) — não é port literal do README, é resumo dos componentes e do modo de instalação relevantes para esta skill. Confirmado por leitura direta do repo (licença, stack, comando de instalação) e da página https://www.extend.ai/ui. O kit já modelava Extend como referência visual em skills/02-ui-ux-design/data/products.csv e ui-reasoning.csv, mas não tinha nenhuma menção à biblioteca de componentes React em si — esse era o gap real medido antes de adicionar esta seção.
Seção "Storage Client-Side Reativo" curada a partir de franciscop/brownies (MIT, 2.566 stars, 61 forks, release 4.0.1). API confirmada por leitura direta de readme.md e package.json do repo: getter/setter direto em cookies/local/session/db (não .get()/.set()), db assíncrono, subscribe(obj, key, cb)/unsubscribe() para reagir a mudanças entre abas. Gap medido: grep por localStorage|sessionStorage|indexedDB|subscribe() em skill 04 e patterns/ não retornava nada — a skill cobria Zustand/React Query para estado de app, mas não tinha padrão para storage local reativo. Tratado como nota de baixa prioridade: o middleware persist do Zustand já cobre a maior parte desse caso quando o projeto já usa Zustand.

Integração com Pipeline

Orquestrador (skill 09): Coordena quando esta skill é invocada e define a próxima etapa
Context Manager (skill 08): Rastreia progresso das tasks dentro desta skill
Documentador (skill 10): Documenta entregas desta skill durante o desenvolvimento

Repository: felvieira/claude-skills-fv
Path: skills/04-frontend-integration/SKILL.md
Commit: f3492ef

Last updated: 5 days ago
First committed: 6 months ago

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.