visual-hierarchy
Skill2 starsChanged 11 days agoMITView on GitHub
Use whenever a screen or page needs a clear order of importance, in any language and at any length - "nothing stands out", "it looks flat, busy or like a template", "what should be the main thing", "make it pop", "which button should win", "why does everything compete". Covers the focal point and first screen of a landing page, app screen, dashboard, settings page, card, pricing section, empty state, slide or poster; the steps between levels, one primary action, how loud a warning, badge, price or recommended plan is, and whether a shadow, gradient, border or icon earns its place. Not for spacing values, type sizes, palettes and contrast numbers, page grids, chart encodings or logos.
5 other projects use a version of this.
Adopted by
Most recently taken up by
- Above-the-Fold-Studio/designmd-skillstheir own version, first seen Nov 1, 2026
- pengGgxp/skillstheir own version, first seen Oct 11, 2026
- SkillMedev/brand-visual-identitytheir own version, first seen Oct 5, 2026
- miovrag/claude-skillstheir own version, first seen Jun 12, 2026
- launchapp-dev/animus-clitheir own version, first seen Mar 15, 2026
Other versions5 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 5
- launchapp-dev/animus-cli★ 39same name
- miovrag/claude-skills★ 1same name
- pengGgxp/skills★ 1same name
- SkillMedev/brand-visual-identity★ 1same name
- Above-the-Fold-Studio/designmd-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository25 other files it gives its agents.
- agent-interface-designSkill
- brand-identitySkill
- chart-designSkill
- color-paletteSkill
- data-tablesSkill
- design-critiqueSkill
- design-system-builderSkill
- form-designSkill
- generated-ui-restyleSkill
- interface-behaviorSkill
- journey-and-service-mappingSkill
- layout-structureSkill
- practice-and-assessmentSkill
- presentation-designSkill
- pricing-and-packagingSkill
- responsive-layoutSkill
- sales-conversationsSkill
- showing-workSkill
- spacing-and-groupingSkill
- teaching-interfacesSkill
- typeface-selectionSkill
- typesettingSkill
- ui-motionSkill
- ui-polish-passSkill
- user-research-basicsSkill
The file
We split this skill into the rules it gives an agent
12 rules. 0 are common, 12 are distinctive, and 0 are very specific to this project.
0
Common
Most of the 5 edited versions we read keep these.
12
Distinctive
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 16
Not the numbers: spacing values (spacing-and-grouping), type sizes and ramps (typesetting), palettes and contrast floors (color-palette), …
- Distinctive: line 26
Subtract before adding: If the main thing will not stand out and cannot get louder, soften what surrounds it: tinted panels, secondary …
- Distinctive: line 29
Share edges, repeat roles: Every element shares an edge or axis with something.
- Distinctive: line 31
Check, then hand back: Run the quick checks below.
- Distinctive: line 35
Centering: Default: flush at the reading start, never a centered heading over flush-left text.
- Distinctive: line 36
Drama by context: Default: marketing, editorial and onboarding take large jumps in scale.
- Distinctive: line 38
Peer choices: Default: one primary per group.
- Distinctive: line 39
Fading: Default: rank secondary text by size or weight, or a modest value step.
- Distinctive: line 40
Decoration with identity: Default: cut what has no job.
- Distinctive: line 41
Position by content: Default: spend order and space before style.
- Distinctive: line 55
After it, at most two one-line notes (an assumption, or the one trade-off that matters), unless more is asked for.
- Distinctive: line 65
Put two neighboring levels side by side.
“Common” is measured: kept by at least 6 in 10 of the 5 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Visual hierarchy
A view works when a stranger can say what it is for, what matters most and what to do next within a few seconds. Left to defaults, a design splits the difference between sizes, emphasizes everything and adds effects to feel finished. Replace that with a ranked order and visible, deliberate steps.
When to use
Building, restyling or reviewing any composed surface where several things compete for attention.
When not to use
- Not the numbers: spacing values (spacing-and-grouping), type sizes and ramps (typesetting), palettes and contrast floors (color-palette), page grids (layout-structure), chart encodings (chart-design). Use those skills if installed; otherwise ordinary judgment. For scored critiques use design-critique if installed.
- A one-line fix (a button is too loud, an icon sits low) gets only the matching check, not the whole method.
- Explicit user instructions, an existing design system and platform conventions win over every default here. Standard controls stay familiar; distinctiveness belongs in brand moments.
Method
- Name the job and rank the content. One sentence for what the view is for, then primary, secondary, tertiary and meta; three or four levels is normal. If two items cannot be ranked, pick one and say so in a line. Ask only when interactive and the answer changes the design.
- Order before style. Picture everything in one size and weight. If position and grouping alone do not show the order, fix the structure; styling will not rescue it.
- Pull one lever per step. Position and room first, then size, weight, value, color (see contrast levers). The top element may take two; nothing needs four. Size alone leaves oversized headings over tiny text; pair it with weight or value.
- Make steps visible. Neighbors differ by a size step big enough to see at a glance (the ratio comes from typesetting's scale), a two-step weight jump, or a clear value gap; bigger jumps only for a hero. A one-step difference reads as a mistake, not a choice.
- Subtract before adding. If the main thing will not stand out and cannot get louder, soften what surrounds it: tinted panels, secondary buttons, repeated badges, chrome.
- One boss per decision. One primary action style per view or decision group; secondary quieter (outline or text); tertiary link-like.
- Spend emphasis sparingly. About a tenth of what is visible, one technique, used the same way every time. Pair color with a second cue.
- Share edges, repeat roles. Every element shares an edge or axis with something; one primary text edge at the reading start. The same role gets the same treatment everywhere. A deliberate surprise only works against a consistent base. Optical fixes: alignment.
- Give every mark a job. A line, box, shadow, gradient, glow, icon or illustration must organize, emphasize or identify. If removing it loses no information and no identity, remove it. Details: decoration and depth.
- Check, then hand back. Run the quick checks below.
Judgment calls
- Centering. Default: flush at the reading start, never a centered heading over flush-left text. Change for short, ceremonial or single-focus pieces (invitation, certificate, short hero, empty state): center everything in the group consistently and keep any paragraph over a couple of lines flush.
- Drama by context. Default: marketing, editorial and onboarding take large jumps in scale; dense tools, dashboards and tables use calmer steps and one clear focus per region. In a monitoring view never trade visible rows for bigger headings without a task reason.
- Quiet what the context already explains. Default: a section title takes a clear step up from body, and a label stays with the value as the louder part. Change when the context says it already: a title that only names a self-evident group (billing details) can stay small or hidden, and a label can fold into the value ("21 °C" in a sensor row, not "Temperature: 21 °C"). Spec-style pages, where scanning the labels is the task, keep them.
- Peer choices. Default: one primary per group. For true peers (plan cards) the group shares one treatment, and the single recommended option gets a label plus structural emphasis (position, size, border weight), not color alone.
- Fading. Default: rank secondary text by size or weight, or a modest value step. Change only while it still clears the text contrast floor; never use a light weight on small text to quiet it, use a softer value or smaller size.
- Decoration with identity. Default: cut what has no job. Change when a device carries the brand or the mood asked for: keep it, quieter than the headline and the action.
- Position by content. Default: spend order and space before style. When the order is fixed (table, form, feed), rank with weight and value inside it.
Do not produce
- A heading a few pixels larger than body, or every label bold, or three colored badges per card.
- Several solid primary buttons; a red destructive button louder than the main action.
- A centered headline over left-aligned paragraphs.
- A hero plus identical bordered cards each topped by an icon in a colored circle: rank the features, drop the boxes, and keep an icon only if it carries meaning.
- Gradient backdrop, glass panel, glow and shadow stacked on one surface; decorative blobs; an illustration louder than the headline.
- Made-up proof to fill a hero or pricing block: customer counts, logos, ratings, testimonials, stats, prices, deadlines, "only N left". Use a visible placeholder such as "[customer count]" or leave the slot out, and still deliver the full design.
Output discipline
- Deliver the requested thing first: the code, the ranked fix list, or the one pick. When a count, a set or a word limit is given, deliver exactly that, and check the count rather than asserting it.
- After it, at most two one-line notes (an assumption, or the one trade-off that matters), unless more is asked for. No tour of the method.
- Reviews: findings in order of effect on the task, each as what you see, what it costs the viewer and the fix. Name what already works and leave it alone. If the existing design already holds, say so and change only what fails.
- Rewriting a design that works is the common failure of polish requests: touch the parts that break the order, keep the rest, content included.
Quick checks
- Blur or squint: what remains should be the intended primary, then the secondary group.
- Grayscale: the order should survive; if a status or recommendation vanishes, add a second cue.
- Five seconds: could a stranger say what to do? Point to the element that serves the job.
- Count loud things per group and emphasized share; count distinct left edges.
- Put two neighboring levels side by side; if you must look twice, widen the step.
- Name each decorative mark's job; delete those without one.
References
- references/contrast-levers.md: load when two levels look alike or you are choosing how to separate them; lever strengths, combining, starting steps, text colors and weights.
- references/alignment-and-optical-fixes.md: load when edges look off, or when centering icons, numerals and bullets.
- references/decoration-and-depth.md: load when a design uses shadows, gradients, glass, illustration, icon sets or text over images.
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.

