Communitygithub.com

coastdigitalgroup/coastai-skills

파일 업로드 및 관리를 위한 체계적인 프레임워크를 설계합니다. 드롭 영역, 업로드 대기열, 파일 관리 작업의 시각적 및 공간적 구성을 정의하여 신뢰도 높고 효율적인 사용자 경험을 보장합니다.

coastai-skills란 무엇인가요?

이 스킬은 사용자 기기에서 서버로 파일을 전송하는 전체 경험을 설계하기 위한 방법론을 제공합니다. 특히 투명성, 복구 가능성, 접근성을 핵심 가치로 삼아, 드롭 영역의 상호작용 상태, 업로드 대기열의 공간적 리듬, 그리고 사용자 신뢰를 유지하는 피드백 루프(진행률, 성공, 오류)를 체계적으로 정의합니다. 이 스킬은 CMS, SaaS 애플리케이션, 프로젝트 관리 도구, 클라우드 스토리지 등 다양한 플랫폼에서 파일 업로드 기능을 구현할 때 유용하며, 클로드 코드와 같은 AI 어시스턴트가 드롭 영역 디자인, 대기열 관리, 진행 상태 피드백, 사후 파일 관리 작업에 대한 구체적인 지침을 제공합니다. 또한 접근성(WCAG 2.2), 반응형 디자인, 대비(AA 등급) 등 제약 조건을 명시하고 '무음 실패', '증발하는 진행률'과 같은 일반적인 실패 패턴도 제시합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/coastdigitalgroup/coastai-skills/tree/HEAD/website-design/file-upload-management-system

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

파일 업로드 및 관리 시스템

목적

파일 업로드 및 관리 시스템은 사용자 기기에서 서버로 파일을 전송하는 전체 경험을 설계하기 위한 방법론을 제공합니다. 이 프로세스가 투명하고, 복구 가능하며, 접근 가능하도록 보장합니다. 이 시스템은 업로드 트리거(드롭 영역)의 상호작용 상태, 업로드 대기열의 공간적 리듬, 그리고 높은 지연 시간 작업 중 사용자 신뢰를 유지하는 데 필요한 피드백 루프(진행률, 성공, 오류)를 정의합니다.

사용 사례

  • 콘텐츠 관리 시스템(CMS): 미디어 라이브러리 및 에셋 업로더 설계.
  • SaaS 애플리케이션: 문서 관리, CSV 가져오기 또는 사용자 프로필 첨부 파일 구현.
  • 프로젝트 관리 도구: 작업 또는 댓글 내 파일 첨부 구조화.
  • 크리에이티브 도구: 사진, 비디오 또는 디자인 파일을 위한 대용량 업로더 설계.
  • 클라우드 스토리지 인터페이스: 복잡한 폴더 및 파일 업로드 작업 관리.

사용하지 말아야 할 경우

  • 작은 텍스트 첨부 파일: "파일"이 단지 작은 텍스트 조각인 경우, 표준 텍스트 영역이나 클립보드-복사-구현을 사용하십시오.
  • 시스템 자동 전송: 사용자가 업로드를 트리거하거나 모니터링하지 않는 경우(예: 백그라운드 원격 측정).
  • 단일 입력 프로필 사진: 이 시스템이 적용 가능하지만, 낮은 복잡성의 단일 이미지 업데이트에는 간단한 "아바타" 트리거(사용자-아바타-시스템에서)가 더 적합할 수 있습니다.
  • 정적 에셋: 사이트 코드의 일부인 에셋(예: 아이콘, 테마 이미지)은 개발자 워크플로를 통해 관리됩니다.

입력

  1. 파일 유형 및 크기 제약: 허용되는 파일(PDF, JPG, PNG) 및 최대 크기는 무엇입니까?
  2. 볼륨 예상: 사용자가 한 번에 하나의 파일을 업로드합니까? 아니면 50개 이상의 파일을 대량으로 업로드합니까?
  3. 업로드 컨텍스트: 이것은 독립적인 작업(예: "데이터 가져오기")입니까? 아니면 지원 작업(예: "메시지에 첨부")입니까?
  4. 메타데이터 요구 사항: 업로드 프로세스 중에 파일에 제목, 설명 또는 태그가 필요합니까?
  5. 시스템 토큰: 상위 디자인 시스템의 간격, 색상 및 타이포그래피 규모.

출력

  1. 드롭 영역 명세서: 업로드 트리거(대기, 호버, 활성, 비활성 상태)에 대한 시각적 정의.
  2. 대기열 관리 청사진: "대기 중", "업로드 중", "완료됨" 목록 항목의 공간적 구성.
  3. 진행률 및 피드백 매트릭스: 진행률 표시줄, 백분율 표시기 및 성공/오류 상태에 대한 시각적 처리.
  4. 액션 계층 구조: 파일 목록 내 "취소", "재시도", "삭제" 및 "편집" 작업에 대한 규칙.

워크플로

1. 업로드 트리거(드롭 영역) 설계

상호작용에 대한 명확한 초대장을 설정합니다:

  • 대기 상태: 아이콘(보통 클라우드 업 또는 종이 클립)과 명확한 지침(예: "드래그 앤 드롭 또는 클릭하여 업로드")이 있는 점선 또는 실선 테두리를 사용합니다.
  • 드래그 오버 상태: 배경색 또는 테두리 스타일을 변경하여 영역이 파일을 받을 준비가 되었음을 즉시 알 수 있도록 합니다.
  • 모바일 폴백: 드롭 영역이 기본 시스템 파일 선택기를 여는 크고 탭 가능한 버튼(WCAG 2.2 SC 2.5.8 기준 최소 24x24px, 44x44px 권장)으로 유지되도록 합니다.

2. 업로드 대기열 설정

인터페이스를 복잡하게 만들지 않고 여러 파일을 관리합니다:

  • 즉각적인 피드백: 파일이 선택되는 즉시 트리거 내부 또는 아래 목록에 추가합니다.
  • 파일 구성: 각 목록 항목에는 다음이 포함되어야 합니다:
    • 썸네일/아이콘: 사용자가 파일 유형 또는 내용을 식별하는 데 도움을 줍니다.
    • 파일 이름 및 크기: 올바른 파일이 선택되었는지 확인합니다.
    • 진행률 표시기: 업로드 상태를 보여주는 막대 또는 원.
    • 액션: 진행 중인 업로드를 취소하거나 완료된 업로드를 제거하는 방법.

3. 세분화된 상태 피드백 제공

파일 상태에 대해 단계-진행-시스템 및 상호작용-상태-시스템을 사용합니다:

  • 업로드 중: 진행률 표시줄을 표시하고 긴 업로드의 경우 "X of Y MB" 업로드된 백분율을 표시합니다.
  • 성공: 의미론적 "성공" 색상(녹색)과 확인 표시 아이콘을 사용합니다. "보기" 또는 "링크" 작업을 제공합니다.
  • 오류: 의미론적 "오류" 색상(빨간색)을 사용합니다. 명확한 이유(예: "파일이 너무 큼")와 "재시도" 버튼을 제공합니다.

4. 파일 관리(업로드 후) 설계

사용자가 업로드한 에셋과 상호 작용하는 방식을 정의합니다:

  • 메타데이터 편집: 제목이나 설명이 필요한 경우 인라인 편집 또는 "설정" 모달을 제공합니다.
  • 삭제: 파괴적인 작업에 대해 확인 단계가 있는 "휴지통" 아이콘을 사용합니다.
  • 그리드 vs. 목록 보기: 미디어가 많은 업로드의 경우 썸네일 그리드 보기를 제공하고, 문서가 많은 업로드의 경우 메타데이터 밀도를 위해 목록 보기를 사용합니다.

5. 반응형 스태킹 계획

  • 컴팩트 대기열: 모바일에서는 메타데이터(파일 크기 등)를 축소하고 파일 이름과 진행률 표시줄을 우선시합니다.
  • 전체 화면 포커스: 매핑이 있는 CSV 가져오기와 같은 복잡한 업로더의 경우 전체 화면 오버레이를 사용하여 방해 요소를 제거합니다.

결정 규칙

  • "즉시 항목" 규칙: 실제 서버 요청이 아직 시작되지 않았더라도 파일은 드롭/선택되는 순간 UI에 나타나야 합니다.
  • 진행률 가시성: 업로드에 1초 이상 걸리는 파일에는 진행률 표시줄을 사용하십시오. 매우 빠른 업로드의 경우 직접 "성공" 상태로 전환하십시오.
  • 배치 작업: 사용자가 5개 이상의 파일을 업로드할 수 있는 경우 대기열을 집합적으로 관리하기 위해 "모두 지우기" 또는 "모두 업로드" 작업을 제공하십시오.
  • 충돌 관리: 동일한 이름의 파일이 이미 있는 경우 어떻게 처리할지 정의하십시오(예: "둘 다 유지", "바꾸기", "건너뛰기").
  • 빈 상태: 미디어 라이브러리가 비어 있는 경우 빈-상태-시스템을 사용하여 기본 CTA로 "업로드" 버튼을 제공하십시오.

제약 조건

  • 접근성:
    • 드롭 영역은 포커스가 가능해야 하며 Space 또는 Enter 키를 통해 작동할 수 있어야 합니다.
    • aria-live="polite"를 사용하여 화면 판독기에 업로드 진행률 및 완료를 알리십시오(모든 백분율 틱으로 넘치지 않도록 하십시오).
    • 파일 입력에는 숨겨져 있지만 접근 가능한 <label>이 있어야 합니다.
    • 포커스가 드롭 영역이나 진행률 목록 뒤에 갇히지 않도록 하십시오(WCAG 2.4.11 포커스 비가림). 고정 헤더나 토스트가 포커스된 요소를 가리지 않아야 합니다.
    • 취소/재시도/삭제 작업의 터치 대상은 최소 24x24px(WCAG 2.2 SC 2.5.8)를 충족해야 하며, 주요 작업의 경우 44x44px가 선호됩니다.
  • 반응성: 드롭 영역은 유동적이어야 하며 가로 오버플로를 유발하지 않아야 합니다.
  • 대비: 진행률 표시줄 및 오류 메시지는 WCAG AA(4.5:1) 대비 비율을 충족해야 합니다.

일반적인 실패 패턴

  • "무음 실패": 업로드가 실패했지만 UI가 피드백을 제공하지 않아 사용자가 무기한 기다리게 됩니다.
  • 증발하는 진행률: 업로드가 실제로 완료되기 전에 진행률 표시줄이 사라져 "후기 불안"을 유발합니다.
  • 작은 드롭 영역: 마우스나 엄지손가락으로 클릭하기 어려운 작은 대상을 만듭니다.
  • "취소" 부족: 사용자가 크고 우발적인 업로드를 중지할 수 없도록 합니다.
  • 모호한 오류: "서버가 현재 사용 중입니다. 잠시 후 다시 시도해 주세요." 대신 "오류 500"을 표시합니다.

검증 기준

  • 드롭 영역에 고유한 대기, 호버 및 드래그 오버 상태가 있습니다.
  • 대기열의 각 파일에 이름, 크기 및 진행률이 표시됩니다.
  • 성공 및 오류 상태가 색상과 아이콘으로 모두 표시됩니다.
  • 사용자가 대기열에서 파일을 취소하거나 제거할 수 있습니다.
  • ARIA 라이브 영역이 상태 업데이트에 사용됩니다.
  • 레이아웃이 반응형이며 긴 파일 이름을 적절하게 처리합니다.
  • 모든 대화형 요소가 WCAG 2.2 24x24px 터치 대상 최소 기준(44x44px 권장)을 충족합니다.

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.

관련 스킬