Ajuda do Up Web DS

Introdução

O Up Web DS é uma camada de normalização entre fontes externas, componentes internos e os produtos da equipe. Nada entra por conveniência: cada item declara o que é, de onde veio, sob qual licença, e o que já foi verificado nele.

Esta página é a referência rápida para pessoas. AGENTS.md continua sendo a referência de engenharia para agentes, e as duas descrevem a mesma política — a taxonomia e as tabelas aqui são lidas de src/catalog/taxonomy.ts, o mesmo módulo que o CLI e o ds:validate usam para aceitar ou recusar um item.

Como classificar um item

A metadata tem três eixos independentes. Responder aos três é o que transforma um arquivo em um item do design system.

type

Onde o item vive na arquitetura.

category

O que o item faz na interface.

domain

Em qual contexto de produto ele ganha significado.

Os três eixos são independentes. Nunca use um deles para representar outro: category não é layer, domain não é categoria, e type não é o lugar onde o arquivo mora.

Type

type é o nível de abstração — o que o item é arquiteturalmente. São seis valores, e a lista é fechada.

layout não é um type. Uma estrutura pequena e genérica é primitive com category: 'layout'; uma estrutura grande é block ou template. Foundation também não é um type: tokens, tipografia e a escala de motion vivem na folha de estilo da Foundation, não em um diretório de item.

Category

category é a família funcional: o que o item faz na interface. Não representa layer e não representa domínio.

Domain

domain é o contexto de produto em que o item ganha significado. primitive e recipe são sempre null; os demais types exigem um domínio.

Domínio é classificação, nunca comportamento: nenhum item muda o que faz em runtime por causa do seu domain.

Exemplos de classificação

Na interface, domain: null aparece como Domain-free. No código continua sendo null.

Lifecycle

Todo item nasce incoming e sobe por prova, não por decisão. Somente stable entra no registry consumível.

1. incomingAparece no catálogo, fora do registry.Scaffold ou matéria-prima recém-ingerida. A normalização ainda não aconteceu.
2. experimentalAparece no catálogo, fora do registry.Implementação em avaliação: existe, funciona, mas o contrato ainda pode mudar.
3. stableÚnico status publicado no registry consumível.Contrato aprovado. Exige metadata, examples, testes, tokens, acessibilidade, dark mode, responsivo, ícones semânticos, motion e validators verdes.
4. deprecatedAparece no catálogo, não é distribuído como item novo.Mantido por compatibilidade e documentação, com substituto planejado.

Adicionar do shadcn/ui

O caminho tem duas etapas separadas de propósito: inspecionar não baixa nada para src/, e promover é uma decisão explícita.

npm run ds:inspect -- \
  --source shadcn \
  --name select

npm run ds:add -- \
  --source shadcn \
  --name select \
  --type primitive \
  --category selection

npm run ds:add -- \
  --source shadcn \
  --name select \
  --type primitive \
  --category selection \
  --promote

npm run ds:inspect -- \
  --source shadcn \
  --name dialog

npm run ds:add -- \
  --source shadcn \
  --name dialog \
  --type primitive \
  --category overlay

npm run ds:inspect -- \
  --source shadcn \
  --name radio-group

npm run ds:add -- \
  --source shadcn \
  --name radio-group \
  --type primitive \
  --category selection

Adicionar de outras fontes

A fonte não define o type. Um item do Magic UI pode ser uma recipe, um do Kibo pode ser um component, e o mesmo registry pode fornecer os dois — a classificação é decidida depois do inspect, com o código à vista.

npm run ds:inspect -- \
  --source magic \
  --name shimmer-button

npm run ds:add -- \
  --source magic \
  --name shimmer-button \
  --type recipe \
  --category action \
  --base button

npm run ds:inspect -- \
  --source kibo \
  --name gantt

npm run ds:add -- \
  --source kibo \
  --name gantt \
  --type component \
  --domain application \
  --category data-display

npm run ds:compare -- \
  --source coss \
  --name button \
  --against button

npm run ds:inspect -- \
  --source cult \
  --name <item>

npm run ds:inspect -- \
  --source ncdai \
  --name <item>

Criar do zero

Antes de implementar: procure primitives existentes, componha Button/Radio/Badge em vez de duplicar comportamento de foundation, e não acople o item a Firebase, Supabase, Prisma, Server Actions ou autenticação. Um item recebe dados e devolve eventos por props.

npm run ds:create -- \
  --type component \
  --domain education \
  --name question-card \
  --category assessment \
  --description "Enunciado, alternativas e feedback de uma questão."

src/components/education/question-card/
├── question-card.tsx
├── question-card.examples.tsx
├── question-card.meta.ts
├── question-card.test.tsx
└── index.ts

<QuestionCard
  question={question}
  value={value}
  onValueChange={setValue}
/>

Adicionar código licenciado

Fontes comerciais não são baixadas automaticamente. O código chega por --from-file, sob revisão humana de licença.

npm run ds:add -- \
  --source tailwindPlus \
  --name hero \
  --from-file ./hero.tsx \
  --type block \
  --domain marketing \
  --category hero

Restrito não é isento: o código licenciado passa pelos mesmos tokens, primitives, API pública, light/dark, acessibilidade, responsividade, testes e preview que qualquer outro item.

Quando o componente já existe

Se ds:add reportar conflito, não force outro nome. Compare.

npm run ds:compare -- \
  --source coss \
  --name button \
  --against button

Normalização obrigatória

A automação detecta e relata; ela não decide semântica. Qual token um azul representa é decisão de quem tem contexto de produto. Esta é a lista que um item precisa fechar antes de reivindicar stable.

Validação

npm run check encadeia biome, typecheck, testes, ds:catalog --check, ds:validate, ds:icons:validate e registry:validate. É o portão que precisa estar verde antes de concluir qualquer tarefa.

npm run ds:catalog
npm run ds:validate
npm run ds:icons:validate
npm run check
npm run test:e2e
npm run ds:registry

Publicação no registry

Catálogo e registry respondem perguntas diferentes. O preview documenta o que a equipe está construindo; o registry distribui o que um produto pode instalar.

up-web-ds add dialog

Troubleshooting rápido