250 lines
10 KiB
Markdown
250 lines
10 KiB
Markdown
---
|
||
phase: 19
|
||
slug: template-editor-ui
|
||
status: draft
|
||
shadcn_initialized: false
|
||
preset: none
|
||
created: 2026-04-06
|
||
---
|
||
|
||
# Phase 19 — UI Design Contract
|
||
|
||
> Visual and interaction contract for the template editor UI phase. Generated by gsd-ui-researcher, verified by gsd-ui-checker.
|
||
|
||
---
|
||
|
||
## Design System
|
||
|
||
| Property | Value |
|
||
|----------|-------|
|
||
| Tool | none — manual inline styles + Tailwind utilities |
|
||
| Preset | not applicable |
|
||
| Component library | none (Radix not installed; components are custom) |
|
||
| Icon library | none (text/Unicode symbols used inline, e.g. `+`, `✓`, `×`) |
|
||
| Font (sans) | Geist Sans via `var(--font-sans)` / `var(--font-geist-sans)` |
|
||
| Font (serif/display) | Cormorant Garamond via `var(--font-serif)` — wordmark only |
|
||
|
||
Source: `globals.css`, `PortalNav.tsx`, `layout.tsx`
|
||
|
||
**Note:** `components.json` was not found. The project does not use shadcn. All new components follow the existing inline-style + selective Tailwind pattern established in PreparePanel, ClientsPageClient, and PortalNav.
|
||
|
||
---
|
||
|
||
## Spacing Scale
|
||
|
||
Declared values (multiples of 4 only):
|
||
|
||
| Token | Value | Usage |
|
||
|-------|-------|-------|
|
||
| xs | 4px | Icon gaps, dot indicator margin |
|
||
| sm | 8px | Inline element spacing, button padding vertical |
|
||
| md | 16px | Panel internal padding, form field gaps |
|
||
| lg | 24px | Section spacing within panels, list gaps |
|
||
| xl | 32px | Page-level top margin |
|
||
| 2xl | 48px | Empty-state vertical padding |
|
||
| 3xl | 64px | Nav height (established: PortalNav is 64px) |
|
||
|
||
Exceptions:
|
||
- Role color dot: 8px diameter (not a layout token — cosmetic)
|
||
- Signer/role pill height: 32px (matches PreparePanel signer pill pattern)
|
||
- Right panel (TemplatePanel) width: 280px fixed — matches PreparePanel column width in DocumentPageClient split layout
|
||
- AI Auto-place button and Save button minimum height: 36px (matches existing PreparePanel button height)
|
||
|
||
Source: `PreparePanel.tsx`, `PortalNav.tsx`, `layout.tsx` (2rem = 32px page padding)
|
||
|
||
---
|
||
|
||
## Typography
|
||
|
||
| Role | Size | Weight | Line Height |
|
||
|------|------|--------|-------------|
|
||
| Body | 14px (0.875rem) | 400 | 1.5 |
|
||
| Label / caption | 12px (0.75rem) | 400 | 1.4 |
|
||
| Section heading | 14px (0.875rem) | 600 | 1.3 |
|
||
| Page heading | 24px (1.5rem) | 700 | 1.2 |
|
||
|
||
Source: `ClientsPageClient.tsx` (h1: 1.5rem/700), `PreparePanel.tsx` (h2: font-semibold/text-gray-900, body: 0.875rem/400), `PortalNav.tsx` (links: 0.8125rem/500 uppercase)
|
||
|
||
Weights used: regular (400) and semibold/bold (600/700). No third weight.
|
||
|
||
Letter-spacing exceptions:
|
||
- Nav links: `letter-spacing: 0.08em; text-transform: uppercase` — preserved exactly, no change
|
||
- Wordmark: `letter-spacing: 0.02em` — no change
|
||
|
||
---
|
||
|
||
## Color
|
||
|
||
| Role | Value | Usage |
|
||
|------|-------|-------|
|
||
| Dominant (60%) | `#FAF9F7` (cream) | Page background, panel backgrounds, modal backgrounds |
|
||
| Secondary (30%) | `#F9FAFB` / `#F0EDE8` (cream-mid) | Panel interior fill, list row backgrounds, right panel |
|
||
| Accent (10%) | `#C9A84C` (gold) | Primary CTA buttons only, active nav underline |
|
||
| Navy | `#1B2B4B` | Page headings, nav background, secondary button fill |
|
||
| Destructive | `#DC2626` (red-600) | Delete role action button only |
|
||
|
||
Accent (`#C9A84C`) reserved for:
|
||
- "Save Template" button (primary CTA)
|
||
- "Add Role" button (secondary CTA within TemplatePanel)
|
||
- Active nav link underline (existing pattern, unchanged)
|
||
|
||
Navy (`#1B2B4B`) used for:
|
||
- "AI Auto-place" button fill (matches PreparePanel AI button pattern)
|
||
- Page heading text
|
||
- Wordmark
|
||
|
||
Semantic colors:
|
||
- Success inline: `#059669` (green — "Saved" confirmation inline text, same as PreparePanel "Sent ✓")
|
||
- Error inline: `#DC2626` (red — error messages)
|
||
- Muted text: `#6B7280` (gray-500 — counts, timestamps, placeholder copy)
|
||
- Border default: `#E5E7EB` (gray-200)
|
||
|
||
Source: `globals.css`, `PreparePanel.tsx`, `ClientsPageClient.tsx`, `ConfirmDialog.tsx`
|
||
|
||
---
|
||
|
||
## Component Inventory
|
||
|
||
Components this phase must produce (from CONTEXT.md D-12/D-13):
|
||
|
||
### 1. TemplatePanel (new)
|
||
Right panel, 280px wide, sticky within the editor view.
|
||
|
||
Sections (top to bottom):
|
||
1. **Template name** — editable inline `<input>` (14px, border-bottom-only style when focused, gray-200 border at rest). Displays current name from DB.
|
||
2. **Roles section** — heading "Signers / Roles" (12px uppercase label), list of role pills, "Add role" button.
|
||
3. **Role pill** — colored dot (8px, `background: role.color`) + role label string + rename icon (pencil, text "Edit") + remove button (`×`). Free-form rename via inline edit on click.
|
||
4. **Add role** — text input + "Add" button. Preset suggestions: "Buyer", "Co-Buyer", "Seller", "Co-Seller" as clickable chips below the input.
|
||
5. **AI Auto-place button** — full-width, navy fill (`#1B2B4B`), white text, 36px height. Label: "AI Auto-place Fields". Shows spinner + "Placing…" during loading.
|
||
6. **Save button** — full-width, gold fill (`#C9A84C`), white text, 36px height. Label: "Save Template". Shows "Saving…" during loading. Shows inline "Saved" (green) or error message after.
|
||
|
||
### 2. TemplatePageClient (new)
|
||
State owner. Layout: CSS flexbox row — left: `PdfViewerWrapper` + `FieldPlacer` (flex: 1, min-width: 0), right: `TemplatePanel` (280px, flex-shrink: 0). Gap: 24px. Pattern mirrors `DocumentPageClient`.
|
||
|
||
### 3. Templates list page (new)
|
||
- Page heading: "Templates" (24px/700, navy)
|
||
- Subtitle: "{N} template{s}" (14px/400, gray-500)
|
||
- "New Template" button: top-right, gold fill (primary CTA). Label: "+ New Template"
|
||
- Table/list rows: each row shows template name (14px/600, navy), form name (14px/400, gray-500), field count ("N fields", 12px/400, gray-500), last updated (12px/400, gray-500). Click row → navigate to editor.
|
||
- Row hover: `background: #F0EDE8` (cream-mid), cursor pointer.
|
||
|
||
### 4. PortalNav update
|
||
Add "Templates" link between "Clients" and "Profile" in `navLinks` array. No visual change — same style as existing links.
|
||
|
||
### 5. FieldPlacer update (non-breaking)
|
||
Add optional `onPersist?: (fields: SignatureFieldData[]) => Promise<void> | void` prop. When provided, replaces the 4 internal `persistFields(docId, fields)` call sites. Existing callers unaffected.
|
||
|
||
---
|
||
|
||
## Interaction States
|
||
|
||
### AI Auto-place button
|
||
| State | Visual |
|
||
|-------|--------|
|
||
| Idle | Navy fill, "AI Auto-place Fields", full opacity |
|
||
| Loading | Navy fill, "Placing…" + spinner (CSS border-radius spin), disabled |
|
||
| Success | Button returns to idle; FieldPlacer reloads via key increment |
|
||
| Error | Inline error message below button in red-600 text (14px), button returns to idle |
|
||
|
||
### Save button
|
||
| State | Visual |
|
||
|-------|--------|
|
||
| Idle | Gold fill, "Save Template", full opacity |
|
||
| Loading | Gold fill at 0.7 opacity, "Saving…", disabled |
|
||
| Success | Inline "Saved" text in green (#059669) below button, fades after 3s |
|
||
| Error | Inline error in red below button |
|
||
|
||
### Role pill inline rename
|
||
- Click role label → label becomes a text input (same font, border-bottom style)
|
||
- Enter or blur → commits rename, calls PATCH /api/templates/[id] with updated `signatureFields` role strings
|
||
- Escape → cancels rename, reverts to original label
|
||
|
||
### Remove role
|
||
- Click `×` on role pill
|
||
- If no fields are assigned to that role: remove immediately
|
||
- If fields are assigned to that role: show ConfirmDialog — "Remove role?" / "Removing 'Buyer' will unassign {N} field(s). This cannot be undone." / Confirm: "Remove Role" (red-600), Cancel: "Cancel"
|
||
|
||
### New Template modal (from list page)
|
||
- Reuses AddDocumentModal pattern: overlay, white rounded card, form fields.
|
||
- Fields: "Template name" (text input), "Select form" (PDF form picker from library).
|
||
- CTA: "Create Template" (gold fill). On success: navigate to `/portal/templates/[id]`.
|
||
|
||
---
|
||
|
||
## Layout
|
||
|
||
### Template editor page (`/portal/templates/[id]`)
|
||
```
|
||
[PortalNav — 64px sticky top]
|
||
[main — max-width 1200px, margin: 0 auto, padding: 32px]
|
||
[page header — flex row]
|
||
[h1 "Edit Template: {name}"] [field count badge "{N} fields placed" — optional, muted]
|
||
[editor body — flex row, gap: 24px]
|
||
[left: PdfViewerWrapper + FieldPlacer — flex:1]
|
||
[right: TemplatePanel — width: 280px, flex-shrink: 0]
|
||
```
|
||
|
||
### Templates list page (`/portal/templates`)
|
||
```
|
||
[PortalNav — 64px sticky top]
|
||
[main — max-width 1200px, margin: 0 auto, padding: 32px]
|
||
[page header — flex row space-between]
|
||
[h1 "Templates"] [subtitle "{N} templates"] [CTA "+ New Template"]
|
||
[list — flex column, gap: 8px]
|
||
[template row × N]
|
||
```
|
||
|
||
---
|
||
|
||
## Copywriting Contract
|
||
|
||
| Element | Copy |
|
||
|---------|------|
|
||
| Primary CTA (list page) | "+ New Template" |
|
||
| Primary CTA (editor) | "Save Template" |
|
||
| Secondary CTA (editor) | "AI Auto-place Fields" |
|
||
| Nav link | "Templates" |
|
||
| Page heading (list) | "Templates" |
|
||
| Page heading (editor) | "Edit Template: {name}" |
|
||
| Empty state heading (list) | "No templates yet" |
|
||
| Empty state body (list) | "Create a template to reuse field placements across documents." |
|
||
| Empty state CTA (list) | "+ Create your first template" |
|
||
| Error — AI auto-place | "AI placement failed. Check that the form PDF is accessible and try again." |
|
||
| Error — save | "Save failed. Please try again." |
|
||
| Loading — AI | "Placing…" |
|
||
| Loading — save | "Saving…" |
|
||
| Success — save | "Saved" |
|
||
| Panel section label — roles | "Signers / Roles" |
|
||
| Role add placeholder | "Role label (e.g. Buyer)" |
|
||
| Role remove confirm title | "Remove role?" |
|
||
| Role remove confirm body | "Removing '{role}' will unassign {N} field(s). This cannot be undone." |
|
||
| Role remove confirm CTA | "Remove Role" |
|
||
| Role remove cancel | "Cancel" |
|
||
| Field count badge | "{N} field{s} placed" |
|
||
|
||
Source: CONTEXT.md decisions D-04, D-05, D-12, D-13; modeled on PreparePanel copy patterns.
|
||
|
||
---
|
||
|
||
## Registry Safety
|
||
|
||
| Registry | Blocks Used | Safety Gate |
|
||
|----------|-------------|-------------|
|
||
| shadcn official | none — shadcn not installed | not applicable |
|
||
| Third-party | none declared | not applicable |
|
||
|
||
No third-party registry blocks in scope for this phase.
|
||
|
||
---
|
||
|
||
## 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
|