Add views-and-ui.md

views-and-ui.md

@@ -0,0 +1,104 @@
+# Non-Linear: Views & UI
+
+## Overview
+
+Non-Linear provides two primary graph views plus a flat fallback. The graph views test the core thesis (top-down decomposition helps people think about projects). The flat view ensures daily workflows aren't compromised.
+
+## View 1: Layered Overview
+
+**Purpose:** See the entire project structure at a glance, organized by abstraction level.
+
+**Layout:** Rows arranged by depth in the decomposition tree. Each row represents one abstraction layer.
+
+```
+Layer 0 (root):     [My SaaS Project]
+                    /        |         \
+Layer 1:     [Auth]      [Billing]    [Dashboard]
+              / \           |          /    \
+Layer 2:  [Login] [SSO]  [Stripe]  [Charts] [Filters]
+            |                         |
+Layer 3:  [OAuth flow]             [Bar chart component]
+```
+
+### Behavior
+
+- **Edges visible:** Parent→child edges are drawn between layers. Lateral links (blocks, relates-to) shown as overlay edges with different styling (dashed, colored by type).
+- **Collapse/expand:** Each node can collapse its subtree to reduce visual noise.
+- **Zoom:** The view supports zoom in/out. At high zoom, nodes show only title. At lower zoom, nodes show title + status + assignee.
+- **Filtering:** Filter by label, status, assignee to highlight relevant subsets. Non-matching nodes are dimmed, not hidden (preserving structural context).
+- **Node coloring:** Status-based coloring by default. Optionally color by label, assignee, or priority.
+
+### What This View Is Good For
+
+- Understanding overall project structure
+- Identifying structural gaps (a component with no tasks beneath it)
+- Seeing where work is concentrated (many in-progress nodes in one subtree)
+- Onboarding new team members to a project
+- Agent overview: "show me the full graph"
+
+## View 2: Focus Widget
+
+**Purpose:** Inspect a single node and its immediate context — parent and direct children.
+
+**Layout:** Selected node in the center. Parent shown above. Children shown below. Lateral links shown as badges or a side panel.
+
+```
+         [Parent: Auth]
+              |
+    ──► [Selected: Login] ◄── blocked by [Stripe integration]
+          /        \
+   [OAuth flow]  [Email/pass form]
+```
+
+### Behavior
+
+- **Navigation:** Click any node to make it the new focus. This enables "walking the tree" up and down.
+- **Detail panel:** The selected node's full detail (description, comments, history, links) is visible in a side or bottom panel.
+- **Quick actions:** Change status, assign, add labels, add child, add link — all from this view.
+- **Lateral links:** Shown as a list/badge on the selected node: "Blocked by: [Stripe integration]", "Relates to: [Dashboard filters]".
+
+### What This View Is Good For
+
+- Daily work: understanding what's above and below your current task
+- Breaking down work: creating children from a component node
+- Reviewing context: what blocks this? what depends on this?
+- Agent focus: "what are the children of Backend API?"
+
+## View 3: Flat List / Board (Fallback)
+
+**Purpose:** Quick triage, standup-style review, batch operations.
+
+**Layout:** Standard list or Kanban board (columns = statuses). No graph structure visible.
+
+### Behavior
+
+- **Sorting:** By status, priority, assignee, updated date, creation date.
+- **Grouping:** By parent node, label, assignee. Grouping by parent gives a lightweight hierarchy without the full graph view.
+- **Bulk actions:** Multi-select to change status, assign, add labels.
+- **Search:** Full-text search across titles and descriptions.
+
+### What This View Is Good For
+
+- Morning triage: "what's in review? what's blocked?"
+- Standup: quick scan of in-progress items
+- Batch operations: close all done items, reassign a set of tasks
+- Users who prefer traditional workflows
+
+## View Switching
+
+Users can switch between views freely. The selected node context is preserved when switching — if you're focused on "Login" in the Focus Widget and switch to Layered Overview, "Login" is highlighted/centered in the graph.
+
+## Entry Experience
+
+### New Project (Clean Start)
+
+1. User creates a project → automatically creates a root node with the project name
+2. User is placed in the Focus Widget on the root node
+3. Prompt to add first children (components/areas of the project)
+4. As children are added, the Layered Overview becomes useful
+
+### Import (v0.2+)
+
+- Import from Linear, Jira, GitHub Issues
+- System infers hierarchy from existing relationships (epics→stories→tasks)
+- User reviews and adjusts the inferred tree before confirming