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

Preservação da API upstream

Normalizar um item externo preserva, por padrão, a API pública observável, o comportamento funcional e a identidade visual dele. O que pode mudar é a implementação: primitives, imports, tokens, semantic icons, acessibilidade, foco, reduced motion e infraestrutura.

npm run ds:compare -- \
  --source magic \
  --name hero-video-dialog \
  --against hero-video-dialog

Uma capability que vive no primitive base aparece como delegated(dialog), não como ausente. Não copie uma implementação ruim do upstream só para as colunas baterem: um role="button" manual não é melhor que o Dialog oficial.

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.

Remover um item

ds:remove tira o item e tudo que foi gerado a partir dele. Nunca tira o que ele apenas usa: primitive base, hook compartilhado, semantic icon, style capability, token da Foundation e dependência npm ficam.

npm run ds:remove -- \
  --name hero-video-dialog

npm run ds:remove -- \
  --name hero-video-dialog \
  --confirm

Documentação do item

A página de um item ganha Usage, Props e Composition quando elas existem — e nenhuma delas é escrita na página. npm run ds:docs deriva tudo do source e grava src/catalog/docs.generated.ts; o catálogo lê dado puro.

Props herdadas não entram na tabela. Uma prop declarada em @types/react é atributo de HTML, e listar as 285 de um <button> enterra as duas que são do design system — elas viram uma linha de “Estende”. Prop semântica que uma biblioteca de comportamento adiciona (render, onValueChange) é prop do item e é documentada.

docs: {
  usage: { example: 'basic' },
  composition: {
    description: 'Os gatilhos ficam agrupados na TabsList.',
    tree: [
      { name: 'TabsList', children: [{ name: 'TabsTrigger' }] },
      { name: 'TabsContent' },
    ],
  },
}

Em incoming e experimental os cinco são aviso; em stable são erro. Documentação quebrada não chega ao registry, e um acervo em normalização não trava o CI.

Particles

Um Particle é uma composição copiável de itens que já existem, construída sobre um example real, publicada em /particles. Ele mostra como primitives, recipes e os demais itens se combinam para resolver uma necessidade concreta de interface — um date picker, uma paleta de comandos, um painel de filtros.

docs: {
  particles: [
    {
      example: 'withForm',
      title: 'Edição rápida em Popover',
      description: 'Um campo e duas ações ancorados ao item.',
      tags: ['form', 'inline-edit'],
    },
  ],
}

Como os cinco anteriores: aviso em incoming e experimental, erro em stable. Um example sem código próprio continua sendo DS_DOCS_005 — o Particle apenas não é gerado, em vez de virar um segundo aviso sobre o mesmo fato.

Registrar um papel de ícone

Componente do DS não importa lucide-react: importa o papel de que precisa de @/lib/up-web-icons. O papel é o contrato — close, chevron-down, folder-open — e qual glifo o desenha é decisão do projeto que consome, em components.json → iconLibrary. Registrar um papel novo é preencher essa equivalência nos quatro providers e levá-la até quem depende dela.

// src/catalog/types.ts
export const semanticIconNames = [
  // …
  'folder-open',
] as const

// scripts/ds/icons/mappings.ts
'folder-open': {
  lucide: lucide('FolderOpenIcon'),
  phosphor: phosphor('FolderOpenIcon'),
  tabler: tabler('IconFolderOpen'),
  hugeicons: hugeicons('FolderOpenIcon'),
},

npm run ds:cli:sync

npm run ds:icons

npm run ds:icons:validate

npm run ds:registry

npm run verify

Cobertura é governada pela maturidade de quem usa o papel, não pelo mapping (requireEveryProviderFrom em .ds/icons.ts). Papel usado por item stable sem os quatro providers é erro e barra a distribuição; usado só por incoming ou experimental, é aviso; sem nenhum item usando, é informativo.

npm run ds:cli:sync
npm run ds:icons
npm run ds:icons:validate
npm run ds:registry
npm run verify

npx up-web-ds init

Validação

npm run verify encadeia biome, typecheck, testes, ds:catalog --check, ds:docs --check, ds:validate, ds:icons:validate, registry:validate e o build da CLI. É o portão que precisa estar verde antes de concluir qualquer tarefa — npm run check continua funcionando como alias.

npm run ds:catalog
npm run ds:docs
npm run ds:validate
npm run ds:icons:validate
npm run verify
npm run verify:full
npm run ds:registry

Fluxo até a Pull Request

A regressão completa roda na sua máquina, antes da PR. O GitHub Actions fica com as verificações leves e determinísticas, e nada é executado duas vezes entre local, PR, main e Vercel.

1. Desenvolvimentolocalnpm run verifyA cada ajuste relevante. Lint, tipos, testes unitários e políticas do DS — sem build e sem browser.
2. Antes da PRlocalnpm run verify:fullObrigatório. Soma o build de produção e o Playwright completo: axe em todas as rotas, page-overflow e os specs de cada item.
3. Pull RequestGitHub Actionsnpm run verifyO check Verify roda o mesmo comando do desenvolvimento. Um commit novo cancela o run anterior da mesma PR.
4. Merge em mainGitHubnenhum jobNada se repete: o merge só leva para a main o que o check Verify já aprovou.
5. DeployVercelnpm run buildRefaz e valida o registry e gera o build de produção. Não roda testes nem instala browser.

npm ci
npx playwright install chromium

npm run verify

npm run test:run -- tabs
E2E_BASE_URL=http://localhost:3000 npm run test:e2e -- tabs

npm run verify:full

git push -u origin <sua-branch>
gh pr create --base main --fill

gh pr checks --watch

gh workflow run full-regression.yml --ref <sua-branch>

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.

npx up-web-ds add dialog

npx up-web-ds add badge --path src/components/ds

npm login --scope=@upwebstudio --auth-type=legacy --registry=https://npm.pkg.github.com

npm install -D @upwebstudio/up-web-ds

npx up-web-ds auth set

npx up-web-ds init

Novos componentes e a CLI

Componente novo não pede CLI nova. O icons.json do registry leva tudo o que a instalação precisa: o glifo de cada ícone nos quatro providers, o CSS de cada style capability, os hooks e os itens base. A CLI instalada lê isso no momento do add. A cópia que vem dentro do pacote serve só de reserva.

npm run ds:catalog
npm run ds:docs

npm run ds:cli:sync

npm run verify

npm run ds:registry

npm run verify:full
gh pr create --base main --fill

npx up-web-ds add <item>

cd packages/cli && npm version minor --no-git-tag-version && cd -

npm run cli:verify

gh workflow run publish-cli.yml --ref main

npm install -D @upwebstudio/up-web-ds@latest

npx up-web-ds --version

npx up-web-ds init

Troubleshooting rápido