Apply natural mapping — the strongest form of mapping, in which the spatial position, motion, or shape of a control directly corresponds to what it affects.

Apache-2.0Auto-check passedProductivity & Automation

Install Mapping Natural

skills CLI
$ npx skills add hashgraph-online/awesome-codex-plugins --skill mapping-natural -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install hashgraph-online/awesome-codex-plugins mapping-natural --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/hashgraph-online/awesome-codex-plugins.git skills-src && mkdir -p .claude/skills && cp -r skills-src/plugins/HDeibler/universal-design-principles/plugins/interaction-and-control-principles/skills/mapping-natural .claude/skills/mapping-natural && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
mapping-natural
GitHub stars
1.2k
Token cost
~2.5k tokens
SKILL.md length
1,493 words
Files
2 (incl. references)
Skills in repo
686
Repo updated
First seen
Licence
Apache-2.0

At a glance

Apply natural mapping — the strongest form of mapping, in which the spatial position, motion, or shape of a control directly corresponds to what it affects.

  • Works in 4 steps: Use natural mapping if available. → Use a strong cultural convention (volume… → Use a labeled control with an… → …
  • Designing physical control panels
  • SKILL.md covers Recognizing when natural…, Worked examples, When natural mapping is not… and Common anti-patterns, plus 3 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Mapping Natural is an agent skill from hashgraph-online/awesome-codex-plugins. Apply natural mapping — the strongest form of mapping, in which the spatial position, motion, or shape of a control directly corresponds to what it affects. Use when designing physical control panels, in-screen controls that affect specific regions of a UI, chart legends, multi-target remote controls, vehicle dashboards, or any situation where the user must connect "this control" to "that affected thing." A natural mapping is one a first-time user can predict without instruction. When the form factor allows it…

Its SKILL.md is about 2.5k tokens, which your agent loads only when the skill is triggered. The skill folder holds 2 other files, including reference files (for example `references/spatial-correspondence.md`).

It sits in Productivity & Automation, covering Desktop control. The repository describes itself as: A curated list of awesome OpenAI Codex / ChatGPT plugins, skills, and resources. The 1 Codex Marketplace. See live plugins at: https://hol.org/plugins/best-codex-plugins. The licence is Apache-2.0.

When your agent uses it

  • Designing physical control panels
  • In-screen controls that affect specific regions of a UI
  • Multi-target remote controls
  • Vehicle dashboards

Example prompts

  • “this control”
  • “that affected thing.”
  • “/mapping-natural”

Workflow steps

4 steps, taken from the first numbered list in SKILL.md.

  1. Use natural mapping if available.
  2. Use a strong cultural convention (volume slider direction, gear icon for settings) if natural mapping is unavailable.
  3. Use a labeled control with an unambiguous label (this is fine — labels are not failure, they're insurance).
  4. Use a contextual cue that highlights the affected region when the control is touched or hovered (the speaker icon flashes when you adjust…

What it can do on your machine

Read from SKILL.md and the folder at commit 78497e5. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Mapping Natural loads about 2.5k tokens when it runs, and up to ~4.3k if it reads all its reference files. Until then it costs about 145 tokens; SKILL.md has 1,493 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~145
When it runs · the whole SKILL.md, loaded when a task matches
~2.5k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~4.3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from hashgraph-online/awesome-codex-plugins at commit 78497e5, republished under its Apache-2.0 licence (© hashgraph-online). 1,493 words, ~2,492 tokens.

Download SKILL.mdSave it as .claude/skills/mapping-natural/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.
name
mapping-natural
description
Apply natural mapping — the strongest form of mapping, in which the spatial position, motion, or shape of a control directly corresponds to what it affects. Use when designing physical control panels, in-screen controls that affect specific regions of a UI, chart legends, multi-target remote controls, vehicle dashboards, or any situation where the user must connect "this control" to "that affected thing." A natural mapping is one a first-time user can predict without instruction. When the form factor allows it, natural mapping is essentially free correctness.

Mapping — natural (spatial and physical)

Natural mapping is the form of mapping that requires no learning. The control is positioned where the affected element is, or moves the way the affected element moves, or is shaped like the affected element. The user does not have to think; they reach.

Natural mapping comes in two forms.

Spatial correspondence. The control's position in space matches the affected element's position in space. Stove knobs in a 2×2 grid that mirror the burners. The seat-position controls on a Mercedes-Benz, shaped like a tiny seat — push the headrest forward to recline, push the seat back forward to slide forward. A chart legend whose entries appear in the same vertical order as the data lines they describe, so the topmost legend entry corresponds to the topmost line. A row of speaker volume controls arranged left-to-right in the same order as the speakers in the room.

Physical analogy. The control's motion or shape corresponds to a physical action whose meaning is universally understood — usually because it mimics gravity, force, or direction. Up = more, down = less. Right = forward in time, left = backward. Clockwise = increase, counterclockwise = decrease (in cultures that read left-to-right; the convention is local but extremely strong). Pinch out = zoom in. Pull a slider toward you = grab and bring closer. These mappings are not innate, but they're embodied — users feel them rather than think them — and breaking them generates immediate confusion that no amount of labeling will fix.

Recognizing when natural mapping is available

The form factor either supports natural mapping or it doesn't. A four-burner stove with the burners in a 2×2 grid and physical room for knobs in a 2×2 grid: spatial mapping available. A cooktop with knobs along the front edge and burners behind: spatial mapping not directly available; you'll have to weaken to a labeled or angled approximation. A horizontal slider for an inherently vertical quantity (height, depth, intensity from low-to-high): natural mapping mismatched; consider rotating the slider or changing the metaphor.

The question to ask early in a design is: what is the spatial or physical structure of the thing being controlled, and can the controls share that structure?

Worked examples

A four-burner stove control panel

Bad design: four knobs in a row labeled "FL FR RL RR" (front-left, front-right, rear-left, rear-right). The user has to read the label, decode the abbreviation, locate the burner, and turn the right knob. Three cognitive steps for an action that should require zero. Approximately 5–10% of users will turn the wrong knob in distracted use.

Good design: four knobs in a 2×2 grid, each knob positioned directly in front of (or below) the burner it controls. No label needed. The user reaches for the knob in the position of the burner. The error rate drops near zero.

When the cooktop is too shallow for a 2×2 grid, the next-best approach is to angle the row of knobs so each knob is at least visually closer to its corresponding burner — paired with a small dot or graphic showing the relationship. This is weaker than true spatial correspondence but stronger than abstract labels.

Volume controls on a multi-speaker setup

Bad design: a settings panel labeled "Speaker 1, Speaker 2, Speaker 3, Speaker 4" with sliders. The user does not remember which physical speaker is which.

Good design: a small floor plan showing the speakers in their actual positions, with each volume slider positioned next to its speaker. Or, if a floor plan is too elaborate, a row of sliders arranged in the same left-to-right order as the speakers in the room, with a brief location label ("Living Room — South Wall").

The principle: the user is reasoning about the room, so the controls should be arranged like the room.

Chart legend ordering

Bad design: a multi-line chart with five data series; the legend is alphabetical. The user has to scan the chart, identify a line of interest, then scan the legend to find which series name corresponds to which color. Two scans, with a memory step between.

Good design: the legend is ordered by the vertical position of each line at the right edge of the chart (or the left edge — pick a consistent anchor). The topmost line in the chart has the topmost legend entry. The user's eye traces from the line directly to its label. One scan.

This is a small change with a large effect. It is one of the highest-ROI improvements you can make to a multi-series chart.

Video editor timeline

Bad design: a "skip forward" button positioned at the top of the screen, far from the timeline. A "split clip" command in a menu somewhere.

Good design: skip controls directly under the timeline, where the user is already looking. Split-clip is a button that appears at the playhead — the visual marker on the timeline — when the playhead is positioned over a clip. The control is at the location it affects.

Brightness slider direction

Bad design: a brightness slider where dragging down makes the screen brighter. This violates the up-is-more convention.

Good design: dragging up (or right, depending on orientation) increases brightness. The user does not have to think.

This convention is so strong that violating it triggers visible double-takes from users; many will drag the slider the "right" way the first time, see the wrong result, and pause for a moment of disorientation.

Show full SKILL.md (603 more words)Show less
Pinch to zoom

The pinch-to-zoom gesture is a strong physical analogy: you are stretching the image between two fingers, the way you might stretch fabric. Reverse pinch (zoom out) corresponds to crumpling, also intuitive. The mapping is so strong that it crossed cultures and platforms within a few years of being introduced and is now nearly universal.

By contrast, "double-tap to zoom in to a fixed level" is a weaker mapping — there's no physical analogy — and survives only because pinch is also available as the natural-mapping fallback.

When natural mapping is not available

If the form factor or screen real estate makes natural mapping impossible, do not fake it. A diagram next to each control showing what it affects is harder to interpret than a clear label. The hierarchy of fallbacks is:

  1. Use natural mapping if available.
  2. Use a strong cultural convention (volume slider direction, gear icon for settings) if natural mapping is unavailable.
  3. Use a labeled control with an unambiguous label (this is fine — labels are not failure, they're insurance).
  4. Use a contextual cue that highlights the affected region when the control is touched or hovered (the speaker icon flashes when you adjust speaker 2's volume).

Avoid the temptation to invent a fake spatial mapping (a tiny abstract diagram, a color-code that requires a key) when no real one exists.

Common anti-patterns

Aesthetic uniformity destroying mapping. Designers arrange controls in a clean grid because it looks tidy, ignoring that the controlled elements are not in a corresponding grid. The four-burner stove with knobs in a row is the canonical example. The fix is to choose a layout that mirrors the controlled space, even at some cost to visual neatness.

Inverted directional mappings. A volume slider where down is louder, a "back" button on the right of the screen, a brightness control that goes left-to-right with darker on the right. These are usually accidents of code (a coordinate system was inverted somewhere, and the visual was not corrected) but they read as design failures and generate constant low-grade confusion.

Mapping by color when color is the only cue. Color-coded controls without spatial correspondence ("the red knob controls the red burner") force the user to look at both control and target, then mentally connect them. They also fail entirely for color-blind users. Color is a useful supplement to spatial mapping but a poor replacement.

Animating between unmapped positions. A control whose effect snaps to a new position with no transition forces the user to re-locate the affected element each time. Animated transitions that move from old to new state preserve the mapping by showing the relationship as motion.

Heuristic checklist

Before shipping a new control, ask: Where is the thing being affected, and where is the control? If they are not in the same location or arranged in the same pattern, ask whether they can be. Does the motion of the control correspond to the change in the affected element? If not, can it be made to? If you removed all labels from the controls, could a first-time user still operate them? If yes, the mapping is doing its job.

  • mapping-cultural — for the cases where natural mapping isn't available and you have to fall back to convention.
  • affordance — what the control suggests it can do (mapping picks up where affordance leaves off).
  • proximity — controls that affect the same thing should be close to each other (the layout-level form of mapping).
  • recognition-over-recall — natural mapping is recognition-driven; the user sees and reaches.

See also

  • references/spatial-correspondence.md — case studies and patterns for spatial mappings, including chart legends, dashboards, and physical control panels.

© hashgraph-online, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file (references) in plugins/HDeibler/universal-design-principles/plugins/interaction-and-control-principles/skills/mapping-natural of hashgraph-online/awesome-codex-plugins.

  • SKILL.md
  • references/spatial-correspondence.md

Open the folder on GitHubat commit 78497e5

Compare with similar skills

Mapping Natural next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Mapping Natural compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Mapping Natural this skillhashgraph-online/awesome-codex-plugins1.2k—~2.5kAutomated safety check: PassApache-2.0
Vision SkillsAnionex/agent-vision-toolkit1.2k1 repos~4kAutomated safety check: PassMIT
Mac Computer UseTo3akaRin/mac-computer-use1.1k1 repos~495Automated safety check: PassMIT
Crabbox Appsopenclaw/openclaw392k—~1.5kAutomated safety check: PassMIT
Agent Managementautonomous-ai/Physical-AI-Operating-System381—~1.7kAutomated safety check: PassApache-2.0
Computer Usebam-bam-2/solo-skills3671 repos~915Automated safety check: PassMIT

Similar skills

  • Vision Skills

    Anionex/agent-vision-toolkit

    Local vision CLIs: glance (describe/ask/OCR an image), ground (locate a target, pixel box), detect (element inventory), trace (image to SVG geometry), crop (cut a pixel box to a file), and…

    1.2k GitHub starsUsed in 1 repo~4k tokens
    Productivity & AutomationAuto-check passed
  • Mac Computer Use

    To3akaRin/mac-computer-use

    操作 macOS 桌面应用,探测窗口和自动化接口、截图、读取或修改辅助功能元素、执行鼠标键盘动作,以及通过 CDP 操作内嵌 Chromium 页面。适用于桌面应用自动化与界面验收;普通网页任务优先使用已有浏览器工具。

    1.1k GitHub starsUsed in 1 repo~495 tokens
    Productivity & AutomationAuto-check passed
  • Crabbox Apps

    openclaw/openclaw

    A skill your agent uses when asked to open, run, test, or show an app in Crabbox, including native desktops, web previews, and computer use on a temporary machine.

    392k GitHub stars~1.5k tokensUpdated today
    Productivity & AutomationAuto-check passed
  • Agent Management

    autonomous-ai/Physical-AI-Operating-System

    Legacy Autonomous Buddy control for explicitly requested Buddy coding sessions.

    381 GitHub stars~1.7k tokensUpdated today
    Productivity & AutomationAuto-check passed
  • Computer Use

    bam-bam-2/solo-skills

    Use Orca's computer-use CLI to inspect and operate local desktop app windows through accessibility trees, screenshots, and safe UI actions.

    367 GitHub starsUsed in 1 repo~915 tokens
    Productivity & AutomationAuto-check passed
  • Cloud Computer Use

    davidondrej/cloudroom-core

    See and control desktop apps on this Cloud sandbox’s virtual Linux screen with cloudroom computer-use: launch GUI apps you build or install, read their UI, click, type, and take screenshots.

    272 GitHub stars~881 tokensUpdated yesterday
    Productivity & AutomationAuto-check: notes

More from hashgraph-online/awesome-codex-plugins

All 686 skills in this repo
  • Anime Reaction Gif

    hashgraph-online/awesome-codex-plugins

    Create original anime-style reaction stickers as looping GIFs and MP4 previews, using generated character pose sheets and timed key poses.

    1.2k GitHub stars~922 tokensUpdated today
    Auto-check passed
  • Calibredb

    hashgraph-online/awesome-codex-plugins

    Manage and query Calibre libraries with the calibredb CLI (local paths or Calibre Content server URLs).

    1.2k GitHub stars~1k tokensUpdated today
    Auto-check passed
  • Rust API Test Harness

    hashgraph-online/awesome-codex-plugins

    A skill your agent uses when adding, changing, testing, or debugging Rust HTTP APIs and services, especially when Codex needs black-box integration tests, random-port app startup, real database test…

    1.2k GitHub stars~1.7k tokensUpdated today
    Auto-check passed
  • Art

    hashgraph-online/awesome-codex-plugins

    Make a studio's game look like something at build time — a cover from a real frame of the game (free), painted covers, backdrops, textures and character plates from image models through the…

    1.2k GitHub stars~2.4k tokensUpdated today
    Auto-check passed
  • Game Balance Economy

    hashgraph-online/awesome-codex-plugins

    Balance game difficulty, resources, rewards, probability, progression, economies, and dominant strategies.

    1.2k GitHub stars~618 tokensUpdated today
    Auto-check passed
  • Manuscript Engagement Analytics

    hashgraph-online/awesome-codex-plugins

    Analyze nonfiction manuscripts for reader engagement signals, including heading-level word counts, slow starts, long slogs, weak takeaway titles, value pacing, beta-reader comment dropoff, and…

    1.2k GitHub stars~875 tokensUpdated today
    Auto-check passed

Questions about Mapping Natural

What does Mapping Natural do?

Apply natural mapping — the strongest form of mapping, in which the spatial position, motion, or shape of a control directly corresponds to what it affects. Mapping Natural is an agent skill from hashgraph-online/awesome-codex-plugins. Apply natural mapping — the strongest form of mapping, in which the spatial position, motion, or shape of a control directly corresponds to what it affects.

When should I use Mapping Natural?

Mapping Natural fits situations like: designing physical control panels; in-screen controls that affect specific regions of a UI; multi-target remote controls; vehicle dashboards.

How do I install Mapping Natural in Claude Code?

Run `npx skills add hashgraph-online/awesome-codex-plugins --skill mapping-natural -a claude-code`. Or copy the skill folder (plugins/HDeibler/universal-design-principles/plugins/interaction-and-control-principles/skills/mapping-natural in hashgraph-online/awesome-codex-plugins) into .claude/skills/mapping-natural in your project. Claude Code loads it when a task matches its description.

How do I install Mapping Natural in Codex?

Run `npx skills add hashgraph-online/awesome-codex-plugins --skill mapping-natural -a codex`. Or copy the skill folder (plugins/HDeibler/universal-design-principles/plugins/interaction-and-control-principles/skills/mapping-natural in hashgraph-online/awesome-codex-plugins) into .agents/skills/mapping-natural in your project. Codex loads it when a task matches its description.

Can I use Mapping Natural in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add hashgraph-online/awesome-codex-plugins --skill mapping-natural -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/mapping-natural, .gemini/skills/mapping-natural, .github/skills/mapping-natural and .opencode/skills/mapping-natural in your project.

What does Mapping Natural need to run?

SKILL.md names no scripts, command-line tools or credentials: Mapping Natural is instructions for the agent only.

Does Mapping Natural access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Mapping Natural safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Mapping Natural use?

Mapping Natural is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Mapping Natural use?

About 2.5k tokens (SKILL.md is roughly 10k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 1.8k tokens, read only when the agent opens those files.

What are the alternatives to Mapping Natural?

Skills that share tags, products or a category with Mapping Natural: Vision Skills (Anionex/agent-vision-toolkit, 1.2k stars), Mac Computer Use (To3akaRin/mac-computer-use, 1.1k stars), Crabbox Apps (openclaw/openclaw, 392k stars) and Agent Management (autonomous-ai/Physical-AI-Operating-System, 381 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Mapping Natural?

hashgraph-online (a GitHub organization) maintains it in hashgraph-online/awesome-codex-plugins, which has 1,242 GitHub stars. The repository holds 686 skills in this directory. The repository was last updated on October 8, 2026.

Source: hashgraph-online/awesome-codex-plugins on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.