From source checkout to your first local design.

01 / Install

Build the plugin from reviewed source.

Requirements: Obsidian 1.5.0 or later, Community plugins enabled for the target vault, Git, Node.js 20 or later, and npm.

git clone https://github.com/ZenithResearch/obsidian-design-studio.git
cd obsidian-design-studio
npm ci
npm run verify
npm run build
PLUGIN_DIR="/path/to/vault/.obsidian/plugins/obsidian-design-studio"
mkdir -p "$PLUGIN_DIR"
cp main.js manifest.json styles.css "$PLUGIN_DIR/"

The plugin folder must contain main.js, manifest.json, and styles.css directly.

1. Open the target vaultPlugin enablement is per vault.
2. Open Settings → Community pluginsApprove the trust prompt if Community plugins are not yet enabled.
3. Reload pluginsRestart Obsidian or select Reload plugins after copying a build.
4. Enable Obsidian Design StudioThe plugin then owns valid .obsdesign files.

02 / Create and open

Create a readable design document.

Run Obsidian Design Studio: Create new design document from the command palette, or use the Create design document ribbon action.

The plugin creates Untitled design.obsdesign in the vault root and opens it in a new workspace leaf. If that name exists, it chooses the next numbered name. Existing valid .obsdesign files open in the custom editor.

03 / Editor layout

Four regions, one local source.

04 / Edit

Compose with current v1 primitives.

Artboard

Select Artboard. The editor adds and selects a 1200 × 800 artboard. Edit name, X, Y, W, H, and background in the inspector.

Rectangle

Select an artboard, then select Rectangle. Edit layer name, frame, fill, and corner radius. With no selected artboard, the first artboard receives the new element.

Text

Select an artboard, then select Text. Edit layer name, frame, content, color, and font size. Double-click canvas text to focus the content editor.

Select, move, resize

• Select from Layers or directly on the canvas.
• Drag an element to move it.
• Drag its selected resize handle to change width and height.
• Use X, Y, W, and H in the inspector for precise geometry.
• Press Escape or click empty canvas space to clear selection.

Delete

Select a rectangle or text element and choose Delete layer, or press Delete/Backspace while focus is outside an input. Artboard deletion is not exposed.

Zoom

Zoom out and Zoom in cover 20%–200%. Fit document fits all artboards into the current canvas and caps the result at 125%.

05 / Save and recover

Preserve source before convenience.

Every accepted mutation requests an Obsidian save. Canonical source remains two-space JSON with one trailing newline. For important work, save, close, reopen, and verify structure and appearance.

node skills/obsidian-design-studio/scripts/validate-design.mjs --check path/to/design.obsdesign

Safety error

Malformed JSON, unknown properties, invalid limits, duplicate IDs, and unsupported versions show This design document could not be opened safely. The original source is preserved and displayed for diagnosis. The editor does not replace it with a blank document.

Make a recovery copy before manual repair. Unknown v1 fields are not extensions and should not be deleted merely to force a file open.

06 / Agent skill

Give an agent the current contract.

hermes skills install https://github.com/ZenithResearch/obsidian-design-studio/tree/main/skills/obsidian-design-studio
hermes skills info obsidian-design-studio

In a repository checkout, Hermes and Codex use AGENTS.md; Claude Code uses CLAUDE.md. A generic harness can be told: Read skills/obsidian-design-studio/SKILL.md before working in this repository.

Design Mode works inside current capabilities. Unsupported requests stop in Contribution Mode at a local capability-gap handoff; the skill does not independently authorize schema or public actions.

07 / Current limits

Know what the editor does not claim.

The current implementation is not Figma-equivalent. It does not yet support images, vectors, raster editing, masks, true groups, components, constraints, proprietary-format fidelity, collaboration, accounts, cloud storage, hosted editing, a general web renderer, or version migrations.

The project grows from concrete workflows. Do not invent fields or fake unsupported structure with labels.

08 / Troubleshooting

Resolve the boundary first.

The plugin is not listed

Confirm the directory name is exactly obsidian-design-studio and the three plugin files are directly inside it. Reload plugins or restart Obsidian.

A file opens as text

Confirm the extension is .obsdesign, the plugin is enabled in this vault, and the root declares "format": "obsdesign" and "version": 1.

The canvas appears empty

Select Fit document. If the file validates, inspect artboard coordinates and dimensions.

The file shows a safety error

Preserve the file, read the displayed reason, and run the production validator. Do not normalize away data you do not understand.

You need proof of editor behavior

The browser demo proves editor-frame CSS only. Editing, saving, reopening, and Obsidian runtime claims require the actual plugin.