A working library of design principles, packaged as portable Agent Skills plus native plugin metadata for Claude Code, Codex, and Cursor. Install one or more plugins and your agent gains access to curated skills that fire automatically whenever you work on UX, UI, or product design — regardless of design system, SDK, framework, or platform.

Each principle is built as a reference-grade entry: a router-style SKILL.md (~350–500 lines), 2–4 sub-aspect skills for context-specific application (~200–300 lines each), and per-skill references/ deep-dive files with origins, research lineage, and worked patterns. The result is a library an agent can apply with the same depth as a senior designer who has internalized the canon.

Many products today are built and reviewed by AI agents. The quality of their design judgment depends heavily on what they've been taught to attend to. Without a working library of principles, an agent will produce designs that are competent on average but blind in specific ways — the typography will drift, hierarchy will collapse on the third screen, the error states will be afterthoughts, the interaction patterns will be inconsistent across surfaces.

This marketplace gives your agent the same canon that experienced designers have internalized over years. Instead of one giant prompt, the canon is split across five composable plugins so you can install only what you need:

Each plugin contains a router skill (which triggers on the plugin's category and points the agent at the right principle), one main skill per principle, and 2–4 sub-aspect skills for principles whose application varies meaningfully by context (e.g., Hick's Law has different shapes in menus vs. defaults vs. pricing).

Pick the agent you actually use. The same skills/<skill-name>/SKILL.md folders are the source of truth for every install path; only the plugin manifest or destination directory changes.

The packaging follows the Agent Skills open format, where each skill is a folder containing SKILL.md and optional supporting files.

In Claude Code, add this repository as a plugin marketplace and install the plugins you want:

/plugin marketplace add HDeibler/universal-design-principles
/plugin install perception-and-hierarchy-principles@universal-design-principles
/plugin install cognition-and-learnability-principles@universal-design-principles

Use /plugin to browse the remaining plugins. Claude Code plugin skills are namespaced by plugin, so a skill is available as /perception-and-hierarchy-principles:hierarchy when explicitly invoked. Claude can also load skills automatically when the task matches a skill description.

For a local checkout instead of GitHub shorthand:

git clone https://github.com/HDeibler/universal-design-principles.git ~/code/universal-design-principles

Then run:

/plugin marketplace add ~/code/universal-design-principles

Reference: Claude Code plugins, Claude Code skills, and Claude plugin marketplaces.

Codex can install this repository either as one collection plugin or as five focused plugin bundles.

For the single collection plugin, use the root Codex manifest. This is the best path for directories that expect one plugin per repository:

npx codex-marketplace add HDeibler/universal-design-principles --plugin --project

For the five focused plugin bundles, use the repo marketplace:

npx codex-marketplace add HDeibler/universal-design-principles --plugins --project

Codex can also use this repository as a repo-scoped plugin marketplace because it includes .agents/plugins/marketplace.json and each focused plugin includes .codex-plugin/plugin.json.

codex plugin marketplace add HDeibler/universal-design-principles
codex

Inside Codex, open the plugin directory:

/plugins

Choose the Universal Design Principles marketplace and install one or more plugins.

If you only want the skills without plugin metadata, copy the skill folders into a standard Codex skills directory:

git clone https://github.com/HDeibler/universal-design-principles.git ~/code/universal-design-principles
mkdir -p ~/.agents/skills
cp -R ~/code/universal-design-principles/plugins/*-principles/skills/* ~/.agents/skills/

Restart Codex after copying or installing. Codex scans .agents/skills in the repository, parent directories, $HOME/.agents/skills, admin locations, and bundled system skills.

Reference: Codex plugins, Codex plugin authoring, Codex skills, and AGENTS.md discovery.

Cursor has first-class plugin and rules surfaces. This repository includes a Cursor marketplace manifest and per-plugin manifests, matching the structure used by Cursor's official plugin repository.

git clone https://github.com/HDeibler/universal-design-principles.git ~/code/universal-design-principles

In Cursor, open the command palette, choose Add Plugin, and point Cursor at the GitHub repository URL or the local checkout path:

https://github.com/HDeibler/universal-design-principles
~/code/universal-design-principles

If you are not using Cursor plugins yet, use a project rule as a lightweight fallback:

---
description: Use Universal Design Principles when working on UX, UI, product design, visual hierarchy, interaction design, accessibility, or design critique.
alwaysApply: false
---

When the task involves UX or product design, consult the Universal Design Principles skill repository and prefer the most specific principle skill before giving recommendations.

Save that as .cursor/rules/universal-design-principles.mdc. Cursor project rules can be Always, Auto Attached, Agent Requested, or Manual; Agent Requested is the best fit for this kind of optional design expertise.

Reference: Cursor rules, Cursor plugin marketplace, and the Cursor official plugin repo.

Gemini CLI supports Agent Skills directly. Link each plugin's skills/ directory into your user skill store:

git clone https://github.com/HDeibler/universal-design-principles.git ~/code/universal-design-principles

for plugin in ~/code/universal-design-principles/plugins/*-principles; do
  gemini skills link "$plugin/skills" --scope user
done

gemini skills list

Use --scope workspace instead of --scope user when you want the skills available only in the current project. You can also copy selected skill folders into .gemini/skills/, .agents/skills/, ~/.gemini/skills/, or ~/.agents/skills/.

Reference: Gemini CLI Agent Skills, Gemini skills getting started, and Gemini CLI extensions.

For agents that do not yet load SKILL.md folders as skills, use their native rule format to point the agent at this repository, or copy a short subset of the relevant principle guidance into that rule system.

For GitHub Copilot, use .github/copilot-instructions.md, .github/instructions/*.instructions.md, or AGENTS.md depending on your editor surface. For Windsurf, use .windsurf/rules/*.md or AGENTS.md. For any agent that supports the AGENTS.md convention, add a root-level AGENTS.md with a compact instruction such as:

# Design guidance

When working on UX, UI, product design, visual hierarchy, interaction design,
accessibility, or design critique, use the Universal Design Principles skills
from https://github.com/HDeibler/universal-design-principles. Prefer the most specific principle
skill for the task, and use the reference files only when the answer needs
research depth.

Reference: GitHub Copilot custom instructions, Windsurf rules, and AGENTS.md.

This repository now uses a parallel-manifest, single-source skill structure:

universal-design-principles/
├── .claude-plugin/marketplace.json
├── .cursor-plugin/marketplace.json
├── .agents/plugins/marketplace.json
├── plugins/
│   ├── perception-and-hierarchy-principles/
│   │   ├── .claude-plugin/plugin.json
│   │   ├── .codex-plugin/plugin.json
│   │   ├── .cursor-plugin/plugin.json
│   │   └── skills/
│   │       └── <skill-name>/SKILL.md
│   └── ...
└── ...

This is the best structure for the current ecosystem because Claude, Codex, and Cursor each expect different manifest directories, while all of them can consume the same underlying Agent Skills. The root-level marketplace manifests stay where each client expects discovery metadata, and the installable packages live under plugins/ with one shared skills/ tree per package. Duplicating the skills into agent-specific folders would create drift and break deep links.

See docs/getting-started.md for a more detailed walkthrough including verification steps and troubleshooting.

After installing one of the plugins (say, Cognition & Learnability), you can use it like this in any agent conversation:

You: I'm designing a settings page for a SaaS dashboard. The product has
     accumulated about 60 settings across 8 categories. Help me think
     through the structure.

Agent: [loads the cognition-router → progressive-disclosure skill]
       Looking at this through the lens of progressive disclosure and
       the 80/20 rule: roughly 12 of those 60 settings probably account
       for 80% of actual changes. Surface those in a clear default view,
       and tuck the remaining ~50 behind clearly-labeled disclosure...

The skills fire automatically based on the conversation context. You don't have to remember to invoke them.

For more concrete usage examples, see docs/getting-started.md.

Take Hick's Law as an example. Inside plugins/cognition-and-learnability-principles/skills/, you'll find:

hicks-law/
├── SKILL.md                                  # the principle's main entry (~450 lines)
└── references/
    └── lineage.md                            # origins, Hick (1952), Hyman (1953), modern empirical work

hicks-law-menus/
├── SKILL.md                                  # how Hick's Law applies to menus specifically
└── references/
    └── menu-design-patterns.md               # patterns and anti-patterns

hicks-law-defaults/
├── SKILL.md                                  # how Hick's Law applies to defaults
└── references/
    └── defaults-recipes.md

hicks-law-pricing/
├── SKILL.md                                  # how Hick's Law applies to pricing pages
└── references/
    └── pricing-tier-strategies.md

Each main SKILL.md includes:

1. Definition — Plain-language definition in our own words.
2. Origins and research lineage — Where the principle comes from, who studied it, what evidence supports it.
3. When to apply — Surfaces and decisions where the principle is decisive.
4. When NOT to apply — Contexts where the principle backfires or doesn't transfer.
5. Worked examples — Multiple cross-domain examples with code or diagrams.
6. Anti-patterns — Common misapplications and how to recognize them.
7. Heuristic checklist — Concrete questions to ask before shipping.
8. Related principles — What to read next.
9. See also — Links to references/ and to sub-aspect skills.

For the full architecture, see docs/architecture.md.

universal-design-principles/
├── .codex-plugin/
│   └── plugin.json                         # Codex root collection plugin manifest
├── .agents/
│   └── plugins/
│       └── marketplace.json                # Codex marketplace manifest
├── .claude-plugin/
│   └── marketplace.json                    # Claude Code marketplace manifest
├── .cursor-plugin/
│   └── marketplace.json                    # Cursor marketplace manifest
├── docs/                                   # cross-plugin documentation
│   ├── getting-started.md
│   ├── architecture.md
│   ├── how-skills-trigger.md
│   └── principle-index.md
├── plugins/
│   ├── perception-and-hierarchy-principles/    # 34 skills + Claude/Codex/Cursor plugin manifests
│   ├── cognition-and-learnability-principles/  # 33 skills + Claude/Codex/Cursor plugin manifests
│   ├── interaction-and-control-principles/     # 29 skills + Claude/Codex/Cursor plugin manifests
│   ├── aesthetics-and-emotion-principles/      # 17 skills + Claude/Codex/Cursor plugin manifests
│   └── process-and-robustness-principles/      # 24 skills + Claude/Codex/Cursor plugin manifests
├── README.md
├── CONTRIBUTING.md
├── ATTRIBUTION.md
├── CHANGELOG.md
├── LICENSE
├── .gitignore
└── .gitattributes

Browse the Principle Index for the alphabetical list with direct links into the relevant SKILL.md.

The 2003 first edition of Universal Principles of Design contains exactly 100 principles. We have built 42 of them at reference-grade depth — the principles most relevant to modern product, web, and software UX. Each per-plugin README.md lists the next-priority builds; contributions are welcome.

This repository owes its principle names and taxonomy to:

Lidwell, W., Holden, K., & Butler, J. (2003). Universal Principles of Design: 100 Ways to Enhance Usability, Influence Perception, Increase Appeal, Make Better Design Decisions, and Teach through Design. Rockport Publishers. ISBN 1-59253-007-9.

Each principle entry's definitions, prose, code examples, anti-patterns, and analyses are written in our own words, drawing on the broader design and HCI research literature: Wertheimer's Gestalt psychology, Hick (1952) and Hyman (1953) on choice latency, Fitts (1954) on motor capacity, Norman's Design of Everyday Things and Emotional Design, Nielsen's usability work, Tufte on information design, Lynch's Image of the City on wayfinding, the W3C WCAG framework on accessibility, Lavie & Tractinsky on aesthetic-usability, Csikszentmihalyi on flow, Zajonc on the mere-exposure effect, and many others.

The book is a starting point; this plugin set is a working tool. It is not a substitute for the book. If you find this useful, please buy the book — it remains an essential reference and the source of the editorial taxonomy this repository builds on.

For a complete attribution breakdown — including how this repository used the source book, every key research source, and our content-originality commitments — see ATTRIBUTION.md.

• By AI coding agents: install one or more plugins or skill folders; the skills fire automatically when you work on design tasks; the agent applies the principle vocabulary in its reasoning and outputs.
• By human designers: the SKILL.md files are written as standalone documents you can read directly. Many designers use the repository as a personal reference even without an AI tool.
• By teaching contexts: the references/lineage.md files trace the research lineage of each principle and are useful as teaching material.
• By contributors: see CONTRIBUTING.md — the repository is designed to grow incrementally toward covering all 100 principles.

This repository is the vendor-neutral version of the design principle library. Examples are in plain HTML, CSS, and conceptual pseudocode, with cross-domain examples from web, mobile, print, physical product, and information design. You should be able to apply any of these principles whether you're working in shadcn/ui, Material, Carbon, Tamagui, Ant Design, Bootstrap, vanilla CSS, SwiftUI, Jetpack Compose, Figma, or whiteboard markers.

If a sibling repository ships that maps these principles to a specific design system (e.g., universal-design-shadcn), it will be linked here. The two are designed to compose: this one teaches the principle, the other shows how to apply it via specific primitives.

Contributions are welcome and held to a high prose-quality bar. See CONTRIBUTING.md for:

• Structural conventions for adding a new principle.
• The quality bar for prose, examples, and references.
• Attribution rules.
• The pull-request process.

For new-principle proposals, please open an issue first to discuss scope and audience.

This repository is licensed under the MIT License. The principle names and high-level taxonomy are drawn from Universal Principles of Design (Lidwell, Holden, Butler, 2003) under fair use as a research reference; all prose and examples are original work licensed under MIT. See ATTRIBUTION.md and LICENSE for details.

To William Lidwell, Kritina Holden, and Jill Butler — for assembling the editorial taxonomy that makes a repository like this possible. To the researchers cited in the per-principle references/lineage.md files — whose primary work is the actual substance behind every entry. To the teams building agent skill, plugin, and rules infrastructure — for making a marketplace of design principles a useful artifact rather than just a library no one reads.