Devin Knowledge Base

DESIGN.md + Devin

Referência de configuração: DESIGN.md in Knowledge

Por que Devin + DESIGN.md resolve um problema real

O Devin opera num loop que outros agentes não têm:

  1. Clona o repo → lê toda a estrutura
  2. Planeja → decide arquivos a criar/editar
  3. Implementa → escreve código
  4. Testa → roda testes e verifica erros
  5. Itera → corrige o que falhou
  6. Entrega → abre PR ou commita

O DESIGN.md entra no passo 1. Quando o Devin clona e explora o repo, ele encontra o DESIGN.md na raiz (assim como encontra o README.md). Se as instruções de Knowledge dizem “leia o DESIGN.md antes de UI”, ele lê e aplica.

Sem isso, o passo 3 vira uma roleta. Com isso, todo o loop produz código visualmente consistente do início ao fim. E como o Devin pode iterar sozinho (passo 5), ele se autocorrige quando percebe que saiu da paleta.

Passo a Passo de Configuração

1. Colocar o DESIGN.md no repositório

O Devin clona seu repo. Ele precisa encontrar o DESIGN.md ali:

meu-projeto/
├── DESIGN.md          ← Primeiro arquivo visual que ele lê
├── README.md          ← Contexto do projeto
├── AGENTS.md          ← Instruções genéricas para agentes (opcional)
├── src/
│   └── components/
├── package.json
└── ...

O DESIGN.md deve ter o formato padrão com YAML front matter + prosa markdown. O Devin parseia ambos.

2. Configurar Knowledge no Devin

No dashboard do Devin, vá em Knowledge e adicione uma entrada de documentação:

Título: Design System Guidelines

Conteúdo:

## Regras de Design System

Todos os repositórios deste workspace usam o formato DESIGN.md para design tokens.

### Workflow obrigatório para tarefas de UI

1. Ao clonar qualquer repo, verificar se existe DESIGN.md na raiz
2. Se existir, ler COMPLETAMENTE antes de gerar qualquer componente
3. Extrair tokens de: cores, tipografia, espaçamento, border-radius
4. Aplicar os tokens em todo código de UI gerado
5. Verificar a seção "Restrições" e não violar nenhuma

### Como interpretar o DESIGN.md

O arquivo tem duas partes:
- **YAML front matter** — tokens de design em formato estruturado (cores hex, tamanhos em px/rem, escalas)
- **Markdown body** — rationale de design, padrões de componentes, exemplos, restrições

Priorizar o YAML para valores exatos. Usar o markdown para entender intenção e contexto.

### Padrões de componentes

Ao criar componentes de UI:
- Toda cor deve vir do DESIGN.md (nunca inventar)
- Espaçamentos: múltiplos do base value
- Tipografia: usar apenas sizes da escala definida
- Elementos interativos: estados hover, focus, disabled obrigatórios
- Acessibilidade: aria-labels, keyboard nav, color contrast

### Output esperado

- Código que usa os tokens exatos do DESIGN.md
- Componentes visualmente consistentes entre si
- Zero cores inventadas ou espaçamentos arbitrários

3. Conectar o repositório

No Devin, vá em Repos e conecte o repositório:

  1. Authorize access via GitHub/GitLab
  2. Selecione o repo do projeto
  3. O Devin agora pode clonar e acessar o DESIGN.md diretamente

4. Instruções no README.md (reforço)

O Devin lê o README.md para entender o projeto. Adicione uma seção:

## 🎨 Design System

Este projeto usa [DESIGN.md](./DESIGN.md) como source of truth para decisões visuais.

**Para agentes IA:** leia o DESIGN.md antes de gerar ou modificar qualquer componente de UI.
Os tokens de cor, tipografia e espaçamento são obrigatórios.

Isso funciona como reforço — além da Knowledge base, o próprio README instrui.

5. Prompt de sessão otimizado

Ao criar uma sessão no Devin, use prompts que referenciem explicitamente o design system:

Tarefa: Criar uma página de pricing com 3 tiers (Free, Pro, Enterprise).

Requisitos:
- Ler DESIGN.md para tokens visuais
- Layout responsivo (grid 3 colunas desktop, stack mobile)
- Tier "Pro" destacado como popular
- Cada tier: nome, preço, features list, CTA button
- Usar os padrões de Button e Card definidos no DESIGN.md
- Não usar cores fora da paleta definida
- Accessibility: WCAG AA

Exemplo Concreto de Uso

Você cria uma sessão no Devin:

Implementar o design system completo como componentes React:
1. Ler DESIGN.md na raiz
2. Criar componentes em src/components/ui/
3. Componentes necessários: Button, Input, Select, Textarea, Card, Badge, Avatar, Modal, Dropdown, Tabs
4. Cada componente deve:
   - Usar tokens do DESIGN.md (cores, spacing, radius, typography)
   - Ter TypeScript interfaces para props
   - Suportar variantes via prop (ex: Button variant="primary"|"secondary"|"ghost")
   - Ter estados: default, hover, focus, disabled
   - Ser acessível (aria, keyboard)
5. Criar um arquivo src/components/ui/index.ts exportando tudo
6. Criar Storybook stories para cada componente (opcional)
7. Rodar build para verificar erros de TypeScript

O Devin executa a tarefa inteira:

  1. Clona o repo
  2. Lê DESIGN.md — extrai tokens
  3. Cria a estrutura src/components/ui/
  4. Gera cada componente seguindo os tokens
  5. Cria as interfaces TypeScript
  6. Testa o build (npm run build)
  7. Corrige erros se houver
  8. Abre PR com todos os componentes

O resultado é algo assim para o Button:

// src/components/ui/Button.tsx
import { forwardRef, type ButtonHTMLAttributes } from 'react';
import { clsx } from 'clsx';

type ButtonVariant = 'primary' | 'secondary' | 'ghost';
type ButtonSize = 'sm' | 'md' | 'lg';

interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: ButtonVariant;
  size?: ButtonSize;
  loading?: boolean;
}

const variantStyles: Record<ButtonVariant, string> = {
  primary: 'bg-[#1A73E8] text-white hover:bg-[#1557B0] focus:ring-[#1A73E8]',
  secondary: 'bg-transparent border border-[#1A73E8] text-[#1A73E8] hover:bg-[#1A73E8]/5 focus:ring-[#1A73E8]',
  ghost: 'bg-transparent text-[#1A73E8] hover:bg-[#F8F9FA] focus:ring-[#1A73E8]',
};

const sizeStyles: Record<ButtonSize, string> = {
  sm: 'px-3 py-1.5 text-xs rounded-md',
  md: 'px-4 py-2.5 text-sm rounded-lg',
  lg: 'px-6 py-3 text-base rounded-lg',
};

export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
  ({ variant = 'primary', size = 'md', loading, disabled, className, children, ...props }, ref) => {
    return (
      <button
        ref={ref}
        disabled={disabled || loading}
        className={clsx(
          'inline-flex items-center justify-center font-medium transition-colors',
          'focus:outline-none focus:ring-2 focus:ring-offset-2',
          'disabled:opacity-50 disabled:pointer-events-none',
          variantStyles[variant],
          sizeStyles[size],
          className,
        )}
        {...props}
      >
        {loading && (
          <svg className="animate-spin -ml-1 mr-2 h-4 w-4" viewBox="0 0 24 24">
            <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" fill="none" />
            <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z" />
          </svg>
        )}
        {children}
      </button>
    );
  }
);

Button.displayName = 'Button';

Cores #1A73E8, #1557B0 (hover), #F8F9FA (ghost hover) — tudo do DESIGN.md. Radius rounded-md (sm: 4) e rounded-lg (md: 8) conforme tokens. Espaçamentos em múltiplos de 4. Estados implementados.

Dicas Específicas do Devin

Knowledge hierárquico

Se trabalha com múltiplos projetos com design systems diferentes, organize a Knowledge:

Knowledge Entry: "Design System — Projeto A"
→ Links to: repo-projeto-a DESIGN.md

Knowledge Entry: "Design System — Projeto B"  
→ Links to: repo-projeto-b DESIGN.md

Knowledge Entry: "Design System — Global Rules"
→ Regras comuns a todos os projetos (leitura obrigatória do DESIGN.md)

O Devin cruza a Knowledge com o repo que está trabalhando.

Use Playbooks para tarefas recorrentes

Se frequentemente pede “gere componentes seguindo DESIGN.md”, crie um Playbook:

Playbook: Criar componente UI

1. Ler DESIGN.md na raiz do projeto
2. Verificar componentes existentes em src/components/ para consistência
3. Criar o componente com TypeScript strict
4. Aplicar tokens do DESIGN.md para cores, spacing, radius
5. Implementar variantes e estados
6. Garantir acessibilidade (aria, keyboard)
7. Rodar npm run build para verificar types
8. Commitar com mensagem descritiva

Feedback de sessão treina o Devin

Se o Devin gerar UI com cores erradas, dê feedback na sessão:

O Button está usando #3B82F6 em vez de #1A73E8. Corrija para usar a cor primary 
definida no DESIGN.md. Verifique TODOS os componentes gerados e corrija se necessário.

O Devin corrige e aprende no contexto daquela sessão. Para aprendizado persistente, atualize a Knowledge.

Devin + PRs como design review

Configure o Devin para abrir PRs em vez de commitar direto. Isso permite:

  1. O Devin gera os componentes
  2. Abre PR com diff completo
  3. Você (ou o time) revisa se seguiu o DESIGN.md
  4. Merge se aprovado, feedback se não

Esse workflow é o mais seguro para design systems — nenhum código entra na main sem revisão visual.

Referências cruzadas com exemplos

Se o repo já tem componentes que seguem o DESIGN.md corretamente, instrua o Devin a usá-los como referência:

Antes de criar novos componentes, leia os existentes em src/components/ui/ 
para entender como os tokens do DESIGN.md são aplicados neste projeto. 
Mantenha consistência com a implementação existente.

Troubleshooting e Gotchas

O Devin ignora o DESIGN.md

Causas comuns:

  • Knowledge não está configurada com a instrução de ler DESIGN.md
  • O prompt da sessão não menciona design system
  • O DESIGN.md está em subpasta (deve estar na raiz)

Solução: seja explícito no prompt E na Knowledge. Redundância ajuda com agentes autônomos.

Cores inconsistentes entre componentes

Se o Devin gera 10 componentes e os últimos usam cores diferentes dos primeiros:

  1. O contexto pode ter sido cortado. DESIGN.md grande demais.
  2. Solução: mantenha o DESIGN.md abaixo de 2000 tokens
  3. Coloque um resumo dos tokens mais usados no topo do arquivo
  4. Divida a tarefa em batches menores (5 componentes por sessão)

O Devin instala libs de UI inesperadas

Sem instruções claras, o Devin pode decidir usar shadcn, Radix ou MUI. Controle via Knowledge:

### Dependências de UI

Este projeto NÃO usa component libraries de terceiros.
Todos os componentes são custom, construídos sobre Tailwind CSS.
Não instalar: @radix-ui/*, @headlessui/*, @mui/*, shadcn.
Permitido: clsx, tailwind-merge, lucide-react.

Sessão demora muito

O Devin pode gastar tempo explorando documentação online sobre design patterns. Reduza instruin-do-o:

Não pesquisar padrões de design na web. Usar EXCLUSIVAMENTE o DESIGN.md do projeto 
como referência visual. Para decisões não cobertas, inferir a partir dos tokens existentes.

O Devin edita o DESIGN.md

Às vezes ele interpreta “seguir o design system” como “melhorar o design system”. Proteja:

Na Knowledge:

### Arquivos protegidos

NUNCA editar estes arquivos:
- DESIGN.md — source of truth, somente leitura
- README.md — modificar apenas se explicitamente pedido

Versão do DESIGN.md fica desatualizada

Se o design system evolui mas a Knowledge do Devin tem cache antigo:

  1. Atualize a Knowledge entry quando mudar o DESIGN.md
  2. Melhor: confie no arquivo do repo (o Devin sempre lê o mais recente ao clonar)
  3. A Knowledge serve como “regras gerais”, o DESIGN.md do repo é “source of truth atual”

Workflow Completo com Devin

  1. Setup inicial:

    • DESIGN.md na raiz do repo
    • Knowledge configurada no Devin
    • Repo conectado

  2. Tarefa de componentes:

    • Sessão com prompt claro referenciando DESIGN.md
    • Devin executa autonomamente
    • PR aberto para review

  3. Review:

    • Verificar cores, espaçamentos, tipografia contra DESIGN.md
    • Aprovar ou dar feedback

  4. Iteração:

    • Devin corrige baseado no feedback
    • Nova PR ou push no mesmo branch

  5. Evolução:

    • Quando DESIGN.md muda, atualizar Knowledge
    • Próximas sessões já usam tokens atualizados

Conclusão e Próximo Passo

O Devin com DESIGN.md é para quem quer delegar o trabalho pesado. “Gere todos os componentes do design system” não é um sonho — é uma sessão do Devin com o contexto certo. A Knowledge base mantém as regras persistentes, o DESIGN.md no repo garante tokens atualizados, e o sistema de PRs dá a rede de segurança.

O setup inicial é o mais demorado entre os agentes (Knowledge + Repos + Playbooks), mas o payoff é proporcional: você delega tarefas inteiras de UI sem abrir IDE. Para times que querem produtividade máxima com consistência visual, essa é a configuração.

Próximos passos:

Links úteis