visual-standards
Skill8 starsChanged 8 months agoMITView on GitHub
Visual formatting standards for repository documentation — emoji heading prefixes, horizontal rules, TOC anchors, callouts, screenshots (device dimensions, HTML patterns, captions, shadows), and image optimisation. Load when generating READMEs with visual elements or working with screenshots.
In this repository20 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- llms-full.txtllms.txt
- llms.txtllms.txt
- api-referenceSkill
- changelogSkill
- doc-refreshSkill
- docs-verifySkill
- feature-benefitsSkill
- geo-optimisationSkill
- launch-artifactsSkill
- llms-txtSkill
- package-registrySkill
- pitchdocs-suiteSkill
- platform-profilesSkill
- public-readmeSkill
- roadmapSkill
- user-guidesSkill
- pitchdocsSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 3 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
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 11
Use a single emoji before each H2 heading to create visual anchors when scrolling.
- Distinctive: line 36
Use the same emoji consistently for the same section type across projects
- Very specific: line 41
Use --- between major H2 sections to create visual breathing room (especially in 200+ line READMEs).
- Distinctive: line 43
When to use: After hero/badge section, after TOC, between H2 sections, before licence/footer.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 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
Visual Standards
Emoji Heading Prefixes
Use a single emoji before each H2 heading to create visual anchors when scrolling.
Pattern: ## {emoji} Section Title
Recommended emoji by section type:
| Section Type | Emoji | Example |
| Quick start / Getting started | ⚡ | ## ⚡ Quick start |
| Why / Value proposition | 💡 | ## 💡 Why ProjectName? |
| Features | 🎯 | ## 🎯 Features |
| Commands / API / Usage | 🤖 | ## 🤖 Commands |
| Configuration | ⚙️ | ## ⚙️ Configuration |
| Requirements / Prerequisites | 📦 | ## 📦 Requirements |
| Documentation links | 📚 | ## 📚 Documentation |
| Contributing | 🤝 | ## 🤝 Contributing |
| Licence / License | 📄 | ## 📄 Licence |
| Security | 🔒 | ## 🔒 Security |
| Integrations / Plugins | 🔌 | ## 🔌 Integrations |
| How it compares | ⚖️ | ## ⚖️ How it compares |
| Roadmap | 🗺️ | ## 🗺️ Roadmap |
| What it does / Use cases | 🚀 | ## 🚀 What ProjectName Does |
Rules:
- One emoji per heading — never two
- Use the same emoji consistently for the same section type across projects
- Skip emoji prefixes for READMEs under 5 sections
Horizontal Rules as Section Separators
Use --- between major H2 sections to create visual breathing room (especially in 200+ line READMEs).
When to use: After hero/badge section, after TOC, between H2 sections, before licence/footer. When to skip: Between H3 subsections, in short documents (under 150 lines), in non-README files.
Table of Contents with Emoji Anchors
GitHub and GitLab strip the emoji character but retain the leading hyphen. Bitbucket prefixes all heading anchors with markdown-header- — load the platform-profiles skill when targeting Bitbucket.
- [Quick start](#-quick-start)
- [Why ProjectName?](#-why-projectname)
- [Features](#-features)
- [Configuration](#%EF%B8%8F-configuration)Include a TOC for READMEs with 7+ sections.
Bold Inline Callouts
For brief warnings, tips, and notes, use bold inline callouts rather than GitHub-specific [!NOTE] syntax (which breaks on npm and PyPI).
**Note:** This only applies when running in production mode.
**Tip:** Pass `--verbose` to see detailed output.
**Warning:** Never commit this file — it contains credentials.Reserve GitHub callout syntax for GitHub-only documents (issue templates, PR templates).
Screenshots & Device Images
For device-specific capture dimensions, HTML display patterns, retina handling, annotation conventions, captions, shadows/borders, browser chrome, file naming, and optimisation guidance, load SKILL-reference.md from this skill directory.
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.