Table of Contents
Overview
Resource directories are special folders in an Android project where you place all the non-code assets that your app needs. These include layouts, images, strings, colors, styles, and more. They are stored inside the res directory of your module, usually at app/src/main/res. The Android build system reads these folders, processes their content, and generates references that you can use directly in your Kotlin code and XML layouts.
Understanding how resource directories are organized, how they are named, and how Android chooses the right resource at runtime is essential for building flexible and maintainable apps. In this chapter, you focus on what these directories are, what each is used for, and how to refer to their contents.
The `res` Directory Structure
Inside the res directory, you find several subdirectories. Each one contains a specific type of resource and must follow a strict naming convention. The general pattern is:
res/<resource-type>-<qualifiers>/
The resource type is mandatory and tells Android what kind of data the folder contains, for example layout, drawable, or values. Qualifiers are optional and are used to provide different resources for different devices, such as layout-land for landscape orientation or values-fr for French language strings. You will learn the idea of qualifiers in more detail later in this chapter.
Each resource you place in these folders gets an automatically generated identifier inside the R class, which allows you to access it from code as R.type.name, for example R.layout.activity_main or R.string.app_name.
Every resource directory must use a valid, recognized resource type name, and files inside must follow Android naming rules, which usually means using only lowercase letters, digits, and underscores.
Layout Resources: `layout` Directories
Layout resources define the user interface structure of screens and individual UI components in XML. They live in the res/layout directory or in layout directories with qualifiers such as res/layout-land.
A typical file in res/layout might be named activity_main.xml. Each XML file defines how views are arranged and configured on the screen. These layouts are usually loaded in an Activity or Fragment using methods that expect a layout resource id, for example by passing R.layout.activity_main.
You can also create multiple versions of the same layout file for different device configurations. For instance, res/layout/activity_main.xml and res/layout-land/activity_main.xml can both exist. Android will choose the one that best matches the current device orientation or configuration.
Drawable Resources: `drawable` Directories
Drawable resources are visual elements that can be drawn on the screen, such as bitmap images, vector graphics, shapes, and selectors. They live in res/drawable and its qualified variants such as res/drawable-hdpi or res/drawable-night.
You can place different types of files in drawable directories, including PNG or WebP image files, as well as XML files that describe shapes or combined drawables. Vector drawables, often stored as .xml, are especially useful because they scale cleanly on different screen densities.
Older Android projects often used density-specific drawable folders such as drawable-mdpi, drawable-hdpi, drawable-xhdpi, and so on, to provide images tailored to particular screen densities. Modern projects frequently rely on vector drawables to reduce the need for many bitmap variants, but density-specific folders are still supported and sometimes needed for complex images.
In XML, you can reference a drawable resource with @drawable/resource_name. In code, you use the generated id R.drawable.resource_name.
Values Resources: `values` Directories
The values directories contain XML files that define simple data as key value pairs. Common examples are strings, colors, dimensions, styles, and themes. The base directory is res/values, and you can have variants such as res/values-night or res/values-fr.
Inside res/values, each XML file groups related items. Some of the most common files are:
strings.xml which defines text resources with <string> elements.
colors.xml which defines named colors with <color> elements.
dimens.xml which defines dimension values like margins and text sizes with <dimen> elements.
styles.xml which defines styles and themes with <style> elements.
Each resource defined in values gets a name, for example <string name="app_name">My App</string>. This name is what you use when referencing the resource from XML or Kotlin. For instance, in XML you can write @string/app_name, while in code you refer to R.string.app_name.
The values directories are key to making your application adaptable and easy to maintain, because they centralize reusable properties instead of hardcoding them inside layouts or Kotlin code.
Drawable and Mipmap for App Icons: `mipmap` Directories
In addition to drawable, Android uses mipmap directories to store app launcher icons. These directories follow a pattern similar to drawables, such as mipmap-mdpi, mipmap-hdpi, mipmap-xhdpi, and so on.
The main idea of mipmap is to provide icons in different resolutions for different screen densities. The launcher can decide which icon to use for best appearance. You usually do not edit these files manually in modern Android Studio projects, because the IDE generates them when you create a new project or when you use the Image Asset tool.
Launcher icons are referenced as @mipmap/ic_launcher in the manifest or XML. In code they appear as R.mipmap.ic_launcher.
Menu Resources: `menu` Directories
Menu resources define the items that appear in application menus, such as toolbar overflow menus or contextual menus. They are stored in the res/menu directory.
Each menu XML file contains one or more <item> elements with attributes like android:id, android:title, and optionally android:icon. A typical use is defining the menu items for an Activity and inflating that menu from code at runtime.
By placing menus in resource files, you separate the visual structure of the menu from the code that handles what happens when a user selects an item.
Raw Resources: `raw` Directory
The res/raw directory is for arbitrary raw files that you want packaged inside the application as-is. These might be audio files, text files, JSON data, or any other file format that you want to access as a stream.
Unlike drawables or layouts, raw resources are not interpreted by the Android system. You are responsible for reading them from code. You reference them as R.raw.file_name and typically obtain an input stream in Kotlin to read their contents.
Using res/raw is especially useful when you need to bundle data with the app that does not fit naturally into other resource types.
Asset Files: `assets` Directory
Although not technically inside res, the assets directory is another place where you can store external files. It is usually located at app/src/main/assets. Assets are similar to raw resources in the sense that they are not processed by the system and are shipped as is.
The key difference is that assets are accessed by file path through the assets API, not via resource ids. You can create your own folder structure inside assets, for example assets/docs or assets/fonts. Android preserves this structure inside the packaged application.
Use the assets directory when you need flexible file organization and when resource ids like R.raw.name are not necessary or not suitable.
Resource Qualifiers and Configuration-Specific Directories
Resource qualifiers allow you to provide multiple versions of the same resource for different configurations, such as language, screen orientation, screen size, or night mode. Qualifiers are appended to the resource directory name after a hyphen.
Some common examples include:
values-fr for French translations of text and other values resources.
layout-land for landscape variants of layout files.
values-night for colors and styles that apply when the device is in dark mode.
drawable-hdpi for images intended for high-density screens.
When Android needs a particular resource, it looks at all the available directories and chooses the one that best matches the current device configuration. If no specialized version is found, it falls back to the basic directory, such as layout or values.
This process lets you tune your app to look and behave appropriately on a wide range of devices and locale settings, without changing your code. You simply provide alternative resources with the same name, but place them in directories that include the right qualifiers.
When using qualifiers, the file names for alternative versions of a resource must be identical, and you must use only valid, recognized qualifiers in the correct order. Android will only consider directories that follow the proper naming rules when choosing resources.
Naming Rules and Referencing Resources
Resource files and names must follow specific naming rules. Typically, you use lowercase letters, digits, and underscores, and avoid spaces or capital letters. For example, activity_main.xml is valid, while ActivityMain.xml or activity main.xml are not recommended and may cause build errors.
Inside values XML files, observe the requirement that each resource has a unique name attribute within its type. For instance, you cannot have two <string> elements with the same name in the same values configuration.
In XML layouts or other resources, you reference resources using the @ syntax. The general form is:
@resource_type/resource_name
For example:
@string/app_name
@color/primaryColor
@drawable/ic_launcher
In Kotlin code, you refer to the same resources through the generated R class, such as R.string.app_name or R.color.primaryColor. The build system creates this class from the contents of your res directory, so it is important that the directories and files are valid and that they compile without errors.
How Resource Directories Impact App Development
The way Android organizes resource directories affects how you design and maintain your app. By keeping layouts, strings, images, and styles in their respective folders, you create a clear separation between code and presentation. This separation makes it easier to:
Localize your app for multiple languages by providing translated text in different values folders.
Support different screen sizes and orientations with specialized layout folders.
Support dark mode and other themes through different values or drawable variants.
Update visuals or wording without touching the Kotlin code.
As your project grows, the res directory can contain many files, and maintaining a clean structure becomes vital. Good naming conventions, proper use of qualifiers, and a clear understanding of each resource directory help keep your app manageable and easier to evolve over time.