Delano Read-Only Viewer UI
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Delano Read-Only Viewer is a localhost-only document reader and navigator designed for inspecting file-backed delivery contracts within the .project/ directory. Its primary purpose is to provide maintainers, operators, and coding agents with a clear, inspectable view of planning, execution, and validation state without requiring external vendor workflows or mutating the underlying source of truth.
The viewer is packaged within the @bvdm/delano npm package and operates as a quiet, "local dossier." It indexes project context, templates, and project-specific artifacts (specs, plans, workstreams, and tasks) to derive relationships and rendered views for local inspection.
Sources: README.md:12-16, README.md:139-145, PRODUCT.md:7-12
Architecture and Components
The Viewer UI follows a decoupled architecture where a local Node.js server acts as the backend for a static web interface. It relies on the project's file-backed structure as its database.
System Flow
The following diagram illustrates the relationship between the CLI command, the local server, and the file-backed contracts.
The viewer indexes the repository and provides a read-only interface for navigating delivery artifacts.
Sources: README.md:143-145, package.json:28
Key Components
| Component | Path / Reference | Description |
|---|---|---|
| Server | .delano/viewer/server.js | Local Node server that handles file indexing and provides APIs. |
| Static Assets | .delano/viewer/public/ | Contains the HTML, CSS, and JSX/JS files for the browser interface. |
| Indexing API | Server-side logic | Derives project outlines, task/workstream relationships, and snippets. |
| Markdown Renderer | UI Component | Displays rendered versions of specs, plans, and tasks while keeping body prose narrow for legibility. |
Sources: README.md:143-148, test/package.test.js:28-36
Design System and Visual Language
The Viewer UI is built on a specific "Creative North Star" titled The Local Dossier. This design philosophy emphasizes a flat hierarchy, warm neutral tones, and the visible provenance of data.
Visual Characteristics
- Tonal Palette: Uses OKLCH tokens. It avoids pure black or pure white, favoring "Document Ground" and "Paper Surface" for a warm, document-like feel.
- Typography: Uses Inter for UI and documentation text, while JetBrains Mono is reserved for paths, timestamps, and metadata to emphasize exact provenance.
- Elevation: Flat by design. Depth is conveyed via 1px hairline borders and tonal surface changes rather than shadows.
- Hierarchy: Open ledger rows are preferred over stacked cards to maintain the dossier aesthetic.
Sources: DESIGN.md:136-150, README.md:46-55, PRODUCT.md:28-31
UI Components and Tokens
| Token Category | Values / Examples | Usage |
|---|---|---|
| Document Ground | oklch(0.985 0.004 85) | Primary application background. |
| Paper Surface | oklch(0.995 0.003 85) | Sidebars, panels, code blocks, and table headers. |
| Ink | oklch(0.21 0.008 80) | Main text and primary button surfaces. |
| Slate Accent | oklch(0.52 0.08 245) | Restricted to selected states and active workflow signals. |
| Status Chips | Success, Warning, Low-signal | Pill-shaped labels with 6px status dots. |
Sources: DESIGN.md:9-25, DESIGN.md:310-316
Data Modeling and Navigation
The viewer interprets the frontmatter of Markdown files to build its navigation tree. This process involves resolving IDs such as WS-A (workstreams) and T-001 (tasks).
Lifecycle Tracking
The viewer tracks the state of projects through hierarchical rollups. Actions performed via the CLI (such as task start or task close) are reflected in the viewer's UI as status transitions.
The state transitions are governed by rules that prevent tasks from progressing if parent lifecycles (Spec/Plan) are still in a "Planned" state.
Sources: src/cli/lib/project-state.js:6-7, test/package.test.js:145-160
Configuration
The viewer behavior can be adjusted via environment variables:
DELANO_VIEWER_PORTorPORT: Defines the listening port (default:3977).target: The directory containing the.projectfolder (defaults to the current working directory).
Sources: README.md:139-141, src/cli/commands/viewer.js (Referenced via src/cli/index.js:52)
Summary
The Delano Read-Only Viewer UI serves as the essential presentation layer for the Delano delivery runtime. By adhering to a "Local Dossier" design language and strictly reading from file-backed contracts, it ensures that project state remains transparent and traceable for both human operators and automated agents. It transforms raw Markdown artifacts into a navigable, visually coherent interface while strictly maintaining a read-only posture to preserve the integrity of the underlying .project source of truth.