Skip to content

agentsorg/design-engineering

v2.7.2MIT

Design engineering for AI agents — a navigable skill graph covering animation timing, transitions, typography, color, components, layout, accessibility, anti-patterns, sound, SVG, and launch films, plus ten workflow subagents and an eve runtime. Distills Emil Kowalski, Benji Taylor, Jakub Antalik, guidelines.sh, Vercel, Ben DC, DiceBear, lucide-animated, Google Labs design.md, Agentation, and Index.

GitHubOpen Website

design-engineering

skills.sh CI License: MIT

Design engineering for AI agents — the invisible details that make UI feel right. Distills Emil Kowalski (animation), Benji Taylor (delight + Agentation), Jakub Antalik (transitions), James Frewin (guidelines), Vercel (web-interface rules), Ben DC (CSS conventions), Google Labs design.md (design-token format), lucide-animated (icon animation), DiceBear (avatars), Index (design vocabulary), Apple's audio-haptic principles, Josh Comeau (use-sound), bruno / superfx (launch-video sound), and 47 launch films measured frame by frame (Skale's portfolio, HeyGen's HyperFrames launches, and 18 acclaimed 2024–26 films) into one navigable skill graph.

Not a tutorial. Not a doc site. A working memory the agent loads when you're reviewing UI code, picking an easing curve, designing a component, deciding whether a send button should make a sound, or asking "why does this feel flat?"

npx skills add AgentsORG/design-engineering

Launch film

The first ten seconds of the launch film: "Your agent ships UI." with "UI." slamming in, AI-default tells stamping in faster and faster, a cursor pressing Review and the ink filling the frame, a Before / After / Why review striking each tell, and the name flapping in slot by slot

The first ten seconds of a 34.6 s launch film for this repo, made with the skill's own rules. Watch the whole film with sound. It ends on one command: npx skills add AgentsORG/design-engineering.

The picture is Skale's UI-motion register, which pov.md names as the default for an unspecified launch film:

  • The UI is rebuilt as vector and the type carries the script.
  • The newest word lands in the accent, then settles.
  • Every hold creeps on its entry vector, so no frame freezes.
  • Hard cuts hide inside a fill, on a constant ground, or on a palette flip.
  • One montage accelerates into a snap.
  • No spring overshoot and no decorative idle motion.

The sound is OpenAI's register, derived from the motion: a warm sub-heavy bed in F, dry clicks on every stamp and thuds on the big landings. The sub is pulled before the name, before the counters snap and before Enter. Nothing is picked from a library.

Measured like the corpus. The render was measured at its native frame rate with the same script that measured the 47 reference films (docs/research/launch-films/):

  • One detectable hard cut in 34.6 s (the palette flip); the others sit inside fills.
  • 6.8 % of frames still (Skale's UI-motion films: 9 %).
  • 45 moves a minute, with a 0.52 s median.
  • The first word at 0.07 s, the name at 6.75 s (19 % of the runtime), a 4.4 s endcard.
  • −18.5 LUFS integrated, −2.2 dBTP; half of the strong hits land within 67 ms of a motion peak.
What you seeWhat made it
The compositiondocs/demo/hyperframes/: a HyperFrames 0.8.82 project with one sub-composition per scene. The eases are in assets/film-motion.js: exponential settles sized to each move and seeded typing. The storyboard carries the register, the acts, the cue map and HyperFrames blueprint citations for every scene. check passes with 0 errors, 0 warnings and 75/75 contrast checks. launch-video-registers, launch-video-structure, launch-video-type
The seamsEight, typed in the ledger: a click that fills the frame, a cut on a constant ground, a dive through the caret, cut-the-curve on the film's leftward current, a playhead that widens into a fill, a rising hard cut on a palette flip, and a carrier dot that paper grows out of. Seam values are HyperFrames' stamp values, written by hand. launch-video-seams, launch-video-cuts, hyperframes-reconciliation
The soundOne stereo stem rendered by scripts/sound-sheet.mjs from a cue sheet: 138 cues, 240 onsets, three dropouts, keystrokes on their seeded onsets. Each cue sits on its motion's contact frame; size sets pitch and x sets pan. In the sound scene, the on-screen events play the sounds they are labelled with. launch-video-sound, sound-from-motion, sound-motion-sync
The typeInstrument Sans (OFL, shipped in assets/fonts/) with JetBrains Mono as the system voice. Words land 0.167 s apart, and the command types at 15.4 characters a second, read speed.

Re-render it yourself:

cd docs/demo/hyperframes && npm run check && npm run render

What /design-engineering produces

Frames from the film, each an output shape of the skill.

Benchmarks: with and without the skill

The skill ships its own DesignBench-style fixtures — generation, edit, and repair tasks with deterministic must_match / must_not_match rules tied to the review checklist — and a runner that scores real outputs. Same model in both arms; the only difference is whether the agent read SKILL.md and followed its routing before answering. Scoring looks only at the code each arm shipped, not the prose around it.

armrules passedfixtures fully clean
Sonnet, own knowledge32 / 36 (89%)7 / 10
Sonnet + /design-engineering35 / 36 (97%)9 / 10

Run of 2026-09-05, ten scorable fixtures, one sample each — a floor check, not a leaderboard. Per-fixture results, every rule each arm missed, and all twenty raw outputs are in evals/results/2026-09-05-sonnet/. What the skill fixed: the card-hover edit (named transition properties, a hover: hover guard, a smaller lift), the dark-mode repair (a lifted surface instead of #000), the icon toolbar (hover: hover). What it still missed: one login form shipped 15 px inputs, which zoom on iOS.

One fixture, both arms — edit-hover-01: "Make the card lift on hover."

Input:

.card { transition: all 0.3s ease-in; }
.card:hover { transform: translateY(-4px); box-shadow: 0 16px 32px rgba(0,0,0,0.3); }

Without the skill (3 of 5 rules):

.card {
  transition: transform 0.2s ease-out, box-shadow 0.2s ease-out;
}
.card:hover {
  transform: translateY(-4px);
  box-shadow: 0 16px 32px rgba(0,0,0,0.3);
}

With the skill (5 of 5):

.card {
  transition:
    transform 160ms cubic-bezier(0.25, 1, 0.5, 1),
    box-shadow 160ms cubic-bezier(0.25, 1, 0.5, 1);
}

@media (hover: hover) {
  .card:hover {
    transform: translateY(-1px);
    box-shadow:
      0 1px 1px rgba(17, 17, 17, 0.04),
      0 2px 4px rgba(17, 17, 17, 0.04);
  }
}

@media (prefers-reduced-motion: reduce) {
  .card {
    transition: box-shadow 160ms cubic-bezier(0.25, 1, 0.5, 1);
  }

  .card:hover {
    transform: none;
  }
}

Reproduce: produce the two arms with any agent that can read files (prompts are the fixture rows in design-bench.jsonl), then:

node evals/run-bench.mjs evals/results/<run>

The eve evals in evals/ are the other half: five defineEval() checks (review format, motion values, sound values, launch-film numbers, and the generated-modal floor) run with npm run eval. The methodology behind both is in references/meta/design-benchmarks.md.

The four primitives

Since v2.0.0 the repo is organized around four primitives, each owned by an open spec, each independently useful:

PrimitiveWhat it isWhereSpec
KnowledgeThe skill graph — 120 atomic, wikilinked nodes in 12 themed clusters, plus three generation scriptsskills/design-engineering/Agent Skills
PackageThe portable plugin — one manifest, portable skills, namespaced client extensionsplugin.json + skills/Agent Plugins v1.0.0
RuntimeA durable agent that runs the knowledge — root agent, ten specialist subagents, scored evalsagent/ + evals/eve
Client extensionsPer-host adapters — subagents, slash commands, host manifests, shadcn registryagents/, commands/, .claude-plugin/, .codex-plugin/, .cursor-plugin/, .plugin/, registry.json + r/per host

The knowledge is the core; everything else is a delivery mechanism for it. plugin.json declares the client extensions under reverse-domain namespaces (com.anthropic.claude-code, com.openai.codex, com.cursor.editor, dev.vercel.plugins, dev.eve.agent) so any Agent Plugins client can discover what this repo ships and ignore what it doesn't implement.

Install

The fastest path is the one-liner at the top — npx skills add AgentsORG/design-engineering. It uses the skills.sh CLI to install into your detected agent (Claude Code, Cursor, Windsurf, Codex, Gemini, Cline, Aider, and 18+ others). The CLI prompts for scope (project vs. global) and method (symlink vs. copy).

Plugins CLI (Claude Code + Cursor + Codex)

Install the full plugin bundle — skill graph, ten workflow subagents, and slash commands — in one step via vercel-labs/plugins:

npx plugins add AgentsORG/design-engineering

# Dry run — see skills, agents, and commands before installing
npx plugins discover AgentsORG/design-engineering

Restart your agent tools after install. Slash commands (when your host supports them) include /design-engineering:review-ui, /design-engineering:motion-audit, /design-engineering:scan-ai-tells, /design-engineering:agentation-fix, /design-engineering:apply-design-md, /design-engineering:fork-pov, /design-engineering:sound-pass, /design-engineering:svg-create, /design-engineering:svg-animate, and /design-engineering:film-review.

Per-agent install

The repo ships host manifests so you can install via each agent's native plugin system:

Claude Code — .claude-plugin/marketplace.json + .claude-plugin/plugin.json; skills under skills/ auto-discover.

/plugin marketplace add AgentsORG/design-engineering
/plugin install design-engineering

Codex — .codex-plugin/plugin.json with the full interface block.

codex plugin marketplace add AgentsORG/design-engineering --sparse .codex-plugin --sparse skills

Cursor — .cursor-plugin/plugin.json; install via the Cursor Marketplace or Settings → Plugins → Load unpacked.

All manifests share name, version, description, author, homepage, repository, and license; the root plugin.json is canonical and CI enforces version parity across all six plus SKILL.md.

shadcn CLI

The repo doubles as a shadcn registry, so a frontend project can pull the skill — or just its motion tokens — with the CLI it already has:

# The full skill graph → .agents/skills/design-engineering/
npx shadcn@latest add https://raw.githubusercontent.com/AgentsORG/design-engineering/main/r/design-engineering.json

Four items ship:

ItemInstallsInto
design-engineeringThe full skill graph (markdown, eval fixtures, and all three scripts).agents/skills/design-engineering/
design-engineering-agentsTen subagents + ten slash commands.claude/agents/, .claude/commands/
design-engineering-design-fileThe starter .design contract.design at project root
design-engineering-motionMotion tokens as theme CSS variablesyour global CSS

Swap the filename in the URL for any of them. The motion item is the lightest way in — four easing curves and a duration scale, no skill install:

npx shadcn@latest add https://raw.githubusercontent.com/AgentsORG/design-engineering/main/r/design-engineering-motion.json

That gives you --ease-out-quart, --ease-out-expo, --ease-in-out, --ease-spring, and --duration-press through --duration-page. On Tailwind v4, register the ones you want utilities for under @theme inline. Preview any item before installing with --dry-run, or read it with npx shadcn@latest view <url>.

Registry sources live in registry.json; the built, content-embedded items in r/ are generated by npm run build:registry and committed so the raw URLs resolve.

Run it as an agent (eve)

The repo is also a runnable eve project — a durable backend design-engineering agent with the skill graph seeded into its sandbox and ten specialist subagents it can delegate to:

npm install
npm run dev      # syncs the skill graph into agent/skills/ and starts eve dev
npm run eval     # scored checks: review-format table contract, concrete motion values

agent/instructions.md is the identity (distilled from SOUL.md), agent/agent.ts the runtime config, agent/subagents/<name>/ the specialists (each with its own agent.ts description the root reads to decide when to delegate), and evals/*.eval.ts the regression gates. agent/skills/ is generated by scripts/sync-skills.mjs from the canonical skills/design-engineering/ — single source of truth, two consumers.

Recommended companions

# Obsidian — view + edit the skill graph in a real graph view
# https://obsidian.md → "Open folder as vault" → pick this repo

# Agentation — click-to-annotate design review in your localhost dev environment
npx skills add benjitaylor/agentation

Obsidian turns the wikilinks-and-frontmatter graph into a navigable canvas. Agentation (agentation.com) mounts a toolbar in your dev environment so annotations become structured markdown your agent can act on — see [[pointing-beats-describing]] and [[agentation-workflow]].

Paste this into your coding agent

Drop the block below into your agent's instructions / AGENTS.md / .cursorrules / system prompt:

You have access to the design-engineering skill — a navigable graph of
opinionated, source-cited design-engineering knowledge. Load it when the
user is reviewing UI code, designing a component or page layout, picking
an easing curve or transition pattern, deciding "should this animate at
all?", choosing an avatar / typography / color system, auditing for
AI-default tells, or asking "why does this feel flat?"

- Repo:        https://github.com/AgentsORG/design-engineering
- Skill root:  skills/design-engineering/
- Install:     npx skills add AgentsORG/design-engineering

Navigation:
- Route first: references/meta/routing-table.md maps intent → entry node
  and names the four postures (build / judge / decide / name).
- When two intents blur, references/meta/disambiguation.md names the
  tiebreaker; multi-cluster jobs follow references/meta/stacking-chains.md.
- SKILL.md is a thin Map of Content with [[wikilinks]] to atomic nodes in
  11 themed folders: philosophy, motion, sound, svg, launch-video,
  typography, surface, components, layout, anti-patterns, meta. Wikilinks
  resolve by basename.

Rules:
1. For any UI code review, use the Before | After | Why table from
   references/meta/review-format.md, scanned against
   references/meta/review-checklist.md.
2. Cite the node basename you used (e.g. [[easing-curves]]). Don't
   paraphrase a node without naming it.
3. Prefer reading a specific references/<theme>/<node>.md over the whole
   SKILL.md — cheaper on context; the graph is built for it.
4. Before producing UI code or a review, load references/meta/gotchas.md
   (lived failures) and references/meta/pov.md (installer overrides).

Smoke test: "review this CSS for a modal animation" → open
references/meta/review-format.md first, then the relevant motion nodes
([[easing-curves]], [[duration-table]], [[never-scale-from-zero]]).

What's included

One skill, organised into 12 themed clusters, fronted by a router: /design-engineering resolves the project's design contract, classifies the phase of the work, and hands the job to one owner — a node here, one of ten subagents, or an installed companion skill (AgentsORG design, impeccable, HyperFrames, ElevenLabs, transitions-dev, the shadcn CLI, diagram-design, tldraw, GSAP, better-icons). See references/meta/skill-router.md. Each cluster has its own MOC (meta indexes from SKILL.md directly).

ThemeUse it when…
philosophyJustifying polish, picking between two valid approaches, debating delight budget. The "why bother" cluster.
motionAdding or reviewing any animation. Easing, durations, springs, gestures, transitions, stagger. The largest cluster.
soundDeciding whether an interaction should make a sound (usually no), designing one material family, syncing transients to frames, generating files — ElevenLabs on demand or open-weight / procedural / CC0 without a key — scoring a launch video in the register its picture sets, placing a music track or a voice under it, and deriving a video's whole stem from its motion. Ships scripts/sound-family.mjs and scripts/sound-sheet.mjs.
svgCreating clean, token-aware, editable SVG; animating it with the engine its home allows (inline CSS/WAAPI, embedded keyframes or SMIL for image use); morphing paths by the command-count rule; turning flat clips into editable animated mascots. Ships scripts/svg-flipbook.mjs.
diagramDeciding whether a picture earns its place and which surface it lives on: a finished figure for readers, an editable tldraw canvas, a Mermaid block or FigJam. The craft of a figure (deletion, focal accents, the six connector rules), how a .design contract maps into Cathryn Lavery's diagram-design, and the canvas rules for tldraw's Desktop skill and MCP app.
launch-videoPlanning, cutting, scoring and reviewing a launch film: registers measured across 47 films, beat timings, seams and cuts, film motion, type, UI demo, HyperFrames reconciliation. These are film numbers; they don't transfer to product UI.
typographyPicking a typeface, building a type scale, leading, tracking, wrapping, truncation, underlines, the 16px and contrast floors. Avoiding AI-default font tells.
surfaceColor palette and OKLCH ramps, dark mode, shadows and nested radii, hairlines, image outlines, visual imperfection.
componentsButtons, hovers, empty/loading states, cards, forms (validation and behavior), touch and focus, the polish pass, component APIs, avatars, icons, a11y, copy.
layoutPage-level grids, viewports, sticky chrome, URL-as-state, marketing / docs / blog surface rules.
anti-patternsAuditing for "could this have been generated in 30s with a prompt?" tells — visual, copy, and code — and the unslop pass that removes them. The deletion cluster.
metaThe /design-engineering skill router, routing (routing-table, disambiguation, stacking-chains), review format + checklist, .design and DESIGN.md consumption, design-system docs for agents, prototyping behind a picker, tools before artifacts, skill-writing rules, design benchmarks, Agentation workflow, gotchas, pov.

Structure: a skill graph, not a SKILL.md file

The skill is a graph, not a single file (per Akshay Pachaar's "Skill Graphs > SKILL.md"):

  • SKILL.md is a Map of Content — short descriptions of every cluster, plus [[wikilinks]] to follow.
  • references/<theme>/MOC-<theme>.md is the topic hub for each theme.
  • references/<theme>/<node>.md are atomic concept files — one complete thought each, 40–80 lines, with YAML frontmatter and outbound [[wikilinks]].
  • references/meta/routing-table.md is the entry router: classify the intent, open exactly one node. Most decisions happen before reading a single full node.
  • Wikilinks resolve by basename across the whole graph — themed subfolders are organizational, not namespaces.
  • The skill follows Perplexity's progressive-disclosure pattern — three tiers of context cost (index → SKILL.md body → on-demand nodes).

Repository layout

design-engineering/
├── plugin.json                        ← canonical Agent Plugins v1.0.0 manifest (portable core + extensions)
├── package.json                       ← eve app root (npm run dev / eval / sync:skills)
├── tsconfig.json
├── README.md
├── AGENTS.md                          ← repo-level agent guidance (the "what / how")
├── SOUL.md                            ← identity layer (the "who / why") — voice, taste lineage
├── CONTRIBUTING.md / CODE_OF_CONDUCT.md / SECURITY.md / CHANGELOG.md / LICENSE
├── .github/workflows/lint.yml         ← markdownlint + frontmatter + wikilinks + manifest parity
├── .claude-plugin/                    ← Claude Code manifest + marketplace   (com.anthropic.claude-code)
├── .codex-plugin/                     ← OpenAI Codex manifest                (com.openai.codex)
├── .cursor-plugin/                    ← Cursor IDE manifest                  (com.cursor.editor)
├── .plugin/                           ← vendor-neutral plugins-CLI manifest  (dev.vercel.plugins)
├── agents/                            ← ten workflow subagents (Claude Code subagent format)
├── commands/                          ← ten slash-command workflows
├── agent/                             ← eve runtime                          (dev.eve.agent)
│   ├── agent.ts                       ← defineAgent() — model + runtime config
│   ├── instructions.md                ← base system prompt, distilled from SOUL.md
│   ├── skills/                        ← generated: skill graph synced in (gitignored)
│   └── subagents/<name>/              ← agent.ts (description + model) + instructions.md × 10
├── evals/                             ← eve evals: defineEval() scored checks
│   ├── evals.config.ts
│   ├── review-format.eval.ts          ← review requests must return the Before|After|Why table
│   ├── motion-values.eval.ts          ← easing advice must name concrete values
│   ├── sound-values.eval.ts           ← sound advice names a duration, a level, or says "no sound"
│   ├── launch-values.eval.ts          ← launch-film advice names seconds or a share of runtime and a cut rate per minute
│   ├── design-bench.eval.ts           ← generated UI passes the review-checklist floor (DesignBench-style repair)
│   ├── run-bench.mjs                  ← scores with/without-skill outputs against design-bench.jsonl
│   └── results/<run>/                 ← raw outputs of both arms + REPORT.md
├── scripts/sync-skills.mjs            ← skills/ → agent/skills/ (single source of truth)
├── registry.json                      ← shadcn registry source          (com.shadcn.registry)
├── r/                                 ← built registry items (generated, committed for raw URLs)
├── scripts/build-registry.mjs         ← registry.json + r/*.json builder
├── spec/                              ← offline mirrors: agent-skills-spec.md, design-md-spec.md, design-file-spec.md
├── templates/design-engineering.design ← starter .design contract (this skill's motion + surface defaults)
├── docs/brand/                        ← AgentsORG wordmark (light / dark) and icon
├── docs/research/launch-register/     ← the scripts and summaries that measured the OpenAI launch-film register
├── docs/research/launch-films/        ← the native-fps measurements behind the launch-video cluster: 29 Skale pieces, 18 acclaimed films, 3 HeyGen renders
├── docs/demo/                         ← the launch film: HyperFrames source + storyboard + ledger, MP4/GIF, screenshots, the stem and cue sheet
├── template/TEMPLATE.md
└── skills/design-engineering/         ← THE KNOWLEDGE (portable core)
    ├── SKILL.md                       ← thin Map of Content
    ├── evals/                         ← Step-0 routing fixtures (loading.jsonl, progressive-reads.jsonl)
    ├── scripts/                       ← sound-family.mjs (ElevenLabs or offline synth), sound-sheet.mjs (motion cue sheet → stereo stem), svg-flipbook.mjs (frames → animated SVG)
    └── references/                    ← 12 themed clusters, 120 atomic nodes, 11 MOCs

Total: 120 atomic nodes across 12 clusters (134 markdown files in the skill), 10 workflow subagents ×2 formats, 10 commands, 5 eve evals plus the design-bench runner, 6 plugin manifests, 3 scripts.

Agent Plugins conformance

The repo follows the Agent Plugins specification v1.0.0:

  • plugin.json at the root with $schema: https://agent-plugins.org/schemas/1.0.0/plugin.schema.json — the portable identity.
  • skills/ — each immediate child directory containing a SKILL.md is one skill, per the Agent Skills spec (mirrored offline at spec/agent-skills-spec.md).
  • Client extensions are declared in plugin.json under extensions, keyed by reverse-domain namespace. Clients that don't implement a namespace ignore it — a Cursor install never parses the eve runtime; an eve deploy never parses the Codex interface block.
  • No mcp.json — this plugin ships no MCP servers (Agentation's MCP is a companion install, not bundled).

View and edit in Obsidian

The graph of .md files connected by [[wikilinks]] with YAML frontmatter is the exact shape Obsidian was built for. Open folder as vault → pick this repo root → Ctrl/Cmd + G for the graph view. MOC-<theme>.md files are the hubs. Recommended companion: kepano/obsidian-skills.

Customize for yourself

When you install this skill, edit two files to make it yours:

  • skills/design-engineering/references/meta/pov.md — your opinions, taste calls, and overrides on defaults.
  • skills/design-engineering/references/meta/gotchas.md — append a one-liner every time your agent gets a UI detail wrong.

These two files are designed to be edited per-installer. Everything else should stay close to canonical.

Contributing

PRs welcome. The shorter the better. See CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, CHANGELOG.md. CI runs markdownlint, frontmatter validation, required-files, wikilink resolution, and six-manifest version parity on every PR.

Sources

See also

License

MIT. See LICENSE.