curo/kite
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(03): UI design contract for document migration and quota UI

Browse Source 
Phase 3 UI-SPEC covering two-step presigned upload progress bar,
quota usage bar (amber 80% / red 95%), and 413 quota rejection
inline error block — all inheriting Phase 2 design system tokens.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
curo1305
2026-05-23 10:16:28 +02:00
parent f261c1a53b
commit 5905642a31
1 changed files with 350 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.planning/phases/03-document-migration-multi-user-isolation/03-UI-SPEC.md
+350
View File
@@ -0,0 +1,350 @@
---
phase: 3
slug: document-migration-multi-user-isolation
status: draft
shadcn_initialized: false
preset: none
created: 2026-05-23
---
# Phase 3 — UI Design Contract
> Visual and interaction contract for Phase 3: Document Migration & Multi-User Isolation.
> Generated by gsd-ui-researcher, verified by gsd-ui-checker.
---
## Design System
| Property | Value |
|----------|-------|
| Tool | none — raw Tailwind CSS v3 |
| Preset | not applicable |
| Component library | none |
| Icon library | Inline SVG heroicons (stroke, no fill) — matches existing AppSidebar, DropZone, and UploadProgress patterns |
| Font | System font stack (Tailwind default: ui-sans-serif, system-ui, sans-serif) |
**Source:** Inherited from Phase 2 UI-SPEC (approved 2026-05-22). No design system changes in Phase 3. `tailwind.config.js` has empty `theme.extend` — no custom tokens.
---
## Spacing Scale
Identical to Phase 2 — inherited, not re-specified.
| Token | Value | Usage |
|-------|-------|-------|
| xs | 4px | Icon-to-label gaps, badge padding, progress step gaps |
| sm | 8px | Compact inline spacing, quota bar label gap |
| md | 16px | Default field padding, card internal padding |
| lg | 24px | Section vertical gap |
| xl | 32px | Upload card top margin |
| 2xl | 48px | Page vertical centering padding |
| 3xl | 64px | Page-level clearance |
Exceptions:
- Upload progress bar track height: 8px (`h-2`). Justification: 4px (xs) is too narrow to show color transitions clearly at small viewport widths; 8px is the established browser progress-bar idiom and remains within the scale.
- Quota bar track height: 8px (`h-2`). Same justification as upload progress bar.
- Quota bar touch/click area (sidebar widget, not interactive): no min-height required — display-only element.
**Source:** Phase 2 UI-SPEC approved spacing scale. Phase 3 adds no new interactive controls that require new spacing exceptions.
---
## Typography
Identical to Phase 2 — inherited, not re-specified.
| Role | Size | Weight | Line Height | Tailwind Class |
|------|------|--------|-------------|----------------|
| Body | 14px | 400 (regular) | 1.5 | `text-sm` |
| Label | 14px | 600 (semibold) | 1.4 | `text-sm font-semibold` |
| Heading | 20px | 600 (semibold) | 1.3 | `text-xl font-semibold` |
| Display | 24px | 600 (semibold) | 1.2 | `text-2xl font-semibold` |
Font weight scale: exactly 2 weights — regular (400) and semibold (600). Do not introduce `font-medium` (500) or `font-bold` (700). Do not use `font-medium` that already appears in `.nav-link` scoped styles — that is a pre-existing pattern in AppSidebar and must not be propagated to new components.
**New in Phase 3:**
- Quota bar label: `text-xs text-gray-500` (body at reduced size — acceptable exception for sidebar metadata density).
- Upload step label (beneath progress bar): `text-xs text-gray-400` — same pattern as existing `UploadProgress.vue` status lines.
- Error detail lines in quota rejection: `text-xs text-red-600` — matches Phase 2 inline field error style.
**Source:** Phase 2 UI-SPEC. `UploadProgress.vue` uses `text-xs text-gray-400` for status lines — retained for consistency.
---
## Color
Identical to Phase 2 palette — no new colors introduced. Phase 3 adds two state-specific usages within the existing amber and red semantic tokens.
| Role | Value | Tailwind Token | Usage |
|------|-------|----------------|-------|
| Dominant (60%) | #f9fafb | `bg-gray-50` | Page background |
| Secondary (30%) | #ffffff | `bg-white` | Cards, upload progress rows, sidebar |
| Accent (10%) | #4f46e5 | `indigo-600` / `indigo-700` | Primary CTA buttons only, active nav link text, brand logo text |
| Accent subtle | #eef2ff | `indigo-50` | Active nav link background; upload progress bar fill (in-progress step) |
| Destructive | #dc2626 | `red-600` | Quota bar at ≥ 95% fill; quota rejection error banner border/text |
| Warning | #d97706 | `amber-600` | Quota bar at ≥ 80% fill (below 95%); quota warning text |
| Success | #16a34a | `green-600` | Upload complete checkmark icon — existing UploadProgress pattern |
| Neutral border | #e5e7eb | `gray-200` | Card borders, progress row borders, quota bar track background |
| Muted text | #9ca3af | `gray-400` | Quota bar label secondary text, upload step sub-labels |
**Source:** Phase 2 UI-SPEC. CONTEXT.md STORE-04 locks amber at 80%, red at 95%. CONTEXT.md D-07 specifies HTTP 413 response — maps to `red-600` error treatment.
Accent reserved for: primary CTA buttons, active sidebar nav link text, DocuVault brand/logo text, in-progress upload step indicator fill (`indigo-50` track fill).
Accent is NOT used on: quota bar fills, error banners, or secondary link text.
### Quota Bar Color Logic (State Machine)
| Condition | Bar fill color | Label color |
|-----------|---------------|-------------|
| `usage < 80%` | `bg-indigo-500` | `text-gray-500` |
| `80% ≤ usage < 95%` | `bg-amber-500` | `text-amber-600` |
| `usage ≥ 95%` | `bg-red-500` | `text-red-600` |
Bar track (background): `bg-gray-200` always.
Bar fill width: `style="width: {percent}%"` clamped to `max-w-full`.
---
## Upload Flow — Interaction Contract
### Overview
The two-step presigned upload (CONTEXT.md D-05) is invisible to the user as a multi-step operation. The user sees a single continuous upload experience from file selection to completion.
### Step Mapping to UI States
| Internal Step | User-visible state |
|---------------|--------------------|
| Step 1: `POST /api/documents/upload-url` | "Preparing upload…" — spinner active, 0% progress |
| Step 2: `PUT {presigned_url}` (browser → MinIO) | "Uploading…" — progress bar advances 5% → 90% using XHR `progress` event |
| Step 3: `POST /api/documents/{id}/confirm` | "Processing…" — progress bar at 95%, spinner resumes |
| Celery enqueued (confirm returns 200) | "Done — classifying…" — progress bar completes to 100%, green checkmark |
| Error at any step | Error state (see Error States below) |
### Progress Bar Visual Contract
The progress bar is an addition to the existing `UploadProgress.vue` component row.
Each upload row in `UploadProgress.vue` gains a progress bar between the filename and the status line:
```
[ filename.pdf (spinner/checkmark/error icon) ]
[ ████████████░░░░░░░░░░ 62% ]
[ Uploading… ]
```
Bar specifications:
- Track: `w-full h-2 bg-gray-100 rounded-full mt-1`
- Fill: `h-2 rounded-full transition-all duration-300` + color class from state
- In-progress fill color: `bg-indigo-500`
- Complete fill color: `bg-green-500`
- Error fill color: `bg-red-400` (stops at last % value, does not reset to 0)
- Percentage label: `text-xs text-gray-400 text-right mt-0.5` — shown during upload, hidden after completion
### Upload Progress Values by Step
| Step | Progress value | Visual |
|------|---------------|--------|
| Awaiting upload URL | 0% | Bar at 0, status "Preparing upload…" |
| Upload URL received | 5% | Bar jumps to 5% |
| XHR progress events | 5% → 90% (linear from XHR `loaded/total`) | Bar animates smoothly |
| Confirm call in flight | 92% | Bar at 92%, status "Processing…" |
| Confirm returned 200 | 100% | Bar fills green, status "Done — classifying…" |
The 5%–90% range is reserved for the XHR PUT. The remaining 10% (90%–100%) covers confirm + classification enqueue. This prevents the bar appearing "stuck" at 100% waiting for the confirm call.
### CORS and MinIO PUT
The browser PUTs directly to MinIO over a presigned URL (cross-origin). This is transparent to the user. If the PUT fails due to a network error or CORS rejection, treat it as a generic upload error (see Error States). Do not surface "CORS" in any user-facing copy.
---
## Quota Usage Bar — Sidebar Contract
### Placement in AppSidebar.vue
Insert the quota bar between the topics nav section (`.flex-1 nav`) and the bottom settings/admin/identity footer (`.px-3.py-4.border-t`).
```
[ Topics nav section ]
[ ────────────────────── ] ← existing border-t border-gray-100
[ Quota bar widget ] ← NEW: Phase 3
[ ────────────────────── ] ← existing border-t border-gray-100
[ Admin / Settings / Footer ]
```
### Quota Bar Widget Structure
```html
<div class="px-4 py-3 border-t border-gray-100">
<!-- Label row -->
<div class="flex items-center justify-between mb-1.5">
<span class="text-xs font-semibold text-gray-500">Storage</span>
<span class="text-xs {label-color}">X MB of Y MB</span>
</div>
<!-- Bar track -->
<div class="w-full h-2 bg-gray-200 rounded-full">
<div class="h-2 rounded-full transition-all duration-500 {fill-color}" style="width: Z%"></div>
</div>
</div>
```
Label format: `"{used} MB of {limit} MB"` — values rounded to 1 decimal place (e.g., "12.3 MB of 100.0 MB"). Do not show bytes or KB — always MB with 1 decimal place.
### Loading and Error States
| State | Display |
|-------|---------|
| Loading (initial fetch) | Skeleton bar: `bg-gray-100 animate-pulse h-2 rounded-full w-full` — no label text |
| Fetch error | Hide widget entirely — fail silently (consistent with AdminQuotasTab pattern of filtering failed quota fetches silently) |
| `used_bytes = 0` | Show bar at 0% with label "0.0 MB of Y MB" — do not hide the widget |
### Data Source
Fetches from `GET /api/me/quota` on sidebar mount. Re-fetches after every successful document upload (confirm step returns 200) and after every document delete. No polling.
Store: quota state lives in `useAuthStore` as `quota: { used_bytes, limit_bytes }` — updated by the documents store after upload/delete. Do not create a separate quota store.
---
## Error States
### Upload Error Types
| HTTP status | Trigger | User-facing copy |
|------------|---------|-----------------|
| 401 | Access token expired mid-upload | Dismiss upload row, show session-expired toast (Phase 2 contract), redirect to `/login` |
| 413 | Quota exceeded at confirm step | Show quota rejection error block (see below) |
| Network error (XHR fail, CORS) | MinIO unreachable or CORS misconfiguration | "Upload failed. Please try again." — row error state |
| 500 | Server error on upload-url or confirm | "Something went wrong. Please try again." — row error state |
| Other 4xx | Unexpected API error | "Upload failed. Please try again." — row error state |
### Quota Rejection Error Block (413)
Displayed inline within the upload progress row, replacing the progress bar and status line. NOT a toast — inline only.
```
[ filename.pdf (error icon red) ]
[ ┌─────────────────────────────────────────────────────┐ ]
[ │ Not enough storage │ ]
[ │ This file (X MB) would exceed your quota. │ ]
[ │ You're using Y MB of Z MB. │ ]
[ │ Manage storage → │ ]
[ └─────────────────────────────────────────────────────┘ ]
```
Error block styles:
- Container: `mt-1 p-3 rounded-lg bg-red-50 border border-red-200`
- Heading: `text-sm font-semibold text-red-700`
- Body lines: `text-xs text-red-600 mt-0.5`
- Link: `text-xs text-red-600 underline hover:text-red-700 font-semibold` — navigates to `/settings` (the existing settings route; storage settings live there in Phase 3 since the dedicated storage page is Phase 4)
Values populated from 413 response body: `{"detail": {"used_bytes": N, "limit_bytes": M, "rejected_bytes": K}}`.
- "This file (X MB)" — `rejected_bytes` converted to MB, 1 decimal place
- "You're using Y MB of Z MB" — `used_bytes` / `limit_bytes` converted to MB, 1 decimal place
### 401 During Upload
When a 401 occurs at any upload step:
1. Mark the upload row as failed with copy "Session expired. Signing you in again…"
2. Fire the session-expired toast (Phase 2 contract: `bg-gray-900 text-white text-sm px-4 py-3 rounded-lg shadow-lg`, 5s auto-dismiss)
3. Redirect to `/login` after 1.5s (gives user time to read the row message)
4. Do NOT retry the upload automatically — the user must sign in and re-upload
---
## Loading States (Phase 3 Additions)
Extends Phase 2 loading state contract.
| Action | Loading indicator | Element state |
|--------|------------------|---------------|
| Upload step 1 (get URL) | Spinner in row icon slot, progress bar at 0% | Row status "Preparing upload…" |
| Upload step 2 (XHR PUT) | Progress bar advancing, spinner removed | Row status "Uploading…" |
| Upload step 3 (confirm) | Progress bar at 92%, spinner in row icon slot resumes | Row status "Processing…" |
| Quota bar initial load | Skeleton pulse bar | No label text |
| Quota refetch after upload | Silent — bar updates on next successful fetch; no spinner shown in sidebar |
Spinner reuse: `AppSpinner.vue` from Phase 2 — `animate-spin rounded-full border-2 border-current border-t-transparent` inheriting color.
---
## Copywriting Contract
Phase 2 copy contract is fully inherited. Phase 3 additions only.
| Element | Copy |
|---------|------|
| Upload step: preparing | "Preparing upload…" |
| Upload step: uploading | "Uploading…" |
| Upload step: processing | "Processing…" |
| Upload step: complete | "Done — classifying…" |
| Upload step: classified | "Done — classified as: {topics}" (matches existing UploadProgress pattern) |
| Upload step: no topics | "Done — no topics assigned" (matches existing UploadProgress pattern) |
| Upload generic error | "Upload failed. Please try again." |
| Upload 401 error | "Session expired. Signing you in again…" |
| Upload quota rejection heading | "Not enough storage" |
| Upload quota rejection body line 1 | "This file ({X} MB) would exceed your quota." |
| Upload quota rejection body line 2 | "You're using {Y} MB of {Z} MB." |
| Upload quota rejection link | "Manage storage →" |
| Quota bar label | "Storage" |
| Quota bar usage display | "{used} MB of {limit} MB" |
| Quota bar loading (aria) | `aria-label="Loading storage usage"` on skeleton element |
| Empty document list | Heading: "No documents yet" / Body: "Upload a file to get started." |
| Document list loading error | "Failed to load documents. Please refresh." |
### Security Copy Rules (Inherited)
- Never confirm or deny whether an email exists
- Generic error messages must not echo PII
- Quota messages display bytes only from the server-authoritative 413 response body — never from client-side file size alone
---
## Component Inventory (New or Modified — Phase 3)
| Component | Path | Change Type | Description |
|-----------|------|-------------|-------------|
| AppSidebar | `src/components/layout/AppSidebar.vue` | Modified | Add QuotaBar widget between topics nav and footer section |
| UploadProgress | `src/components/upload/UploadProgress.vue` | Modified | Add progress bar track + fill per row; add step status strings; add quota rejection error block |
| QuotaBar | `src/components/layout/QuotaBar.vue` | New | Standalone quota bar widget — extracted for testability; used inside AppSidebar |
| documents store | `src/stores/documents.js` | Modified | Replace single `upload()` with three-step flow (upload-url → PUT → confirm); add `uploadProgress` reactive map keyed by filename; dispatch quota refetch after upload/delete |
No new views required. No new layouts required. All Phase 3 UI is additive to existing AppSidebar and UploadProgress components.
---
## Registry Safety
| Registry | Blocks Used | Safety Gate |
|----------|-------------|-------------|
| shadcn official | none | not applicable — shadcn not installed |
| third-party | none | not applicable |
No third-party component registries. All components are handwritten Vue 3 SFC with raw Tailwind CSS.
---
## Accessibility
| Element | Requirement |
|---------|-------------|
| Quota bar | `role="progressbar"` on the fill `<div>`, `aria-valuenow="{percent}"`, `aria-valuemin="0"`, `aria-valuemax="100"`, `aria-label="Storage usage: {used} MB of {limit} MB"` |
| Upload progress bar | `role="progressbar"` on each row's fill `<div>`, `aria-valuenow="{percent}"`, `aria-valuemin="0"`, `aria-valuemax="100"`, `aria-label="Upload progress for {filename}"` |
| Quota rejection error | `role="alert"` on the error container so screen readers announce it immediately |
| Quota bar skeleton | `aria-label="Loading storage usage"` + `aria-busy="true"` |
---
## Checker Sign-Off
- [ ] Dimension 1 Copywriting: PASS
- [ ] Dimension 2 Visuals: PASS
- [ ] Dimension 3 Color: PASS
- [ ] Dimension 4 Typography: PASS
- [ ] Dimension 5 Spacing: PASS
- [ ] Dimension 6 Registry Safety: PASS
**Approval:** pending