Implementa interfaces e integra o frontend com APIs e estados. 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", "HTML", "CSS", "JavaScript no navegador", "API do browser".
82%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
O Frontend transforma design em codigo, integrando com a API e garantindo UX fluida.
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.
Ao criar ou redesenhar um app, site ou landing de ponta a ponta, 92-design-director mantém a direção de UX/UI; esta skill implementa a interface e suas integrações.
Ao alterar mídia ou recursos da página, reserve dimensões e investigue prioridade e scripts conforme o contexto. Identifique o elemento de LCP por medição antes de priorizá-lo e não afirme melhoria de desempenho sem dados; consulte skills/91-unslop/references/evidencia-web.md quando aplicável.
Quando a tarefa exigir navegacao real, screenshots ou verificacao visual do app rodando, esta skill pode configurar ou reutilizar Playwright MCP localmente.
Antes de alterar HTML, CSS ou JavaScript executado no navegador, consulte Modern Web Guidance pelo motor existente, quando disponível:
web_guidance_search e depois web_guidance_retrieve; o host executa as consultas.ginga_web_guidance_search e ginga_web_guidance_retrieve. Se o OMP expuser devices, leia xd://ginga_web_guidance_search ou xd://ginga_web_guidance_retrieve e envie os argumentos JSON pelo mesmo device. O corpus já vem integrado; não instale o pacote npm.Busque uma capacidade por vez, com 2–5 termos de ação em inglês, sem nome de framework ou projeto; recupere apenas os guias pertinentes. Adapte exemplos à stack e ao suporte de navegadores do projeto, incluindo acessibilidade e fallback. Regras do projeto e decisão explícita do usuário prevalecem. Ignore guias fora do escopo ou incompatíveis. Se usar guias, cite cada ID aplicado e o motivo no resumo final.
Pule tarefas de backend, infraestrutura, scripts, testes e mudanças triviais. Se o recurso estiver desligado ou indisponível, continue sem ele; não alegue consulta que não ocorreu.
Para auth, o access token fica apenas em memoria. Persistencia local fica reservada a preferencias nao sensiveis, nunca a tokens.
Stack de referencia:
Para estrutura de pastas e exemplos completos de store, auth e API client, consultar docs/skill-guides/frontend-integration.md.
accessToken apenas em memoriaAo implementar ou revisar uma tela, priorize gargalos percebidos pelo usuario: cascatas de rede, JavaScript enviado ao navegador e trabalho repetido de renderizacao. Primeiro identifique o caminho lento; aplique memoizacao ou outras otimizacoes locais somente quando o perfil ou o comportamento observado justificar.
Promise.all; para dependencias parciais, comece cada busca assim que seus dados de entrada estiverem disponiveis. Mantenha sequencial apenas o que realmente depende do resultado anterior.await para o ramo que usa o resultado e verifique condicoes locais baratas antes de iniciar operacoes remotas que talvez sejam desnecessarias.use client na menor subarvore interativa possivel. Passe para componentes de cliente apenas os dados que eles precisam.Suspense para liberar partes independentes da pagina enquanto dados nao criticos chegam. Mantenha o fallback com dimensoes proximas ao conteudo e nao atrase conteudo essencial para SEO ou decisoes de layout.const [profile, notifications] = await Promise.all([
getProfile(userId),
getNotifications(userId),
]);79-react-useeffect-review.memo, useMemo ou useCallback por padrao: primeiro confirme que ha trabalho caro ou renderizacao repetida relevante. Para interacoes caras que bloqueiam a entrada, avalie startTransition ou useDeferredValue.Ao aplicar uma otimizacao, preserve comportamento, acessibilidade e estabilidade visual; confirme o efeito com profiling ou comparacao do bundle quando o projeto oferecer essas ferramentas.
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.
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:
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-viewerQuando 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.
Para validacao visual real, esta skill pode usar Playwright MCP para:
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.
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);
},
});
}Checkpoint antes de considerar a integração pronta: para toda mutation com optimistic, forçar o backend a retornar erro (mockar 500, ou desligar o endpoint temporariamente) e confirmar que a UI reverte pro estado anterior — não só que o optimistic update aparece no caminho feliz. Se o rollback não reverter visualmente, o previous capturado em onMutate está errado (query key diferente da que o updater mexeu) — corrigir a query key e repetir o teste de erro forçado antes de seguir.
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>
);
}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;
}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>
);
}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>
);
}Toda tela que faz fetch DEVE ter estes estados:
Retry pattern no useApi:
const RETRY_CONFIG = {
retries: 3,
retryDelay: (attempt: number) => Math.min(1000 * 2 ** attempt, 10000),
};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.
Entregar:
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.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.felvieira/claude-skills-fv
b0cbfa3
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.