docs: explain how @use/@import requests are resolved

[alexander-akait]

Closes #1064

The README said resolution tries a relative path and then node_modules, which left the reporter unsure whether resolve.alias participates and whether resolve.modules is used at all. Both do — this documents that, and the rest of what the loader actually does.

What changed

Resolving import and use at-rules becomes Resolving import, use and forward at-rules and gains six short subsections:

• How a request is resolved — the candidates tried in order (the partial, the plain name, then the request as written so aliases and package requests resolve), _index/index for directories, the .import files that apply to @import only, and the relative-over-module preference.
• What your resolve configuration controls — alias, modules, byDependency.sass (requests are resolved with dependencyType: "sass"), plugins/symlinks/roots, with a config and stylesheet example. Then the options fixed to match Sass's algorithm — extensions, mainFiles, mainFields, conditionNames — including the note that resolve.extensions therefore does not apply, and that your own mainFields/conditionNames are kept after the Sass-specific ones.
• Packages — the sass/style export conditions, the sass/style/main field fallback, and the pkg: scheme.
• When webpack can't resolve a request — the importer hands it back to Sass, which applies loadPaths, SASS_PATH and any custom importer.
• Plain CSS files — @import "theme.css" stays a plain @import in the loader's output while @use "theme.css" inlines the file.
• The ~ prefix — existing content, moved into its own subsection and updated to @use.

Verification

Every claim was checked by building the case against the loader, with negative controls where a claim is about something not applying:

resolve.modules   : OK "body { color: red; }"
  (without it)    : ERROR Can't find stylesheet to import.
resolve.alias     : OK "body { color: blue; }"
byDependency.sass : OK "body { color: green; }"
  (without it)    : ERROR Can't find stylesheet to import.
resolve.extensions: ERROR Can't find stylesheet to import.

The alias + modules example in the README is the one from that run, so it compiles as written.

Two claims were corrected by testing rather than taken from the source comments:

• A partial does not simply "win" over a non-partial — a directory holding both _theme.scss and theme.scss makes Sass report It's not clear which file to import. The text says the order within a directory rarely matters and names the ambiguity instead.
• @import "theme.css" is not "never resolved by webpack": the loader leaves the @import in place, and the built-in CSS support or css-loader may then resolve it downstream. Confirmed by reading the loader's raw output through asset/resource, where @import "theme.css" survives verbatim and @use "theme.css" inlines the content.

Docs only — no code changes, so no changeset. prettier and cspell pass.

🤖 Generated with Claude Code

https://claude.ai/code/session_013PtW7eezwuQP5epLFMrAky

---

Generated by Claude Code

[changeset-bot]

⚠️ No Changeset found

Latest commit: e2feac3

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.62%. Comparing base (72640db) to head (e2feac3).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1339   +/-   ##
=======================================
  Coverage   96.62%   96.62%           
=======================================
  Files           2        2           
  Lines        1007     1007           
=======================================
  Hits          973      973           
  Misses         34       34           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.