Deibler/universal-design-principles

aesthetic-usability-effect

When your agent uses it

Use this skill when the design's perceived quality affects whether users will tolerate friction, give the product a chance, or judge it as well-made — which is most consumer-facing surfaces, marketing, onboarding, first-run, and any moment where an unfamiliar user is forming a quick judgment. Trigger when designing landing pages, sign-up flows, first-time UX, app store screenshots, demo videos, sales decks, or any surface where the user's first impression matters and friction is unavoidable. Also trigger when defending why "polish" matters on a working product, or when the user asks "should we ship the spartan version or invest in design?"

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

aesthetics-router

When your agent uses it

Use this skill whenever a design task involves the felt quality of an interface — beauty, polish, brand voice, persuasion, emotional response, marketing surfaces, hero sections, onboarding tone, empty/celebration states, illustrations, mascots, avatars. Trigger when the user mentions tone, polish, brand, "feels cold/cheap/premium," personality, voice, mascot, hero, "make it more delightful," or asks how a screen should make the user feel. Framework-agnostic. Routes the model to the right aesthetics principle in this plugin.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

archetypes

When your agent uses it

Use this skill when designing brand voice, marketing positioning, mascot or character design, narrative arcs in product onboarding, or any expressive surface where the design must communicate personality. Trigger when picking how a brand "feels" (rebellious, nurturing, sage-like), when designing storytelling for marketing, or when reviewing why a brand voice feels generic. Archetypes is one of the foundational principles in 'Universal Principles of Design' (Lidwell, Holden, Butler 2003), grounded in Jung's analytical psychology and widely applied in branding, storytelling, and product personality.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

archetypes-brand-voice

When your agent uses it

Use this skill when picking a brand archetype, propagating it across product and marketing surfaces, or auditing brand-voice consistency. Trigger when designing the voice of microcopy, marketing pages, support tone, or any brand-facing communication. Sub-aspect of `archetypes`; read that first.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

archetypes-storytelling-arcs

When your agent uses it

Use this skill when designing narrative content — landing pages, case studies, onboarding flows, marketing campaigns, sales decks, ad arcs. Trigger when picking how to frame a customer story, when writing a launch campaign, or when the user mentions "this campaign feels flat" or "we need a better narrative." Sub-aspect of `archetypes`; read that first.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

exposure-effect

When your agent uses it

Apply the Exposure Effect (mere-exposure effect) — the well-documented finding that repeated exposure to something tends to increase liking for it. Use when launching new features, planning redesigns, building brand familiarity, or evaluating user resistance to change. Familiarity reads as comfort and trust; novelty reads as risk. The effect explains why redesigns generate disproportionate user backlash, why incremental change beats radical change, and why brand consistency over time builds value beyond any single design choice.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

exposure-onboarding

When your agent uses it

Use the exposure effect deliberately in onboarding and habit formation — getting users to repeated, low-friction encounters with the product so familiarity builds and preference forms. Use when designing onboarding flows, planning feature introductions, building user habits, or evaluating why users churn after first use. The exposure effect operates over time; products that get users to come back early benefit from accumulated familiarity that single-session products don't.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

exposure-redesign-risk

When your agent uses it

Manage the risks of redesigns when users have built up exposure-based preference for the existing design. Use when planning a major redesign, evaluating user backlash to changes, deciding between incremental and radical change, or recovering from a redesign that generated complaints. Users like what they're used to; redesigns must be planned to manage the transition cost. Even objectively-better redesigns trigger resistance disproportionate to the actual change.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

form-follows-function

When your agent uses it

Use this skill when designing the visual or aesthetic layer of a product, deciding between expressive style and functional restraint, evaluating decorative elements, or arguing about whether a feature should ship plain vs. polished. Trigger when stakeholders ask "should we add visual flair to this?", when reviewing a design that "feels too decorated," or when picking between competing visual directions. Form Follows Function is one of the foundational principles in 'Universal Principles of Design' (Lidwell, Holden, Butler 2003) and one of the most-quoted dictums in design — but its meaning depends on which interpretation (descriptive vs. prescriptive) you take.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

form-follows-function-as-axiom

When your agent uses it

Use this skill when applying the descriptive form-follows-function interpretation — functional clarity as a source of aesthetic quality. Trigger when designing tools, dashboards, or instrumental surfaces where every element should earn its presence. Sub-aspect of `form-follows-function`; read that first.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

form-follows-function-success-criteria

When your agent uses it

Use this skill when the team is in a form-vs-function debate and needs to step back to define what "success" actually means for the design. Trigger when stakeholders disagree about visual treatment, when a design feels off and no one can articulate why, or when reviewing a design against an unclear brief. Sub-aspect of `form-follows-function`; read that first.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

immersion

When your agent uses it

Apply the principle of Immersion — designing for sustained focus and engagement, where the user becomes absorbed in the activity and loses awareness of the surrounding environment. Use when designing for creative work, deep reading, gameplay, learning, or any activity that benefits from extended focused attention. Immersion requires removing distractions, providing clear feedback, calibrating challenge to skill, and respecting the user's flow state. Modern attention-driven products often work against immersion in pursuit of engagement metrics; designs that genuinely serve immersion are increasingly distinctive.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

immersion-distraction-cost

When your agent uses it

Recognize and design against the cost of attention fragmentation — the disproportionate damage that even small interruptions do to focused work. Use when designing notification systems, evaluating whether a feature should interrupt the user, planning feature introductions, or auditing a product for unintended attention costs. The cost of breaking immersion is much higher than designers usually estimate; restraint in interruption is one of the most user-respectful design moves.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

immersion-flow

When your agent uses it

Design for flow specifically — calibrate challenge to skill, provide immediate feedback, set clear goals, foreground the activity. Use when designing tools for skilled work (writing, drawing, programming, music), games, learning experiences, or any context where sustained engagement is the goal. Flow is the most-researched aspect of immersion; the conditions for it are specific and the design moves that support it are well-documented.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

wabi-sabi

When your agent uses it

Apply the principle of Wabi-Sabi — the aesthetic embrace of imperfection, impermanence, and naturalness. Use when designing for warmth and authenticity, creating spaces that feel lived-in rather than sterile, choosing handcrafted-feeling materials over machined perfection, or evaluating whether a design feels too polished and impersonal. Wabi-sabi resists the digital-design tendency toward pixel-perfect uniformity in favor of subtle asymmetry, organic textures, and the visible mark of process. Used appropriately, it produces designs that feel human; used reflexively, it produces fake-looking sloppiness.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

wabi-sabi-imperfection

When your agent uses it

Design intentional imperfection that reads as warmth — subtle asymmetry, hand-drawn elements, organic textures, intentional irregularities. Use when adding human warmth to a digital design, distinguishing from competitors with uniform design systems, designing for personal or creative contexts. The skill is making imperfection look intentional and refined rather than sloppy or broken; the line between "designed warmth" and "looks unfinished" is narrow.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

wabi-sabi-restraint

When your agent uses it

Apply wabi-sabi restraint — the discipline of leaving things out, of resisting decoration, of letting empty space and silence do design work. Use when designing reading-focused interfaces, paring back accumulated clutter, choosing between decoration and absence, or evaluating whether each element earns its place. Restraint is the often-overlooked half of wabi-sabi: the imperfection side gets attention, but the principle is equally about modesty and the elegance of what's not there.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

80-20-feature-prioritization

When your agent uses it

Use this skill when scoping a roadmap, prioritizing features, planning an MVP, or deciding what to ship and what to defer. Trigger when the user asks "what should we build next?", "is this feature worth it?", "should we ship feature X?", or when reviewing a feature backlog. Sub-aspect of `80-20-rule`; read that first.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

80-20-redesign-targeting

When your agent uses it

Use this skill when scoping a redesign or refactor — choosing which existing surfaces deserve full attention and which can be left mostly alone. Trigger when the user asks "where should we focus our redesign?", "do we need to redo all of this?", or when planning incremental design improvements with limited capacity. Sub-aspect of `80-20-rule`; read that first.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

80-20-rule

When your agent uses it

Use this skill whenever the design has many features, controls, or content elements and decisions about which to prioritize matter — feature roadmaps, redesign scoping, IA decisions, dashboard design, settings page audits, marketing content prioritization, or any design with many candidates competing for attention. Trigger when the user asks "what should we focus on?", "should we add another feature?", "what can we cut?", or when reviewing a UI cluttered with rarely-used controls. The 80/20 rule (Pareto principle) is one of the foundational principles in 'Universal Principles of Design' (Lidwell, Holden, Butler 2003) and one of the most quoted across design, business, and engineering.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

chunking

When your agent uses it

Use this skill whenever the user must hold a sequence of items in working memory — phone numbers, OTP codes, account IDs, address strings, multi-step instructions, long forms, navigation menus with many items. Trigger when designing OTP / verification UIs, formatting numeric strings, breaking long forms into sections, grouping nav items, or reviewing surfaces that "have too many things at once." Chunking is one of the foundational principles in 'Universal Principles of Design' (Lidwell, Holden, Butler 2003), grounded in Miller's classic working-memory research.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

chunking-form-grouping

When your agent uses it

Use this skill when designing or fixing long forms that ask the user for many fields — sign-up flows, profile setup, settings panels, checkout, intake forms, applications. Trigger when forms exceed ~6 fields, when users complain forms are "too long," when seeing high mid-form drop-off, or when picking how to break a form into sections. Sub-aspect of `chunking`; read that first.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

chunking-numeric-and-otp

When your agent uses it

Use this skill when designing inputs or displays for numeric strings — phone numbers, OTP / verification codes, credit card numbers, account IDs, license keys, currency, dates, social security numbers. Trigger when picking a format for displaying numbers, designing OTP entry UIs, or formatting identifiers in tables and receipts. Sub-aspect of `chunking`; read that first.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

cognition-router

When your agent uses it

Use this skill whenever a design task involves cognition, mental models, learnability, complexity reduction, defaults, memory, scanning, or comprehension — regardless of framework or platform. Trigger when the user is designing forms, settings, onboarding, dashboards with many widgets, complex tables, navigation IA, search experiences, or any flow that has many options or asks the user to learn something new. Trigger when the user mentions "too complex," "too many options," "users keep getting confused," defaults, labels, copy, mental models, progressive disclosure, autocomplete, or ergonomics. Routes the model to the right cognition principle in this plugin.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

consistency

When your agent uses it

Apply the principle of Consistency — making similar things look and behave similarly so users can transfer learning across the interface. Use when designing component libraries, defining naming conventions, choosing whether to invent or borrow patterns, auditing across surfaces (web, mobile, email, support docs), or evaluating whether two features should share or diverge in their interaction model. Strong consistency reduces cognitive load and learnability cost; aggressive consistency can flatten meaningful differences. There are four kinds — aesthetic, functional, internal, external — each with different applications.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

consistency-external

When your agent uses it

Apply external consistency — honoring conventions from outside your product (platform conventions, category conventions, established interaction patterns) so users can transfer their learning into your product. Use when designing for a specific platform (iOS, Android, web), entering an established product category (calendar, email, file manager), choosing icons or gestures, or deciding when to follow vs. lead a convention. External consistency reduces the learning cost for new users; deviating from it requires both a strong reason and explicit framing.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

consistency-internal

When your agent uses it

Apply internal consistency — making your product coherent with itself across all surfaces, components, and flows. Use when designing or auditing component libraries, defining design tokens, settling cross-team naming conventions, planning a design-system rollout, integrating acquired or legacy code, or evaluating whether two features should share or diverge in their interaction model. Internal consistency is enforced through design systems, shared vocabularies, and process discipline; it erodes through hand-off losses, sprint-driven shortcuts, and team boundaries that don't coordinate.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

hicks-law

When your agent uses it

Use this skill whenever a design has many options the user must choose among — menus, navigation, pickers, plan tiers, settings panels, action toolbars, lists of templates, anything that asks "which one?" Trigger when the user is laying out a navigation menu, designing a settings page, picking the structure of a wizard, building a country/timezone/currency picker, designing a pricing table, or reviewing a UI where users hesitate over which control to use. Trigger when there's debate about "should we add another option?" — Hick's Law is the principle that costs the option a price. Routes to sub-aspect skills for menus, defaults, and pricing.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

hicks-law-defaults

When your agent uses it

Use this skill when the question is what to *pre-select* in a list of options — radio groups, dropdowns, configuration UIs, plan pickers, sign-up flows, settings. A strong default is the highest-leverage Hick's Law mitigation: most users accept the default, paying almost no decision cost. Trigger when picking what's selected on first load, when stakeholders argue "shouldn't we let the user choose?", when designing wizards or onboarding, or when a UI has many options but most users want the same one. Sub-aspect of `hicks-law`; read that first if you haven't already.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

hicks-law-menus

When your agent uses it

Use this skill when designing menus, dropdowns, navigation, command palettes, or any interface where the user picks from a list. Trigger when the menu has more than ~7 items, when navigation feels overwhelming, when designing a cmd-K palette, when picking what goes in a "More" overflow, or when arguing about whether to add another menu item. Sub-aspect of `hicks-law`; read that first if you haven't already.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

hicks-law-pricing

When your agent uses it

Use this skill when designing pricing tables, plan pickers, tier selectors, or any conversion surface where the choice itself is the conversion event. Trigger when laying out 3-tier or 4-tier pricing, when arguing about whether to add a fourth plan, when designing the "Choose your plan" step of onboarding, or when fixing low conversion on a pricing page. Pricing pages are a special Hick's Law case: the decision is the entire purpose of the page, and decision fatigue equals lost revenue. Sub-aspect of `hicks-law`; read that first if you haven't already.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

iconic-arbitrary-and-symbolic

When your agent uses it

Apply arbitrary and symbolic icon design — using forms with no inherent meaning that depend on convention to communicate (the hamburger menu, the kebab menu, the AI sparkle, app brand-mark icons). Use when a function has no clear visual referent, when working within a domain that has its own icon vocabulary, when establishing or following a convention, or when evaluating whether a convention is strong enough to support icon-only treatment. Arbitrary icons require prior learning to work; the skill is calibrating when to follow a convention vs. when to label.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

iconic-representation

When your agent uses it

Apply iconic representation — using simplified visual symbols to communicate function, status, or category at a glance. Use when designing icon sets, choosing between icon and text labels, evaluating whether to lean on existing iconography (resemblance to a known object) or invent symbolic icons (arbitrary forms with assigned meanings), or auditing whether your icons are actually communicating. Three kinds: similar (icons that look like what they represent), example (icons that depict an object associated with the function), and arbitrary/symbolic (forms with no inherent meaning, like the hamburger menu).

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

iconic-resemblance

When your agent uses it

Apply iconic resemblance — designing or choosing icons that visually look like what they represent. Use when picking icons for actions or objects with strong visual referents (camera, clock, lock, calendar), evaluating whether a custom icon is communicating, or testing whether your icon set actually conveys meaning to your audience. Resemblance is the strongest form of icon recognition because it requires no prior learning; it fails when the function has no visual referent or when the audience doesn't recognize the object being depicted.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

mental-model

When your agent uses it

Use this skill whenever the design will be used by people who bring prior expectations — which is essentially every design. Trigger when designing onboarding, when picking metaphors (folders, channels, projects), when reviewing why users keep getting confused, when migrating from one product convention to another, or when the user mentions "users don't understand," "they keep doing X wrong," or "we're inventing something new." Mental Model is one of the foundational principles in 'Universal Principles of Design' (Lidwell, Holden, Butler 2003) and grounds most modern user-experience design.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

mental-model-mismatch-and-onboarding

When your agent uses it

Use this skill when designing onboarding, when diagnosing why users keep getting confused, when migrating users from one product convention to another, or when the system genuinely differs from familiar comparable products. Trigger when the user mentions "users don't get it," "we keep getting the same support tickets," or "this is a new pattern they need to learn." Sub-aspect of `mental-model`; read that first.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

mental-model-system-vs-interaction

When your agent uses it

Use this skill when distinguishing the two mental-model types — system models (how the user thinks the system works) and interaction models (how the user thinks they should use it). Trigger when designing onboarding (which model to teach), reviewing user confusion (which model is wrong), or building documentation (which model to explain). Sub-aspect of `mental-model`; read that first.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

mimicry

When your agent uses it

Apply the principle of Mimicry — borrowing the form, behavior, or visual language of something familiar to make a new design recognizable. Use when introducing a novel feature whose function would be opaque without an analogy, choosing between metaphor and convention, designing for a category your users already know, or evaluating whether a "skeuomorphic" element helps or hurts. Mimicry comes in surface (visual resemblance), behavioral (acts like the source), and functional (does what the source does) forms. Used well, it accelerates learning; used badly, it carries forward limitations the new medium doesn't share.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

mimicry-behavioral

When your agent uses it

Apply behavioral mimicry — making an interface element behave like a familiar physical object so the user's physical-world intuitions transfer to the digital interaction. Use when designing gestures, animations, transitions, drag-and-drop, scroll behaviors, or any interaction where physical-world analogies could clarify the experience. Behavioral mimicry is more durable than visual skeuomorphism — physics-mimicking behaviors age well — but it requires deliberate calibration: too much physical fidelity slows the interaction down without communicating anything new.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

mimicry-surface

When your agent uses it

Apply surface mimicry — making an interface element look like a familiar physical object to communicate its purpose at a glance. Use when introducing a control or container that has no native UI vocabulary, designing a niche product that benefits from a recognizable visual reference (a journal that looks like a journal, a wallet that looks like a wallet), or evaluating whether visual skeuomorphism is communicating or just decorating. Surface mimicry is most useful for novice users in unfamiliar mediums; it becomes anachronistic as the source fades or as users learn the abstract conventions.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

progressive-disclosure

When your agent uses it

Use this skill whenever a design has *more* available than the user needs to see at this moment — settings panels with advanced options, forms with optional fields, dashboards with drill-down detail, navigation with deep IA, dialogs with "More options" affordances, marketing pages with FAQ accordions. Trigger when designing or fixing surfaces that feel "overwhelming," when stakeholders argue about whether to expose every option up front, when novice and expert users have different tolerance for the same surface, or when reviewing a UI cluttered with rarely-used controls. Progressive disclosure is one of the foundational principles in 'Universal Principles of Design' (Lidwell, Holden, Butler 2003), originally formalized through the Xerox Star user-interface work in the 1970s.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

progressive-disclosure-defaults-and-tucking

When your agent uses it

Use this skill when deciding *what to surface* and *what to tuck* — the editorial choices behind progressive disclosure. Trigger when laying out a settings page, picking which form fields to show by default, deciding whether a section starts collapsed or open, or arguing about whether a feature deserves primary chrome or belongs in "Advanced." Sub-aspect of `progressive-disclosure`; read that first.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

progressive-disclosure-disclosure-affordances

When your agent uses it

Use this skill when picking the *mechanism* for revealing tucked content — accordion vs. modal vs. tab vs. separate page vs. tooltip. Trigger when designing the UI for "More options," picking between an inline accordion and a side sheet, deciding whether a wizard step should be a modal or a separate page, or reviewing whether existing disclosure affordances are doing their job. Sub-aspect of `progressive-disclosure`; read that first.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

recognition-over-recall

When your agent uses it

Use this skill whenever the user must locate or choose something from many possibilities — pickers, command palettes, navigation menus, autocompletes, recents lists, search results, settings panels. Trigger when designing inputs that ask the user to "type the right thing," when picking between dropdowns and search-first interfaces, when reviewing why users keep typing wrong values into autocomplete fields. Recognition Over Recall is one of the foundational principles in 'Universal Principles of Design' (Lidwell, Holden, Butler 2003) and one of Nielsen's 10 heuristics — recognizing options is far easier than recalling them from memory.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

recognition-pickers-and-palettes

When your agent uses it

Use this skill when designing pickers, dropdowns, comboboxes, autocompletes, command palettes, or any UI that lets the user select from a known set. Trigger when picking between a free-text field and a select; when designing a command palette; when reviewing why users keep typing wrong values into autocomplete inputs. Sub-aspect of `recognition-over-recall`; read that first.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

recognition-recents-and-suggestions

When your agent uses it

Use this skill when designing surfaces that accelerate repeat tasks through recents, frequently-used items, and contextual suggestions. Trigger when designing pickers used repeatedly, command palettes, navigation that should adapt to user behavior, or any surface where a returning user shouldn't have to retype their frequent destinations. Sub-aspect of `recognition-over-recall`; read that first.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

wayfinding

When your agent uses it

Use this skill whenever a user must navigate within a non-trivial space — a multi-page web app, a documentation site, a hierarchical settings panel, a conference site, a multi-step flow, a campus, a building, an app with deep IA. Trigger when the user asks how navigation should be structured, when users get lost, when "I can't find X" complaints recur, when designing breadcrumbs, sitemaps, search, or recovery flows. Wayfinding is one of the foundational principles in 'Universal Principles of Design' (Lidwell, Holden, Butler 2003); it's also the only principle from that source not previously covered by these plugins. Routes to sub-aspect skills for spatial metaphors, search-and-recovery, and breadcrumbs.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

wayfinding-breadcrumbs-and-context

When your agent uses it

Use this skill when designing the orientation chrome that tells users where they are — breadcrumbs, current-page indicators, page titles, header context, "you are here" markers, parent-link affordances. Trigger when designing a multi-level IA, when users complain "I lost track of where I was," when reviewing whether to add or remove a breadcrumb, or when picking between navigation patterns for hierarchical content. Sub-aspect of `wayfinding`; read that first.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

wayfinding-physical-spatial-metaphors

When your agent uses it

Use this skill when deciding whether (and how) to borrow physical-world wayfinding metaphors for software — rooms, doors, paths, maps, landmarks. Trigger when designing app shells with multiple "spaces," when picking metaphors for navigation (workspace, channel, board, project), when reviewing skeuomorphic vs. flat navigation choices, or when the user mentions "feels like a maze" or "where's the front door of this app." Sub-aspect of `wayfinding`; read that first.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

wayfinding-search-and-recovery

When your agent uses it

Use this skill when designing search as the universal wayfinding recovery, or when designing for users who got lost — 404 pages, "results not found," "you've reached an unexpected page," empty states that should orient, and any moment where the user's mental map has failed and the system must repair it. Trigger when designing global search, command palette, error pages, or recovery flows. Sub-aspect of `wayfinding`; read that first.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

affordance

When your agent uses it

Use this skill whenever the question is whether the user can tell what an element does — whether it looks clickable, draggable, expandable, editable, or interactive at all. Trigger when designing buttons, links, custom controls, drag handles, draggable cards, editable inline fields, or any interactive element. Trigger on reviews when users hesitate, miss controls, or click on things that aren't interactive. Affordance is one of the most decisive principles in interaction design — Norman placed it at the center of *The Design of Everyday Things* — and it's one of the most violated by modern flat-design conventions that strip the visual cues users rely on.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

affordance-false-and-anti

When your agent uses it

Use this skill when designing or fixing controls that mislead users — elements that look interactive but aren't (false affordance), or controls that need to clearly communicate "you can't do that here" (anti-affordance, like disabled states). Trigger when reviewing UIs where users tap inert elements expecting response, when designing disabled states, when picking treatments for read-only fields, or when a "decorative" element is being mistaken for a button. Sub-aspect of `affordance`; read that first.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

affordance-signifiers

When your agent uses it

Use this skill when the design has interactive capability but users aren't *seeing* it — when the affordance is technically present but the signifier (the visible cue that tells users "you can do this") is missing or weak. Trigger when reviewing flat-design UIs where everything looks the same, when designing custom controls, when stakeholders ask "should this be more obvious?", or when picking signifier strength for primary vs. secondary actions. Sub-aspect of `affordance`; read that first.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

constraint

When your agent uses it

Use this skill whenever the design must structurally prevent invalid actions — input validation, disabled states, required fields, type-restricted inputs, mode locks, role-based gates, hardware lockouts. Trigger when designing forms, picking input types, designing destructive flows, gating multi-step procedures, or thinking about how to prevent a class of errors from being possible at all. Constraint is one of the foundational principles in 'Universal Principles of Design' (Lidwell, Holden, Butler 2003) and one of the strongest design moves available — preventing wrong actions is more powerful than detecting them after the fact.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

constraint-physical

When your agent uses it

Use this skill when designing structural constraints that prevent invalid actions through the shape, layout, or behavior of the design itself — paths (channels of motion), axes (rotary controls), barriers (blocks). Trigger when designing input controls, drag-and-drop affordances, modal dialogs, or hardware-style structural prevention. Sub-aspect of `constraint`; read that first.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

constraint-psychological

When your agent uses it

Use this skill when designing constraints that work through perception, expectation, and learned convention — symbols, conventions, mappings. Trigger when designing iconography, picking control conventions, or designing for behavioral predictability. Sub-aspect of `constraint`; read that first.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

control

When your agent uses it

Apply the principle of Control — the level of autonomy a system gives the user, and how that level should be matched to the user's expertise and the task's stakes. Use when designing for novice vs. expert audiences, choosing between fully automated and manually controlled behaviors, deciding what to expose vs. abstract away, or building products that span experience levels (a tool a beginner will use once and an expert will use thousands of times). Too much control overwhelms novices; too little frustrates experts. The skill is calibrating control to the user, the task, and the moment.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

control-locus

When your agent uses it

Apply locus of control — the design choice between making the system appear to act on the user's behalf (external locus) and making the user appear to direct the system (internal locus). Use when designing AI-assisted features, autocorrect/autocomplete behaviors, recommendation surfaces, automated workflows, and any feature where the system could either do things automatically or wait for user instruction. Internal locus produces higher engagement, learning, and satisfaction; external locus produces higher convenience but lower agency. The skill is choosing deliberately and explaining the choice in the UI.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

control-power-vs-simplicity

When your agent uses it

Apply layered control — designing interfaces that serve novice and expert users in the same product without forcing one audience into the other's interface. Use when building products that span experience levels (most consumer software, most professional tools used occasionally), choosing between "simple by default" and "powerful by default," or deciding what to expose vs. hide behind progressive disclosure. The skill is creating a default surface that suffices for novices and a depth surface that doesn't intimidate them but is fully present for experts.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

errors

When your agent uses it

Use this skill whenever a design must accommodate the inevitability of human error — typos, wrong-button presses, misread instructions, mistimed actions, misunderstandings of system state. Trigger when designing form validation, input handling, destructive flows, complex multi-step procedures, alert systems, or any UI where users can do the wrong thing. Trigger when post-incident analyses reveal patterns of "human error" — most are design errors in disguise. Errors is one of the foundational principles in 'Universal Principles of Design' (Lidwell, Holden, Butler 2003), grounded in Norman's and Reason's foundational human-error research.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

errors-mistakes

When your agent uses it

Use this skill when designing to prevent errors of intention — wrong actions taken because the user's model of the situation was wrong. Trigger when designing for ambiguous information, novel situations, complex decisions, or contexts where users may proceed with confidence based on a wrong understanding. Sub-aspect of `errors`; read that first.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

errors-slips

When your agent uses it

Use this skill when designing to prevent or recover from execution errors — actions that don't match the user's intent. Trigger when designing critical action confirmations, distinct affordances for similar-purpose elements, recovery from wrong-button presses, "I didn't mean to do that" flows. Sub-aspect of `errors`; read that first.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

expectation-effect

When your agent uses it

Apply the Expectation Effect — the principle that prior expectations measurably change a person's perception of a product or experience. Use when shaping the framing of new features, designing onboarding, choosing visual cues that signal premium vs. budget, or diagnosing why two functionally identical features feel different to users. Expectations are set by visual cues (premium materials, polished typography), language (precise, confident copy), social proof, price, and prior brand exposure. Setting expectations too high creates disappointment; too low and the product reads as mediocre. The skill is calibrating what to promise.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

expectation-effect-design-cues

When your agent uses it

Apply in-product expectation cues — typography, animation, spacing, copy tone, micro-interactions, and visual register that signal "this is the kind of product you're using" within seconds of opening it. Use when designing the first-screen experience, picking a typography system, deciding loading-state behavior, choosing animation timing, or polishing the surface details that telegraph product quality. Surface cues set expectations for the whole session and create halo effects (positive or negative) that color every later interaction. Small surface details have outsized impact on perceived overall quality.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

expectation-effect-priming

When your agent uses it

Apply expectation priming — deliberately shaping the prior context (brand, marketing, price, social proof, recommendations) that users bring to a product before they ever touch it. Use when planning a launch, choosing positioning copy, deciding pricing tier, designing the marketing surface, or framing a feature for first encounter. Pre-encounter priming is often more powerful than in-product polish, because it sets the lens through which the in-product experience will be interpreted. The skill is calibrating priming honestly enough to outlast the first session.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

feedback-loop

When your agent uses it

Use this skill whenever a user takes an action and the system must communicate that the action was received, is in progress, succeeded, or failed. Trigger when designing button states, form submission, file uploads, payment flows, real-time UI updates, loading states, error states, success confirmations, or any moment when the user is waiting for the system to do something. Trigger when the user mentions "feels broken," "doesn't seem to work," "users keep clicking again," or any symptom of feedback gaps. Feedback Loop is one of the foundational principles in 'Universal Principles of Design' (Lidwell, Holden, Butler 2003) — and one of the principles whose absence most reliably damages a product's perceived quality.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

feedback-loop-positive-vs-negative

When your agent uses it

Use this skill when designing system architecture or product mechanics that involve feedback loops at a higher level than UI state — recommendation engines, gamification, growth mechanics, engagement systems, or any system where one user action affects subsequent actions in compounding or stabilizing ways. Trigger when designing growth loops, retention features, or system dynamics; when reviewing a feature for unintended consequences; when discussing engagement vs. wellbeing tradeoffs. Sub-aspect of `feedback-loop`; read that first.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

feedback-loop-states-and-latency

When your agent uses it

Use this skill when designing the visible states an interactive element passes through (idle / pending / success / error) and matching feedback timing to the user's perceptual thresholds. Trigger when designing button states, form-submit flows, file-upload progress, loading screens, or any interaction whose response time is variable. Sub-aspect of `feedback-loop`; read that first.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

fitts-law

When your agent uses it

Use this skill whenever the question involves how easy it is to *hit* an interactive target — buttons, links, form controls, drag handles, scrollbars, mobile tap targets, anything the user must move a pointer or finger to. Trigger when sizing buttons, designing toolbars, picking a hit-area for icon buttons, designing for touch screens, debugging "users keep mis-clicking," or arguing about button density vs. usability. Trigger when the user mentions touch targets, target size, "fat fingers," pointer accuracy, edge gestures, or accessibility around motor impairments. Routes to sub-aspect skills for touch targets, screen edges, and pointer acceleration.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

fitts-law-pointer-acceleration

When your agent uses it

Use this skill when the question involves cursor speed, pointer acceleration curves, or interaction with input devices that vary in precision (mouse, trackpad, stylus, touchscreen, eye-tracking). Trigger when designing for varied input devices, building drag interactions, designing scrubbers / sliders / handles, or analyzing why a UI feels "fiddly." Sub-aspect of `fitts-law`; read that first if you haven't already.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

fitts-law-screen-edges

When your agent uses it

Use this skill when designing for the edges and corners of the screen — where the cursor cannot overshoot, making them effectively infinite-sized targets along one axis. Trigger when designing global navigation, system menus, sticky headers, fixed sidebars, full-bleed CTAs, or anywhere you can put the most-frequent or hardest-to-find actions. Trigger when reviewing an app that has wasteful margins on every side and asks the user to aim for tiny targets in the middle. Sub-aspect of `fitts-law`; read that first if you haven't already.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

fitts-law-touch-targets

When your agent uses it

Use this skill when designing for touch — phones, tablets, kiosks, in-car displays, smart-TV remotes, anything where the input is a finger or thumb rather than a precise pointer. Trigger when sizing buttons for mobile, debugging "users keep mistapping," designing a mobile bottom-nav, picking icon sizes for a phone toolbar, or reviewing whether a desktop UI is touch-friendly. Sub-aspect of `fitts-law`; read that first if you haven't already.

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub

forgiveness

When your agent uses it

Use this skill whenever a design lets users do something they might regret — delete, send, publish, charge, transfer, archive, overwrite, irrecoverably commit. Trigger when designing destructive actions, undo systems, confirmation dialogs, soft-delete recovery, draft-saving, transaction reversal, "are you sure?" patterns, or any flow where a wrong move costs the user time, data, money, or trust. Trigger when the user mentions "users keep deleting things," "we get support tickets about lost data," "is this dangerous?", or when reviewing destructive UI. Forgiveness is one of the central principles in 'Universal Principles of Design' (Lidwell, Holden, Butler 2003) and one of Nielsen's 10 heuristics ("user control and freedom").

What it loads into context

Token counts are estimates. Scripts run separately; they are not counted as reference context.

No excerpt is shown for this license. Read the source on GitHub.

View the complete source on GitHub