specsfy-specialist-shadcn-ui

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

shadcn/ui

Para interfaces React e Tailwind da Promovaweb, esta skill prepara as primitives,

components.json

, aliases e tema. Quando a tela precisar de CRUD ou composição de produto, carregue

$specsfy-specialist-reui

em conjunto: ela instala primeiro componentes gratuitos ReUI sobre esta base.

针对Promovaweb的React和Tailwind界面，本技能用于准备基础组件、

components.json

、别名和主题。当页面需要CRUD或产品组合功能时，可同时加载

$specsfy-specialist-reui

：它会先在此基础上安装免费的ReUI组件。

Quando usar

使用场景

Acionar quando o projeto tem
```
components.json
```
ou componentes shadcn já incorporados, ou quando a pessoa pede explicitamente um componente shadcn/ui (Data Table, Sidebar, Dialog, Form, Chart).
Acionar também para identificar se o shadcn/ui do projeto usa Base UI, Radix ou React Aria antes de compor um padrão (dashboard, formulário, overlay).
Não acionar para o sistema de tokens/utilitários Tailwind em si; combinar com
```
$specsfy-specialist-tailwind-css
```
para isso.
Não acionar quando o projeto usa uma biblioteca de componentes visual diferente (galeria copiável não-Radix); nesse caso avaliar
```
$specsfy-specialist-react-ui-components
```
com
```
$specsfy-specialist-ui-design
```
.
Combinar com
```
$specsfy-specialist-web-accessibility
```
para auditoria aprofundada além da acessibilidade já garantida pelo primitive Radix.

当项目包含
```
components.json
```
、已集成shadcn组件，或用户明确请求shadcn/ui组件（如Data Table、Sidebar、Dialog、Form、Chart）时触发。
也可用于识别项目中的shadcn/ui使用的是Base UI、Radix还是React Aria，之后再构建标准化界面（如仪表盘、表单、浮层）。
不可单独用于Tailwind的tokens/工具系统；需结合
```
$specsfy-specialist-tailwind-css
```
技能处理此类需求。
当项目使用其他可视化组件库（非Radix的可复制组件库）时，不可触发本技能；此时应评估结合使用
```
$specsfy-specialist-react-ui-components
```
与
```
$specsfy-specialist-ui-design
```
技能。
如需在Radix基础组件已提供的无障碍能力之外进行深度审计，可结合
```
$specsfy-specialist-web-accessibility
```
技能。

Fluxo

流程

Confirmar framework, versão do shadcn/ui,
```
components.json
```
(aliases de import, estilo, CSS variables) e o registry configurado antes de adicionar qualquer componente.
Identificar a base de primitives em uso: começar pelos imports dos componentes shadcn já incorporados e confirmar no manifest. Classificar
```
@base-ui/react
```
como Base UI,
```
radix-ui
```
ou
```
@radix-ui/react-*
```
como Radix e
```
react-aria-components
```
ou
```
@react-aria/*
```
como React Aria. Se os componentes usarem mais de uma base ou os sinais não bastarem, registrar a base por arquivo e não adicionar, migrar ou reescrever primitives até esclarecer a divergência.
Auditar os componentes já incorporados no projeto e suas customizações locais antes de adicionar um novo, para não duplicar ou divergir de um componente equivalente já existente.
Escolher o primitive da base identificada pelo comportamento e semântica exigidos (diálogo modal vs popover vs sheet lateral), não pela aparência mais próxima do design.
Adicionar o menor conjunto de componentes necessário e revisar o código gerado linha a linha — ele é copiado para o projeto e passa a ser mantido por quem o adicionou.
Adaptar tokens, variantes (
```
cva
```
) e composição ao design do projeto sem remover roles,
```
aria-*
```
, gestão de foco ou atalhos de teclado oferecidos pela base identificada.
Construir todos os estados reais do componente (loading, empty, error, disabled, permission denied), não apenas o estado nominal mostrado na documentação.
Testar teclado, foco, responsividade, submissão de formulário e os dois temas (claro/escuro) antes de considerar o componente pronto.
Atualizar
```
INTERFACE.md
```
para cada primitive ou bloco criado, alterado ou reaproveitado, incluindo arquivo, origem, finalidade, API, estados, acessibilidade, consumidores e orientação de extensão.

在添加任何组件前，确认框架、shadcn/ui版本、
```
components.json
```
（导入别名、样式、CSS变量）及已配置的registry。
识别当前使用的基础组件库：从已集成的shadcn组件的导入语句入手，在清单中确认。将
```
@base-ui/react
```
归为Base UI，
```
radix-ui
```
或
```
@radix-ui/react-*
```
归为Radix，
```
react-aria-components
```
或
```
@react-aria/*
```
归为React Aria。若组件使用多种基础库或信号不足，则按文件记录基础库类型，在分歧明确前不添加、迁移或重写基础组件。
在添加新组件前，审计项目中已集成的组件及其本地自定义内容，避免重复添加或与现有等效组件产生差异。
根据所需的行为和语义（如模态对话框、弹出框、侧边面板）选择对应基础库的组件，而非仅依据与设计最接近的外观。
添加必要的最小组件集，并逐行检查生成的代码——代码会被复制到项目中，由添加者负责维护。
调整tokens、变体（
```
cva
```
）及组件组合以适配项目设计，但不得移除基础库提供的角色、
```
aria-*
```
属性、焦点管理或键盘快捷键。
构建组件的所有实际状态（加载、空状态、错误、禁用、无权限），而非仅实现文档中展示的常规状态。
在确认组件就绪前，测试键盘操作、焦点、响应式、表单提交及两种主题（浅色/深色）。
针对每个创建、修改或复用的基础组件或模块，更新
```
INTERFACE.md
```
，包含文件路径、来源、用途、API、状态、无障碍信息、使用者及扩展指南。

Padrões

规范

Não tratar shadcn/ui como dependência opaca versionada num pacote; o código copiado pertence ao projeto e qualquer bug ou desvio de acessibilidade nele é responsabilidade do time, não "responsabilidade da lib".
Usar somente APIs, atributos de estado e composição próprios da base identificada. Base UI, Radix e React Aria expõem contratos semelhantes, mas seus imports, props e atributos não são intercambiáveis.
Preservar roles ARIA, labels, gestão de foco (foco inicial, trap e retorno ao trigger) e Escape quando a base os oferece; customização visual não pode remover esse comportamento.
Centralizar tokens de tema (CSS variables) num único lugar; nunca editar dezenas de componentes individualmente para trocar uma cor de marca ou ajustar o tema.
Em projetos React da Promovaweb, usar shadcn/ui junto do ReUI: o primeiro atende primitives e o segundo atende composições gratuitas de produto. Toda tela é uma composição de componentes React, não um arquivo monolítico.
Compor um Data Table para o caso de uso real (colunas, ordenação, filtro, seleção, paginação necessários) em vez de importar um componente universal com todas as capacidades possíveis "por garantia".
Fazer a Sidebar responder a viewport (colapsar em mobile), densidade de navegação e destacar a rota atual de forma perceptível.
Validar todo formulário também no servidor (a validação client-side é UX, não segurança) e associar cada mensagem de erro ao campo correspondente via
```
aria-describedby
```
/label.
Atualizar um componente já customizado apenas depois de comparar o diff entre a versão nova do registry e as customizações locais — um
```
add
```
ingênuo pode sobrescrever uma correção de acessibilidade feita anteriormente.

不可将shadcn/ui视为版本化的黑盒依赖；复制的代码属于项目，其中的任何bug或无障碍问题均由团队负责，而非“组件库的责任”。
仅使用已识别基础库的原生API、状态属性及组合方式。Base UI、Radix和React Aria的接口相似，但导入方式、props及属性不可互换。
保留基础库提供的ARIA角色、标签、焦点管理（初始焦点、焦点陷阱、返回触发元素）及Esc快捷键；视觉自定义不可移除这些行为。
将主题tokens（CSS变量）集中管理；绝不可单独编辑数十个组件来更改品牌颜色或调整主题。
在Promovaweb的React项目中，需结合使用shadcn/ui与ReUI：前者负责基础组件，后者负责免费的产品组合组件。所有页面均由React组件组合而成，而非单一的单体文件。
根据实际使用场景构建Data Table（包含所需的列、排序、筛选、选择、分页功能），而非为了“保险”导入具备所有功能的通用组件。
实现响应式Sidebar（在移动端折叠）、适配导航密度，并以清晰的方式突出当前路由。
表单验证需同时在服务器端进行（客户端验证仅为提升UX，而非保障安全），并通过
```
aria-describedby
```
/标签将每条错误消息与对应字段关联。
仅在对比registry新版本与本地自定义内容的差异后，才可更新已自定义的组件——直接执行
```
add
```
操作可能会覆盖之前的无障碍修复。

Antipadrões

反模式

Assumir que todo shadcn/ui usa Radix porque o componente tem a mesma API pública. Isso introduz imports e props incompatíveis com Base UI ou React Aria.
Importar um Dialog do shadcn/ui e remover o
```
aria-describedby
```
/título por achar "redundante visualmente" — quebra o anúncio do leitor de tela sobre o que o diálogo faz.
Editar o arquivo gerado do componente para "consertar" um estilo em vez de ajustar o token/variant central — a próxima pessoa que atualizar o componente perde a correção sem saber que ela existia.
Tratar o Data Table como componente único e genérico para toda tabela do sistema, acumulando props condicionais até virar impossível de entender — compor uma tabela por caso de uso a partir dos blocos do registry.
Validar formulário só no cliente (schema no front) e nunca repetir a validação no servidor — qualquer requisição direta ao endpoint ignora a validação do formulário.
Rodar
```
shadcn add
```
sobre um componente já customizado sem diff prévio, perdendo silenciosamente ajustes de acessibilidade ou de negócio feitos localmente.

假设所有shadcn/ui都使用Radix，仅因组件具有相同的公共API。这会引入与Base UI或React Aria不兼容的导入和props。
导入shadcn/ui的Dialog后，因觉得“视觉上冗余”而移除
```
aria-describedby
```
/标题——这会破坏屏幕阅读器对对话框功能的播报。
编辑组件生成文件来“修复”样式，而非调整集中管理的token/变体——下次有人更新组件时会不知情地丢失该修复。
将Data Table视为适用于系统所有表格的单一通用组件，不断添加条件props直至难以理解——应基于registry模块，针对每个使用场景构建专属表格。
仅在客户端验证表单（前端schema），不在服务器端重复验证——任何直接请求端点的操作都会绕过表单验证。
在未预先对比差异的情况下，对已自定义的组件执行
```
shadcn add
```
操作，无声地丢失本地已完成的无障碍或业务逻辑调整。

Validação

验证

Rodar typecheck, lint, testes e build do projeto após adicionar ou modificar um componente.
Percorrer a navegação completa por teclado: abrir/fechar overlay, focus trap dentro do Dialog/Sheet, e retorno do foco ao elemento que o abriu.
Testar em mobile e desktop, tema claro e escuro, zoom alto e conteúdo longo/truncado nas células de tabela e nos rótulos.
Exercitar os estados de tabela (vazio, carregando, erro, com dados), gráfico (sem dado, com dado), formulário (pendente, erro, sucesso, reabrir após falha preservando valores) e sidebar (colapsada, expandida, rota ativa) realmente usados pela tela.
Não declarar um componente "acessível" só porque veio do shadcn/ui; qualquer customização precisa da comprovação acima antes da afirmação.

添加或修改组件后，运行项目的类型检查、代码扫描、测试及构建。
通过键盘完成完整导航测试：打开/关闭浮层、Dialog/Sheet内的焦点陷阱、焦点返回至触发元素。
在移动端和桌面端、浅色和深色主题、高缩放比例及表格单元格与标签内容过长/截断的场景下进行测试。
测试页面实际使用的组件状态：表格（空、加载、错误、有数据）、图表（无数据、有数据）、表单（待处理、错误、成功、失败后重新打开并保留值）及侧边栏（折叠、展开、当前路由）。
不可仅因组件来自shadcn/ui就宣称其“无障碍”；任何自定义内容都需经过上述验证后才可做出该声明。

specsfy-specialist-shadcn-ui

Original

Translation

shadcn/ui

shadcn/ui

Quando usar

使用场景

Fluxo

流程

Padrões

规范

Antipadrões

反模式

Validação

验证

Skills relacionadas

相关技能