real-world-metaphors
Skill194 starsChanged 4 months agoMITView on GitHub
Cards, drawers, carousels and other patterns borrowed from the physical world. Use when designing layout patterns, gestures or navigation paradigms.
In this repository44 other files it gives its agents.
- algorithmic-color-paletteSkill
- app-shellSkill
- authentic-product-representationSkill
- brand-visual-languageSkill
- button-statesSkill
- clone-websiteSkill
- color-mode-and-themeSkill
- component-family-consistencySkill
- coordinated-data-viewsSkill
- data-display-and-selectionSkill
- dembrandtSkill
- domain-expert-configurationSkill
- elevation-and-depthSkill
- extract-designSkill
- form-designSkill
- generate-ui-from-brandSkill
- gestalt-ui-organisationSkill
- global-toolbar-controlsSkill
- information-architectureSkill
- layout-paradigms-and-consistencySkill
- loading-states-and-perceived-performanceSkill
- marketing-vs-product-systemSkill
- micro-interactionsSkill
- modal-and-overlay-patternsSkill
- modular-scale-typographySkill
- motion-and-storytellingSkill
- nielsen-usability-heuristicsSkill
- notifications-and-recoverySkill
- operational-expert-tool-uiSkill
- performance-and-web-vitalsSkill
- repeated-component-alignmentSkill
- responsive-paradigmsSkill
- scroll-areasSkill
- semantic-html-and-seoSkill
- sizing-unitsSkill
- status-colors-and-errorsSkill
- sticky-and-fixed-elementsSkill
- surface-separationSkill
- tab-navigationSkill
- ui-context-and-scopeSkill
- ui-densitySkill
- user-flows-and-guided-pathsSkill
- visual-emphasis-and-hierarchySkill
- wcag-accessibilitySkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 4 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 46
Use them deliberately, not decoratively.
- Distinctive: line 60
All cards in a set should be the same width.
- Distinctive: line 87
Always provide a clear close action (× button and clicking outside)
- Distinctive: line 104
All tabs are equally relevant to the same context
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Real-World Metaphors in UI
UI patterns borrowed from the physical world reduce the learning curve because users already know how they work. A card feels like something you can pick up. A carousel feels like flipping through a stack. A drawer feels like it slides out from the side. These metaphors carry affordance — the user knows what to do before reading any instructions.
Use them deliberately, not decoratively.
Common Metaphors and When to Use Them
Card
A card is a bounded, self-contained unit of content — like a physical index card or a product on a shelf.
Use when:
- Content items are discrete and comparable (products, people, articles, tasks)
- Each item needs to be scanned quickly and potentially acted on
- Items benefit from a visual thumbnail, image, or icon
Key properties:
- Cards should be graspable: elevation (
--shadow-sm), border-radius, and clear boundary - All cards in a set should be the same width; height can vary with content
- One primary action per card — secondary actions appear on hover or inside a detail view
- Cards imply "I can pick this up and do something with it" — if nothing happens on click, use a list instead
Carousel / Horizontal Scroll
A carousel borrows from the physical act of flipping through a stack or sliding items along a rail.
Use when:
- There are more items than fit the viewport and browsing is the primary mode
- Items have a natural visual order (steps, featured content, media)
- The user is expected to explore, not to find a specific item
Caution:
- Carousels hide content — important items should not live only inside a carousel
- Auto-advancing carousels reduce user control; prefer user-driven navigation
- On mobile, a horizontal scroll without explicit navigation dots feels more natural than arrows
Drawer / Side Panel
A drawer slides in from an edge, like a physical desk drawer — it brings additional context without replacing the current view.
Use when:
- Secondary detail is needed without losing context of the main view
- Editing or configuring an item while keeping the list visible behind
- Mobile navigation patterns (hamburger menu opens a side drawer)
Key properties:
- The drawer should feel anchored to an edge — left for navigation, right for detail/settings
- Always provide a clear close action (× button and clicking outside)
- The content behind should dim slightly (overlay) to signal the drawer is a layer above
Accordion
Like a physical folder that expands to reveal contents — collapses to save space, expands to show detail.
Use when:
- Content has a clear parent–child hierarchy
- Most users need only a few sections at a time
- Vertical space is constrained
Tabs
Like physical divider tabs in a binder — select a tab to see its section.
Use when:
- Content is divided into mutually exclusive, peer-level sections
- The user switches between sections frequently
- All tabs are equally relevant to the same context
Caution: Tabs imply peer-level, equal-importance sections. Do not use tabs for hierarchical navigation (use breadcrumbs or sidebar instead).
Tooltip
Like a sticky note attached to an object — appears on hover, provides brief additional context.
Use when:
- An icon or control needs a short label that would clutter the layout if always visible
- A term or value needs brief explanation in context
Not a replacement for: clear labels, inline help text, or documentation for complex features.
Principles for Using Metaphors Well
- The metaphor should match the interaction — a card that does nothing on click creates a false affordance
- Don't mix metaphors — a carousel inside a card inside a drawer creates cognitive noise
- Mobile borrows different metaphors than desktop — swipe-to-dismiss, bottom sheets, and pull-to-refresh are mobile-native; forcing them onto desktop feels wrong in both directions
- Elevation reinforces the metaphor — a card without shadow doesn't feel graspable; a drawer without an overlay doesn't feel layered
Review Checklist
- Does the chosen pattern match the physical metaphor users will intuit?
- Do cards have a clear primary action — not just decoration?
- Does the carousel or horizontal scroll have navigation affordance (dots, arrows, or partial next item visible)?
- Do drawers dim the background content to signal layering?
- Are physical metaphors consistent — the same pattern used for the same type of content throughout the product?
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

