real-world-metaphors

Name: real-world-metaphors
Author: dembrandt

268installs5forks

How to install real-world-metaphors?

dembrandt/dembrandt-skills/real-world-metaphors

$npx -y skills add dembrandt/dembrandt-skills --skill real-world-metaphors

Installs into the current project.

Summary

UI patterns borrowed from the physical world feel immediately intuitive — cards feel graspable, carousels feel scrollable, drawers feel pullable. Use real-world metaphors deliberately to reduce the learning curve and make interactions feel natural. Use when designing layout patte

Files · 1

View on GitHub

SKILL.md

1	# Real-World Metaphors in UI
2
3	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.
4
5	Use them deliberately, not decoratively.
6
7	## Common Metaphors and When to Use Them
8
9	### Card
10	A card is a bounded, self-contained unit of content — like a physical index card or a product on a shelf.
11
12	Use when:
13	- Content items are discrete and comparable (products, people, articles, tasks)
14	- Each item needs to be scanned quickly and potentially acted on
15	- Items benefit from a visual thumbnail, image, or icon
16
17	Key properties:
18	- Cards should be graspable: elevation (`--shadow-sm`), border-radius, and clear boundary
19	- All cards in a set should be the same width; height can vary with content
20	- One primary action per card — secondary actions appear on hover or inside a detail view
21	- Cards imply "I can pick this up and do something with it" — if nothing happens on click, use a list instead
22
23	### Carousel / Horizontal Scroll
24	A carousel borrows from the physical act of flipping through a stack or sliding items along a rail.
25
26	Use when:
27	- There are more items than fit the viewport and browsing is the primary mode
28	- Items have a natural visual order (steps, featured content, media)
29	- The user is expected to explore, not to find a specific item
30
31	Caution:
32	- Carousels hide content — important items should not live only inside a carousel
33	- Auto-advancing carousels reduce user control; prefer user-driven navigation
34	- On mobile, a horizontal scroll without explicit navigation dots feels more natural than arrows
35
36	### Drawer / Side Panel
37	A drawer slides in from an edge, like a physical desk drawer — it brings additional context without replacing the current view.
38
39	Use when:
40	- Secondary detail is needed without losing context of the main view
41	- Editing or configuring an item while keeping the list visible behind
42	- Mobile navigation patterns (hamburger menu opens a side drawer)
43
44	Key properties:
45	- The drawer should feel anchored to an edge — left for navigation, right for detail/settings
46	- Always provide a clear close action (× button and clicking outside)
47	- The content behind should dim slightly (overlay) to signal the drawer is a layer above
48
49	### Accordion
50	Like a physical folder that expands to reveal contents — collapses to save space, expands to show detail.
51
52	Use when:
53	- Content has a clear parent–child hierarchy
54	- Most users need only a few sections at a time
55	- Vertical space is constrained
56
57	### Tabs
58	Like physical divider tabs in a binder — select a tab to see its section.
59
60	Use when:
61	- Content is divided into mutually exclusive, peer-level sections
62	- The user switches between sections frequently
63	- All tabs are equally relevant to the same context
64
65	Caution: Tabs imply peer-level, equal-importance sections. Do not use tabs for hierarchical navigation (use breadcrumbs or sidebar instead).
66
67	### Tooltip
68	Like a sticky note attached to an object — appears on hover, provides brief additional context.
69
70	Use when:
71	- An icon or control needs a short label that would clutter the layout if always visible
72	- A term or value needs brief explanation in context
73
74	Not a replacement for: clear labels, inline help text, or documentation for complex features.
75
76	## Principles for Using Metaphors Well
77
78	1. The metaphor should match the interaction — a card that does nothing on click creates a false affordance
79	2. Don't mix metaphors — a carousel inside a card inside a drawer creates cognitive noise
80	3. Mobile borrows different metaphors than desktop — swipe-to-dismiss, bottom sheets, and pull-to-refresh are mobile-

People who liked this also viewed

6 picks

Type

real-world-metaphors

268installs5forks

View on GitHub

How to install real-world-metaphors?

dembrandt/dembrandt-skills/real-world-metaphors

$npx -y skills add dembrandt/dembrandt-skills --skill real-world-metaphors

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Real-World Metaphors in UI
2
3	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.
4
5	Use them deliberately, not decoratively.
6
7	## Common Metaphors and When to Use Them
8
9	### Card
10	A card is a bounded, self-contained unit of content — like a physical index card or a product on a shelf.
11
12	Use when:
13	- Content items are discrete and comparable (products, people, articles, tasks)
14	- Each item needs to be scanned quickly and potentially acted on
15	- Items benefit from a visual thumbnail, image, or icon
16
17	Key properties:
18	- Cards should be graspable: elevation (`--shadow-sm`), border-radius, and clear boundary
19	- All cards in a set should be the same width; height can vary with content
20	- One primary action per card — secondary actions appear on hover or inside a detail view
21	- Cards imply "I can pick this up and do something with it" — if nothing happens on click, use a list instead
22
23	### Carousel / Horizontal Scroll
24	A carousel borrows from the physical act of flipping through a stack or sliding items along a rail.
25
26	Use when:
27	- There are more items than fit the viewport and browsing is the primary mode
28	- Items have a natural visual order (steps, featured content, media)
29	- The user is expected to explore, not to find a specific item
30
31	Caution:
32	- Carousels hide content — important items should not live only inside a carousel
33	- Auto-advancing carousels reduce user control; prefer user-driven navigation
34	- On mobile, a horizontal scroll without explicit navigation dots feels more natural than arrows
35
36	### Drawer / Side Panel
37	A drawer slides in from an edge, like a physical desk drawer — it brings additional context without replacing the current view.
38
39	Use when:
40	- Secondary detail is needed without losing context of the main view
41	- Editing or configuring an item while keeping the list visible behind
42	- Mobile navigation patterns (hamburger menu opens a side drawer)
43
44	Key properties:
45	- The drawer should feel anchored to an edge — left for navigation, right for detail/settings
46	- Always provide a clear close action (× button and clicking outside)
47	- The content behind should dim slightly (overlay) to signal the drawer is a layer above
48
49	### Accordion
50	Like a physical folder that expands to reveal contents — collapses to save space, expands to show detail.
51
52	Use when:
53	- Content has a clear parent–child hierarchy
54	- Most users need only a few sections at a time
55	- Vertical space is constrained
56
57	### Tabs
58	Like physical divider tabs in a binder — select a tab to see its section.
59
60	Use when:
61	- Content is divided into mutually exclusive, peer-level sections
62	- The user switches between sections frequently
63	- All tabs are equally relevant to the same context
64
65	Caution: Tabs imply peer-level, equal-importance sections. Do not use tabs for hierarchical navigation (use breadcrumbs or sidebar instead).
66
67	### Tooltip
68	Like a sticky note attached to an object — appears on hover, provides brief additional context.
69
70	Use when:
71	- An icon or control needs a short label that would clutter the layout if always visible
72	- A term or value needs brief explanation in context
73
74	Not a replacement for: clear labels, inline help text, or documentation for complex features.
75
76	## Principles for Using Metaphors Well
77
78	1. The metaphor should match the interaction — a card that does nothing on click creates a false affordance
79	2. Don't mix metaphors — a carousel inside a card inside a drawer creates cognitive noise
80	3. Mobile borrows different metaphors than desktop — swipe-to-dismiss, bottom sheets, and pull-to-refresh are mobile-

People who liked this also viewed

6 picks

Type