coastdigitalgroup/coastai-skills

Datei-Upload- und Verwaltungssystem

Zweck

Das Datei-Upload- und Verwaltungssystem bietet eine Methodik zur Gestaltung der End-to-End-Erfahrung beim Übertragen von Dateien vom Gerät eines Benutzers auf einen Server. Es stellt sicher, dass der Prozess transparent, wiederherstellbar und zugänglich ist. Dieses System definiert die Interaktionszustände des Upload-Triggers (Drop-Zonen), den räumlichen Rhythmus der Upload-Warteschlange und die Feedback-Schleifen (Fortschritt, Erfolg und Fehler), die erforderlich sind, um das Vertrauen der Benutzer bei hochlatenzintensiven Vorgängen aufrechtzuerhalten.

Anwendungsfälle

• Content-Management-Systeme (CMS): Gestaltung von Medienbibliotheken und Asset-Uploadern.
• SaaS-Anwendungen: Implementierung von Dokumentenverwaltung, CSV-Importen oder Benutzerprofil-Anhängen.
• Projektmanagement-Tools: Strukturierung von Dateianhängen innerhalb von Aufgaben oder Kommentaren.
• Kreativ-Tools: Gestaltung von Hochvolumen-Uploadern für Fotos, Videos oder Designdateien.
• Cloud-Speicher-Oberflächen: Verwaltung komplexer Ordner- und Datei-Upload-Vorgänge.

Wann NICHT zu verwenden

• Kleine Textanhänge: Wenn die „Datei“ nur ein winziger Textausschnitt ist, verwenden Sie ein standardmäßiges Textfeld oder die copy-to-clipboard-implementation.
• Systemautomatisierte Übertragungen: Wenn der Benutzer den Upload nicht auslöst oder überwacht (z. B. Hintergrundtelemetrie).
• Einzelfoto-Profilbilder: Obwohl dieses System anwendbar ist, könnte ein einfacher „Avatar“-Trigger (aus user-avatar-system) für Einzelbild-Updates mit geringer Komplexität besser geeignet sein.
• Statische Assets: Für Assets, die Teil des Site-Codes sind (z. B. Symbole, Theme-Bilder), die über Entwickler-Workflows verwaltet werden.

Eingaben

1. Dateityp- und Größenbeschränkungen: Was ist erlaubt (PDF, JPG, PNG) und welche maximalen Größen gibt es?
2. Mengenerwartung: Lädt der Benutzer eine Datei nach der anderen oder 50+ Dateien im Bulk hoch?
3. Kontext des Uploads: Handelt es sich um eine eigenständige Aufgabe (z. B. „Daten importieren“) oder eine unterstützende Aktion (z. B. „An Nachricht anhängen“)?
4. Metadatenanforderungen: Benötigt die Datei während des Upload-Prozesses einen Titel, eine Beschreibung oder Tags?
5. System-Token: Abstands-, Farb- und Typografie-Skalen des übergeordneten Designsystems.

Ausgaben

1. Drop-Zonen-Anatomie-Spezifikation: Visuelle Definitionen für den Upload-Trigger (Idle, Hover, Active und Disabled Zustände).
2. Warteschlangenverwaltungs-Blueprint: Die räumliche Organisation der Listenelemente „Ausstehend“, „Wird hochgeladen“ und „Abgeschlossen“.
3. Fortschritts- und Feedback-Matrix: Visuelle Behandlungen für Fortschrittsbalken, Prozentanzeigen und Erfolgs-/Fehlerzustände.
4. Aktionshierarchie: Regeln für die Aktionen „Abbrechen“, „Wiederholen“, „Löschen“ und „Bearbeiten“ innerhalb der Dateiliste.

Workflow

1. Gestalten Sie den Upload-Trigger (Die Drop-Zone)

Schaffen Sie eine klare Einladung zur Interaktion:

• Idle-Zustand: Verwenden Sie eine gestrichelte oder durchgezogene Linie mit einem Symbol (normalerweise ein Cloud-Hinauf- oder Büroklammer-Symbol) und einer klaren Anweisung (z. B. „Drag & Drop oder Klicken zum Hochladen“).
• Drag-Over-Zustand: Ändern Sie die Hintergrundfarbe oder den Linienstil, um sofortiges Feedback zu geben, dass der Bereich bereit ist, die Datei zu empfangen.
• Mobile Fallback: Stellen Sie sicher, dass die Drop-Zone ein großer, tippbarer Button bleibt (min. 24x24px gemäß WCAG 2.2 SC 2.5.8, 44x44px empfohlen), der den nativen System-Dateiauswahl öffnet.

2. Richten Sie die Upload-Warteschlange ein

Verwalten Sie mehrere Dateien, ohne die Oberfläche zu überladen:

• Sofortiges Feedback: Sobald eine Datei ausgewählt wird, fügen Sie sie einer Liste unterhalb oder innerhalb des Triggers hinzu.
• Datei-Anatomie: Jedes Listenelement sollte enthalten:
  • Miniaturansicht/Symbol: Um dem Benutzer zu helfen, den Dateityp oder -inhalt zu identifizieren.
  • Dateiname und -größe: Um zu bestätigen, dass die richtige Datei ausgewählt wurde.
  • Fortschrittsanzeige: Ein Balken oder Kreis, der den Upload-Status anzeigt.
  • Aktionen: Eine Möglichkeit, einen laufenden Upload abzubrechen oder einen abgeschlossenen zu entfernen.

3. Bieten Sie detailliertes Status-Feedback

Verwenden Sie das step-progress-system und interactive-state-system für Dateizustände:

• Wird hochgeladen: Zeigen Sie einen Fortschrittsbalken und, bei langen Uploads, den Prozentsatz oder „X von Y MB“ an.
• Erfolg: Verwenden Sie eine semantische „Erfolgs“-Farbe (grün) und ein Häkchensymbol. Bieten Sie eine „Anzeigen“- oder „Link“-Aktion an.
• Fehler: Verwenden Sie eine semantische „Fehler“-Farbe (rot). Geben Sie einen klaren Grund an (z. B. „Datei zu groß“) und eine „Wiederholen“-Schaltfläche.

4. Gestalten Sie für die Dateiverwaltung (Nach dem Upload)

Definieren Sie, wie Benutzer mit ihren hochgeladenen Assets interagieren:

• Metadaten bearbeiten: Wenn Titel oder Beschreibungen erforderlich sind, bieten Sie Inline-Bearbeitung oder ein „Einstellungen“-Modal an.
• Löschen: Verwenden Sie ein „Papierkorb“-Symbol mit einem Bestätigungsschritt für zerstörerische Aktionen.
• Raster- vs. Listenansicht: Bei medienintensiven Uploads bieten Sie eine Rasteransicht mit Miniaturansichten an; bei dokumentenintensiven Uploads verwenden Sie eine Listenansicht für die Metadatendichte.

5. Planen Sie für reaktionsschnelles Stapeln

• Die kompakte Warteschlange: Klappen Sie auf Mobilgeräten Metadaten (wie Dateigröße) ein und priorisieren Sie den Dateinamen und den Fortschrittsbalken.
• Vollbild-Fokus: Verwenden Sie für komplexe Uploader (wie einen CSV-Import mit Zuordnung) ein Vollbild-Overlay, um Ablenkungen zu entfernen.

Entscheidungsregeln

• Die „Sofortiger Eintrag“-Regel: Dateien müssen in der Benutzeroberfläche erscheinen, sobald sie fallen gelassen/ausgewählt werden, auch wenn die eigentliche Serveranfrage noch nicht begonnen hat.
• Fortschrittssichtbarkeit: Verwenden Sie einen Fortschrittsbalken für jede Datei, deren Upload länger als 1 Sekunde dauert. Bei sehr schnellen Uploads wechseln Sie direkt in den „Erfolg“-Zustand.
• Batch-Aktionen: Wenn der Benutzer 5+ Dateien hochladen kann, bieten Sie eine „Alle löschen“- oder „Alle hochladen“-Aktion an, um die Warteschlange gemeinsam zu verwalten.
• Konfliktmanagement: Definieren Sie, was passiert, wenn eine Datei mit demselben Namen existiert (z. B. „Beide behalten“, „Ersetzen“, „Überspringen“).
• Leerzustand: Wenn die Medienbibliothek leer ist, verwenden Sie das empty-state-system, um eine „Hochladen“-Schaltfläche als primären CTA bereitzustellen.

Einschränkungen

• Barrierefreiheit:
  • Die Drop-Zone muss fokussierbar und über die Space- oder Enter-Taste bedienbar sein.
  • Verwenden Sie aria-live="polite", um Upload-Fortschritt und -Abschluss für Screenreader anzukündigen (vermeiden Sie Überflutung mit jedem Prozent-Tick).
  • Datei-Inputs müssen ein verstecktes, aber zugängliches <label> haben.
  • Stellen Sie sicher, dass der Fokus niemals hinter der Drop-Zone oder der Fortschrittsliste gefangen ist (WCAG 2.4.11 Focus Not Obscured) — sticky Header oder Toasts dürfen das fokussierte Element nicht verdecken.
  • Touch-Ziele für Aktionen wie Abbrechen/Wiederholen/Löschen müssen mindestens 24x24px (WCAG 2.2 SC 2.5.8) betragen; 44x44px wird für primäre Aktionen bevorzugt.
• Reaktionsfähigkeit: Drop-Zonen sollten fließend sein und niemals horizontalen Überlauf verursachen.
• Kontrast: Fortschrittsbalken und Fehlermeldungen müssen WCAG AA (4.5:1) Kontrastverhältnisse erfüllen.

Häufige Fehlermuster

• Der „Stille Fehler“: Ein Upload schlägt fehl, aber die UI gibt kein Feedback, sodass der Benutzer auf unbestimmte Zeit wartet.
• Verschwindender Fortschritt: Der Fortschrittsbalken verschwindet, bevor der Upload tatsächlich abgeschlossen ist, was „Spätphasen-Angst“ verursacht.
• Kleine Drop-Zonen: Ein winziges Ziel, das schwer mit Maus oder Daumen zu treffen ist.
• Fehlender „Abbrechen“: Dem Benutzer wird nicht erlaubt, einen großen, versehentlichen Upload zu stoppen.
• Unklare Fehler: Anzeige von „Fehler 500“ anstatt „Der Server ist derzeit ausgelastet, bitte versuchen Sie es in einem Moment erneut.“

Validierungskriterien

• Drop-Zone hat unterschiedliche Idle-, Hover- und Drag-Over-Zustände.
• Jede Datei in der Warteschlange zeigt Name, Größe und Fortschritt.
• Erfolgs- und Fehlerzustände werden sowohl durch Farbe als auch durch Symbole angezeigt.
• Benutzer können Dateien aus der Warteschlange abbrechen oder entfernen.
• ARIA-Live-Regionen werden für Statusaktualisierungen verwendet.
• Das Layout ist reaktionsschnell und behandelt lange Dateinamen elegant.
• Alle interaktiven Elemente erfüllen das WCAG 2.2 Mindest-Touch-Ziel von 24x24px (44x44px bevorzugt).