A skill your agent uses whenever the question is how to make a composition feel organized — what belongs with what, where groups end, how related items can be visually bound without resorting to…

Apache-2.0Auto-check passed

Install Proximity

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

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

GitHub CLI
$ gh skill install hashgraph-online/awesome-codex-plugins proximity --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/perception-and-hierarchy-principles/skills/proximity .claude/skills/proximity && 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
proximity
GitHub stars
1.2k
Token cost
~3k tokens
SKILL.md length
1,224 words
Files
2 (incl. references)
Skills in repo
686
Repo updated
First seen
Licence
Apache-2.0

At a glance

A skill your agent uses whenever the question is how to make a composition feel organized — what belongs with what, where groups end, how related items can be visually bound without resorting to…

  • Works in 4 steps: Squint test for grouping. Squint until… → Read the cards aloud. "Title, then… → Two-finger test. With two fingers, can… → …
  • The question is how to make a composition feel organized — what belongs with what
  • SKILL.md covers Definition (in our own words), Origins and research lineage, Why proximity matters and When to apply, plus 8 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Proximity is an agent skill from hashgraph-online/awesome-codex-plugins. Use this skill whenever the question is how to make a composition feel organized — what belongs with what, where groups end, how related items can be visually bound without resorting to borders or boxes. Trigger when laying out forms, tables, navigation, lists, cards, dashboards, or any composition with multiple distinguishable groups of content. Trigger when a layout "feels disorganized," when users are confused which label goes with which input, when grouping is being attempted with borders that look heavy, or…

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

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

  • The question is how to make a composition feel organized — what belongs with what
  • Where groups end
  • How related items can be visually bound without resorting to borders
  • Laying out forms

Example prompts

  • “feels disorganized,”
  • “/proximity”

Workflow steps

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

  1. Squint test for grouping. Squint until detail blurs. Each visual cluster should be obvious as a cluster, with clear gaps between clusters…
  2. Read the cards aloud. "Title, then metadata, then body, then actions." If you can hear the pauses between groups, proximity is working. If…
  3. Two-finger test. With two fingers, can you point at a single group and feel that the boundaries are clear? If your finger keeps drifting…
  4. Strip the borders. Remove every border on the page (mentally or actually). If structure collapses, you were leaning on borders to do…

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 (its code samples are html).

    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

Proximity loads about 3k tokens when it runs, and up to ~4.7k if it reads all its reference files. Until then it costs about 196 tokens; SKILL.md has 1,224 words of instructions outside code blocks.

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

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,224 words, ~3,050 tokens.

Download SKILL.mdSave it as .claude/skills/proximity/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.
name
proximity
description
Use this skill whenever the question is how to make a composition feel organized — what belongs with what, where groups end, how related items can be visually bound without resorting to borders or boxes. Trigger when laying out forms, tables, navigation, lists, cards, dashboards, or any composition with multiple distinguishable groups of content. Trigger when a layout "feels disorganized," when users are confused which label goes with which input, when grouping is being attempted with borders that look heavy, or when a designer is reaching for color to encode grouping. Proximity is the cheapest, most powerful grouping tool in design; this skill teaches how to use spacing as the primary grouping mechanism, with sub-aspect skills for forms, tables, and navigation.

Proximity

Proximity is one of the original Gestalt grouping laws: elements close together are perceived as belonging together; elements farther apart are perceived as separate. It is the cheapest grouping mechanism in the designer's toolkit — it requires no ink, no color, no chrome, only the deliberate distribution of space. Used well, proximity makes most other grouping tools (borders, backgrounds, dividers) unnecessary.

Definition (in our own words)

When the human visual system encounters a set of similar elements, it organizes them into groups based on relative spatial distance. Items that share a small gap are perceived as a unit; items separated by a larger gap are perceived as belonging to different units. This perceptual grouping happens preattentively — before conscious thought, before reading. It is one of the most reliable findings in perception research, observed in infants, across cultures, and across animal species.

Origins and research lineage

  • Gestalt psychology (Wertheimer, 1923) formalized the laws of perceptual grouping, of which Proximity (Gesetz der Nähe) is the most basic. Wertheimer's original demonstrations used dots arranged at varying distances; the perceived groupings shifted dramatically with small spacing changes.
  • Treisman's feature integration theory (1980s) and the broader preattentive-processing literature established that grouping by spacing happens within the first ~200ms of viewing — before the user has consciously "looked" at anything.
  • Information design (Tufte; Krug, Don't Make Me Think, 2000) translated proximity from perception research into web/UI practice, particularly in the design of forms and information dense surfaces.
  • Web usability research (Nielsen Norman Group studies on form perception, label-input pairing) repeatedly shows that label-input ambiguity — usually a proximity failure — is among the top usability issues in form design.

Why proximity matters

Every layout makes implicit proximity claims. If a label is equidistant from the input above and the input below, the user must read carefully to figure out which it labels. If two cards are visually identical to two surrounding cards, they read as one group of four — even when conceptually they're two pairs.

Proximity failures are silent: users don't report "this label is ambiguous"; they just take longer, make more mistakes, and feel a low-grade frustration they can't articulate. This is why proximity is one of the highest-leverage things to get right in dense interfaces — small spacing decisions determine whether the page feels organized or chaotic.

When to apply

  • Forms — every label-input pair, every section, every fieldset. Proximity is the dominant principle in form layout.
  • Lists and tables — row spacing, column spacing, group separators.
  • Navigation — clusters of related links, dividers between sections.
  • Cards — internal layout (title, metadata, body, action) and external layout (cards-in-a-grid).
  • Dashboards — grouping of related KPIs.
  • Settings pages — sections, sub-sections, grouped controls.

In short: anywhere you have ≥3 elements and need to communicate which belong together.

When NOT to apply (or when to be careful)

  • When everything genuinely has equal status. A list of 100 search results doesn't want sub-grouping; the user is scanning sequentially. Adding proximity-based grouping where there is no real grouping is noise.
  • When grouping must survive responsive reflow. If your nice 3-column grid wraps to 1 column on mobile, the proximity grouping that worked horizontally may collapse vertically. Plan for both.
  • When proximity conflicts with continuity. Sometimes elements that share a baseline or column should read as a row, even with internal gaps. Then alignment beats proximity (see Good Continuation).

How to encode grouping with proximity

The trick is creating a spacing hierarchy: gaps inside a group should be smaller than gaps between groups, and the difference should be perceptually obvious. A 4px gap looks roughly like a 6px gap; the eye can't tell. A 4px gap is unmistakably tighter than a 16px gap.

A useful spacing scale (most design systems land somewhere near this):

gap-1   = 0.25rem (4px)    inside a tight pair (label/input)
gap-2   = 0.5rem  (8px)    inside a closely related set
gap-3   = 0.75rem (12px)   between fields in a section
gap-4   = 1rem    (16px)   between minor groups
gap-6   = 1.5rem  (24px)   between sections
gap-8   = 2rem    (32px)   between major regions
gap-12  = 3rem    (48px)   between page-level zones

Adjacent values in the scale should differ by at least 1.5× — preferably 2× — for the eye to register them as different ranks of grouping. Don't use both gap-3 and gap-4 in the same composition for different grouping levels; they look identical.

Worked examples

Example 1: a label-input pair (the canonical case)

Anti-pattern (ambiguous):

html
<form>
  <label>Email</label>
  <input type="email" />
  <label>Password</label>
  <input type="password" />
</form>

With default browser margins, each label sits roughly equidistant from the input above and the input below. The user has to read to figure out the pairing.

Right (proximity binds the pair):

html
<form style="display: grid; gap: 1rem;">                  <!-- gap-4 between fields -->
  <div style="display: grid; gap: 0.25rem;">              <!-- gap-1 between label and input -->
    <label for="email">Email</label>
    <input id="email" type="email" />
  </div>
  <div style="display: grid; gap: 0.25rem;">
    <label for="password">Password</label>
    <input id="password" type="password" />
  </div>
</form>

Now the gap inside each pair (4px) is unmistakably tighter than the gap between pairs (16px). Pairing reads instantly without any reading.

Show full SKILL.md (503 more words)Show less
Example 2: a settings page with three sections
html
<style>
  .settings { display: grid; gap: 3rem; }       /* gap-12 between sections */
  .section  { display: grid; gap: 1rem; }       /* gap-4 between fields */
  .section h2 { margin-bottom: 0.5rem; }        /* heading slightly closer to its fields */
  .field { display: grid; gap: 0.25rem; }       /* gap-1 inside label/input pair */
</style>

<form class="settings">
  <section class="section">
    <h2>Profile</h2>
    <div class="field"><label>Name</label><input /></div>
    <div class="field"><label>Email</label><input /></div>
  </section>
  <section class="section">
    <h2>Notifications</h2>
    <div class="field"><label>Frequency</label><select>...</select></div>
    <div class="field"><label>Channels</label><input /></div>
  </section>
  <section class="section">
    <h2>Security</h2>
    <div class="field"><label>Password</label><input type="password" /></div>
  </section>
</form>

Three nested ranks of proximity (4px / 16px / 48px) carry the entire grouping. No borders, no boxes, no dividers, no color — just space.

Example 3: a card with title, metadata, body, and action
html
<style>
  .card { display: grid; gap: 1rem; padding: 1.5rem; }
  .card-header { display: grid; gap: 0.25rem; }     /* title + metadata are paired */
  .card-actions { display: flex; gap: 0.5rem; margin-top: 0.5rem; }
</style>

<article class="card">
  <header class="card-header">
    <h3>Q4 financial review</h3>
    <p class="meta">Updated 3 minutes ago · Owner: Maria</p>
  </header>
  <p>This quarter shows record revenue across the SMB segment...</p>
  <div class="card-actions">
    <button>Open</button>
    <button>Share</button>
  </div>
</article>

Three groupings: title-metadata (tight pair), body (its own paragraph), actions (their own row). Each cluster reads independently; together they form the card.

Example 4: a navigation menu with sections
html
<nav style="display: grid; gap: 1.5rem;">                <!-- gap between sections -->
  <div style="display: grid; gap: 0.25rem;">             <!-- tight gap between links -->
    <a href="/dashboard">Dashboard</a>
    <a href="/projects">Projects</a>
    <a href="/team">Team</a>
  </div>
  <div style="display: grid; gap: 0.25rem;">
    <a href="/settings">Settings</a>
    <a href="/billing">Billing</a>
    <a href="/logout">Sign out</a>
  </div>
</nav>

Two clear sections, no dividers needed. The eye reads the gap between them as a section break.

Anti-patterns

  • The four-equidistant trap. Label, input, label, input — all spaced the same. Common in browser-default form rendering. Always tighter inside the pair, looser between pairs.
  • Borders as grouping. Reaching for border: 1px solid grey around every group adds visual weight without doing what proximity already does for free. Borders are a fallback for when proximity isn't enough.
  • Inconsistent gaps for the same role. Three sections on a page, each separated by a different gap. The eye reads inconsistency as accident; settle on one section gap and use it everywhere.
  • Equal gaps top-to-bottom in a card. Header, body, footer all separated by the same gap. The user has to read to figure out the structure. Vary gaps to encode role.
  • Whitespace orphans. A heading close to its content, but with so much space below the content that the next heading attaches to the previous content rather than its own. Always: heading-tighter-to-its-content; sections-looser-than-fields.

Heuristics

  1. Squint test for grouping. Squint until detail blurs. Each visual cluster should be obvious as a cluster, with clear gaps between clusters. If the page is one continuous mass, proximity is too uniform.
  2. Read the cards aloud. "Title, then metadata, then body, then actions." If you can hear the pauses between groups, proximity is working. If everything runs together, the gaps are equal.
  3. Two-finger test. With two fingers, can you point at a single group and feel that the boundaries are clear? If your finger keeps drifting into the next group, the boundary is too ambiguous.
  4. Strip the borders. Remove every border on the page (mentally or actually). If structure collapses, you were leaning on borders to do proximity's job.
  • uniform-connectedness — when proximity isn't enough, a shared background or container creates a stronger group; proximity tried first.
  • similarity — items that look alike are also grouped; combines with proximity.
  • good-continuation — items aligned on an axis read as a row, even with internal spacing.
  • hierarchy — proximity establishes grouping, hierarchy establishes ranking between groups.
  • signal-to-noise-ratio — proximity reduces noise by replacing chrome (borders, backgrounds) with negative space.
  • horror-vacui — proximity requires whitespace; resist filling it.

Sub-aspect skills

  • proximity-form-fields — applying proximity to form layouts, label-input pairs, sections.
  • proximity-data-tables — row spacing, column spacing, total rows, group separators.
  • proximity-navigation — sidebar groups, top-nav clusters, mobile menus.

Final note

Proximity is the principle most likely to be invisible when working and noisy when failing. The reward for getting it right is that the page feels organized in a way no one can quite pinpoint — they just don't get confused.

© 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/perception-and-hierarchy-principles/skills/proximity of hashgraph-online/awesome-codex-plugins.

  • SKILL.md
  • references/gestalt-and-grouping-research.md

Open the folder on GitHubat commit 78497e5

Compare with similar skills

Proximity 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.

Proximity compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Proximity this skillhashgraph-online/awesome-codex-plugins1.2k—~3kAutomated safety check: PassApache-2.0
Frontend Slideszarazhangrui/frontend-slides30k16 repos~7kAutomated safety check: PassMIT
Algorithmic Art with p5.jsanthropics/skills180k38 repos~4.9kAutomated safety check: PassApache-2.0
Canvas Designanthropics/skills180k52 repos~3kAutomated safety check: PassApache-2.0
Impeccablebestofjs/bestofjs3.1k27 repos~2.6kAutomated safety check: PassMIT
Brand and Design Toolkitnextlevelbuilder/ui-ux-pro-max-skill134k1 repos~3.5kAutomated safety check: PassMIT

Similar skills

  • Frontend Slides

    zarazhangrui/frontend-slides

    Builds animated HTML slide decks that run in the browser with no dependencies, or converts PowerPoint files to the web, starting from visual style previews.

    30k GitHub starsUsed in 16 repos~7k tokens
    Documents & OfficeAuto-check passed
  • Official

    Creates original generative art in two steps: a written algorithmic philosophy, then a p5.js sketch with seeded randomness and an interactive viewer for exploring parameters.

    180k GitHub starsUsed in 38 repos~4.9k tokens
    Media & CreativeAuto-check passed
  • Canvas Design

    anthropics/skills

    Official

    Creates original posters and static art as PNG or PDF by first writing a short design philosophy, then expressing it visually on a canvas.

    180k GitHub starsUsed in 52 repos~3k tokens
    Media & CreativeAuto-check passed
  • Impeccable

    bestofjs/bestofjs

    A skill your agent uses when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a…

    3.1k GitHub starsUsed in 27 repos~2.6k tokens
    Frontend & DesignAuto-check passed
  • Brand and Design Toolkit

    nextlevelbuilder/ui-ux-pro-max-skill

    Bundles design tasks behind one skill: brand identity, tokens, UI styling, logos, corporate identity mockups, slides, banners, icons and social images.

    134k GitHub starsUsed in 1 repo~3.5k tokens
    Media & CreativeAuto-check passed
  • HyperFrames Animation

    heygen-com/hyperframes

    Collects motion rules, scene blueprints, transitions and runtime adapters for HyperFrames video compositions, with GSAP as the default animation runtime.

    59k GitHub starsUsed in 3 repos~2.1k tokens
    Media & CreativeAuto-check passed

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 Proximity

What does Proximity do?

A skill your agent uses whenever the question is how to make a composition feel organized — what belongs with what, where groups end, how related items can be visually bound without resorting to…. Proximity is an agent skill from hashgraph-online/awesome-codex-plugins. Use this skill whenever the question is how to make a composition feel organized — what belongs with what, where groups end, how related items can be visually bound without resorting to borders or boxes.

When should I use Proximity?

Proximity fits situations like: the question is how to make a composition feel organized — what belongs with what; where groups end; how related items can be visually bound without resorting to borders; laying out forms.

How do I install Proximity in Claude Code?

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

How do I install Proximity in Codex?

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

Can I use Proximity 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 proximity -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/proximity, .gemini/skills/proximity, .github/skills/proximity and .opencode/skills/proximity in your project.

What does Proximity need to run?

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

Does Proximity 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 Proximity 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 Proximity use?

Proximity 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 Proximity use?

About 3k tokens (SKILL.md is roughly 12k 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.6k tokens, read only when the agent opens those files.

What are the alternatives to Proximity?

Skills that share tags, products or a category with Proximity: Frontend Slides (zarazhangrui/frontend-slides, 30k stars), Algorithmic Art with p5.js (anthropics/skills, 180k stars), Canvas Design (anthropics/skills, 180k stars) and Impeccable (bestofjs/bestofjs, 3.1k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Proximity?

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.