September 19, 2026 / Web Development
Website image file naming conventions that actually scale
Website image file naming conventions that actually scale
A designer on a small team uploads IMG_4822.jpg to a staging server. A month later, three people are searching for the same banner in the asset library, none of them can find it, and the marketing lead resizes the wrong file for a campaign. The cost of that single careless name is rarely dramatic in the moment, but it compounds into hours of lost time, broken alt text, and duplicate assets that drift out of sync. Clear website image file naming conventions prevent exactly that kind of silent friction.
This guide is written for working teams who already know they have a problem and want a system that survives handoff, scale, and turnover. It focuses on real decisions: how to read a filename at a glance, where to place project and context, how to handle versioning, and what to do with source files. Examples are deliberately grounded in everyday work, not abstract taxonomies.
Why filenames matter more than people expect
Filenames do three jobs that folders and CMS fields cannot do alone. They travel with the file. They appear in search results, code editors, and asset libraries. And they are the only metadata that survive a copy-paste into a chat, a zip archive, or a shared drive without a database behind it.
When a filename carries meaning, a developer can identify a missing asset during a code review, a content editor can recognise a hero image without opening it, and a search engine can use the words to understand the page. When a filename is meaningless, every one of those moments becomes a small tax on attention.
For a solo designer, poor filenames are an inconvenience. For a team of five or more, they become a recurring source of bugs, duplicate work, and accidental publishing of the wrong file. The earlier a team settles on conventions, the less rework is required later.
The three jobs a good filename should do
Before choosing separators, case rules, or length limits, it helps to be explicit about what a filename is for. A useful image filename answers three questions, in this order of priority.
- What is in the image. A reader should be able to predict the content from the name alone, within the context of the project.
- Where the image is used. A filename should hint at the section, component, or page the image belongs to, so editors do not use it in the wrong place.
- How the file is sized or prepared. A short tag for the variant or dimensions helps developers select the right file when multiple versions exist.
Ordering matters. A name like 2400-homepage-hero.jpg is harder to scan than homepage-hero-coffee-2400.jpg. Put the human-meaningful parts first, and the technical details last. This rule alone prevents a great deal of confusion.
Core parts of a scalable filename
Most teams do well with a structure made of four optional segments, separated by a single character. The table below shows a layout that holds up across small and medium projects.
| Segment | Purpose | Example | Notes |
|---|---|---|---|
| Project or client | Disambiguates assets when folders are shared | madevisualstudio |
Omit if the folder already encodes this |
| Section or component | Where the image is used in the site | homepage-hero, about-team |
Use the same names as your components or page slugs |
| Subject or content | What the image actually shows | coffee-cup, founder-portrait |
Two to four short words works well |
| Variant or size | Width, crop, or role in a set | 2400, square, dark |
Numeric widths are easier to script than cryptic codes |
An example built from this table would be madevisualstudio-homepage-hero-coffee-cup-2400.jpg. A reader who knows the project can locate the right file without opening it, and a developer can target a specific width by matching a simple suffix pattern.
Choosing separators: hyphens, underscores, and camelCase
Separators are a small decision with outsized consequences because they affect how tools interpret filenames. Web servers, search engines, and most asset pipelines treat different separators differently.
| Separator | Example | Browser and URL behaviour | Recommended use |
|---|---|---|---|
| Hyphen | homepage-hero.jpg |
Treated as a word break; safe in URLs | Default separator between words |
| Underscore | homepage_hero.jpg |
Treated as part of a single word by many search tools | Reserved for grouping parts of one concept, such as madevisualstudio_home |
| CamelCase | homepageHero.jpg |
No separator, harder to scan | Avoid for new systems |
| Spaces | homepage hero.jpg |
Often URL-encoded as %20 and break tools |
Never use in production filenames |
A practical rule is to use hyphens between words and a single underscore only when a group of words belongs to one logical unit, such as a project code. If a filename ever needs to be URL-encoded, the convention is already failing.
Case rules that survive every operating system
Case sensitivity is one of the easiest things to get wrong because it is invisible until something breaks. Windows and macOS default to case-insensitive filesystems, while most web servers and many content management systems are case-sensitive. A file renamed from Hero.jpg to hero.jpg will appear to work on a designer’s laptop and then 404 in production.
Pick one rule and apply it everywhere. The two common choices are:
- All lowercase. Easy to type, easy to read, and avoids the entire class of case-mismatch bugs. The most common choice for new systems.
- Kebab-case with capitalised project code. Used by teams that need a visible project tag such as
MVS-homepage-hero.jpg. Works well, but requires discipline in the CMS configuration.
Whichever rule is chosen, write it down, and configure the asset library to enforce it. Manual reminders drift; tooling does not.
File extensions and format suffixes
The extension should always reflect the actual binary content of the file. A .jpg saved from a PNG is still a JPEG, and the extension should say so. Lying about format confuses image optimisers, breaks automated pipelines, and leads to serving the wrong mime type.
Some teams add an extra suffix to indicate a derivative, such as homepage-hero-coffee-cup-2400-opt.jpg for an optimised version. This is helpful when the original master must be preserved alongside the delivery file, but it should be reserved for clear derivative work, not used as a generic marker.
For teams that work with layered source files, a common pattern is to keep masters as .psd, .ai, or .afdesign in a separate masters/ folder and export .jpg, .png, or .webp versions into the asset library. The filename stays the same; only the extension and folder change.
Versioning without losing your mind
Versioning is where naming conventions most often break down. Designers iterate, screenshots get retaken, and suddenly a folder contains hero.jpg, hero-v2.jpg, hero-final.jpg, and hero-final-ACTUAL-final.jpg. None of those names tell you which one is current, and only one of them is.
A small set of habits prevents the mess:
- Use a date stamp for archive copies, not for in-progress work.
hero-2026-08-14.jpgis honest;hero-v3.jpgis not. - Keep one canonical filename per asset and replace the file in place when it changes. Rename only when the content or context actually changes.
- If a design has not been approved, keep it outside the shared library. Local drafts in a
wip/folder reduce the chance of an unfinished file being deployed. - When in doubt, prefer
masteror a numeric width overfinal. Neither of those claims to be the last word in a series.
Working with the existing site context
Filenames do not exist in isolation. They have to fit alongside an existing design system, a CMS, and a codebase. Two articles from the same site already point in useful directions for anyone building a small, durable system.
The principle is consistent, human-readable names rather than cryptic codes. If a team has already committed to kebab-case tokens, image names can follow the same shape so editors and developers use one mental model. File extensions still identify the underlying image file format; the descriptive stem identifies the asset. Google Search Central likewise recommends short, descriptive filenames in its image SEO best practices.
Folder structure that supports the naming system
Filenames and folder structures are partners, not substitutes. A good rule is that the folder answers “which project, which area”, and the filename answers “what, where, how”. Keeping the responsibilities separate prevents filenames from becoming long chains of redundant context.
A simple structure that holds up for many small studios looks like this:
/clients/madevisualstudio/web/homepage/for the live homepage assets/clients/madevisualstudio/web/about/for the about section/clients/madevisualstudio/masters/for layered source files/archive/2025/for retired assets kept for reference
Within those folders, a filename such as hero-team-portrait-2400.jpg is enough on its own. The folder supplies project and area; the filename supplies content and size. Nothing is duplicated, and nothing essential is missing.
Internationalisation and non-English content
Filenames are usually written in the language of the team, not the language of the audience. That is a practical choice, because filenames appear in internal tools where Latin characters and ASCII are safest. Mixing scripts in filenames tends to cause subtle bugs, especially in zip archives, email attachments, and shell scripts.
For sites that ship in more than one language, keep filenames in a single, consistent script. Let the CMS or content layer handle the translated versions through separate fields or alt text, rather than reflecting the translation in the filename itself. This keeps the asset library stable while the content layer does the localisation work.
Common filename patterns worth borrowing
Looking at how other systems encode their context can save a great deal of trial and error. The table below collects patterns that are widely used because they map cleanly to real tasks.
| Pattern | Example | When it helps |
|---|---|---|
| Subject plus width | coffee-cup-2400.jpg |
Responsive image sets, where multiple widths ship together |
| Subject plus ratio | coffee-cup-16x9.jpg |
Designers who work in multiple crops for the same subject |
| Component plus variant | card-thumb-light.jpg |
Component libraries with light, dark, and hover states |
| Page slug plus order | about-01.jpg |
Gallery pages where order matters more than subject names |
| Project plus role | mvs-hero-bg.jpg |
Shared drives where multiple projects coexist in one folder |
No single pattern is right for every team. The strongest systems use one or two of these consistently, rather than mixing all of them within a single project. Consistency within a project is more valuable than elegance across projects.
Automation that enforces the convention
A documented convention that nobody enforces tends to erode within a quarter. The cheapest way to keep names honest is to make the right thing the easy thing. A few practical options exist for small teams:
- A pre-commit hook in the design repo that runs a rename script on staged images and rejects names that do not match a regular expression.
- A simple shell or Node script in the asset pipeline that renames files on upload according to a pattern, so designers never have to think about it.
- A naming-policy field in the CMS that constrains the upload field to a regex, with a clear error message that explains the rule.
- A library view that flags files whose names do not match the agreed pattern, with a one-click rename action.
Automation does not need to be sophisticated to be useful. A five-line script that rejects IMG_1234.jpg and asks for a descriptive name is enough to change behaviour over a few weeks.
How filenames interact with SEO and accessibility
Search engines do read image filenames, though they weigh many other signals more heavily. A filename that describes the subject of the image can support page-level relevance, especially when the image appears near related text. The same description belongs in the alt attribute, but the two are not interchangeable: filenames help with discovery, alt text helps with comprehension.
The underlying technical layer for how image files are stored and served is documented in the image file format entry, which covers the differences between raster and vector formats, compression, and how colour depth and pixel count drive file size. Understanding the format side of the pipeline makes the naming side easier to reason about, because a name like homepage-hero-coffee-2400.jpg tells a developer what format to expect and roughly how heavy the file will be. Authoritative guidance on how to size, name, and label images for the web is also available from the W3C Web Accessibility Initiative images tutorial, which gives practical advice on alt text, decorative versus informative images, and the relationship between file naming and accessible publishing.
A reasonable rule of thumb is to write filenames for humans first and search engines second. If a person can recognise the subject and the context from the name, a search engine almost certainly can too.
A short checklist for review
Before publishing a batch of renamed assets, a quick review catches most problems. The list below is short enough to use as a pre-deploy step on small projects and easy to extend for larger ones.
- Every filename is lowercase and uses hyphens between words.
- Project, section, subject, and variant segments are in a consistent order.
- The subject segment describes the content, not the visual style, unless the style is the point of the image.
- There is exactly one canonical filename per asset, with no
finalorv3markers in the live library. - Masters live in a separate folder and are not deployed to production.
- Alt text is set in the CMS or HTML, not encoded into the filename.
- The asset library or CMS rejects uploads that do not match the pattern.
Where this leaves a small team
Website image file naming conventions are not a creative exercise. They are a small piece of operational hygiene that pays back every time a file moves between systems, every time a new person joins, and every time a deadline is tight. The most useful thing a team can do is to write down the rules once, enforce them with a script or a CMS constraint, and stop thinking about them.
If the team is starting fresh, the safest path is lowercase, hyphen-separated, project-then-section-then-subject-then-variant. If a system already exists, the better question is what to change without breaking the rest of the pipeline. In both cases, the goal is the same: a name that is honest, scannable, and durable enough to outlive the project it was created for.
Frequently asked questions
What is the best separator to use in image filenames?
Hyphens are the safest default. They are treated as word breaks by search engines, work in URLs without encoding, and read clearly to humans. Underscores should be reserved for grouping parts of one concept, and spaces or mixed case should be avoided in production filenames.
How long should a website image filename be?
Most teams do well with three to six short segments, totalling roughly thirty to sixty characters. Long enough to be descriptive, short enough to remain scannable in a file list or a CMS media library. Anything beyond about seventy characters tends to be truncated in interfaces and stops being useful.
Should filenames include the date or a version number?
Dates work well for archive copies, because they are honest and sort naturally. Version numbers like v2 or final are usually a sign that the team is keeping too many in-progress files in the shared library. Keep one canonical filename per asset and replace the file in place when it changes.
Should I use uppercase or lowercase filenames?
Lowercase is the most common choice because it removes the risk of case-mismatch errors between operating systems and web servers. If the team has a reason to use uppercase, the rule has to be enforced everywhere, including in the CMS configuration, so the same asset does not appear twice with different cases.
Do filenames matter for SEO?
Filenames are a small but real signal. They help search engines confirm the subject of an image, especially when the image is near related text on the page. They are not a substitute for descriptive alt text, which is the primary accessibility and comprehension signal for images.
How should I name responsive image variants?
Encode the width in pixels at the end of the filename, using a short numeric suffix such as hero-800.jpg, hero-1600.jpg, and hero-2400.jpg. This keeps the subject and context identical across variants, which makes it easy to generate a srcset attribute and to spot missing widths in the library.
What should I do with old or retired assets?
Move them to a clearly named archive folder, such as /archive/2025/, and keep their original filenames. Do not rename retired assets, because the names may still be referenced in old code, blog posts, or external links. The archive folder is also a useful audit trail when a question arises about a previous design.
Can I use non-English characters in filenames?
It is safer to keep filenames in a single Latin script and handle localisation in the CMS through translated fields and alt text. Mixed scripts tend to cause encoding bugs in zip archives, email attachments, and shell scripts, and they rarely add value that a localised alt text or caption cannot provide.
What is the difference between a filename and alt text?
The filename identifies the file for editors, developers, and search engines. Alt text describes the image for people using assistive technology and for search engines that read the surrounding content. They overlap in purpose but are not interchangeable, and both should be written deliberately rather than left as system defaults.