Open-source design agent: on-brand stills, decks, diagrams, charts and motion graphics from a chat thread, built on Deep Agents.
Customization
Everything below is local files: edit them by hand or with your coding agent, then redeploy.
Brand
workspace/brand/ (Git-ignored) holds your pack: brand.toml, tokens.json, fonts.toml,
voice.md, graphic-language.md, logos/. The schema is src/design_agent/brand/schema.py; the
sample pack in examples/brands/example-studio/ shows every field. uv run design-agent brand validate checks it and brand css regenerates tokens.css. The brand-onboarding
skill builds a pack from your sources.
Colour roles: design.roles.light and design.roles.dark in tokens.json name the token for each
role (ground, ink, accent, muted, quiet, rule, and a series list). Charts and diagrams
use them; a role you leave out is measured from the palette.
Fonts: each family in fonts.toml points at an open font in fonts/ or a licensed file in
private-fonts/ (Git-ignored), and family is the name inside the file (fonts verify checks it).
Web formats work: tokens.css declares .woff2 and .woff faces with @font-face. Licensed fonts
reach the sandbox as deployment files (MDA) or a read-only mount (self-hosted), never through Git.
Instructions and skills
Two folders hold skills. .agents/skills/ is for coding agents working on this repo (onboarding,
brand setup, deploy, evals); skills/ is what the agent itself reads at work.
instructions.mdis the always-loaded prompt: identity, how the agent works, delivery and approval rules, how it talks. Keep it short; the budget test fails past about 8k tokens.skills/<name>/SKILL.mdare workflows the agent opens when a job needs them. Add one for a format your team makes often (a newsletter header, a conference kit): a one-line "when to use" description, steps, sizes, the gates to run, and links toreferences/for depth. Keep the folder to text: MDA syncs it to Context Hub, which takes only UTF-8, so a skill's fonts or images go inskill-binaries/<name>/and reach the sandbox beside the skill.- Rules come with evidence or are phrased as defaults; brand facts belong in the brand pack, not in skills.
Learning
After a job the agent can save what it learned for the skill it used (save_observations), or
have a quick helper propose observations (learn_from_job). Before a similar job it reads them and
rates the ones that helped. Observations live in the deployment's store and are notes the agent
weighs, never rules. Turn it off with DESIGN_AGENT_ENABLE_LEARNING=0.
Traces
The agent reads its own LangSmith traces: list_traces finds runs by time, thread, trigger or
failure, and read_trace writes one run tree to the workspace with its errors and slowest steps.
Ask it in the thread ("why did the last render fail?") and it can look. It reads only the project
its runs are traced to, but every thread in it: turn it off with DESIGN_AGENT_ENABLE_TRACES=0
where people must not see each other's requests (SECURITY.md).
MCP servers
Integrations sets up the hosted ones (Notion, Linear, GitHub, Figma and more) in
a few commands. Copy config/mcp.example.toml to config/mcp.toml and declare servers there. Every runtime names
their tools {server}_{tool}; the agent discovers them on demand, so many servers do not crowd its
context. Locally, header values come from your environment (headers_env); on MDA a server that
needs credentials names a workspace connection (connection), owned by the deployment or by each
person (owner). A local app's own server can run
over stdio (transport = "stdio" with a command) locally and self-hosted; MDA serves HTTP and SSE
only and leaves it out. A server that fails to load or errors leaves the rest working. Paper is
configured with PAPER_* instead (Paper), so do not declare a paper server.
Settings
uv run design-agent config show lists every setting with its current value (secrets as set or
unset); .env.example documents each one.