Pipeline de build para isolar habilidades de design externas do Claude no código de produção
TuBrief 편집팀
2026년 9월 11일
0
Computing/Software원본 영상을 바탕으로 AI의 도움을 받아 작성했습니다. 원본 영상이 기준입니다.
커뮤니티의 다른 글
댓글 (0)
Log in to leave a comment
아직 작성된 글이 없습니다
원본 영상을 바탕으로 AI의 도움을 받아 작성했습니다. 원본 영상이 기준입니다.
Log in to leave a comment
아직 작성된 글이 없습니다
Para um desenvolvedor que cria um serviço full-stack sozinho, sem um designer, documentos de habilidades de design externas parecem atraentes. Copiar um prompt de sistema de design de 5.000 linhas encontrado no Twitter ou no GitHub e colá-lo nas instruções de sistema do Claude dá a impressão de que a interface ficará limpa.
Na realidade, o resultado é exatamente o oposto. Assim que a primeira mensagem é enviada, um aviso de limite de tokens aparece e o tempo de espera pela resposta da API aumenta indefinidamente. O código gerado pelo modelo insere estilos em linha (inline styles) não identificados em componentes ou importa um módulo do Framer Motion que nunca foi instalado no projeto. No fim das contas, depois de passar a madrugada consertando manualmente uma interface quebrada, você acaba voltando para o template padrão do shadcn/ui.
O problema não é o senso estético do modelo. A causa em si é a forma de despejar markdown em texto corrido não estruturado diretamente no prompt do sistema. É necessário converter descrições de estilo em linguagem natural para especificações de tokens legíveis por máquina e construir um pipeline que realize testes de isolamento no código gerado pelo modelo antes que ele chegue aos arquivos de produção.
Colar o markdown de um sistema de design inteiro no prompt gera um desperdício grave de tokens. Modificadores estéticos como "um azul marinho profundo que transmite confiança ao usuário" são completamente inúteis para a geração de layouts. Essas frases consomem recursos computacionais dentro do modelo de linguagem que deveriam ser direcionados a interfaces TypeScript ou lógicas de validação essenciais.
Elimine as descrições em linguagem natural e reconstrua o prompt do sistema com objetos JSON seguindo a especificação W3C Design Tokens Community Group (DTCG). Mantenha apenas cores, espaçamentos e raios de borda.
`json
{
"color": {
"background": {
"surface": { "type": "color" },
"canvas": { "type": "color" }
},
"action": {
"primary": { "type": "color" },
"primary-hover": { "type": "color" }
}
},
"spacing": {
"compact": { "type": "dimension" },
"comfortable": { "type": "dimension" }
},
"radius": {
"md": { "type": "dimension" }
}
}
`
Combine a especificação de tokens padronizada com o Prompt Caching da Anthropic. Defina os tokens básicos e o papel do sistema como um bloco fixo e aplique cache_control: { type: "ephemeral" }.
`typescript
import Anthropic from "@anthropic-ai/sdk";
const anthropic = new Anthropic();
export async function requestComponentGeneration(componentBrief: string) {
return await anthropic.messages.create({
model: "claude-3-5-sonnet-20241022",
max_tokens: 4096,
system: [
{
type: "text",
text: Gerador de componentes Next.js e Tailwind CSS. Utilize obrigatoriamente apenas as classes definidas na especificação de tokens DTCG abaixo e não emita estilos em linha (atributo style). [DTCG_TOKENS_JSON_DATA],
cache_control: { type: "ephemeral" },
},
],
messages: [
{
role: "user",
content: componentBrief,
},
],
});
}
`
A eliminação de documentos em texto corrido reduz o tamanho do prompt de cerca de 10.000 tokens para o patamar de 1.200 tokens. De acordo com a documentação da Anthropic, a leitura de cache de prompts cobra apenas 10% da taxa de tokens de entrada padrão, o que reduz os custos de API em mais de 70% em chamadas repetidas.
Ao injetar habilidades externas, o Claude frequentemente insere valores arbitrários ocultos como style={{ marginTop: '13px' }}. Classes arbitrárias entre colchetes (w-[342px]) também são geradas de forma aleatória. Esse tipo de código corrói aos poucos o sistema de estilos global.
Utilize o eslint-plugin-react e o eslint-plugin-tailwindcss no Flat Config do eslint.config.mjs para filtrá-los na etapa de build.
`javascript
import reactPlugin from "eslint-plugin-react";
import tailwindPlugin from "eslint-plugin-tailwindcss";
export default [
{
files: ["**/.{ts,tsx}"],
plugins: {
react: reactPlugin,
tailwindcss: tailwindPlugin,
},
settings: {
tailwindcss: {
callees: ["cn", "cva"],
config: "./tailwind.config.ts",
},
},
rules: {
"react/forbid-dom-props": [
"error",
{
forbid: [
{
propName: "style",
message: "Estilos em linha não são permitidos. Utilize os utilitários do Tailwind especificados.",
},
],
},
],
"tailwindcss/no-arbitrary-value": "error",
"tailwindcss/no-custom-classname": [
"error",
{
whitelist: ["animate-."],
},
],
},
},
];
`
Mapeie os tokens extraídos para theme.extend em tailwind.config.ts. Sobrescrever a paleta padrão corrompe as cores referenciadas pelas primitivas internas do shadcn/ui.
`typescript
import type { Config } from "tailwindcss";
import themeTokens from "./build/tailwind/theme.json";
const config: Config = {
content: ["./src/**/*.{ts,tsx}"],
theme: {
extend: {
colors: {
surface: themeTokens.color.background.surface,
canvas: themeTokens.color.background.canvas,
action: {
primary: themeTokens.color.action.primary,
"primary-hover": themeTokens.color.action["primary-hover"],
},
},
borderRadius: {
token: themeTokens.radius.md,
},
},
},
plugins: [require("tailwindcss-animate")],
};
export default config;
`
Isole as interações por meio de variantes do Class Variance Authority (CVA). Alterar diretamente as primitivas do Radix UI remove os atributos da árvore de acessibilidade (ARIA).
`typescript
import * as React from "react";
import { Slot } from "@radix-ui/react-slot";
import { cva, type VariantProps } from "class-variance-authority";
import { cn } from "@/lib/utils";
const buttonVariants = cva(
"inline-flex items-center justify-center rounded-token text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-action-primary disabled:pointer-events-none disabled:opacity-50",
{
variants: {
variant: {
default: "bg-action-primary text-white hover:bg-action-hover active:scale-[0.98]",
secondary: "bg-surface text-foreground hover:bg-surface/80",
ghost: "hover:bg-surface text-foreground",
},
size: {
default: "h-10 px-4 py-2",
sm: "h-8 px-3 text-xs",
lg: "h-12 px-8 text-base",
},
motion: {
subtle: "transition-all duration-150 ease-out",
expressive: "transition-all duration-300 cubic-bezier(0.16, 1, 0.3, 1)",
},
},
defaultVariants: {
variant: "default",
size: "default",
motion: "subtle",
},
}
);
export interface ActionButtonProps
extends React.ButtonHTMLAttributes,
VariantProps {
asChild?: boolean;
}
export const ActionButton = React.forwardRef<HTMLButtonElement, ActionButtonProps>(
({ className, variant, size, motion, asChild = false, ...props }, ref) => {
const Comp = asChild ? Slot : "button";
return (
<Comp
className={cn(buttonVariants({ variant, size, motion, className }))}
ref={ref}
{...props}
/>
);
}
);
ActionButton.displayName = "ActionButton";
`
Quando solicitado a criar animações chamativas, o Claude costuma importar o Framer Motion por hábito. Segundo as métricas do Bundlephobia, o Framer Motion ocupa cerca de 60KB mesmo após a compactação Gzip. No momento em que você adiciona 60KB só para movimentar alguns botões, o LCP (método de avaliação de carregamento inicial) é comprometido.
Proíba a importação de bibliotecas de terceiros no prompt do sistema e restrinja o uso exclusivamente a propriedades voltadas para a thread do compositor do navegador (Compositor Thread).
`typescript
// Forma desaconselhada: causa reflow de layout na thread principal
//
// Forma recomendada: processada na thread do compositor da GPU
`
Propriedades geométricas como top, left, width e height recalculam a árvore de layout a cada frame. Em contrapartida, utilitários como transform-gpu e opacity são processados em uma camada independente na GPU sem passar pela thread principal, mantendo os 60 FPS de forma fluida.
Remova também efeitos de desfoque de fundo (backdrop-filter: blur()) em áreas com rolagem. Em navegadores móveis de baixo desempenho, filtros de desfoque dentro de uma viewport com scroll recalculam texturas a cada frame, derrubando a taxa de atualização da tela para menos de 20 FPS. Em vez do desfoque, o uso de um canal alfa translúcido de cor sólida (bg-background/80 com uma borda de 1px) previne problemas de ocupação de memória de vídeo.
Inserir o código gerado pelo Claude diretamente no diretório app/ do Next.js causa quebras de layout e erros de hidratação. Faça a renderização primeiro em um ambiente isolado no Storybook e mescle em produção apenas os componentes que passarem nos testes.
Adicione o axe-playwright em .storybook/test-runner.js para verificar a acessibilidade com base no padrão WCAG 2.1 AA.
`javascript
const { injectAxe, checkA11y } = require("axe-playwright");
module.exports = {
async preVisit(page) {
await injectAxe(page);
},
async postVisit(page) {
await page.waitForSelector("#storybook-root", { state: "attached" });
await checkA11y(page, "#storybook-root", {
detailedReport: true,
axeOptions: {
runOnly: {
type: "tag",
values: ["wcag2a", "wcag2aa"],
},
},
});
},
};
`
Caso um teste falhe, envie o log de erro diretamente de volta para o Claude.
`text
[Loop de feedback de IA: Prompt de correção precisa de componente]
O código gerado falhou no teste de acessibilidade do axe-core.
Analise o log e emita o código corrigido apenas com as falhas corrigidas, mantendo a estrutura existente.
[Detalhes da falha]
Item violado: color-contrast
Nó com falha:
Motivo: O contraste de cor é de 2.8:1, ficando abaixo do padrão WCAG AA de 4.5:1.
Diretriz de solução: Substitua o utilitário de texto por text-foreground ou text-action-primary-hover.
`
Configure um script de shell que tire capturas de tela para regressão visual com o Playwright e crie uma branch apenas quando todas as verificações forem aprovadas.
`typescript
import { test, expect } from "@playwright/test";
import storybookManifest from "../../storybook-static/index.json";
const stories = Object.values(storybookManifest.entries).filter(
(entry) => entry.type === "story"
);
for (const story of stories) {
test(Verificação de snapshot: ${story.title} - ${story.name}, async ({ page }) => {
await page.goto(/iframe.html?id=${story.id}&viewMode=story);
await page.waitForSelector("#storybook-root");
await page.waitForLoadState("networkidle");
await expect(page).toHaveScreenshot(`${story.id}.png`, {
animations: "disabled",
maxDiffPixelRatio: 0.01,
threshold: 0.2,
});
});
}
`
`bash
#!/usr/bin/env bash
set -e
COMPONENT_NAME=$1
if [ -z "$COMPONENT_NAME" ]; then
echo "Erro: Insira o nome do componente a ser validado."
exit 1
fi
echo "1. Inspeção de guardrails do linter"
pnpm eslint "src/components/ui/${COMPONENT_NAME}.tsx" --max-warnings=0
echo "2. Build estático do Storybook"
pnpm build-storybook --quiet
echo "3. Teste CLI de acessibilidade do Storybook"
pnpm test-storybook
echo "4. Comparação de snapshot de regressão visual do Playwright"
pnpm playwright test tests/visual/component-regression.spec.ts
echo "5. Aprovado: Criação de branch e envio de PR"
git checkout -b "feature/ui-{COMPONENT_NAME}.tsx"
git commit -m "feat(ui): {COMPONENT_NAME}"
gh pr create --title "feat(ui): Adição de ${COMPONENT_NAME}" --body "Componente que passou nos testes de A11y do Storybook e de regressão do Playwright."
`
Não há necessidade de abrir as ferramentas de desenvolvedor do navegador e ajustar margens pixel por pixel toda vez que a interface se desalinhar. Se você delegar as regras de validação para um script de terminal, conseguirá produzir interfaces de forma segura mesmo trabalhando sozinho.