{
"markdown": "\n\n# Universal Design Principles\n\n**A cross-agent skill marketplace of 42 framework-agnostic UX & product-design principles, drawn from *Universal Principles of Design* (Lidwell, Holden, Butler, 2003) and the broader design and HCI research literature.**\n\n[](LICENSE)\n[](#whats-inside)\n[](docs/principle-index.md)\n[](docs/principle-index.md)\n[](#repository-stats)\n\n[Getting Started](docs/getting-started.md) · [Architecture](docs/architecture.md) · [Principle Index](docs/principle-index.md) · [How Skills Trigger](docs/how-skills-trigger.md) · [Attribution](ATTRIBUTION.md) · [Contributing](CONTRIBUTING.md)\n\n
\n\n---\n\n## What this is\n\nA **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.\n\nEach 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.\n\n## Why a plugin marketplace?\n\nMany 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.\n\nThis 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:\n\n| Plugin | What it teaches | Skills |\n|---|---|---:|\n| **[Perception & Hierarchy](plugins/perception-and-hierarchy-principles/)** | How the eye groups elements, where it lands first, what makes a composition read as ordered | 34 |\n| **[Cognition & Learnability](plugins/cognition-and-learnability-principles/)** | Mental models, complexity reduction, memory load, how new users get oriented | 33 |\n| **[Interaction & Control](plugins/interaction-and-control-principles/)** | Affordance, feedback, errors, user agency, Fitts's Law for touch targets | 29 |\n| **[Aesthetics & Emotion](plugins/aesthetics-and-emotion-principles/)** | Beauty, perceived quality, brand voice, flow, persuasive form | 17 |\n| **[Process & Robustness](plugins/process-and-robustness-principles/)** | Iteration, accessibility, reliability under stress, what to prune | 24 |\n\nEach 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).\n\n## Installation\n\nPick the agent you actually use. The same `skills//SKILL.md` folders are the source of truth for every install path; only the plugin manifest or destination directory changes.\n\n| Agent | Best install path | This repo provides |\n|---|---|---|\n| Claude Code | Native plugin marketplace | `.claude-plugin/marketplace.json` and per-plugin `.claude-plugin/plugin.json` |\n| Codex | Native plugin marketplace, or direct Agent Skills | `.agents/plugins/marketplace.json` and per-plugin `.codex-plugin/plugin.json` |\n| Cursor | Cursor plugin flow, or project rules fallback | `.cursor-plugin/marketplace.json` and per-plugin `.cursor-plugin/plugin.json` |\n| Gemini CLI | Link or copy Agent Skills | Plain `skills/*/SKILL.md` folders |\n| Copilot, Windsurf, and other agents | Native rules or `AGENTS.md` fallback | Portable skill folders plus a compact rule/instruction pattern |\n\nThe packaging follows the [Agent Skills open format](https://agentskills.io/), where each skill is a folder containing `SKILL.md` and optional supporting files.\n\n### Claude Code\n\nIn Claude Code, add this repository as a plugin marketplace and install the plugins you want:\n\n```text\n/plugin marketplace add HDeibler/universal-design-principles\n/plugin install perception-and-hierarchy-principles@universal-design-principles\n/plugin install cognition-and-learnability-principles@universal-design-principles\n```\n\nUse `/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.\n\nFor a local checkout instead of GitHub shorthand:\n\n```bash\ngit clone https://github.com/HDeibler/universal-design-principles.git ~/code/universal-design-principles\n```\n\nThen run:\n\n```text\n/plugin marketplace add ~/code/universal-design-principles\n```\n\nReference: [Claude Code plugins](https://code.claude.com/docs/en/plugins), [Claude Code skills](https://code.claude.com/docs/en/skills), and [Claude plugin marketplaces](https://code.claude.com/docs/en/plugin-marketplaces).\n\n### Codex\n\nCodex can install this repository either as one collection plugin or as five focused plugin bundles.\n\nFor the single collection plugin, use the root Codex manifest. This is the best path for directories that expect one plugin per repository:\n\n```bash\nnpx codex-marketplace add HDeibler/universal-design-principles --plugin --project\n```\n\nFor the five focused plugin bundles, use the repo marketplace:\n\n```bash\nnpx codex-marketplace add HDeibler/universal-design-principles --plugins --project\n```\n\nCodex 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`.\n\n```bash\ncodex plugin marketplace add HDeibler/universal-design-principles\ncodex\n```\n\nInside Codex, open the plugin directory:\n\n```text\n/plugins\n```\n\nChoose the `Universal Design Principles` marketplace and install one or more plugins.\n\nIf you only want the skills without plugin metadata, copy the skill folders into a standard Codex skills directory:\n\n```bash\ngit clone https://github.com/HDeibler/universal-design-principles.git ~/code/universal-design-principles\nmkdir -p ~/.agents/skills\ncp -R ~/code/universal-design-principles/plugins/*-principles/skills/* ~/.agents/skills/\n```\n\nRestart Codex after copying or installing. Codex scans `.agents/skills` in the repository, parent directories, `$HOME/.agents/skills`, admin locations, and bundled system skills.\n\nReference: [Codex plugins](https://developers.openai.com/codex/plugins), [Codex plugin authoring](https://developers.openai.com/codex/plugins/build), [Codex skills](https://developers.openai.com/codex/skills), and [AGENTS.md discovery](https://developers.openai.com/codex/guides/agents-md).\n\n### Cursor\n\nCursor 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.\n\n```bash\ngit clone https://github.com/HDeibler/universal-design-principles.git ~/code/universal-design-principles\n```\n\nIn Cursor, open the command palette, choose **Add Plugin**, and point Cursor at the GitHub repository URL or the local checkout path:\n\n```text\nhttps://github.com/HDeibler/universal-design-principles\n~/code/universal-design-principles\n```\n\nIf you are not using Cursor plugins yet, use a project rule as a lightweight fallback:\n\n```mdc\n---\ndescription: Use Universal Design Principles when working on UX, UI, product design, visual hierarchy, interaction design, accessibility, or design critique.\nalwaysApply: false\n---\n\nWhen the task involves UX or product design, consult the Universal Design Principles skill repository and prefer the most specific principle skill before giving recommendations.\n```\n\nSave 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.\n\nReference: [Cursor rules](https://docs.cursor.com/context/rules), [Cursor plugin marketplace](https://cursor.com/plugins), and the [Cursor official plugin repo](https://github.com/cursor/plugins).\n\n### Gemini CLI\n\nGemini CLI supports Agent Skills directly. Link each plugin's `skills/` directory into your user skill store:\n\n```bash\ngit clone https://github.com/HDeibler/universal-design-principles.git ~/code/universal-design-principles\n\nfor plugin in ~/code/universal-design-principles/plugins/*-principles; do\n gemini skills link \"$plugin/skills\" --scope user\ndone\n\ngemini skills list\n```\n\nUse `--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/`.\n\nReference: [Gemini CLI Agent Skills](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/skills.md), [Gemini skills getting started](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/tutorials/skills-getting-started.md), and [Gemini CLI extensions](https://google-gemini.github.io/gemini-cli/docs/extensions/).\n\n### Copilot, Windsurf, and other agents\n\nFor 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.\n\nFor 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:\n\n```md\n# Design guidance\n\nWhen working on UX, UI, product design, visual hierarchy, interaction design,\naccessibility, or design critique, use the Universal Design Principles skills\nfrom https://github.com/HDeibler/universal-design-principles. Prefer the most specific principle\nskill for the task, and use the reference files only when the answer needs\nresearch depth.\n```\n\nReference: [GitHub Copilot custom instructions](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions), [Windsurf rules](https://docs.windsurf.com/windsurf/cascade/memories), and [AGENTS.md](https://github.com/agentsmd/agents.md).\n\n### Directory structure recommendation\n\nThis repository now uses a **parallel-manifest, single-source skill structure**:\n\n```text\nuniversal-design-principles/\n├── .claude-plugin/marketplace.json\n├── .cursor-plugin/marketplace.json\n├── .agents/plugins/marketplace.json\n├── plugins/\n│ ├── perception-and-hierarchy-principles/\n│ │ ├── .claude-plugin/plugin.json\n│ │ ├── .codex-plugin/plugin.json\n│ │ ├── .cursor-plugin/plugin.json\n│ │ └── skills/\n│ │ └── /SKILL.md\n│ └── ...\n└── ...\n```\n\nThis 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.\n\nSee **[docs/getting-started.md](docs/getting-started.md)** for a more detailed walkthrough including verification steps and troubleshooting.\n\n## Quick example\n\nAfter installing one of the plugins (say, **Cognition & Learnability**), you can use it like this in any agent conversation:\n\n```\nYou: I'm designing a settings page for a SaaS dashboard. The product has\n accumulated about 60 settings across 8 categories. Help me think\n through the structure.\n\nAgent: [loads the cognition-router → progressive-disclosure skill]\n Looking at this through the lens of progressive disclosure and\n the 80/20 rule: roughly 12 of those 60 settings probably account\n for 80% of actual changes. Surface those in a clear default view,\n and tuck the remaining ~50 behind clearly-labeled disclosure...\n```\n\nThe skills fire automatically based on the conversation context. You don't have to remember to invoke them.\n\nFor more concrete usage examples, see [docs/getting-started.md](docs/getting-started.md).\n\n## Anatomy of a principle\n\nTake **Hick's Law** as an example. Inside `plugins/cognition-and-learnability-principles/skills/`, you'll find:\n\n```\nhicks-law/\n├── SKILL.md # the principle's main entry (~450 lines)\n└── references/\n └── lineage.md # origins, Hick (1952), Hyman (1953), modern empirical work\n\nhicks-law-menus/\n├── SKILL.md # how Hick's Law applies to menus specifically\n└── references/\n └── menu-design-patterns.md # patterns and anti-patterns\n\nhicks-law-defaults/\n├── SKILL.md # how Hick's Law applies to defaults\n└── references/\n └── defaults-recipes.md\n\nhicks-law-pricing/\n├── SKILL.md # how Hick's Law applies to pricing pages\n└── references/\n └── pricing-tier-strategies.md\n```\n\nEach main `SKILL.md` includes:\n\n1. **Definition** — Plain-language definition in our own words.\n2. **Origins and research lineage** — Where the principle comes from, who studied it, what evidence supports it.\n3. **When to apply** — Surfaces and decisions where the principle is decisive.\n4. **When NOT to apply** — Contexts where the principle backfires or doesn't transfer.\n5. **Worked examples** — Multiple cross-domain examples with code or diagrams.\n6. **Anti-patterns** — Common misapplications and how to recognize them.\n7. **Heuristic checklist** — Concrete questions to ask before shipping.\n8. **Related principles** — What to read next.\n9. **See also** — Links to `references/` and to sub-aspect skills.\n\nFor the full architecture, see **[docs/architecture.md](docs/architecture.md)**.\n\n## What's inside\n\n```\nuniversal-design-principles/\n├── .codex-plugin/\n│ └── plugin.json # Codex root collection plugin manifest\n├── .agents/\n│ └── plugins/\n│ └── marketplace.json # Codex marketplace manifest\n├── .claude-plugin/\n│ └── marketplace.json # Claude Code marketplace manifest\n├── .cursor-plugin/\n│ └── marketplace.json # Cursor marketplace manifest\n├── docs/ # cross-plugin documentation\n│ ├── getting-started.md\n│ ├── architecture.md\n│ ├── how-skills-trigger.md\n│ └── principle-index.md\n├── plugins/\n│ ├── perception-and-hierarchy-principles/ # 34 skills + Claude/Codex/Cursor plugin manifests\n│ ├── cognition-and-learnability-principles/ # 33 skills + Claude/Codex/Cursor plugin manifests\n│ ├── interaction-and-control-principles/ # 29 skills + Claude/Codex/Cursor plugin manifests\n│ ├── aesthetics-and-emotion-principles/ # 17 skills + Claude/Codex/Cursor plugin manifests\n│ └── process-and-robustness-principles/ # 24 skills + Claude/Codex/Cursor plugin manifests\n├── README.md\n├── CONTRIBUTING.md\n├── ATTRIBUTION.md\n├── CHANGELOG.md\n├── LICENSE\n├── .gitignore\n└── .gitattributes\n```\n\nBrowse the **[Principle Index](docs/principle-index.md)** for the alphabetical list with direct links into the relevant `SKILL.md`.\n\n## Repository stats\n\n| Metric | Count |\n|---|---:|\n| Plugins | 5 |\n| Principles built | 42 |\n| Skills (`SKILL.md` files) | 137 |\n| Reference deep-dives (`references/*.md` files) | 137 |\n| Lines of original content | ~35,700 |\n\nThe 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.\n\n## Source attribution\n\nThis repository owes its **principle names and taxonomy** to:\n\n> 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.\n\nEach 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.\n\n**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.\n\nFor a complete attribution breakdown — including how this repository used the source book, every key research source, and our content-originality commitments — see **[ATTRIBUTION.md](ATTRIBUTION.md)**.\n\n## How this repository is intended to be used\n\n- **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.\n- **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.\n- **By teaching contexts:** the `references/lineage.md` files trace the research lineage of each principle and are useful as teaching material.\n- **By contributors:** see [CONTRIBUTING.md](CONTRIBUTING.md) — the repository is designed to grow incrementally toward covering all 100 principles.\n\n## Companion plugins\n\nThis 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.\n\nIf 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.\n\n## Contributing\n\nContributions are welcome and held to a high prose-quality bar. See **[CONTRIBUTING.md](CONTRIBUTING.md)** for:\n\n- Structural conventions for adding a new principle.\n- The quality bar for prose, examples, and references.\n- Attribution rules.\n- The pull-request process.\n\nFor new-principle proposals, please open an issue first to discuss scope and audience.\n\n## License\n\nThis repository is licensed under the [MIT License](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](ATTRIBUTION.md) and [LICENSE](LICENSE) for details.\n\n## Acknowledgments\n\nTo 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.\n\n---\n\n\n\n**[Browse all 42 principles →](docs/principle-index.md)**\n\n
\n",
"bytes": 21074,
"sha": "46aa12561f1bf876810138dc8a5b808065d948b910c7f777a91a77d02c71ac6f",
"repo_slug": "hdeibler/universal-design-principles",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/plg_hdeibler_universal_design_principles_uni_31e8344f/readme"
}