← All posts

tool guides · 6 min read

The DesignMD skills layer: making Claude natively design-aware

Skill files let you inject design system knowledge directly into Claude's context. Here is how the DesignMD skills layer works and how to use it.

Claude does not know your design system by default. It knows design systems in general — common patterns, reasonable defaults, what most Tailwind configs look like. But that is different from knowing your specific tokens, your motion language, your component constraints.

DESIGN.md solves this for visual design. Skill files solve it for tooling.

What a skill file is

A skill file is a markdown document — named SKILL.md by convention — that you inject into Claude's context. It is not code. It is structured knowledge that tells the model how to use a specific tool the way an expert would use it.

Think of the difference between Claude generating a Framer Motion animation from general knowledge versus generating one from a document that says: prefer useAnimate over animate for imperative controls, use the layout prop for automatic layout animations, reach for AnimatePresence for exit animations, and here are the exact spring configs that work well for different interaction types.

The output from the informed version is measurably different. Not because Claude learned something new — it already knows Framer Motion — but because the skill file collapses the space of reasonable choices toward the choices that actually work.

The four DesignMD skills

DesignMD ships four skill files, each covering a different layer of the frontend stack:

designmd — How to read and apply DESIGN.md files. Covers token interpretation, how to map design tokens to Tailwind classes, how to handle tokens that do not have direct Tailwind equivalents, and what to do when a DESIGN.md is incomplete. This is the meta-skill. Add it if you are using any DESIGN.md file in your project.

framer-motion — Opinionated guidance on Framer Motion. Covers: when to use motion.div versus useAnimate, exit animation patterns with AnimatePresence, layout animations with the layout prop, spring configurations for interactive elements versus transitions, and stagger patterns for lists. Also covers common mistakes — like animating width with animate when layout would give better results.

tailwind — Goes beyond what Tailwind's docs cover. Focuses on the decisions that require judgment: when to use @apply versus inline classes, how to structure responsive variants cleanly, when to reach for arbitrary values versus extending the config, how to keep a long className from becoming unreadable.

shadcn — Covers shadcn/ui component patterns. How to extend components without breaking their accessibility contracts, how to compose primitives into complex UI, how to handle theming through CSS variables, and which components to reach for versus build from scratch.

How to download and use them

The skill files live at designmd.co/skills/[name] and can be downloaded directly:

curl -o content/skills/framer-motion.md https://designmd.co/skills/framer-motion
curl -o content/skills/tailwind.md https://designmd.co/skills/tailwind
curl -o content/skills/shadcn.md https://designmd.co/skills/shadcn
curl -o content/skills/designmd.md https://designmd.co/skills/designmd

Once downloaded, you wire them into Claude's context through CLAUDE.md:

# Design system
@content/designs/my-project.md

# Skills
@content/skills/designmd.md
@content/skills/framer-motion.md
@content/skills/tailwind.md

Claude reads these at the start of every session. The skills are in context before you write your first prompt.

CLAUDE.md integration

The placement matters. Put skills after your design system reference, not before. The skill for designmd should appear before any specific tool skills, since it governs how the other token files are interpreted.

A complete CLAUDE.md setup:

# Project context
This is a Next.js project using App Router, Tailwind, and Framer Motion.

# Design system
@content/designs/my-project.md

# Skills  
@content/skills/designmd.md
@content/skills/framer-motion.md
@content/skills/tailwind.md
@content/skills/shadcn.md

That is it. From this point, every component Claude generates uses your tokens correctly, your animation library idiomatically, and your utility framework without the common anti-patterns.

The MCP alternative: get_skill

If you are using the DesignMD MCP server, there is a get_skill tool that retrieves skill files on demand rather than pre-loading them all into context.

The MCP approach is useful when you are working across multiple projects with different tool combinations and do not want all four skills loaded all the time. The cost of loading four skill files is negligible for most projects, but if you are context-budget conscious, pull only what you need.

Usage:

get_skill("framer-motion")

This returns the current version of the Framer Motion skill file. The MCP server always serves the latest version, so you get improvements without re-downloading.

A concrete workflow

You want to add a staggered list entrance animation to a component. Here is how it plays out with the framer-motion skill loaded:

Prompt: "Add an entrance animation to this list. Items should stagger in from below with a spring feel."

Without the skill, Claude might use animate on each item, hardcode a delay prop, and produce something that works but has arbitrary timing values and no exit behavior.

With the skill, Claude knows to:

  1. Wrap the list in AnimatePresence
  2. Use motion.li with initial, animate, and exit variants
  3. Pass a custom index to each item for stagger calculation
  4. Use the spring config from the skill (stiffness: 300, damping: 30) rather than a duration-based ease
  5. Add a layoutId if the list items can reorder

The skill does not add magic. It adds specificity. And specificity is what closes the gap between "works" and "feels right."

What the skills layer is not

It is not a replacement for reading the docs. If you are building something novel with Framer Motion, you still need to understand how the library works. The skill file encodes judgment, not exhaustive API knowledge.

It is also not a substitute for your own DESIGN.md. The tailwind skill knows how to use Tailwind well; it does not know your specific design tokens. Those live in the DESIGN.md. The skill and the design system work together — one tells Claude how to use the tool, the other tells it what to build.

Together they are the difference between an AI coding assistant that happens to know your tech stack and one that reasons about it the way a senior developer who has worked in your codebase would.