What the agent does
Current Dart Sass prints Sass @import rules are deprecated and will be removed in Dart Sass 3.0.0 for every @import, and the same build usually carries two more kinds of warning: global built-in functions such as map-get and type-of, and / used for division. The agent counts before it changes anything. In a Sass library like propublica/column-setter, main.scss imports three partials, reset, column-settings and column-setter. Compiling it with Dart Sass 1.108 in verbose mode succeeds and prints 90 deprecation warnings: 3 for @import, 77 for global built-ins, 7 for slash division and 3 for the old if() function syntax. The agent keeps the CSS from that compile as the reference. It does not use the main.css committed in the repository, which an older compiler produced and which already differs from a fresh build in rule order.
It then runs the official tool, sass-migrator division followed by sass-migrator module --migrate-deps main.scss. The migrator rewrites @import to @use, adds @use "sass:map", sass:math, sass:meta, sass:string and sass:list to _column-setter.scss, namespaces every call, and turns $a / $b into math.div($a, $b). On many codebases that is the whole job. On this one the result does not compile, and the reason is the design @import allowed: one global scope shared by every file.
Column Setter keeps its grid variables, $mar, $col, $gut and $pad, in _column-settings.scss, and its breakpoint mixin in _column-setter.scss reassigns them for the duration of a media query and then restores them, each assignment flagged !global. After migration those lines read column-settings.$mar: ... !global, and Sass stops with !global isn't allowed for variables in other modules. Assigning to another module's variable is legal; the flag is not. The agent removes the flag from the twenty assignments. The next compile fails differently, with the library's own error that the grid variables are missing: its guards call global-variable-exists("mar"), which now looks in the wrong module. The agent adds $module: "column-settings" to the fifteen checks.
After those two repairs the stylesheet compiles, and the agent compares the output with the reference using a byte comparison. For column-setter the two files are identical. Three warnings remain, all for the if() function syntax, which the module migrator does not rewrite; the agent lists them with their lines and leaves them. It also reports the change in how the library is consumed: main.scss now calls column-setter.colspan() and @include column-setter.grid(...), so the README's instructions and any project that imports these partials need the namespace, or @use "column-setter" as *.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Migrate this project's Sass from @import to the module system (@use and @forward) and clear the Dart Sass deprecation warnings. Find every stylesheet entry point from the build scripts, bundler config or the files that are not partials. Before changing anything, compile each entry point with the current Dart Sass release in verbose mode, save the CSS in expanded style as the reference, and count the deprecation warnings by kind (import, global-builtin, slash-div, and others). If compiled CSS is committed, compare it with the fresh compile and say whether they match; use the fresh compile as the reference either way. Run sass-migrator division and then sass-migrator module with --migrate-deps on each entry point. Compile again. If it fails, fix the cause by hand and explain it; expect the patterns the migrator cannot resolve: !global assignments to variables that now live in another module, global-variable-exists, mixin-exists and function-exists checks that need a module argument, variables configured before an @import that now need @use ... with (...), and partials imported inside a selector or media query. Do not change values, selectors or rule order. When it compiles, compare each output with its reference byte for byte and report identical or show the diff. Count warnings again and list any that remain with file and line. If the project is a library that others import, say how the public API changed (namespaces, @forward) and update the README examples. Open a pull request.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
A pull request that looks larger than it is. For column-setter the diff touches a few hundred lines across main.scss and _column-setter.scss, nearly all of them a function gaining a namespace. The description puts the numbers first: 90 warnings before and 3 after, and compiled CSS identical to the reference. It then separates what the migrator did from the two repairs made by hand, each with the compiler error that prompted it, so a reviewer reads thirty-five hand-edited lines closely and skims the mechanical ones.
The reviewer checks the comparison method, since it carries the whole argument: same compiler version, same output style, source maps off, compared as bytes. They read the note about the committed main.css, which the agent regenerates only if the request says to, because regenerating it changes rule order for reasons unrelated to this migration. For a library they decide whether the namespace change calls for a major version.
Run it on every pull request that changes a stylesheet
Once the migration is merged, the remaining risk is a new @import arriving in someone's next pull request. Create an automation in the Project that holds the repository with a github trigger on pull_request.opened and pull_request.synchronize, and switch on Read only, so its runs can read the repository and comment but cannot push. Save a shorter prompt for it: compile every entry point in verbose mode, and if the output contains a deprecation warning, comment on the pull request with the warning and the line; otherwise say nothing.
The trigger adds the pull request event after the saved prompt and fills in nothing. Pull requests from forks do not fire it, and neither do ones opened by bots. Use branch_patterns to limit it to pull requests aimed at your main branch, and keep its max runs per hour high enough for a busy afternoon, since synchronize fires on every push to an open pull request.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
Why run it on Rush?
The migrator is a good tool that stops being enough at exactly the point where a stylesheet relied on shared global state, and you only learn that by compiling its output. The run does the whole loop in its own sandbox: reference compile, migration, failed compile, repair, compile again, byte comparison. Each compiler error and each command is kept in the session transcript, so the two hand repairs in the pull request can be traced to the messages that required them.
Byte-identical CSS is a strong claim, and it is cheap for a machine to check and tedious for a person. With it, review becomes a question of whether the comparison was done properly, not whether a few hundred changed lines each preserve behaviour. Without it, a migration like this tends to sit unmerged because nobody can vouch for it.
Frequently asked questions
Does the Sass migrator do everything automatically?
Often, for stylesheets that only share variables, mixins and functions downward. It does not resolve code that writes to another file's variables with !global, or checks such as global-variable-exists that assumed a single global scope. Those compile errors appear right after migration and need a small manual fix each.
Will my compiled CSS change?
It should not, and you can prove it. Compile before and after with the same Dart Sass version and the same output style and compare the files. @use loads each module once, so a partial that was imported several times and emitted its rules each time will emit them once; the comparison shows that case immediately.
What replaces map-get, type-of and percentage?
The same functions in built-in modules: map.get from sass:map, meta.type-of from sass:meta, math.percentage and math.div from sass:math, string.slice from sass:string, list.nth from sass:list. The migrator adds the @use lines and renames the calls.
How do I pass variables to a partial now?
With @use "library" with ($variable: value), for variables the partial declares with !default. Setting a variable before an @import and expecting the imported file to see it no longer works, because each module has its own scope. A library can re-export another module's members with @forward.
Can I just silence the warnings?
For a while. Dart Sass accepts --silence-deprecation=import and similar flags, and bundlers expose the same option. The warning text says @import will be removed in Dart Sass 3.0.0, so silencing buys time and does not remove the work. It is a fair choice while a dependency you import has not migrated yet.
More Sass jobs
More jobs like this: Upgrade dependencies weekly
- Migrate From satori/go.uuid to google/uuid in a Go App (satori/go.uuid)
- Migrate From sqlite3 to better-sqlite3 in a Node.js API (node-sqlite3)
- Replace golang.org/x/crypto/ssh/terminal With golang.org/x/term (golang.org/x/crypto)