lllin000_PaperForge/paperforge/plugin/DESIGN.md

PaperForge Plugin Design System

1. Atmosphere & Identity

PaperForge is an Obsidian-native, quiet professional control center: calm when work is healthy, explicit when the user must act, and technical only when support needs evidence. Its signature is progressive clarity — every surface leads with a plain-language outcome, while implementation detail stays out of the reading path.

2. Color

PaperForge inherits the active Obsidian theme. It does not define independent light/dark hex palettes.

Role	Obsidian token	Usage
Primary surface	--background-primary	Page and card background
Secondary surface	--background-secondary	Grouped sections, historical status
Hover surface	--background-modifier-hover	Hovered rows and navigation
Default border	--background-modifier-border	Cards, dividers, inputs
Hover border	--background-modifier-border-hover	Hovered clickable cards
Primary text	--text-normal	Headings and body
Secondary text	--text-muted	Explanations and metadata
Tertiary text	--text-faint	Nonessential timestamps only
Accent	--interactive-accent	Primary action, active navigation, focus
Accent text	--text-on-accent	Text on accent surfaces
Success	--text-success	Ready state only
Warning	--text-warning	Setup Required and Action Required
Error	--text-error	Detection Failed and destructive effects

Rules:

• Color communicates status or interactivity; it is never decorative.
• Not Enabled is neutral, not warning-colored.
• Checking uses muted text plus activity, not a warning color.
• Status color is always paired with text; color is never the only signal.
• Raw RGB or hex values are prohibited. Alpha tints use color-mix() with an Obsidian semantic token.

3. Typography

PaperForge inherits Obsidian font families and UI scale.

Level	Token / value	Weight	Usage
Page heading	--font-ui-large	--font-semibold	Overview, Maintenance, Help
Module heading	18px	--font-semibold	Module Detail title
Section heading	--font-ui-medium	--font-semibold	Module body sections
Body	--font-ui-small	normal	Explanations and configuration summaries
Metadata	12px	normal	Counts, timestamps, secondary facts
Badge	11px	medium	Six-state labels
Diagnostic excerpt	--font-monospace-theme at 12px	normal	Copied or explicitly revealed support data only

Rules:

• User-facing content uses Obsidian’s interface font; technical excerpts alone use monospace.
• Body copy is never smaller than Obsidian’s configured small UI font.
• Headings use sentence case. Uppercase eyebrow labels are removed.
• Error codes and raw commands never serve as headings or explanatory copy.

4. Spacing & Layout

Base unit

All PaperForge spacing is a multiple of 4px.

Token	Value	Usage
space-1	4px	Icon-to-label, compact metadata
space-2	8px	Inline groups and list gaps
space-3	12px	Compact panel padding
space-4	16px	Card padding and section gaps
space-5	20px	Summary panel horizontal padding
space-6	24px	Major section separation
space-8	32px	Page-level separation

Layout

• Settings content uses the host-provided width; PaperForge does not impose a competing page width.
• Overview module cards use two columns above a 620px container width and one column at or below 620px.
• Module Detail uses five visible module tabs above 620px and one native module select at or below 620px.
• Forms and maintenance items become one column at or below 620px.
• Nested vertical scrolling inside Settings is prohibited; long operational tables open in a full-width PaperForge workspace.

5. Components

Control Center Navigation

• Structure: three top-level tabs — Overview, Maintenance, Help.
• States: default, hover, active, focus-visible.
• Accessibility: tab semantics, arrow-key movement, Enter/Space activation, visible focus.
• Rule: Module Detail is contextual and never appears as a top-level tab.

Control Center Summary

• Structure: baseline conclusion, one supporting sentence, maintenance count, last-updated state, global Refresh Status.
• Variants: baseline ready, baseline blocked, refreshing, refresh failed with last-known result.
• Rule: Not Enabled optional capabilities do not lower the baseline conclusion.

Module Card

• Structure: module name, six-state badge, one plain-language sentence, at most one key metric, navigation affordance.
• Interaction: the entire card opens Module Detail; no operation executes from the card.
• States: default, hover, active, focus-visible, refreshing, detection failed.
• Accessibility: one keyboard-focusable target with an accessible name containing module and status.

Module Status Badge

• Variants: Checking, Ready, Not Enabled, Setup Required, Action Required, Detection Failed.
• Rule: badge wording is identical across modules; reason-specific detail belongs in body copy.
• Accessibility: text label is mandatory; status changes use polite live announcements.

Module Detail Shell

• Structure: return navigation, responsive five-module switcher, module title, Module Status, plain-language summary, Contextual Primary Action area, custom module body, Support Diagnostic entry.
• Responsive states: tab list above 620px; native select at or below 620px.
• Navigation memory: persist only top-level destination or selected module; refresh state on reopen.
• Accessibility: restore focus to the source card or maintenance item on return.

Contextual Primary Action

• Structure: one backend-authorized action localized by stable action ID.
• States: absent when Ready, enabled, hover, active, focus-visible, disabled while starting, running in Module Activity, terminal error.
• Rule: multiple competing primary actions and generic action menus are prohibited.

Module Activity

• Structure: task label, bounded current/total progress when known, affected scope, safe Stop when supported.
• Rule: activity is separate from Module Status and does not enter Maintenance until terminal failure.
• Accessibility: role="progressbar" for bounded progress; polite live updates; Stop always remains reachable.

Configuration Summary

• Structure: safe read-only value or configured state, explanation, explicit Change control.
• Edit state: local form with Cancel and Save and Verify.
• Credentials: show configured/not configured only; never repopulate plaintext.
• Error state: keep the verified saved value while explaining why the draft failed validation.

User-visible Problem

• Structure: what happened, what is and is not affected, one next step, Copy Diagnostic Information.
• Rule: raw stderr, reason codes, paths, and exception text are excluded from the user explanation.
• Accessibility: error heading receives focus after a failed foreground action; copied state is announced.

Maintenance Item

• Structure: owning module, User-visible Problem, affected scope, one Maintenance Action.
• Eligibility: only enabled-module blockers, failed requested tasks, unusable outputs, or material data risk.
• Excluded: optional modules never enabled, optimization suggestions, internal OCR quality signals, stale cache alone.
• Interaction: safe retry may run in place; configuration, scoped, batch, or destructive work navigates with context.

Impact Confirmation

• Structure: affected count/scope, replaced derived outputs, preserved sources and user data, interruptibility, Cancel, concrete action verb.
• Rule: generic “Are you sure?” and typed confirmation for regenerable artifacts are prohibited.
• Accessibility: focus trap, Escape cancellation, initial focus on Cancel, restore focus to invoker.

Setup Journey

• Structure: four dynamic stages — Foundation, Library, selected Optional Capabilities, review and begin.
• States: checking, ready to continue, validation failed, operation running, optional capability skipped, complete.
• Rule: Setup Completion never reverses automatically because of later health failures.

6. Motion & Interaction

Type	Duration	Easing	Usage
Micro	120ms	ease-out	Hover, press, focus surface response
Standard	180ms	ease-in-out	Disclosure and module-body replacement

Rules:

• Motion is subordinate to Obsidian and limited to opacity and transform.
• Progress uses transform-based fill where practical.
• No entrance choreography, decorative animation, or layout-property animation.
• prefers-reduced-motion: reduce disables nonessential transitions.
• A visible hover, active, and focus-visible state is required for every interactive element.

7. Depth & Surface

Strategy: borders-only. PaperForge uses Obsidian surfaces and borders, without decorative shadows.

Surface	Treatment
Page	--background-primary, no border
Clickable card	primary surface, 1px default border, host radius
Grouped section	secondary surface or a top divider, not a nested card stack
Status tint	semantic text color mixed at low opacity with transparency
Modal	Obsidian-owned modal surface and elevation

Rules:

• Avoid cards inside cards.
• Use spacing before adding a divider; use a divider before adding another container.
• PaperForge does not override Obsidian modal shadows or global radii.
• Current “Vercel-inspired” styling, inline CSS duplication, raw emoji warning icons, overview action buttons, and permanently visible technical diagnostics are migration targets, not accepted primitives.