Preamble:
<theme-root> = app/design/adminhtml/{theme-vendor}/{theme-code}
{theme-code} = theme-adminhtml-backend
Alright, I've figured it out. _extend.less files are not picked up in adminhtml themes. I wish this was made clear in the documentation, but alas.
I've come up with the following workaround which allows for _extend.less files to be used for applying styles to modules in the admin interface without creating any "hidden dependencies" on Magento's adminhtml theme CSS roots (as would be the case with copy/pasting files into your adminhtml theme).
There is a caveat I should mention for the "add another root CSS source file" method that I've described in this answer. Using this approach, redeclaring variables will not have any effect because of the manner in which LESS files are processed i.e., the root file is processed, LESS files are gathered, and CSS is generated. If you wish to be able to redeclare variables (e.g., @primary__color) you must copy/paste styles.less from the Magento adminhtml theme into your own theme, then append the contents of my extends.less file onto the end of the copy/pasted file. This unfortunately creates what I call a "hidden dependency" on the original file (which is subject to changes in future versions of theme-adminhtml-backend) so it will become your responsibility to check for changes to this file whenever theme-adminhtml-backend is updated, and copy those changes to your local copy.
Firstly, we must add another Root CSS Source File. This is described in the Magento 2 documentation as-so:
The .less files from which the .css files included in layout are
compiled. For example, in one of the layout files of the Magento Blank
theme, the following .css files are included in the head:
<head>
<css src="css/styles-m.css"/>
<css src="css/styles-l.css" media="screen and (min-width: 768px)"/>
<css src="css/print.css" media="print"/>
</head>
For development mode, using Grunt as a LESS processor, add another Source to the theme declaration in themes.js or local-themes.js depending on how you have your environment setup. Your theme declaration should look something like this:
your_adminhtml_theme_name: {
area: 'adminhtml',
name: 'VendorName/theme-name',
locale: 'en_US',
files: [
'css/styles-old',
'css/styles',
'css/extends' // we've added this file
],
dsl: 'less'
}
This step is not necessary for server-side compilation mode, as Magento simply looks for corresponding LESS files depending on what CSS files are included in the page head.
That said, this new file (extends.css) must be included in the layout in the same fashion as the other CSS source files for the theme. Since the Magento_Backend module is responsible for this, lets add the layout update to that module in our own adminhtml theme.
Create the file:
<theme-root>/Magento_Backend/layout/default.xml
With contents:
<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<head>
<css src="css/extends.css"/>
</head>
</page>
Now we must create this Root CSS Source File.
Create the file: <theme-root>/web/css/extends.less
With the contents:
// import theme-wide extend file (use this for importing other theme-level extension files)
@import 'source/_extend.less';
// import module-specific extension file e.g. <ModuleDir>/web/css/source/_extend.less
//@magento_import 'source/_extend.less';
Now you can apply changes to Magento modules in the admin interface in the same fashion as you can with a frontend theme by adding an _extend.less file to the module's web/css/source directory. You can also use the <theme-root>/web/css/source/_extend.less to import other theme-wide LESS files as is recommended for frontend themes (e.g., _navigation_extend.less)
I hope this helps someone.
