Add User Guide section with 11 articles derived from OpenSpec specs

New docs/user-guide/ section covering: canvas navigation, selection & manipulation, drawing shapes, text editing, pen tool, layers & pages, context menu, exporting, auto-layout, components, and variables. Each article includes Mac+Win/Linux shortcuts tables, cross-platform note, cross-links between related articles, and consistent structure. VitePress sidebar updated with User Guide as first group (12 entries).
2026-03-01 13:02:47 +03:00 · 2026-03-01 13:02:47 +03:00 · de048b4d21
parent 15abce330f
commit de048b4d21
21 changed files with 1237 additions and 2 deletions
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@ -20,12 +20,30 @@ export default defineConfig({
    },

    nav: [
+      { text: 'User Guide', link: '/user-guide/' },
      { text: 'Guide', link: '/guide/getting-started' },
      { text: 'Reference', link: '/reference/keyboard-shortcuts' },
      { text: 'Development', link: '/development/contributing' },
    ],

    sidebar: [
+      {
+        text: 'User Guide',
+        items: [
+          { text: 'Overview', link: '/user-guide/' },
+          { text: 'Canvas Navigation', link: '/user-guide/canvas-navigation' },
+          { text: 'Selection & Manipulation', link: '/user-guide/selection-and-manipulation' },
+          { text: 'Drawing Shapes', link: '/user-guide/drawing-shapes' },
+          { text: 'Text Editing', link: '/user-guide/text-editing' },
+          { text: 'Pen Tool', link: '/user-guide/pen-tool' },
+          { text: 'Layers & Pages', link: '/user-guide/layers-and-pages' },
+          { text: 'Context Menu', link: '/user-guide/context-menu' },
+          { text: 'Exporting', link: '/user-guide/exporting' },
+          { text: 'Auto Layout', link: '/user-guide/auto-layout' },
+          { text: 'Components', link: '/user-guide/components' },
+          { text: 'Variables', link: '/user-guide/variables' },
+        ],
+      },
      {
        text: 'Guide',
        items: [
--- a/docs/user-guide/auto-layout.md
+++ b/docs/user-guide/auto-layout.md
@ -0,0 +1,87 @@
+---
+title: Auto Layout
+description: Flexbox-based auto layout in OpenPencil — direction, gap, padding, alignment, and child sizing.
+---
+
+# Auto Layout
+
+Auto layout uses Yoga (flexbox engine) to position children automatically within a frame. It handles direction, spacing, alignment, and responsive sizing.
+
+::: tip Cross-platform shortcuts
+⌘ = Ctrl, ⌥ = Alt on Windows and Linux.
+:::
+
+## Enabling Auto Layout
+
+- Select a frame and press **⇧ A** (Shift + A) to toggle auto layout on or off
+- Select loose nodes (without a parent frame) and press **⇧ A** to wrap them in a new auto-layout frame
+
+When wrapping a selection, nodes are sorted by visual position: left-to-right for horizontal layout, top-to-bottom for vertical.
+
+## Layout Direction
+
+Choose how children are arranged:
+
+- **Horizontal** — children flow left to right
+- **Vertical** — children flow top to bottom
+- **Wrap** — children wrap to the next row/column when they run out of space
+
+## Spacing
+
+### Gap
+
+The space between adjacent children. Set a single value that applies between all children.
+
+### Padding
+
+The space between the frame edge and its children. Set a uniform value for all sides, or expand to set each side independently (top, right, bottom, left).
+
+## Alignment
+
+### Justify (main axis)
+
+Controls how children are distributed along the layout direction:
+
+- **Start** — children pack to the beginning
+- **Center** — children are centered
+- **End** — children pack to the end
+- **Space between** — children spread with equal space between them
+
+### Align (cross axis)
+
+Controls how children are positioned perpendicular to the layout direction:
+
+- **Start** — children align to the start
+- **Center** — children are centered
+- **End** — children align to the end
+- **Stretch** — children stretch to fill the cross axis
+
+## Child Sizing
+
+Each child in an auto-layout frame can have its own sizing mode:
+
+- **Fixed** — uses the child's explicit width/height
+- **Fill** — stretches to fill available space in the parent
+- **Hug** — shrinks to fit the child's content
+
+## Drag Reordering
+
+Within an auto-layout frame, drag a child to reorder it among its siblings. A visual insertion indicator shows where the child will be dropped.
+
+## Properties Panel
+
+When an auto-layout frame is selected, the Layout section in the properties panel shows all auto-layout controls: direction, gap, padding, justify, and align.
+
+## Keyboard Shortcuts
+
+| Action | Mac | Windows / Linux |
+|--------|-----|-----------------|
+| Toggle auto layout | ⇧ A | Shift + A |
+
+## Tips
+
+- Auto layout recomputes immediately after creation, so the selection bounds update right away.
+- Nest auto-layout frames for complex responsive layouts (e.g., a vertical frame containing horizontal rows).
+- Use "Fill" sizing to make a child take up remaining space, like a flex-grow: 1 in CSS.
+- See [Drawing Shapes](./drawing-shapes) for creating the frames that auto layout applies to.
+- See [Components](./components) for using auto layout within reusable components.
--- a/docs/user-guide/canvas-navigation.md
+++ b/docs/user-guide/canvas-navigation.md
@ -0,0 +1,50 @@
+---
+title: Canvas Navigation
+description: Panning, zooming, and the hand tool in OpenPencil.
+---
+
+# Canvas Navigation
+
+The canvas is your infinite workspace. You can pan and zoom freely to navigate your design.
+
+::: tip Cross-platform shortcuts
+⌘ = Ctrl, ⌥ = Alt on Windows and Linux.
+:::
+
+## Panning
+
+Move the visible area of the canvas without affecting any objects.
+
+- **Space + drag** — hold Space and drag anywhere on the canvas
+- **Middle mouse drag** — press and drag the middle mouse button
+- **Two-finger trackpad** — swipe with two fingers on a trackpad
+
+## Hand Tool
+
+Press **H** to activate the hand tool for continuous panning. Any drag on the canvas pans the viewport without needing to hold Space. Switch to another tool (e.g., **V** for Select) to deactivate.
+
+## Zooming
+
+Zoom in and out centered on your cursor position.
+
+- **Ctrl + scroll** (or **⌘ + scroll** on Mac) — scroll up to zoom in, scroll down to zoom out
+- **Pinch gesture** — pinch on a trackpad to zoom in/out
+- **Keyboard shortcuts** — see table below
+
+Pinch-to-zoom on UI panels (layers, properties) is prevented so it doesn't accidentally change the browser zoom level.
+
+## Keyboard Shortcuts
+
+| Action | Mac | Windows / Linux |
+|--------|-----|-----------------|
+| Pan | Space + drag | Space + drag |
+| Hand tool | H | H |
+| Zoom in | ⌘ + | Ctrl + + |
+| Zoom out | ⌘ - | Ctrl + - |
+| Zoom to 100% | ⌘ 0 | Ctrl + 0 |
+
+## Tips
+
+- Zooming always targets the cursor position, so point at what you want to see closer.
+- The hand tool is useful when you need to pan frequently — it stays active until you switch tools.
+- See [Selection & Manipulation](./selection-and-manipulation) for how to work with objects on the canvas.
--- a/docs/user-guide/components.md
+++ b/docs/user-guide/components.md
@ -0,0 +1,91 @@
+---
+title: Components
+description: Creating reusable components, instances, component sets, overrides, and live sync in OpenPencil.
+---
+
+# Components
+
+Components are reusable design elements. Edit the main component and all its instances update automatically.
+
+::: tip Cross-platform shortcuts
+⌘ = Ctrl, ⌥ = Alt on Windows and Linux.
+:::
+
+## Creating a Component
+
+Select a frame or group and press **⌥ ⌘ K** (Ctrl + Alt + K). The node converts to a COMPONENT type in place.
+
+If you select multiple nodes, they're wrapped in a new component positioned at their bounding box.
+
+Components display a purple label with a diamond icon above them.
+
+## Component Sets
+
+Select two or more components and press **⇧ ⌘ K** (Shift + Ctrl + K) to combine them into a component set — a container with a dashed purple border and 40 px padding around its children. Component sets are useful for grouping variants (e.g., button states).
+
+## Creating Instances
+
+Right-click a component and select **Create instance** from the context menu. The instance appears 40 px to the right of the source component, visually identical.
+
+Instance creation is available only through the context menu — there's no toolbar button.
+
+## Detaching an Instance
+
+Select an instance and press **⌥ ⌘ B** (Ctrl + Alt + B) to detach it. The instance becomes a regular frame with no link to the original component. All overrides are baked in.
+
+## Go to Main Component
+
+Right-click an instance and select **Go to main component**. The editor navigates to and selects the main component, switching pages if needed.
+
+## Live Sync
+
+When you edit a component, all its instances update automatically. Synced properties include:
+
+- Width and height
+- Fills, strokes, and effects
+- Opacity and corner radii
+- Layout properties (auto layout settings)
+- Clips content setting
+
+Sync triggers automatically after node updates, moves, and resizes within a component.
+
+## Overrides
+
+Instances can override specific properties without breaking the sync link. When a property is overridden on an instance, that property is skipped during sync — other properties continue to update from the main component.
+
+### Overridable Properties
+
+Child-level overrides support: name, text, fontSize, fontWeight, fontFamily, plus all visual and layout properties (fills, strokes, effects, opacity, corner radii, size).
+
+Override keys use the format `childId:propertyName` in the instance's overrides record.
+
+### New Children
+
+When you add a child to a component, all existing instances gain a cloned copy automatically. Child order in instances always matches the component.
+
+## Hit Testing
+
+Components and instances are opaque containers — clicking on a child selects the component itself, not the child. **Double-click** to enter the component and select children inside it.
+
+## Visual Treatment
+
+| Element | Appearance |
+|---------|------------|
+| Component label | Purple (#9747ff) with diamond icon, always visible |
+| Instance label | Purple (#9747ff) with diamond icon, always visible |
+| Component set border | Dashed purple (6 px dash, 4 px gap, 1.5 px width) |
+
+## Keyboard Shortcuts
+
+| Action | Mac | Windows / Linux |
+|--------|-----|-----------------|
+| Create component | ⌥ ⌘ K | Ctrl + Alt + K |
+| Create component set | ⇧ ⌘ K | Shift + Ctrl + K |
+| Detach instance | ⌥ ⌘ B | Ctrl + Alt + B |
+
+## Tips
+
+- Editing text inside an instance creates an override — the text won't be overwritten when the component changes.
+- Use component sets to organize variants (e.g., Primary/Secondary/Disabled button states).
+- Double-click into a component before editing its children — single click selects the component container.
+- See [Context Menu](./context-menu) for all component-related actions.
--- a/docs/user-guide/context-menu.md
+++ b/docs/user-guide/context-menu.md
@ -0,0 +1,78 @@
+---
+title: Context Menu
+description: Right-click context menu actions in OpenPencil — clipboard, z-order, grouping, components, and more.
+---
+
+# Context Menu
+
+Right-click on the canvas to open the context menu. If you right-click on a node, it is selected first. Right-clicking on empty canvas clears the selection.
+
+::: tip Cross-platform shortcuts
+⌘ = Ctrl, ⌥ = Alt on Windows and Linux.
+:::
+
+## Clipboard Actions
+
+| Action | Shortcut (Mac) | Shortcut (Win/Linux) |
+|--------|----------------|----------------------|
+| Copy | ⌘ C | Ctrl + C |
+| Cut | ⌘ X | Ctrl + X |
+| Paste here | ⌘ V | Ctrl + V |
+| Duplicate | ⌘ D | Ctrl + D |
+| Delete | ⌫ | Backspace / Delete |
+
+Clipboard actions are disabled when nothing is selected (except Paste, which is available when the clipboard has content).
+
+## Z-Order
+
+| Action | Shortcut |
+|--------|----------|
+| Bring to front | ] |
+| Send to back | [ |
+
+Moves the selected node to the top or bottom of its parent's child list.
+
+## Grouping
+
+| Action | Shortcut (Mac) | Shortcut (Win/Linux) |
+|--------|----------------|----------------------|
+| Group | ⌘ G | Ctrl + G |
+| Ungroup | ⇧ ⌘ G | Shift + Ctrl + G |
+| Add auto layout | ⇧ A | Shift + A |
+
+- **Group** requires 2 or more selected nodes
+- **Ungroup** appears when a group is selected — children are reparented to the group's parent
+- **Add auto layout** wraps the selection in a new [auto layout](./auto-layout) frame
+
+## Component Actions
+
+Component actions are displayed in purple to match the component color theme.
+
+| Action | Shortcut (Mac) | Shortcut (Win/Linux) | Available on |
+|--------|----------------|----------------------|--------------|
+| Create component | ⌥ ⌘ K | Ctrl + Alt + K | Frames, groups, multi-selection |
+| Create component set | ⇧ ⌘ K | Shift + Ctrl + K | 2+ selected components |
+| Create instance | — | — | Components (no shortcut) |
+| Go to main component | — | — | Instances |
+| Detach instance | ⌥ ⌘ B | Ctrl + Alt + B | Instances |
+
+See [Components](./components) for details on the component workflow.
+
+## Visibility & Lock
+
+| Action | Shortcut (Mac) | Shortcut (Win/Linux) |
+|--------|----------------|----------------------|
+| Hide / Show | ⇧ ⌘ H | Shift + Ctrl + H |
+| Lock / Unlock | ⇧ ⌘ L | Shift + Ctrl + L |
+
+The label toggles based on the node's current state (e.g., "Hide" for a visible node, "Show" for a hidden one).
+
+## Move to Page
+
+The **Move to page** submenu lists all pages except the current one. Select a page to reparent the selected nodes under that page's canvas.
+
+## Tips
+
+- Right-clicking empty canvas gives you access to Paste — useful for placing content at a specific location.
+- Component actions only appear when relevant (e.g., "Create instance" only for component nodes).
+- The context menu mirrors the keyboard shortcuts — it's a good way to discover shortcuts you don't know yet.
--- a/docs/user-guide/drawing-shapes.md
+++ b/docs/user-guide/drawing-shapes.md
@ -0,0 +1,94 @@
+---
+title: Drawing Shapes
+description: Creating rectangles, ellipses, lines, frames, sections, polygons, and stars in OpenPencil.
+---
+
+# Drawing Shapes
+
+The bottom toolbar provides tools for creating shapes, frames, and sections. Select a tool, then click and drag on the canvas to draw.
+
+::: tip Cross-platform shortcuts
+⌘ = Ctrl, ⌥ = Alt on Windows and Linux.
+:::
+
+## Toolbar Tools
+
+| Tool | Shortcut | Description |
+|------|----------|-------------|
+| Rectangle | R | Draws a rectangle |
+| Ellipse | O | Draws an ellipse |
+| Line | L | Draws a line |
+| Frame | F | Draws a frame (container for other nodes) |
+| Section | S | Draws a section (auto-adopts overlapping siblings) |
+
+## Shapes Flyout
+
+The shapes flyout (accessible from the toolbar) includes additional shapes:
+
+- **Polygon** — creates a polygon with 3 sides by default (triangle)
+- **Star** — creates a 5-pointed star with 0.38 inner radius
+
+Polygon and Star have no keyboard shortcut — access them from the shapes flyout in the toolbar.
+
+## Constrained Drawing
+
+Hold **Shift** while dragging to constrain the shape:
+
+- Rectangle → square (equal width and height)
+- Ellipse → circle
+- Line → snaps to 0°/45°/90° angles
+
+## Shape Properties
+
+After drawing a shape, select it to edit its properties in the Design tab of the properties panel.
+
+### Fill
+
+Every shape can have a fill. The fill section supports:
+
+- **Solid color** — pick via the HSV color picker or type a hex value
+- **Gradient** — Linear, Radial, Angular, or Diamond with editable gradient stops
+- **Image** — select an image file as the fill
+
+### Stroke
+
+Add an outline to any shape. Stroke properties include width, color, cap style, join style, and dash pattern.
+
+### Corner Radius
+
+Available for rectangles, frames, components, and instances. Click the independent corners toggle to set each corner (top-left, top-right, bottom-left, bottom-right) separately.
+
+### Effects
+
+Add visual effects from the Effects section:
+
+- **Drop Shadow** — offset, blur radius, spread, color
+- **Inner Shadow** — same controls, rendered inside the shape
+- **Layer Blur** — blurs the entire node
+- **Background Blur** — blurs content behind the node
+- **Foreground Blur** — blurs content in front
+
+Click **+** to add an effect. Each effect row is collapsible with inline controls. Toggle the eye icon to enable/disable an effect.
+
+## Frames and Sections
+
+**Frames** are containers. Drag shapes into a frame to make them children. Frames can clip their content (off by default) and support [auto layout](./auto-layout).
+
+**Sections** are top-level containers that automatically adopt overlapping sibling nodes when drawn. They're useful for organizing large canvases into logical areas. Sections display a title pill that you can drag.
+
+## Keyboard Shortcuts
+
+| Action | Mac | Windows / Linux |
+|--------|-----|-----------------|
+| Rectangle tool | R | R |
+| Ellipse tool | O | O |
+| Line tool | L | L |
+| Frame tool | F | F |
+| Section tool | S | S |
+| Constrain to square/circle | Shift + drag | Shift + drag |
+
+## Tips
+
+- Sections can only exist at the top level — they can't be nested inside frames.
+- Use frames with [auto layout](./auto-layout) to build responsive layouts.
+- [Export](./exporting) individual shapes or groups as images via the properties panel or context menu.
--- a/docs/user-guide/exporting.md
+++ b/docs/user-guide/exporting.md
@ -0,0 +1,76 @@
+---
+title: Exporting
+description: Exporting images (PNG, JPG, WEBP) and saving/opening .fig files in OpenPencil.
+---
+
+# Exporting
+
+Export individual nodes as images, or save and open entire documents as .fig files.
+
+::: tip Cross-platform shortcuts
+⌘ = Ctrl, ⌥ = Alt on Windows and Linux.
+:::
+
+## Image Export
+
+Select a node and use the Export section in the properties panel.
+
+### Export Settings
+
+- **Scale** — 0.5×, 0.75×, 1×, 1.5×, 2×, 3×, or 4×
+- **Format** — PNG (transparent background), JPG (white background), WEBP (transparent background)
+
+You can add multiple export settings to export the same node at different scales or formats in one go. A live preview with a checkerboard background shows what will be exported.
+
+### Export Methods
+
+| Method | Mac | Windows / Linux |
+|--------|-----|-----------------|
+| Keyboard shortcut | ⇧ ⌘ E | Shift + Ctrl + E |
+| Context menu | Right-click → Export… | Right-click → Export… |
+| Properties panel | Click "Export" button | Click "Export" button |
+
+The exported file is saved via a native dialog (desktop) or browser download.
+
+## .fig File Operations
+
+OpenPencil uses the .fig format for full documents — the same binary format as Figma.
+
+### Opening Files
+
+| Action | Mac | Windows / Linux |
+|--------|-----|-----------------|
+| Open file | ⌘ O | Ctrl + O |
+
+A file picker dialog opens, filtered for .fig files. On the desktop app, this uses the native OS dialog.
+
+### Saving Files
+
+| Action | Mac | Windows / Linux |
+|--------|-----|-----------------|
+| Save | ⌘ S | Ctrl + S |
+| Save As | ⇧ ⌘ S | Shift + Ctrl + S |
+
+- **Save** overwrites the currently open file without a dialog
+- **Save As** opens a save dialog to choose a new location
+
+The export pipeline encodes the scene graph to Kiwi binary format, compresses it, and writes a ZIP archive with the payload and a thumbnail image.
+
+### Round-trip Compatibility
+
+Files exported from OpenPencil can be opened in Figma, and vice versa. The .fig format preserves all node types, properties, fills, strokes, effects, vector data, and layout settings.
+
+## Keyboard Shortcuts
+
+| Action | Mac | Windows / Linux |
+|--------|-----|-----------------|
+| Export selection | ⇧ ⌘ E | Shift + Ctrl + E |
+| Open file | ⌘ O | Ctrl + O |
+| Save | ⌘ S | Ctrl + S |
+| Save As | ⇧ ⌘ S | Shift + Ctrl + S |
+
+## Tips
+
+- Use 2× or 3× scale when exporting for high-DPI screens.
+- JPG always uses a white background — use PNG or WEBP if you need transparency.
+- The thumbnail in exported .fig files enables preview in file browsers and Figma's file picker.
--- a/docs/user-guide/index.md
+++ b/docs/user-guide/index.md
@ -0,0 +1,36 @@
+---
+layout: doc
+title: User Guide
+description: Learn how to use OpenPencil — canvas navigation, drawing, text, components, auto-layout, and more.
+---
+
+# User Guide
+
+OpenPencil is an open-source design editor with full .fig file compatibility. This guide covers everything you need to know to use the editor effectively.
+
+::: tip Cross-platform shortcuts
+Throughout this guide, keyboard shortcuts use Mac notation: **⌘** = Command (Ctrl on Windows/Linux), **⌥** = Option (Alt), **⇧** = Shift.
+:::
+
+## Getting Around
+
+- [Canvas Navigation](./canvas-navigation) — panning, zooming, and the hand tool
+- [Selection & Manipulation](./selection-and-manipulation) — selecting, moving, resizing, rotating, and organizing nodes
+
+## Creating Content
+
+- [Drawing Shapes](./drawing-shapes) — rectangles, ellipses, lines, frames, sections, polygons, and stars
+- [Text Editing](./text-editing) — creating and editing text with rich formatting
+- [Pen Tool](./pen-tool) — drawing vector paths with bezier curves
+
+## Organizing & Managing
+
+- [Layers & Pages](./layers-and-pages) — the layers panel, pages, and properties panel
+- [Context Menu](./context-menu) — right-click actions for clipboard, grouping, components, and more
+- [Exporting](./exporting) — image export and .fig file operations
+
+## Advanced Features
+
+- [Auto Layout](./auto-layout) — flexbox-based automatic positioning with Yoga
+- [Components](./components) — reusable components, instances, and overrides
+- [Variables](./variables) — design variables, collections, modes, and fill bindings
--- a/docs/user-guide/layers-and-pages.md
+++ b/docs/user-guide/layers-and-pages.md
@ -0,0 +1,86 @@
+---
+title: Layers & Pages
+description: Managing layers, pages, and the properties panel in OpenPencil.
+---
+
+# Layers & Pages
+
+The editor interface has three main panels: layers (left), canvas (center), and properties (right). All panels are resizable by dragging the dividers.
+
+::: tip Cross-platform shortcuts
+⌘ = Ctrl, ⌥ = Alt on Windows and Linux.
+:::
+
+## Layers Panel
+
+The layers panel on the left displays the document hierarchy as a tree.
+
+### Tree View
+
+Nodes are shown in a collapsible tree. Click the chevron next to a frame, group, or component to expand or collapse its children.
+
+### Drag Reorder
+
+Drag layers to reorder them. This changes the node's z-order in the scene graph — nodes higher in the list render on top.
+
+### Visibility Toggle
+
+Click the eye icon next to any layer to hide or show it on the canvas. Hidden nodes remain in the tree.
+
+### Rename
+
+Double-click a layer name to rename it inline.
+
+### Selection Sync
+
+Clicking a layer in the panel selects the corresponding node on the canvas, and vice versa.
+
+## Pages Panel
+
+The pages panel shows all pages in the document.
+
+- **Switch page** — click a page tab to make it active. The canvas switches to that page and restores its viewport position.
+- **Add page** — click the add button to create a new page
+- **Delete page** — remove the current page
+- **Rename page** — double-click the page name for inline editing. Pressing Enter or Escape, or clicking away, commits the rename.
+
+Each page has its own canvas and viewport state.
+
+## Properties Panel
+
+The properties panel on the right has three tabs:
+
+### Design Tab
+
+Shows the properties of the selected node(s), organized in sections:
+
+- **Appearance** — opacity, corner radius (with independent corner toggle), visibility
+- **Fill** — solid color, gradients (linear, radial, angular, diamond), image fills, variable bindings
+- **Stroke** — color, width, cap, join, dash pattern
+- **Effects** — drop shadow, inner shadow, layer blur, background blur, foreground blur
+- **Typography** — font family, size, weight, B/I/U/S formatting buttons (visible for text nodes)
+- **Layout** — [auto layout](./auto-layout) controls (visible for auto-layout frames)
+- **Export** — scale, format, and export button (see [Exporting](./exporting))
+
+When no nodes are selected, the Design tab shows page-level properties including the canvas background color.
+
+### Code Tab
+
+Displays the selected node as JSX code with syntax highlighting, line numbers, and a copy button. Useful for exporting designs as code.
+
+### AI Tab
+
+An AI chat interface (also toggled with **⌘ J**) that can create and modify design elements via natural language. Supports multiple AI models through OpenRouter.
+
+## Keyboard Shortcuts
+
+| Action | Mac | Windows / Linux |
+|--------|-----|-----------------|
+| Toggle AI chat | ⌘ J | Ctrl + J |
+
+## Tips
+
+- Panel widths are saved automatically — they persist across reloads.
+- Use the layers panel to find overlapping nodes that are hard to click on the canvas.
+- The [context menu](./context-menu) provides additional actions for selected nodes.
+- See [Selection & Manipulation](./selection-and-manipulation) for z-order shortcuts (]/[) and visibility/lock toggles.
--- a/docs/user-guide/pen-tool.md
+++ b/docs/user-guide/pen-tool.md
@ -0,0 +1,48 @@
+---
+title: Pen Tool
+description: Drawing vector paths with bezier curves using the pen tool in OpenPencil.
+---
+
+# Pen Tool
+
+The pen tool creates vector paths using a vector network data model, compatible with Figma's .fig format.
+
+::: tip Cross-platform shortcuts
+⌘ = Ctrl, ⌥ = Alt on Windows and Linux.
+:::
+
+## Activating
+
+Press **P** to activate the pen tool.
+
+## Placing Points
+
+- **Click** to place a corner point (straight-line segment)
+- **Click + drag** to place a curve point with bezier tangent handles — the drag direction and length control the curve shape
+
+Click multiple points to build a path segment by segment. A preview line extends from the last placed point to your cursor as you move.
+
+## Closing a Path
+
+Click on the **first point** of the path to close it into a loop. Closed paths can be filled.
+
+## Open Paths
+
+Press **Escape** to commit the current path as an open path. Open paths render as strokes only — they're not filled.
+
+## Vector Networks
+
+Under the hood, paths use the vector network data model instead of simple point lists. Vector networks allow more flexible topology (e.g., branching paths) and are encoded in Figma's `vectorNetworkBlob` binary format for .fig file compatibility.
+
+## Keyboard Shortcuts
+
+| Action | Mac | Windows / Linux |
+|--------|-----|-----------------|
+| Pen tool | P | P |
+| Commit open path | Escape | Escape |
+
+## Tips
+
+- The preview line always starts from the last placed point — it won't jump to (0,0).
+- Drag longer when placing a curve point to make the curve wider.
+- After creating a path, use the properties panel to adjust its fill, stroke, and effects.
--- a/docs/user-guide/selection-and-manipulation.md
+++ b/docs/user-guide/selection-and-manipulation.md
@ -0,0 +1,87 @@
+---
+title: Selection & Manipulation
+description: Selecting, moving, resizing, rotating, duplicating, and organizing nodes in OpenPencil.
+---
+
+# Selection & Manipulation
+
+Select objects to move, resize, rotate, duplicate, and organize them on the canvas.
+
+::: tip Cross-platform shortcuts
+⌘ = Ctrl, ⌥ = Alt on Windows and Linux.
+:::
+
+## Selecting
+
+- **Click** a node to select it (deselects everything else)
+- **Shift + click** to add or remove a node from the current selection
+- **Marquee drag** — drag on empty canvas to draw a selection rectangle; all intersecting nodes are selected on release
+- **⌘ A** — select all nodes on the current page
+- **Click empty canvas** — deselect all
+
+## Moving
+
+- **Drag** a selected node to move it (all selected nodes move together)
+- **Arrow keys** — nudge selected nodes by 1 px
+- **Shift + arrow keys** — nudge by 10 px
+
+## Resizing
+
+Selected nodes show 8 resize handles (4 corners + 4 edge midpoints). Drag any handle to resize.
+
+- **Shift + drag** a corner handle to constrain proportions
+
+## Rotating
+
+Hover just outside a corner handle to see the rotation cursor. Drag to rotate.
+
+- **Shift + drag** snaps rotation to 15° increments
+
+## Duplicating
+
+- **Alt + drag** (⌥ + drag on Mac) — duplicate the selected node and move the copy
+- **⌘ D** — duplicate in place
+
+## Deleting
+
+Press **Backspace** or **Delete** to remove all selected nodes.
+
+## Z-Order
+
+Change the stacking order of nodes within their parent:
+
+- **]** — bring to front (top of sibling list)
+- **[** — send to back (bottom of sibling list)
+
+## Visibility & Lock
+
+- **⇧ ⌘ H** — toggle visibility. Hidden nodes don't render but stay in the layers panel.
+- **⇧ ⌘ L** — toggle lock. Locked nodes can't be selected or moved on canvas.
+
+## Move to Page
+
+Move selected nodes to a different page via the [context menu](./context-menu). The nodes are reparented under the target page's canvas.
+
+## Sections
+
+Drawing a section on the canvas automatically adopts overlapping sibling nodes as children of the new section.
+
+## Keyboard Shortcuts
+
+| Action | Mac | Windows / Linux |
+|--------|-----|-----------------|
+| Select all | ⌘ A | Ctrl + A |
+| Duplicate | ⌘ D | Ctrl + D |
+| Duplicate + move | ⌥ + drag | Alt + drag |
+| Delete | ⌫ / Delete | Backspace / Delete |
+| Nudge 1 px | Arrow keys | Arrow keys |
+| Nudge 10 px | ⇧ + Arrow keys | Shift + Arrow keys |
+| Bring to front | ] | ] |
+| Send to back | [ | [ |
+| Toggle visibility | ⇧ ⌘ H | Shift + Ctrl + H |
+| Toggle lock | ⇧ ⌘ L | Shift + Ctrl + L |
+
+## Tips
+
+- Use the [Layers & Pages](./layers-and-pages) panel to see and reorder nodes when they overlap.
+- See [Context Menu](./context-menu) for additional actions like grouping and component creation.
--- a/docs/user-guide/text-editing.md
+++ b/docs/user-guide/text-editing.md
@ -0,0 +1,92 @@
+---
+title: Text Editing
+description: Creating and editing text with rich formatting, fonts, and inline editing in OpenPencil.
+---
+
+# Text Editing
+
+Create text nodes and edit them directly on the canvas with full rich text support.
+
+::: tip Cross-platform shortcuts
+⌘ = Ctrl, ⌥ = Alt on Windows and Linux.
+:::
+
+## Creating Text
+
+Press **T** to activate the text tool, then click on the canvas. An empty text node appears with a blinking cursor — start typing immediately.
+
+## Inline Editing
+
+Double-click any existing text node to enter inline editing mode. A blue outline appears around the text to indicate edit mode. Click outside the text node to commit and exit editing.
+
+Text is rendered directly on the canvas using CanvasKit's Paragraph API — there's no visible text input overlay.
+
+## Cursor Navigation
+
+| Action | Mac | Windows / Linux |
+|--------|-----|-----------------|
+| Move left/right | ← / → | ← / → |
+| Move up/down | ↑ / ↓ | ↑ / ↓ |
+| Move by word | ⌥ ← / ⌥ → | Ctrl + ← / Ctrl + → |
+| Move to line start/end | ⌘ ← / ⌘ → | Home / End |
+
+Hold **Shift** with any movement key to extend the selection.
+
+## Text Selection
+
+- **Click** inside a text node to position the cursor
+- **Click + drag** to select a range of text
+- **Double-click** a word to select it
+- **Triple-click** to select all text in the node
+
+## Rich Text Formatting
+
+Apply formatting to selected text, or toggle the style for the entire node when nothing is selected.
+
+| Action | Mac | Windows / Linux |
+|--------|-----|-----------------|
+| Bold | ⌘ B | Ctrl + B |
+| Italic | ⌘ I | Ctrl + I |
+| Underline | ⌘ U | Ctrl + U |
+
+Strikethrough is available via the **S** toggle button in the Typography section of the properties panel (no keyboard shortcut — ⌘ S is used for Save).
+
+Formatting is stored as style runs (per-character styles). When you type between a bold and regular segment, the new text inherits the style of the preceding segment.
+
+The **B / I / U / S** toggle buttons in the Typography section of the properties panel also apply formatting.
+
+## Editing Operations
+
+| Action | Mac | Windows / Linux |
+|--------|-----|-----------------|
+| Delete word before cursor | ⌥ ⌫ | Ctrl + Backspace |
+| Delete to line start | ⌘ ⌫ | — |
+| Cut | ⌘ X | Ctrl + X |
+| Copy | ⌘ C | Ctrl + C |
+| Paste | ⌘ V | Ctrl + V |
+
+## Font Picker
+
+Open the font picker in the Typography section of the properties panel to change the font family. The picker features:
+
+- **Search filter** — type to narrow the font list
+- **Font preview** — each font name is rendered in its own typeface
+- **Virtual scroll** — handles large font lists efficiently
+- **Scroll-to-current** — the current font is highlighted when the picker opens
+
+## Font Weight
+
+Change the font weight in the Typography section of the properties panel. Available weights depend on the selected font family (e.g., Regular, Medium, Bold, Black). The weight is applied per-node and renders via CanvasKit text styles.
+
+## Font Sources
+
+- **Default font** — Inter is loaded automatically
+- **Desktop (Tauri)** — system fonts are enumerated via the font-kit Rust backend and preloaded on startup
+- **Browser** — system fonts are available via the Local Font Access API (Chrome/Edge)
+
+## Tips
+
+- The font list is preloaded at startup so the picker opens without delay.
+- IME input (Chinese, Japanese, Korean) is fully supported through the phantom textarea.
+- Rich text formatting survives .fig import/export — style runs map to Figma's `characterStyleIDs`.
+- See [Components](./components) for how text overrides work in component instances.
--- a/docs/user-guide/variables.md
+++ b/docs/user-guide/variables.md
@ -0,0 +1,64 @@
+---
+title: Variables
+description: Design variables, collections, modes, and fill bindings in OpenPencil.
+---
+
+# Variables
+
+Variables store reusable design tokens — colors, spacing values, and other properties — that can be bound to nodes. Change a variable's value and every node using it updates.
+
+::: tip Cross-platform shortcuts
+⌘ = Ctrl, ⌥ = Alt on Windows and Linux.
+:::
+
+## Opening the Variables Dialog
+
+With no nodes selected, the Design tab shows page-level properties including a Variables section with collection and variable counts. Click the settings icon to open the variables dialog.
+
+## Collections
+
+Variables are organized into collections. Each collection appears as a tab in the dialog.
+
+- **Switch collection** — click a tab
+- **Rename collection** — double-click the tab name
+
+## Modes
+
+Each collection can have multiple modes (e.g., Light and Dark). Modes appear as columns in the variables table. A variable has a value for each mode.
+
+### Adding Collections and Modes
+
+Create a new collection from the dialog toolbar. Add modes to an existing collection to support theme variants or responsive breakpoints.
+
+## Managing Variables
+
+The variables table uses resizable columns: Name, plus one column per mode.
+
+- **Create variable** — click the "+ Create variable" button
+- **Edit name** — click the variable name cell to edit inline
+- **Edit value** — click any value cell to change it for that mode
+- **Search** — type in the search bar to filter variables by name
+
+### Color Variables
+
+Color variables display an inline color input with a picker. Click the swatch to open the color picker and select a new color.
+
+## Binding Variables to Fills
+
+In the Fill section of the properties panel, use the variable picker to bind a color variable to a node's fill.
+
+- **Bind** — select a color variable from the picker. The fill shows a purple badge with the variable name.
+- **Detach** — click the detach button on the badge to remove the binding. The fill reverts to the resolved color value.
+
+When the variable's value changes (or when switching modes), all bound fills update automatically.
+
+## Keyboard Shortcuts
+
+Variables are managed through the dialog UI — there are no dedicated keyboard shortcuts. Open the dialog via the settings icon in the page-level Variables section.
+
+## Tips
+
+- Use collections to group related tokens (e.g., "Primitives" for raw colors, "Semantic" for role-based aliases, "Spacing" for layout values).
+- Modes are useful for theme switching — define Light and Dark mode values in the same collection.
+- Variables support aliases — a "Semantic" collection can reference values from a "Primitives" collection.
+- See [Drawing Shapes](./drawing-shapes) for how fills and the color picker work.
--- a/openspec/changes/archive/2026-03-01-vitepress-userdoc/.openspec.yaml
+++ b/openspec/changes/archive/2026-03-01-vitepress-userdoc/.openspec.yaml
@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-01
--- a/openspec/changes/archive/2026-03-01-vitepress-userdoc/design.md
+++ b/openspec/changes/archive/2026-03-01-vitepress-userdoc/design.md
@ -0,0 +1,49 @@
+## Context
+
+The project has a VitePress docs site at `docs/` with three sections: Guide (getting started, features, architecture, tech stack, comparison), Reference (shortcuts, node types, MCP tools, scene graph, file format), and Development (contributing, testing, openspec, roadmap). All content is developer/contributor-oriented.
+
+OpenSpec `openspec/specs/` contains 24 feature specs with detailed requirements and scenarios covering every user-facing feature. These specs are the authoritative source of truth for what the editor can do.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Add a "User Guide" section to VitePress with task-oriented articles derived from OpenSpec specs
+- Cover all user-facing features: canvas navigation, selection, drawing, auto-layout, components, text, pen tool, layers/pages, context menu, export, variables
+- Each article explains how to use the feature with keyboard shortcuts, step-by-step instructions, and tips
+- Articles follow consistent structure: intro, how-to steps, shortcuts table, tips
+
+**Non-Goals:**
+- Automated spec-to-docs pipeline (manual generation this time, automation later)
+- Screenshots or video content (text-only for now)
+- API/developer documentation (already covered in existing sections)
+- Translating docs to other languages
+
+## Decisions
+
+**Article structure**: Each article follows a consistent template: brief intro → feature walkthrough with subsections → keyboard shortcuts table → tips/notes. This mirrors how Figma's help center organizes content and is familiar to design tool users.
+
+**File organization**: All user guide articles live under `docs/user-guide/` with an `index.md` landing page. Naming matches the feature area (e.g., `canvas-navigation.md`, `auto-layout.md`).
+
+**Sidebar placement**: The "User Guide" group goes first in the sidebar, before the existing Guide section. User docs are the primary audience; developer docs are secondary.
+
+**Content derivation**: Each article is written by reading the corresponding OpenSpec spec(s) and translating requirements/scenarios into user-friendly how-to content. The spec's Purpose and Scenarios provide the skeleton; the article adds context, flow, and readability.
+
+**Article list** (12 articles):
+1. `index.md` — overview with links to all articles
+2. `canvas-navigation.md` — from `canvas-navigation` spec
+3. `selection-and-manipulation.md` — from `selection-manipulation` spec
+4. `drawing-shapes.md` — from `editor-ui` spec (toolbar, shape tools) + `canvas-rendering` spec
+5. `auto-layout.md` — from `auto-layout` spec
+6. `components.md` — from `components` spec
+7. `text-editing.md` — from `text-editing` spec
+8. `pen-tool.md` — from `pen-tool` spec
+9. `layers-and-pages.md` — from `editor-ui` spec (layers panel, pages panel)
+10. `context-menu.md` — from `context-menu` spec
+11. `exporting.md` — from `editor-ui` spec (export section) + `fig-import` spec
+12. `variables.md` — from `editor-ui` spec (variables dialog, fill variable picker)
+
+## Risks / Trade-offs
+
+- [Content drift] Specs evolve but docs may lag → Mitigate by documenting the spec-to-doc mapping so future changes can update both
+- [No screenshots] Text-only docs are less engaging → Acceptable for v1; screenshots can be added later
+- [Mac-centric shortcuts] Shortcuts use ⌘ notation → Add a note about Ctrl equivalents on Linux/Windows
--- a/openspec/changes/archive/2026-03-01-vitepress-userdoc/proposal.md
+++ b/openspec/changes/archive/2026-03-01-vitepress-userdoc/proposal.md
@ -0,0 +1,25 @@
+## Why
+
+The existing VitePress docs site (`docs/`) is developer-focused — architecture, reference, contributing. There's no user-facing documentation that explains how to actually use the editor. New users have no guide for canvas navigation, drawing shapes, using auto-layout, working with components, editing text, etc. A "User Guide" section derived from the OpenSpec specifications would provide task-oriented documentation covering all implemented features.
+
+## What Changes
+
+- Add a new `User Guide` sidebar group in VitePress with articles covering each user-facing feature area
+- Generate articles from OpenSpec specs: canvas navigation, selection & manipulation, drawing & shapes, auto-layout, components & instances, text editing, pen tool, layers & pages, context menu, export, keyboard shortcuts summary
+- Add a user guide landing page with feature overview and navigation
+- Update VitePress config sidebar/nav to include the new section
+- Keep existing Guide/Reference/Development sections unchanged
+
+## Capabilities
+
+### New Capabilities
+- `userdoc-articles`: VitePress user documentation pages generated from OpenSpec specs — canvas navigation, selection, shapes, auto-layout, components, text, pen tool, layers, export, and variables
+
+### Modified Capabilities
+- `vitepress-docs`: Adding a new "User Guide" sidebar group and nav entry to the existing VitePress config
+
+## Impact
+
+- `docs/` — new `.md` files under `docs/user-guide/`
+- `docs/.vitepress/config.ts` — sidebar and nav updates
+- No runtime code changes, no dependency changes
--- a/openspec/changes/archive/2026-03-01-vitepress-userdoc/specs/userdoc-articles/spec.md
+++ b/openspec/changes/archive/2026-03-01-vitepress-userdoc/specs/userdoc-articles/spec.md
@ -0,0 +1,99 @@
+## ADDED Requirements
+
+### Requirement: User guide landing page
+The docs site SHALL have an `index.md` at `docs/user-guide/` with the title "User Guide", a brief description of OpenPencil's capabilities, and links to all user guide articles organized by category.
+
+#### Scenario: Landing page renders
+- **WHEN** user navigates to /user-guide/
+- **THEN** a page with "User Guide" title and categorized links to all articles is displayed
+
+### Requirement: Canvas navigation article
+The docs site SHALL have a `canvas-navigation.md` article in `docs/user-guide/` documenting panning (space+drag, middle mouse, trackpad, hand tool), zooming (ctrl+scroll, pinch, keyboard shortcuts), and zoom reset.
+
+#### Scenario: Canvas navigation article renders
+- **WHEN** user navigates to /user-guide/canvas-navigation
+- **THEN** an article explaining panning, zooming, and hand tool usage is displayed with a shortcuts table
+
+### Requirement: Selection and manipulation article
+The docs site SHALL have a `selection-and-manipulation.md` article documenting click select, shift multi-select, marquee selection, move by drag, resize handles, rotation with shift snapping, alt+drag duplicate, ⌘D duplicate, nudge with arrows, delete, select all, z-order (]/[), visibility toggle (⇧⌘H), lock toggle (⇧⌘L), and move-to-page.
+
+#### Scenario: Selection article renders
+- **WHEN** user navigates to /user-guide/selection-and-manipulation
+- **THEN** an article explaining all selection and manipulation operations is displayed
+
+### Requirement: Drawing shapes article
+The docs site SHALL have a `drawing-shapes.md` article documenting the bottom toolbar shape tools: Rectangle (R), Ellipse (O), Line (L), Polygon, Star, Frame (F), Section (S). It SHALL cover constrained drawing with Shift, shape properties (fill, stroke, corner radius, effects), and the shapes flyout.
+
+#### Scenario: Drawing shapes article renders
+- **WHEN** user navigates to /user-guide/drawing-shapes
+- **THEN** an article explaining shape creation with tool shortcuts and property editing is displayed
+
+### Requirement: Auto-layout article
+The docs site SHALL have an `auto-layout.md` article documenting Shift+A toggle, layout direction, gap, padding, justify, align, child sizing (fixed/fill/hug), drag reordering, and wrapping selection in auto-layout.
+
+#### Scenario: Auto-layout article renders
+- **WHEN** user navigates to /user-guide/auto-layout
+- **THEN** an article explaining auto-layout creation and configuration is displayed
+
+### Requirement: Components article
+The docs site SHALL have a `components.md` article documenting component creation (⌥⌘K), component sets (⇧⌘K), instance creation (context menu), detach instance (⌥⌘B), go-to-main-component, live sync, overrides, and visual treatment (purple labels, dashed borders).
+
+#### Scenario: Components article renders
+- **WHEN** user navigates to /user-guide/components
+- **THEN** an article explaining the full component workflow is displayed
+
+### Requirement: Text editing article
+The docs site SHALL have a `text-editing.md` article documenting the Text tool (T), inline editing (double-click), cursor navigation (arrow keys, ⌘←/→, ⌥←/→), text selection (click, drag, double-click word, triple-click all), rich text formatting (⌘B/I/U), font picker, and font weight.
+
+#### Scenario: Text editing article renders
+- **WHEN** user navigates to /user-guide/text-editing
+- **THEN** an article explaining text creation and editing is displayed
+
+### Requirement: Pen tool article
+The docs site SHALL have a `pen-tool.md` article documenting the Pen tool (P), placing corner points (click), curve points (click+drag with bezier handles), closing paths (click first point), committing open paths (Escape), and the preview line.
+
+#### Scenario: Pen tool article renders
+- **WHEN** user navigates to /user-guide/pen-tool
+- **THEN** an article explaining vector path creation is displayed
+
+### Requirement: Layers and pages article
+The docs site SHALL have a `layers-and-pages.md` article documenting the layers panel (tree view, expand/collapse, drag reorder, visibility toggle, rename), pages panel (switch, add, delete, rename), and the properties panel tabs (Design, Code, AI).
+
+#### Scenario: Layers and pages article renders
+- **WHEN** user navigates to /user-guide/layers-and-pages
+- **THEN** an article explaining layer management and page operations is displayed
+
+### Requirement: Context menu article
+The docs site SHALL have a `context-menu.md` article documenting right-click actions: clipboard (copy, cut, paste, duplicate, delete), z-order (bring to front, send to back), grouping (group, ungroup, add auto-layout), component actions, visibility/lock, and move-to-page submenu.
+
+#### Scenario: Context menu article renders
+- **WHEN** user navigates to /user-guide/context-menu
+- **THEN** an article listing all context menu actions with their shortcuts is displayed
+
+### Requirement: Exporting article
+The docs site SHALL have an `exporting.md` article documenting the export section in properties panel (scale, format, multi-export), export via context menu, ⇧⌘E shortcut, supported formats (PNG, JPG, WEBP), .fig file save (⌘S, ⇧⌘S), and .fig file import.
+
+#### Scenario: Exporting article renders
+- **WHEN** user navigates to /user-guide/exporting
+- **THEN** an article explaining image export and file operations is displayed
+
+### Requirement: Variables article
+The docs site SHALL have a `variables.md` article documenting the variables dialog (collections, modes, table), creating variables, editing values, color variables, binding variables to fills, and detaching variable bindings.
+
+#### Scenario: Variables article renders
+- **WHEN** user navigates to /user-guide/variables
+- **THEN** an article explaining design variables and their usage is displayed
+
+### Requirement: Cross-platform shortcut note
+Each article that includes keyboard shortcuts SHALL include a note that ⌘ corresponds to Ctrl on Windows/Linux, and ⌥ corresponds to Alt.
+
+#### Scenario: Shortcut platform note present
+- **WHEN** user reads any user guide article with a shortcuts table
+- **THEN** a note about cross-platform key equivalents is visible
+
+### Requirement: Consistent article structure
+Each user guide article SHALL follow a consistent structure: title, brief introduction, feature walkthrough with subsections, keyboard shortcuts table (where applicable), and tips section.
+
+#### Scenario: Article structure consistency
+- **WHEN** user reads any user guide article
+- **THEN** the article has an intro paragraph, subsections explaining features, and a shortcuts table
--- a/openspec/changes/archive/2026-03-01-vitepress-userdoc/specs/vitepress-docs/spec.md
+++ b/openspec/changes/archive/2026-03-01-vitepress-userdoc/specs/vitepress-docs/spec.md
@ -0,0 +1,16 @@
+## MODIFIED Requirements
+
+### Requirement: Sidebar navigation
+The VitePress config SHALL define a sidebar with logical grouping: User Guide, Guide, Reference, Development. The User Guide group SHALL appear first and include entries for all user guide articles. The Guide group SHALL include a "Figma Feature Matrix" entry after "Comparison" linking to `/guide/figma-comparison`.
+
+#### Scenario: Sidebar groups
+- **WHEN** user browses any documentation page
+- **THEN** a sidebar shows four collapsible groups: User Guide, Guide, Reference, Development
+
+#### Scenario: User Guide sidebar entries
+- **WHEN** user views the User Guide sidebar section
+- **THEN** entries for all 12 user guide articles are listed in logical order
+
+#### Scenario: Figma comparison in sidebar
+- **WHEN** user views the Guide sidebar section
+- **THEN** a "Figma Feature Matrix" entry appears after "Comparison" linking to `/guide/figma-comparison`
--- a/openspec/changes/archive/2026-03-01-vitepress-userdoc/tasks.md
+++ b/openspec/changes/archive/2026-03-01-vitepress-userdoc/tasks.md
@ -0,0 +1,30 @@
+## 1. User Guide Landing Page
+
+- [x] 1.1 Create `docs/user-guide/index.md` with `layout: doc` frontmatter (title, description), intro paragraph, and categorized links to all articles (Getting Around, Creating Content, Organizing & Managing, Advanced Features). Include cross-platform shortcut note (⌘=Ctrl, ⌥=Alt on Win/Linux) that all articles reference.
+
+## 2. Core Articles — Getting Around
+
+- [x] 2.1 Create `docs/user-guide/canvas-navigation.md` — derived from `openspec/specs/canvas-navigation/spec.md`. Frontmatter with title+description. Sections: Panning (space+drag, middle mouse, trackpad, hand tool H), Zooming (ctrl+scroll, pinch, ⌘+/⌘-/⌘0). Shortcuts table with Mac and Win/Linux columns. Cross-link to selection article.
+- [x] 2.2 Create `docs/user-guide/selection-and-manipulation.md` — derived from `openspec/specs/selection-manipulation/spec.md`. Frontmatter. Sections: Selecting (click/shift/marquee/⌘A), Moving (drag, arrow nudge 1px/10px), Resizing (8 handles, shift=proportional), Rotating (shift=15° snap), Duplicating (alt+drag, ⌘D), Deleting (⌫), Z-order (]/[), Visibility (⇧⌘H), Lock (⇧⌘L), Move-to-page. Shortcuts table Mac+Win/Linux. Cross-links to context-menu, layers articles.
+
+## 3. Core Articles — Creating Content
+
+- [x] 3.1 Create `docs/user-guide/drawing-shapes.md` — derived from `openspec/specs/editor-ui/spec.md` (toolbar, shape tools) + `openspec/specs/canvas-rendering/spec.md`. Frontmatter. Sections: Toolbar overview, Shape tools (Rectangle R, Ellipse O, Line L, Frame F, Section S), Shapes flyout (Polygon, Star), Constrained drawing (shift), Shape properties (fill, stroke, corner radius, effects). Shortcuts table. Cross-links to auto-layout, exporting.
+- [x] 3.2 Create `docs/user-guide/text-editing.md` — derived from `openspec/specs/text-editing/spec.md`. Frontmatter. Sections: Creating text (T tool), Inline editing (double-click), Cursor navigation (arrows, ⌘←/→, ⌥←/→), Text selection (click/drag/double-click=word/triple-click=all), Rich text formatting (⌘B/I/U/S), Font picker, Font weight. Shortcuts table. Cross-link to components.
+- [x] 3.3 Create `docs/user-guide/pen-tool.md` — derived from `openspec/specs/pen-tool/spec.md`. Frontmatter. Sections: Activating (P), Corner points (click), Curve points (click+drag, bezier handles), Closing paths (click first point), Open paths (Escape), Preview line. Shortcuts table.
+
+## 4. Core Articles — Organizing & Managing
+
+- [x] 4.1 Create `docs/user-guide/layers-and-pages.md` — derived from `openspec/specs/editor-ui/spec.md` (layers panel, pages panel). Frontmatter. Sections: Layers panel (tree view, expand/collapse, drag reorder, visibility toggle, rename), Pages panel (switch, add, delete, inline rename), Properties panel tabs (Design/Code/AI). Cross-links to selection, components.
+- [x] 4.2 Create `docs/user-guide/context-menu.md` — derived from `openspec/specs/context-menu/spec.md`. Frontmatter. Sections: Opening (right-click), Clipboard actions (⌘C/X/V, ⌘D, ⌫), Z-order (]/[), Grouping (⌘G/⇧⌘G, ⇧A), Component actions (purple: ⌥⌘K, ⇧⌘K, create instance, go-to-main, ⌥⌘B), Visibility/Lock (⇧⌘H/⇧⌘L), Move-to-page submenu. Full action table.
+- [x] 4.3 Create `docs/user-guide/exporting.md` — derived from `openspec/specs/editor-ui/spec.md` (export section) + `openspec/specs/fig-import/spec.md`. Frontmatter. Sections: Image export (scale 0.5×–4×, format PNG/JPG/WEBP, multi-export, ⇧⌘E, context menu), File operations (.fig save ⌘S/⇧⌘S, .fig import/open). Shortcuts table.
+
+## 5. Core Articles — Advanced Features
+
+- [x] 5.1 Create `docs/user-guide/auto-layout.md` — derived from `openspec/specs/auto-layout/spec.md`. Frontmatter. Sections: Enabling (⇧A toggle), Direction (horizontal/vertical/wrap), Spacing (gap, padding uniform+per-side), Alignment (justify, align), Child sizing (fixed/fill/hug), Drag reordering, Wrapping selection. Shortcuts table. Cross-link to components, drawing-shapes.
+- [x] 5.2 Create `docs/user-guide/components.md` — derived from `openspec/specs/components/spec.md`. Frontmatter. Sections: Creating components (⌥⌘K, single vs multi-node), Component sets (⇧⌘K, dashed purple border), Instances (context menu, placed 40px right), Detaching (⌥⌘B), Go-to-main (context menu, cross-page), Live sync (fills, size, effects, layout), Overrides (child property preservation), Visual treatment (purple labels, opaque hit testing, double-click to enter). Shortcuts table.
+- [x] 5.3 Create `docs/user-guide/variables.md` — derived from `openspec/specs/editor-ui/spec.md` (variables dialog, fill variable picker). Frontmatter. Sections: Opening variables dialog (settings icon in page properties), Collections and modes, Creating/editing variables, Color variables (inline color input), Binding to fills (purple badge), Detaching bindings. Cross-link to drawing-shapes.
+
+## 6. VitePress Config Update
+
+- [x] 6.1 Update `docs/.vitepress/config.ts` — add "User Guide" as first sidebar group with entries: Overview (/user-guide/), Canvas Navigation, Selection & Manipulation, Drawing Shapes, Text Editing, Pen Tool, Layers & Pages, Context Menu, Exporting, Auto Layout, Components, Variables. Add "User Guide" nav entry before existing "Guide". Verify existing Guide/Reference/Development groups unchanged.
--- a/openspec/specs/userdoc-articles/spec.md
+++ b/openspec/specs/userdoc-articles/spec.md
@ -0,0 +1,103 @@
+# userdoc-articles Specification
+
+## Purpose
+TBD - created by archiving change vitepress-userdoc. Update Purpose after archive.
+## Requirements
+### Requirement: User guide landing page
+The docs site SHALL have an `index.md` at `docs/user-guide/` with the title "User Guide", a brief description of OpenPencil's capabilities, and links to all user guide articles organized by category.
+
+#### Scenario: Landing page renders
+- **WHEN** user navigates to /user-guide/
+- **THEN** a page with "User Guide" title and categorized links to all articles is displayed
+
+### Requirement: Canvas navigation article
+The docs site SHALL have a `canvas-navigation.md` article in `docs/user-guide/` documenting panning (space+drag, middle mouse, trackpad, hand tool), zooming (ctrl+scroll, pinch, keyboard shortcuts), and zoom reset.
+
+#### Scenario: Canvas navigation article renders
+- **WHEN** user navigates to /user-guide/canvas-navigation
+- **THEN** an article explaining panning, zooming, and hand tool usage is displayed with a shortcuts table
+
+### Requirement: Selection and manipulation article
+The docs site SHALL have a `selection-and-manipulation.md` article documenting click select, shift multi-select, marquee selection, move by drag, resize handles, rotation with shift snapping, alt+drag duplicate, ⌘D duplicate, nudge with arrows, delete, select all, z-order (]/[), visibility toggle (⇧⌘H), lock toggle (⇧⌘L), and move-to-page.
+
+#### Scenario: Selection article renders
+- **WHEN** user navigates to /user-guide/selection-and-manipulation
+- **THEN** an article explaining all selection and manipulation operations is displayed
+
+### Requirement: Drawing shapes article
+The docs site SHALL have a `drawing-shapes.md` article documenting the bottom toolbar shape tools: Rectangle (R), Ellipse (O), Line (L), Polygon, Star, Frame (F), Section (S). It SHALL cover constrained drawing with Shift, shape properties (fill, stroke, corner radius, effects), and the shapes flyout.
+
+#### Scenario: Drawing shapes article renders
+- **WHEN** user navigates to /user-guide/drawing-shapes
+- **THEN** an article explaining shape creation with tool shortcuts and property editing is displayed
+
+### Requirement: Auto-layout article
+The docs site SHALL have an `auto-layout.md` article documenting Shift+A toggle, layout direction, gap, padding, justify, align, child sizing (fixed/fill/hug), drag reordering, and wrapping selection in auto-layout.
+
+#### Scenario: Auto-layout article renders
+- **WHEN** user navigates to /user-guide/auto-layout
+- **THEN** an article explaining auto-layout creation and configuration is displayed
+
+### Requirement: Components article
+The docs site SHALL have a `components.md` article documenting component creation (⌥⌘K), component sets (⇧⌘K), instance creation (context menu), detach instance (⌥⌘B), go-to-main-component, live sync, overrides, and visual treatment (purple labels, dashed borders).
+
+#### Scenario: Components article renders
+- **WHEN** user navigates to /user-guide/components
+- **THEN** an article explaining the full component workflow is displayed
+
+### Requirement: Text editing article
+The docs site SHALL have a `text-editing.md` article documenting the Text tool (T), inline editing (double-click), cursor navigation (arrow keys, ⌘←/→, ⌥←/→), text selection (click, drag, double-click word, triple-click all), rich text formatting (⌘B/I/U), font picker, and font weight.
+
+#### Scenario: Text editing article renders
+- **WHEN** user navigates to /user-guide/text-editing
+- **THEN** an article explaining text creation and editing is displayed
+
+### Requirement: Pen tool article
+The docs site SHALL have a `pen-tool.md` article documenting the Pen tool (P), placing corner points (click), curve points (click+drag with bezier handles), closing paths (click first point), committing open paths (Escape), and the preview line.
+
+#### Scenario: Pen tool article renders
+- **WHEN** user navigates to /user-guide/pen-tool
+- **THEN** an article explaining vector path creation is displayed
+
+### Requirement: Layers and pages article
+The docs site SHALL have a `layers-and-pages.md` article documenting the layers panel (tree view, expand/collapse, drag reorder, visibility toggle, rename), pages panel (switch, add, delete, rename), and the properties panel tabs (Design, Code, AI).
+
+#### Scenario: Layers and pages article renders
+- **WHEN** user navigates to /user-guide/layers-and-pages
+- **THEN** an article explaining layer management and page operations is displayed
+
+### Requirement: Context menu article
+The docs site SHALL have a `context-menu.md` article documenting right-click actions: clipboard (copy, cut, paste, duplicate, delete), z-order (bring to front, send to back), grouping (group, ungroup, add auto-layout), component actions, visibility/lock, and move-to-page submenu.
+
+#### Scenario: Context menu article renders
+- **WHEN** user navigates to /user-guide/context-menu
+- **THEN** an article listing all context menu actions with their shortcuts is displayed
+
+### Requirement: Exporting article
+The docs site SHALL have an `exporting.md` article documenting the export section in properties panel (scale, format, multi-export), export via context menu, ⇧⌘E shortcut, supported formats (PNG, JPG, WEBP), .fig file save (⌘S, ⇧⌘S), and .fig file import.
+
+#### Scenario: Exporting article renders
+- **WHEN** user navigates to /user-guide/exporting
+- **THEN** an article explaining image export and file operations is displayed
+
+### Requirement: Variables article
+The docs site SHALL have a `variables.md` article documenting the variables dialog (collections, modes, table), creating variables, editing values, color variables, binding variables to fills, and detaching variable bindings.
+
+#### Scenario: Variables article renders
+- **WHEN** user navigates to /user-guide/variables
+- **THEN** an article explaining design variables and their usage is displayed
+
+### Requirement: Cross-platform shortcut note
+Each article that includes keyboard shortcuts SHALL include a note that ⌘ corresponds to Ctrl on Windows/Linux, and ⌥ corresponds to Alt.
+
+#### Scenario: Shortcut platform note present
+- **WHEN** user reads any user guide article with a shortcuts table
+- **THEN** a note about cross-platform key equivalents is visible
+
+### Requirement: Consistent article structure
+Each user guide article SHALL follow a consistent structure: title, brief introduction, feature walkthrough with subsections, keyboard shortcuts table (where applicable), and tips section.
+
+#### Scenario: Article structure consistency
+- **WHEN** user reads any user guide article
+- **THEN** the article has an intro paragraph, subsections explaining features, and a shortcuts table
+
--- a/openspec/specs/vitepress-docs/spec.md
+++ b/openspec/specs/vitepress-docs/spec.md
@ -55,11 +55,15 @@ The docs site SHALL include a development section with pages: Contributing, Test
 - **THEN** the 6 phases from PLAN.md are listed with current progress

 ### Requirement: Sidebar navigation
-The VitePress config SHALL define a sidebar with logical grouping: Guide, Reference, Development. The Guide group SHALL include a "Figma Feature Matrix" entry after "Comparison" linking to `/guide/figma-comparison`.
+The VitePress config SHALL define a sidebar with logical grouping: User Guide, Guide, Reference, Development. The User Guide group SHALL appear first and include entries for all user guide articles. The Guide group SHALL include a "Figma Feature Matrix" entry after "Comparison" linking to `/guide/figma-comparison`.

 #### Scenario: Sidebar groups
 - **WHEN** user browses any documentation page
- **THEN** a sidebar shows three collapsible groups: Guide, Reference, Development
+- **THEN** a sidebar shows four collapsible groups: User Guide, Guide, Reference, Development
+
+#### Scenario: User Guide sidebar entries
+- **WHEN** user views the User Guide sidebar section
+- **THEN** entries for all 12 user guide articles are listed in logical order

 #### Scenario: Figma comparison in sidebar
 - **WHEN** user views the Guide sidebar section