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

docs(14.1): create phase plan — cloud/local file parity hardening

Browse Source 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
curo1305
2026-06-26 21:13:14 +02:00
co-authored by Claude Sonnet 4.6
parent 4873a22f9b
commit f50cce61cb
8 changed files with 1002 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.planning/phases/14.1-cloud-local-file-parity-hardening/14.1-UI-SPEC.md
+27 -23
View File
@@ -1,10 +1,11 @@
---
phase: 14.1
slug: cloud-local-file-parity-hardening
status: draft
status: approved
shadcn_initialized: false
preset: none
created: 2026-06-26
reviewed_at: 2026-06-26T18:51:13Z
---
# Phase 14.1 — UI Design Contract
@@ -39,7 +40,7 @@ Declared values (must be multiples of 4):
| 2xl | 48px | Major section separation |
| 3xl | 64px | Reserved for full-page spacing only |
Exceptions: `36px` minimum dense icon-button targets inside `StorageBrowser.vue` rows; `44px` minimum for modal and confirmation actions; sticky browser headers keep `12px` vertical padding with `16px` mobile and `24px` desktop horizontal padding.
Dense row icon buttons use `32px` targets inside `StorageBrowser.vue` rows. Sticky browser headers use `16px` vertical padding with `16px` mobile and `24px` desktop horizontal padding. Modal, footer, confirmation, and primary actions use `48px` minimum targets.
---
@@ -73,9 +74,9 @@ Warning and stale states use the existing amber family (`amber-50/200/500/800`),
| Element | Copy |
|---------|------|
| Primary CTA | `Analyze file` when no analysis exists; otherwise the first content action is `Preview` or `Open` and analysis becomes `Re-analyze` |
| Primary CTA | `Analyze file` when no analysis exists; otherwise the first content action is `Preview file` or `Open file` and analysis becomes `Re-analyze` |
| Empty state heading | `No analysis yet` |
| Empty state body | `Analyze this file to extract text and topics.` Follow with a subtle source note for cloud files: `Preview, download, and analysis still run through DocuVault.` |
| Empty state body | `Analyze this file to extract text and topics.` Follow with a subtle source note for cloud files: `Preview file, download, and analysis still run through DocuVault.` |
| Error state | `This file could not be fully analyzed.` Follow with the next step: `Retry analysis or re-analyze to refresh the result.` |
| Destructive confirmation | `Re-analyze this file? Existing extracted text and topics stay visible until the new analysis finishes.` |
@@ -109,7 +110,7 @@ Visible copy rule: user-facing text must say `Re-analyze` everywhere. `Re-classi
2. Cloud rows open a dedicated detail route, named `cloud-file-detail` or an equivalent explicit named route under `/cloud/:connectionId/...`.
3. Cloud route params use `connectionId` plus opaque provider item identity. Vue Router handles encoding; frontend code must not split or infer structure from provider IDs.
4. Clicking a cloud row opens detail first. It does not auto-preview and does not auto-download.
5. Preview/Open and Download are explicit actions from the detail header and any mirrored row action slots.
5. `Preview file` / `Open file` and Download are explicit actions from the detail header and any mirrored row action slots.
---
@@ -139,6 +140,8 @@ The shared detail surface uses this section order for both local and cloud files
5. Extracted text section
6. Secondary controls and inline error/help copy
The filename plus primary action cluster is the first visual anchor on detail screens.
Header rules:
- Display title uses `24px` semibold with wrapping allowed for long filenames.
@@ -149,7 +152,7 @@ Header rules:
Card rules:
- Detail sections stay white with `border-gray-200` and `rounded-xl`.
- Internal section padding is `20-24px`.
- Internal section padding is `24px`.
- Section headings use `18px` semibold for top-level detail sections and `14px` semibold for compact labels.
---
@@ -169,10 +172,10 @@ Card rules:
## Preview, Download, And Unsupported-State Contract
1. Preview and Download stay adjacent in the detail header action cluster.
2. If preview is supported, `Preview` or `Open` is the first content action.
3. If preview is unsupported but download is supported, Preview remains visible but disabled, with helper copy `Preview unavailable` plus the backend reason. Download remains active.
4. Preview never triggers an automatic download.
1. `Preview file` and Download stay adjacent in the detail header action cluster; when inline opening is the correct capability, the label becomes `Open file`.
2. If preview is supported, `Preview file` or `Open file` is the first content action.
3. If preview is unsupported but download is supported, `Preview file` remains visible but disabled, with helper copy `Preview unavailable` plus the backend reason. Download remains active.
4. `Preview file` never triggers an automatic download.
5. No cloud UI may expose provider URLs, provider hostnames, raw tokens, or cache object keys.
6. Any content action copy that differs between local and cloud must be justified by ownership or capability, not by layout convenience.
@@ -190,11 +193,12 @@ Card rules:
## Accessibility And Feedback Contract
1. Dense row icon buttons may use `36px` targets; modal, footer, and primary actions use `44px` minimum targets.
2. Disabled actions must remain keyboard-focusable only when they can surface an explanatory reason; otherwise they are non-interactive and accompanied by inline explanatory text.
3. Status banners use semantic color plus icon plus text; color alone is insufficient.
4. Focus indicators use the indigo ring pattern already present in the app.
5. Long filenames, provider locations, and error reasons must wrap instead of truncating inside the detail header and status areas.
1. Dense row icon buttons use `32px` targets; modal, footer, and primary actions use `48px` minimum targets.
2. Dense icon-only row actions require a tooltip and a visible text fallback anywhere hover is unavailable or the action collapses into a menu.
3. Disabled actions must remain keyboard-focusable only when they can surface an explanatory reason; otherwise they are non-interactive and accompanied by inline explanatory text.
4. Status banners use semantic color plus icon plus text; color alone is insufficient.
5. Focus indicators use the indigo ring pattern already present in the app.
6. Long filenames, provider locations, and error reasons must wrap instead of truncating inside the detail header and status areas.
---
@@ -205,7 +209,7 @@ The implementation must be testable against these UI outcomes:
- Paired local/cloud browser assertions verify identical row title structure, topic placement, status placement, and analysis-action slots.
- Paired local/cloud detail assertions verify identical section order, action order, and stale/partial/failed rendering rules.
- Cloud row click opens detail instead of immediate preview/download.
- Unsupported preview keeps Download active and never auto-downloads from the Preview trigger.
- Unsupported preview keeps Download active and never auto-downloads from the `Preview file` trigger.
- No rendered output or API-fed UI state leaks provider URLs, credentials, or cache object keys.
- Visible UI contains `Re-analyze` and no surviving `Re-classify` copy.
@@ -213,11 +217,11 @@ The implementation must be testable against these UI outcomes:
## 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
- [x] Dimension 1 Copywriting: PASS
- [x] Dimension 2 Visuals: PASS
- [x] Dimension 3 Color: PASS
- [x] Dimension 4 Typography: PASS
- [x] Dimension 5 Spacing: PASS
- [x] Dimension 6 Registry Safety: PASS
**Approval:** pending
**Approval:** approved