OpenDesign's bet: make the agent the engine and files the medium

OpenDesign is an open-source, local-first design product built around a simple division of labor: an existing coding-agent CLI does the model-and-tool work, while OpenDesign supplies the workspace, reusable design context, live preview, persistence, and export path. The focus here is not whether an AI can produce a polished screen from a prompt. It is what changes when design behavior, brand rules, and generated artifacts are kept as portable files around an agent that can be exchanged. That distinction gives this series its practical question: can openness make agent-led design more reusable and controllable without rebuilding the closed suite it is meant to replace?

The question matters because several products can appear similar from the outside. A cloud generator accepts a brief and returns an image or page. A canvas editor lets a person manipulate visual objects. A coding agent writes files. OpenDesign sits across those categories without being identical to any of them. It is an integration layer for a design workflow whose durable output is code and project state, not an ephemeral chat response or a proprietary canvas document.

OpenDesign is a substrate, not another canvas

The repository describes OpenDesign as an alternative to closed, cloud-only design products, but its more precise identity is a substrate. A substrate is useful here in the literal systems sense: a layer that gives other components somewhere to meet. The user can start with a natural-language brief, choose a design system or template, and select an agent that is already installed or configured. OpenDesign then connects those choices to a project in which files can be written, inspected, previewed, refined, and exported.

That arrangement changes where the product's intelligence lives. OpenDesign does not claim to own a universal model router, and it does not reimplement the entire agent loop. The selected CLI remains responsible for model calls, tool use, context management, and the permission behavior of that runtime. OpenDesign's responsibility is to make the run legible and useful: detect the available runtime, resolve the relevant design context, launch it in the project workspace, normalize what comes back, and keep the result attached to the project rather than losing it in a transcript.

flowchart LR Brief["Natural-language brief"] --> Surface["OpenDesign surface"] Surface --> Daemon["OpenDesign daemon: orchestration and project authority"] Skills["Skills and templates: workflow and rendering"] --> Daemon Brand["Design system and craft: brand and universal rules"] --> Daemon Plugin["Plugins: distribution and workflow context"] --> Daemon Daemon --> Agent["Existing coding-agent CLI: model and tool loop"] Agent --> Files["Project files"] Files --> Preview["Sandboxed preview"] Files --> Export["Export and handoff"]

The diagram's most important arrow is not the one from the brief to the agent. It is the path through the daemon and back into project files. The daemon is the point at which a request becomes a governed run: it knows which project is active, which context should be composed, which runtime was selected, and how output becomes state. The agent is still the executor, but the project is not merely a by-product of the agent's terminal session.

This also explains why files are central rather than incidental. A SKILL.md can be versioned, copied, reviewed, and used by more than one compatible agent. A DESIGN.md can express a team's visual language in a form that is visible to people and available to the next run. An HTML artifact can be opened by a preview renderer, handed to an engineer, or exported into another format. The file is a boundary between conversations: it can outlive the model that produced it and provide a concrete object for critique.

OpenDesign therefore does not need every agent to behave identically. Its bet is that agents can differ at the execution boundary while still sharing a project and a set of portable instructions. That is a more modest promise than “one model will understand every design task in the same way,” but it is also a more durable one. The thing being standardized is the workflow surface and the artifact, not the intelligence behind every turn.

Four layers meet around one project

The repository organizes this substrate around four related planes. Functional skills carry agent behavior: they tell a compatible agent how to perform a kind of work. Rendering templates provide a more opinionated starting shape, such as a SaaS landing page or a deck, so the agent is personalizing a known output surface rather than designing from a blank page. Design systems carry brand rules. Plugins package these pieces for discovery, typed inputs, context resolution, and repeatable application.

The distinctions are important because “context” is not one undifferentiated block. A skill might require a sequence of actions and a particular output file. A template might require the agent to start from a prebuilt skeleton. A design system might determine the type scale, palette, spacing, and component shapes. A plugin might say how those resources are discovered and what permissions or stages a run needs. If all four were flattened into a single opaque prompt, a reader could no longer tell whether a visual decision came from the brand, the artifact workflow, or the distribution wrapper.

The SKILL.md convention is the portability floor. Its body is ordinary Markdown describing a workflow, and optional OpenDesign metadata can add mode, preview, scenario, inputs, design-system participation, or craft references. The metadata helps the host application expose a richer picker or form, but it is additive: the underlying skill remains readable by agents that understand the broader Agent Skills convention. This lets an author keep the behavior portable while still making it discoverable inside OpenDesign.

A small SaaS landing skill makes the mechanism concrete. It asks the agent to read the active DESIGN.md, plan a hero, feature section, social proof, pricing, and calls to action, then write one self-contained HTML file. It also places limits on accent use, requires semantic structure, and asks for responsive checks. Those instructions are not the same thing as a visual brand. They define how to build the artifact. The active design system supplies the brand decisions that the skill is required to respect.

The design-system package adds a second channel to the conversation. DESIGN.md is the human-readable contract: it can describe atmosphere, typography, hierarchy, component behavior, and the reasoning behind a palette. tokens.css is the machine-readable binding: semantic custom properties give the agent and the generated page named values to reuse instead of asking the model to remember a set of colors from prose. A Linear-inspired package in the repository illustrates the difference. Its prose describes a dark, precision-oriented interface, Inter Variable typography, a distinctive intermediate weight, tight display tracking, restrained indigo accents, and translucent borders. Its token file binds those decisions to variables for surfaces, foregrounds, borders, accent states, type scale, spacing, radius, focus, and motion.

That prose-plus-token pattern is more than a convenience for styling. It makes a brand reviewable and reusable. A team can inspect the design contract as a file, update a token without rewriting every skill, and apply the same system to a prototype or a deck. The repository also supports richer evidence such as component fixtures, manifests, previews, and importer material when a brand needs them. Older design-system folders containing only DESIGN.md remain readable, which lowers the migration cost from informal prompt guidance to a structured package.

The fourth plane, plugins, turns these resources into a product-level workflow. A plugin can expose a use-case query, typed inputs, previews, context chips, assets, connector or MCP requirements, and a pipeline. It does not have to replace the portable skill; it wraps the skill so the user can select it, fill in missing information, see what context will be applied, and start a run from the same project surface. That is why the repository calls the plugin an agent-era unit of distribution rather than a traditional canvas extension: the active process is the agent run, not a hidden panel inside the UI.

There is a practical boundary inside this composition. The daemon stages selected skill resources into a project-private working copy for the agent to read; it does not install them into the agent's global skill directory as a side effect of every run. User-managed entries can shadow bundled entries by identifier, and the daemon can discover changes by rescanning its roots. These choices support local experimentation and compatibility, but they do not make arbitrary skills trustworthy. Portability concerns where instructions can travel. Trust concerns what those instructions and the selected agent are allowed to do.

The promise is continuity, not magic

Once the pieces are separated, OpenDesign's promise becomes easier to state. It can give a design task continuity across three boundaries that are often disconnected: the agent boundary, the brand boundary, and the artifact boundary. The agent can change without forcing the team to rewrite every workflow. The brand can change in one design-system package rather than in every prompt. The artifact can continue into preview, critique, engineering handoff, or export as a real project file.

That continuity is visible across the project's different surfaces. A prototype, live dashboard, deck, document, image, video, or HyperFrames composition may use a different rendering contract, but each is treated as a project deliverable with a host surface around it. A deck needs navigation and print behavior. A media run needs provider and model controls rather than interface tokens. A prototype may need a responsive preview. The common architecture is therefore not a single visual format; it is the ability to route specialized work into a common workspace and handoff system.

The same design creates limits. OpenDesign does not become Figma simply because it previews HTML, and a previewable artifact is not automatically a production application. It does not make Codex, Claude Code, OpenCode, or another supported runtime equivalent. Their authentication, model discovery, streaming, permissions, and resume behavior remain different. Nor does a DESIGN.md guarantee that an agent will follow every rule. The repository uses craft references, self-checks, critique stages, and host contracts to reduce drift, but those are controls around model behavior, not an aesthetic oracle.

Local-first also moves responsibility rather than eliminating it. Keeping the daemon and project state near the user's data can reduce dependence on a central design service and makes bring-your-own-agent or bring-your-own-key workflows possible. But the operator must then understand the selected CLI's authority, the plugin's capabilities, the daemon's network exposure, and the difference between a sandboxed preview and a sandboxed process. The open surface is valuable precisely because it is open; it cannot be treated as a sealed appliance.

The most useful mental model is thus neither “OpenDesign generates designs” nor “OpenDesign is only a wrapper.” It is a coordination layer that turns an existing agent into one participant in a longer-lived design system. The agent supplies execution. Portable files supply behavior and identity. The daemon supplies project continuity and control surfaces. The preview and export paths make the result inspectable. The unresolved question—and the one the next part of this series follows—is how a concrete brief moves through that arrangement: which component decides what, which component writes what, and why local-agent and API-based runs need different ways to hand off the same artifact.

References