stop-describing-ui
Skill3 starsChanged yesterdayApache-2.0View on GitHub
Strip explanatory copy out of user interfaces. Use when writing, editing, or reviewing any UI text, including headings, empty states, button labels, toggle and setting descriptions, helper text, dialogs, banners, permission notices, and onboarding, and whenever a screen leans on sentences to explain what it does. Replaces descriptions of features, side effects, backend behavior, and missing capabilities with specific verbs, controls, icons, and spacing.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- artouc/stop-describing-uiword for word, first seen Oct 11, 2026
Other versions1 project uses a version of this.
Word for word · 1
- artouc/stop-describing-ui★ 19100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
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 repository56 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .agents/skills/AGENTS.mdAGENTS.md
- analysis-reportingSkill
- analysis-unit-designSkill
- analysis-visualizeSkill
- anomaly-detectionSkill
- areal-interpolationSkill
- causal-designSkill
- causal-estimationSkill
- clustering-analysisSkill
- cross-validation-designSkill
- data-quality-auditSkill
- dataset-discoverySkill
- data-variable-semanticsSkill
- dimensionality-reductionSkill
- eda-and-baselineSkill
- experiment-designSkill
- frontend-designSkill
- grid-risk-mappingSkill
- image-segmentationSkill
- land-cover-costSkill
- leakage-auditSkill
- location-privacySkill
- model-explanationSkill
- natural-japaneseSkill
- noise-ceiling-analysisSkill
- observation-bias-auditSkill
- poi-insightsSkill
- point-pattern-analysisSkill
- raster-cost-distanceSkill
- raster-data-integrationSkill
- research-paper-writingSkill
- research-question-generationSkill
- robustness-analysisSkill
- sar-change-detectionSkill
- spatial-accessibility-analysisSkill
- spatial-autocorrelationSkill
- spatial-data-integrationSkill
- spatial-data-modelingSkill
- spatial-feature-engineeringSkill
- spatial-gnnSkill
- spatial-interpolationSkill
- spatial-network-analysisSkill
- spatial-optimizationSkill
- spatial-process-modelingSkill
- spatial-sampling-designSkill
- spatial-weights-designSkill
- spatiotemporal-modelingSkill
- street-imagery-inspectionSkill
- terrain-hydrologySkill
- time-series-forecastingSkill
- trajectory-predictionSkill
- travel-time-reliabilitySkill
- uncertainty-estimationSkill
- web-design-guidelinesSkill
- yomiyasuSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 4 are distinctive, and 1 is 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.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 10
When writing UI, apply the rules below as you write.
- Distinctive: line 40
When an action has several effects, state the one that matters most and drop the rest.
- Distinctive: line 89
If something becomes available by subscribing, upgrading, connecting, or turning on a setting, put the button or toggle that does it on the …
- Very specific: line 107
Never use ->, >, |, ✔️, !, →, or : as separators, arrows, bullets, or emphasis.
- Distinctive: line 138
If nothing is left after the checklist, leave nothing.
≈ “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
Stop describing UI
An interface shows what the user can do. It does not explain itself. Every sentence is something the user has to read before acting, so keep a sentence only when the user would make a real mistake without it.
When writing UI, apply the rules below as you write. When reviewing UI, go through every string, apply each rule, and present the result as before and after.
Rules
1. Don't describe the feature
Name the action instead. A heading, a control, and its label already say what the screen is for.
Before
# Projects
## No projects yet.
### Choose a GitHub repository and we'll deploy on every push.
+ NewAfter
# Projects
+ Connect repository2. Use specific verbs
Pick the verb that names what actually happens, and give it the object it acts on. Avoid generic verbs such as New, Create, Manage, Set up, Configure, Go, or OK when a more precise one exists. In the example above, "New" becomes "Connect repository".
3. Keep only the most critical consequence
When an action has several effects, state the one that matters most and drop the rest. Effects that follow from it are implied. In a booking service that takes reservations through AI auto-replies, turning off auto-replies obviously stops reservations too.
Before
Turning this off stops AI auto-replies and web reservations. Customer messages are saved only to the conversation log. You can turn it back on anytime from "Replies off" in the header.After
Temporarily turns off AI auto-replies.Irreversible or destructive effects, such as deleting data, charging money, or notifying customers, are the critical consequence and always stay.
4. Don't describe backend behavior
Where data is stored, what gets logged, what syncs, and what runs in the background are not the user's concern. In the example above, "Customer messages are saved only to the conversation log" goes.
5. Don't explain undo when the same control undoes it
A toggle that turns something off also turns it back on. Explain how to undo only when undoing needs a different control or place.
6. Don't explain what the page already tells
The page title, navigation, and section structure carry meaning. On an Options page, the user already knows they are looking at options.
Before
# Other options
### Options that become available with a contract. They cannot be toggled on or off.After
# Other7. Don't state what doesn't exist
Don't say there are no items yet, that something can't be toggled, or that a feature isn't available, when the screen already shows it. An empty list with a clear action says "nothing here yet". A row without a toggle says "can't be toggled".
The exception is a restriction the user would otherwise try and fail at, such as an action their role can't perform. Keep it, in one short line with an icon, as in rule 9.
8. Show how to enable, don't write it
If something becomes available by subscribing, upgrading, connecting, or turning on a setting, put the button or toggle that does it on the screen. Don't write a sentence telling the user where to go or what to do.
Before
Sign up for the Pro plan to use this option.After
[Upgrade to Pro]9. Don't rely on text alone
Break prose into short lines, each led by an icon. Use spacing and grouping for structure.
Never use ->, >, |, ✔️, !, →, or : as separators, arrows, bullets, or emphasis. Use an icon or spacing instead.
Before
Searches across all stores and shows the results. Stores you don't belong to are shown as Operator, and every action records who did what in which store. You can't change applications, payment methods, or plans, or send messages to customers (replies, approving or declining tentative reservations).After
(icon) Every action is recorded
(icon) You can't change applications, payment methods, or plans, or send messages to customersHere "Searches across all stores and shows the results" goes by rule 1, "shown as Operator" by rule 6 because the UI already labels them, and the detailed record format by rule 4.
Checklist
For each string, ask in order.
- Does it explain what the feature is? Delete it, or turn it into a specific action label.
- Is the verb generic? Replace it with one that names the real action and its object.
- Does it list several consequences? Keep the most critical one.
- Does it mention storage, logging, syncing, or other internals? Delete it.
- Does it explain how to undo with the same control? Delete it.
- Does the page title or navigation already say it? Delete it.
- Does it say something is missing or unavailable? Delete it, unless the user would otherwise try and fail.
- Does it tell the user how to enable something? Replace it with the button or toggle.
- Is it a paragraph, or does it use symbols as separators? Split it into icon-led lines and use spacing.
If nothing is left after the checklist, leave nothing. An empty helper text slot is better than a filler sentence.
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.

