Technical documentation — Obsidian Design Studio

01 / Architecture

Four explicit layers.

.obsdesign JSONReadable canonical source owned by the user.

src/document.tsParse, validate, normalize, serialize, and mutate.

src/ObsDesignView.tsEditor state, DOM renderer, interaction, inspector.

src/main.tsObsidian lifecycle, extension, document creation.

src/document.ts is the current host-independent executable model. src/ObsDesignView.ts is the Obsidian TextFileView adapter. src/main.ts registers the extension and creation surfaces. Generated main.js is a release/install artifact, never hand-edited authority.

02 / Format v1

A frozen, fail-closed first contract.

The normative prose is docs/format-v1.md. The machine contract is schema/obsdesign-v1.schema.json; capability discovery uses capabilities/obsdesign-v1.json.

Surface	Version 1 contract
Root	`format: "obsdesign"`, `version: 1`, title, 1–200 artboards
Artboards	Global ID, name, X/Y, positive width/height, background, flat elements
Rectangle	Frame, fill, optional stroke, corner radius
Text	Frame, content, color, font size/weight, left/center/right alignment
Unknown fields	Rejected before editing or canonical save
Serialization	Two-space JSON, one trailing newline, uppercase hexadecimal colors

Unknown properties fail closed. Unsupported versions preserve raw source. There is no v1-to-v2 migration.

03 / Obsidian adapter

The current reference editor.

src/main.ts registers .obsdesign, exposes Create new design document, adds the ribbon action, and opens a collision-safe file in a new workspace leaf.

src/ObsDesignView.ts owns selection, layer presentation, pointer-driven movement and resizing, the inspector, zoom, Fit document, viewport preservation, keyboard deletion, save requests, and the invalid-source recovery surface.

Host boundary: Obsidian is an adapter and reference editor. Its DOM structure is not the file-format specification.

04 / Renderer boundary

Semantic and geometric conformance first.

Cross-host compatibility promises deterministic meaning and geometry, not pixel identity. Fonts and engines vary. Accessibility semantics, input bounds, recovery behavior, and deterministic source remain conformance requirements.

demo/index.html is an editor-frame CSS fixture. It is not a general renderer for arbitrary files.

05 / Canonical skill

One procedure across harnesses.

skills/obsidian-design-studio/SKILL.md owns Design Mode, capability checks, provenance, validator use, actual Obsidian evidence, and the gated capability-gap handoff.

Hermes and Codex discover the pointer through AGENTS.md.
Claude Code uses generated CLAUDE.md.
No adapter duplicates the skill body or relies on a symlink.

Install with Hermes

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

06 / Build and verify

One aggregate gate.

Local verification

npm ci
npm run verify

The aggregate gate runs document, format, plugin, UI, skill, public-foundation, and site contracts; canonical format checks; public-surface checks; TypeScript; and the production build.

Focused commands

npm run verify:format
npm run verify:public
npm run verify:skill
npm run typecheck
npm run build
node skills/obsidian-design-studio/scripts/validate-design.mjs --check path/to/design.obsdesign

07 / Compatibility

Schema changes are governed product changes.

A new field, primitive, extension key, or version requires a real user need, representative fixture, explicit scope approval, a RED contract, migration and recovery analysis, aligned parser/schema/manifest/docs/skill changes, independent review, and actual host evidence.

Do not add fields merely to make one fixture pass. Import/export formats are adapters with named fidelity subsets, not alternate native state.

08 / Security and rights

Untrusted input, bounded behavior.

Documents do not execute scripts. Values, identifiers, counts, geometry, and text are bounded. Unknown properties and future versions fail closed. The static documentation site collects no account, credential, design file, or analytics data.

Report vulnerabilities through private vulnerability reporting, not a public issue. Users retain the rights they hold in their documents and source material.