Communitygithub.com

coastdigitalgroup/coastai-skills

Projete um framework sistemático para upload e gerenciamento de arquivos, definindo a organização visual e espacial de zonas de drop, filas de upload e ações de gerenciamento de arquivos para garantir uma experiência do usuário eficiente e de alta confiança.

O que é coastai-skills?

Este skill define um framework completo para projetar a experiência de upload e gerenciamento de arquivos, desde a zona de drop até o pós-upload. Ele é útil para desenvolvedores e designers que precisam criar sistemas de upload confiáveis, acessíveis e responsivos em plataformas como CMS, aplicativos SaaS, ferramentas de gerenciamento de projetos e interfaces de armazenamento em nuvem. O skill aborda estados de interação da zona de drop, organização espacial da fila de upload, feedback de progresso e ações de gerenciamento (cancelar, editar, excluir), seguindo regras de decisão como a 'Regra de Entrada Instantânea' e diretrizes de acessibilidade WCAG 2.2. O resultado é um blueprint de especificação visual e de comportamento que garante transparência, capacidade de recuperação e usabilidade, mesmo em operações de alta latência.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/coastdigitalgroup/coastai-skills/tree/HEAD/website-design/file-upload-management-system
Ver original→Navegar por todas as habilidades

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

Documentação

Sistema de Upload e Gerenciamento de Arquivos

Propósito

O Sistema de Upload e Gerenciamento de Arquivos fornece uma metodologia para projetar a experiência completa de transferência de arquivos do dispositivo do usuário para um servidor. Ele garante que o processo seja transparente, recuperável e acessível. Este sistema define os estados de interação do gatilho de upload (zonas de drop), o ritmo espacial da fila de upload e os loops de feedback (progresso, sucesso e erro) necessários para manter a confiança do usuário durante operações de alta latência.

Casos de Uso

  • Sistemas de Gerenciamento de Conteúdo (CMS): Projetar bibliotecas de mídia e uploaders de ativos.
  • Aplicativos SaaS: Implementar gerenciamento de documentos, importações de CSV ou anexos de perfil de usuário.
  • Ferramentas de Gerenciamento de Projetos: Estruturar anexos de arquivos dentro de tarefas ou comentários.
  • Ferramentas Criativas: Projetar uploaders de alto volume para fotos, vídeos ou arquivos de design.
  • Interfaces de Armazenamento em Nuvem: Gerenciar operações complexas de upload de pastas e arquivos.

Quando NÃO Usar

  • Pequenos Anexos de Texto: Se o "arquivo" for apenas um pequeno trecho de texto, use uma área de texto padrão ou a copy-to-clipboard-implementation.
  • Transferências Automatizadas pelo Sistema: Onde o usuário não dispara ou monitora o upload (ex: telemetria em segundo plano).
  • Fotos de Perfil de Entrada Única: Embora este sistema se aplique, um gatilho simples de "Avatar" (do user-avatar-system) pode ser mais apropriado para atualizações de baixa complexidade de uma única imagem.
  • Ativos Estáticos: Para ativos que fazem parte do código do site (ex: ícones, imagens de tema), que são gerenciados por workflows de desenvolvedor.

Entradas

  1. Restrições de Tipo e Tamanho de Arquivo: O que é permitido (PDF, JPG, PNG) e quais são os tamanhos máximos?
  2. Expectativa de Volume: O usuário está fazendo upload de um arquivo por vez ou 50+ arquivos em lote?
  3. Contexto do Upload: Esta é uma tarefa independente (ex: "Importar Dados") ou uma ação de suporte (ex: "Anexar à Mensagem")?
  4. Requisitos de Metadados: O arquivo precisa de título, descrição ou tags durante o processo de upload?
  5. Tokens do Sistema: Escalas de espaçamento, cor e tipografia do sistema de design pai.

Saídas

  1. Especificação da Anatomia da Zona de Drop: Definições visuais para o gatilho de upload (estados Ocioso, Pairar, Ativo e Desabilitado).
  2. Blueprint de Gerenciamento de Fila: A organização espacial dos itens da lista "Pendente", "Enviando" e "Concluído".
  3. Matriz de Progresso e Feedback: Tratamentos visuais para barras de progresso, indicadores de porcentagem e estados de sucesso/erro.
  4. Hierarquia de Ações: Regras para ações de "Cancelar", "Tentar Novamente", "Excluir" e "Editar" na lista de arquivos.

Workflow

1. Projete o Gatilho de Upload (A Zona de Drop)

Estabeleça um convite claro para interação:

  • Estado Ocioso: Use uma borda tracejada ou sólida com um ícone (geralmente uma nuvem para cima ou clipe de papel) e uma instrução clara (ex: "Arraste e Solte ou Clique para Enviar").
  • Estado de Arrastar: Altere a cor de fundo ou o estilo da borda para fornecer feedback imediato de que a área está pronta para receber o arquivo.
  • Fallback para Dispositivos Móveis: Garanta que a zona de drop continue sendo um grande botão tocável (mínimo 24x24px conforme WCAG 2.2 SC 2.5.8, 44x44px recomendado) que abre o seletor de arquivos nativo do sistema.

2. Estabeleça a Fila de Upload

Gerencie vários arquivos sem poluir a interface:

  • Feedback Imediato: Assim que um arquivo for selecionado, adicione-o a uma lista abaixo ou dentro do gatilho.
  • Anatomia do Arquivo: Cada item da lista deve incluir:
    • Miniatura/Ícone: Para ajudar o usuário a identificar o tipo ou conteúdo do arquivo.
    • Nome e Tamanho do Arquivo: Para confirmar que o arquivo correto foi escolhido.
    • Indicador de Progresso: Uma barra ou círculo mostrando o status do upload.
    • Ações: Uma maneira de cancelar um upload em andamento ou remover um concluído.

3. Forneça Feedback de Status Granular

Use o step-progress-system e interactive-state-system para estados de arquivo:

  • Enviando: Mostre uma barra de progresso e, para uploads longos, a porcentagem ou "X de Y MB" enviado.
  • Sucesso: Use uma cor semântica de "Sucesso" (verde) e um ícone de visto. Forneça uma ação "Visualizar" ou "Link".
  • Erro: Use uma cor semântica de "Erro" (vermelho). Forneça um motivo claro (ex: "Arquivo muito grande") e um botão "Tentar Novamente".

4. Projete para Gerenciamento de Arquivos (Pós-Upload)

Defina como os usuários interagem com seus ativos enviados:

  • Edição de Metadados: Se títulos ou descrições forem necessários, forneça edição inline ou um modal "Configurações".
  • Exclusão: Use um ícone de "Lixeira" com uma etapa de confirmação para ações destrutivas.
  • Visualização em Grade vs. Lista: Para uploads com muitos arquivos de mídia, forneça uma visualização em grade de miniaturas; para uploads com muitos documentos, use uma visualização em lista para densidade de metadados.

5. Planeje o Empilhamento Responsivo

  • A Fila Compacta: No celular, colapse metadados (como tamanho do arquivo) e priorize o nome do arquivo e a barra de progresso.
  • Foco em Tela Cheia: Para uploaders complexos (como um importador de CSV com mapeamento), use uma sobreposição em tela cheia para remover distrações.

Regras de Decisão

  • A "Regra de Entrada Instantânea": Os arquivos devem aparecer na interface no momento em que são soltos/selecionados, mesmo que a requisição real ao servidor ainda não tenha começado.
  • Visibilidade do Progresso: Use uma barra de progresso para qualquer arquivo que leve mais de 1 segundo para ser enviado. Para uploads muito rápidos, faça a transição diretamente para o estado "Sucesso".
  • Ações em Lote: Se o usuário puder enviar 5+ arquivos, forneça uma ação "Limpar Tudo" ou "Enviar Tudo" para gerenciar a fila coletivamente.
  • Gerenciamento de Conflitos: Defina o que acontece se um arquivo com o mesmo nome existir (ex: "Manter Ambos", "Substituir", "Pular").
  • Estado Vazio: Se a biblioteca de mídia estiver vazia, use o empty-state-system para fornecer um botão "Enviar" como CTA principal.

Restrições

  • Acessibilidade:
    • A zona de drop deve ser focalizável e operável pelas teclas Espaço ou Enter.
    • Use aria-live="polite" para anunciar o progresso do upload e a conclusão para leitores de tela (evite inundar com cada fração de porcentagem).
    • Os inputs de arquivo devem ter um <label> oculto mas acessível.
    • Garanta que o foco nunca fique preso atrás da zona de drop ou da lista de progresso (WCAG 2.4.11 Focus Not Obscured) — cabeçalhos fixos ou toasts não devem cobrir o elemento focado.
    • Os alvos de toque para ações de Cancelar/Tentar Novamente/Excluir devem ter pelo menos 24x24px (WCAG 2.2 SC 2.5.8); 44x44px é preferível para ações primárias.
  • Responsividade: As zonas de drop devem ser fluidas e nunca causar estouro horizontal.
  • Contraste: As barras de progresso e mensagens de erro devem atender às taxas de contraste WCAG AA (4.5:1).

Padrões Comuns de Falha

  • A "Falha Silenciosa": Um upload falha, mas a interface não fornece feedback, deixando o usuário esperando indefinidamente.
  • Progresso Desaparecido: A barra de progresso desaparece antes que o upload seja realmente finalizado, causando "Ansiedade de Última Hora".
  • Zonas de Drop Pequenas: Criar um alvo minúsculo que é difícil de acertar com o mouse ou polegar.
  • Falta de "Cancelar": Não permitir que o usuário pare um upload grande e acidental.
  • Erros Obscuros: Mostrar "Erro 500" em vez de "O servidor está ocupado no momento, por favor tente novamente em alguns instantes."

Critérios de Validação

  • A zona de drop tem estados distintos de Ocioso, Pairar e Arrastar sobre.
  • Cada arquivo na fila mostra nome, tamanho e progresso.
  • Os estados de Sucesso e Erro são indicados tanto por cor quanto por ícones.
  • Os usuários podem cancelar ou remover arquivos da fila.
  • Regiões ARIA live são usadas para atualizações de status.
  • O layout é responsivo e lida graciosamente com nomes de arquivos longos.
  • Todos os elementos interativos atendem ao mínimo de 24x24px do WCAG 2.2 para alvos de toque (44x44px preferível).

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for progressive disclosure using accordions, ensuring structural integrity, visual affordances, and accessibility across different content densities and devices.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for long-form content, managing readability, vertical rhythm, and information density to ensure a superior reading experience.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for informational elements that communicate state (Badges) and categorization (Tags) with clarity and accessibility.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for non-overlay notifications, managing global announcements and contextual inline alerts to communicate system states without interrupting the user's flow.

coastdigitalgroup/coastai-skills

Design and implement a systematic, asymmetrical bento-grid layout framework to organize diverse content types cohesively while maintaining strict visual hierarchy, logical focus order, and responsive flexibility.

coastdigitalgroup/coastai-skills

Design a responsive, mobile-first bottom navigation bar and persistent action dock system for mobile websites and web applications, establishing spatial anchors, tab bar anatomy, badge indicators, thumb-zone ergonomics, safe area inset handling, active/inactive state contrast, and desktop responsive adaptation rules.

coastdigitalgroup/coastai-skills

Design a mobile-first bottom sheet overlay system with configurable detents, drag affordances, safe area padding, responsive desktop modal/popover adaptation, and WCAG AA accessibility compliance.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for secondary navigation trails that provide orientation, context, and one-click access to parent levels in deep information architectures.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for buttons and interactive triggers, managing visual hierarchy, variant logic, and action grouping to ensure clear intent and accessible interaction.

coastdigitalgroup/coastai-skills

Design a systematic framework for date and time selection, managing calendar grids, range pickers, and scheduling interfaces to ensure precision and accessibility.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for modular content containers that maintain hierarchy, structural integrity, and action alignment across variable content and responsive viewports.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for horizontal discovery components, managing navigation affordances, scroll behavior, and accessibility to ensure effective content density without compromising usability.

coastdigitalgroup/coastai-skills

Design a systematic, highly accessible, and developer-friendly UI layout framework for code blocks, snippet showcases, multi-file code tabs, line-highlighting, diff views, and syntax token contrast in technical documentation and developer platforms.

coastdigitalgroup/coastai-skills

Design a systematic framework for global command menus (Cmd+K panels) that combines keyboard-driven navigation, command execution, and shortcut discovery into an accessible, responsive overlay.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for threaded conversations, managing nesting depths, action hierarchies, and community signaling to foster engagement and readability.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for side-by-side comparison interfaces, managing high attribute density and responsive complexity to support informed decision-making.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for user privacy, managing consent banners, preference centers, and persistent privacy controls to balance legal compliance with user trust.

coastdigitalgroup/coastai-skills

Design and implement a systematic, highly accessible, and responsive visual layout framework for conversational chat widgets, live chat boxes, and chatbot panels that ensures clear message scannability, native focus flow, and seamless mobile keyboard adaptation.

coastdigitalgroup/coastai-skills

Design a systematic, accessible, and high-conversion framework for custom select dropdowns and comboboxes, defining anatomy, states, search-filtering, and responsive mobile-adaptive patterns.

coastdigitalgroup/coastai-skills

Design and implement a systematic color palette that ensures WCAG 2.2 accessibility compliance. Trigger this skill when asked to define brand colors, create UI themes, or establish a visual system for a website.

Habilidades Relacionadas

steipete/sag

ElevenLabs text-to-speech with mac-style say UX.

community

steipete/oracle

Oracle CLI second-model review/debug/refactor/design with selected files, dry-run token checks, API or browser engine.

community

steipete/peekaboo

Capture and automate macOS UI with the Peekaboo CLI.

community

mattpocock/design-an-interface

Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".

community

mattpocock/prototype

Build a throwaway prototype to flesh out a design — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route.

community

mattpocock/grill-me

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".

community