Skip to content

Clear three of four Sass deprecation categories - #789

Merged
amjjbonvin merged 1 commit into
masterfrom
fix/sass-deprecations
Sep 29, 2026
Merged

amjjbonvin merged 1 commit into
masterfrom
fix/sass-deprecations

Conversation

@amjjbonvin

Copy link
Copy Markdown
Member

Addresses item 4 of the upgrade backlog.

Item 3 restored the real sass-embedded (dart-sass) toolchain in place of the
sassc (libsass) fallback, which surfaced deprecation warnings in four
categories. This clears three.

Category Before After
color-functions present cleared
global-builtin present cleared
slash-div present cleared
import present remains (see below)

Changes

  • lighten() / darken() → color.adjust() with explicit percentages
  • bare / division → math.div()
  • global built-ins namespaced: round() → math.round(), unquote() → string.unquote()
  • minima theme removed, config and gem

Verification

Every step was verified by rebuilding and byte-comparing the compiled
assets/css/main.css against a baseline captured before any change.

  • main.css is byte-identical at every step
  • 0 HTML pages changed
  • The only site-wide output difference is the removal of three unused minima
    artifacts: assets/main.css, assets/main.css.map, assets/minima-social-icons.svg

Why minima was removed rather than patched

It contributed nothing the site uses: all six layouts in _layouts/ are
standalone with no parent layout, the site has its own _includes, and the only
stylesheet it produced (assets/main.css) is referenced nowhere. Removing it
cleared roughly 40% of the warnings on its own. Dropping the gem also removed its
unused jekyll-seo-tag dependency — there is no {% seo %} tag anywhere.

A bug found and deliberately NOT fixed

_sass/forms.scss has three declarations of the form margin-bottom: 5px / 2.
Sass never evaluated these: with two literals and no parentheses it emits the
slash verbatim, so the published CSS contains margin-bottom:5px/2 — invalid,
and silently discarded by browsers.

Converting them to math.div() would newly apply a 2.5px margin that has never
been in effect
. That is a styling decision, not a deprecation fix, so they are
left as-is. They emit no warning. Flagged for a human call.

Why @import is deferred

It would touch ~25 files: assets/css/main.scss, twelve partials that rely on
variables.scss / mixins.scss being in global scope, and 13 @import
statements inside the vendored Font Awesome and Magnific Popup
. Migrating only
our own files would not clear the category, since the vendored imports would
still warn. @import works until Dart Sass 3.0, which has no release date, and
migrating a frozen Font Awesome 4.x is throwaway work. The natural trigger is
whenever those vendored libraries are replaced.

Vendored files patched here each carry a comment noting the patch must be
re-applied if the library is updated.

Separately noted

_includes/_head.html loads assets/css/main_pretty.css — a committed,
optimised artifact, not the main.css compiled from _sass/. The two have
drifted: 1120 selectors in the compiled CSS vs 1118 in the shipped one, with 5
present only in the SCSS (never regenerated, so not live) and 3 only in the
shipped file. Nothing in the repo regenerates it; the Gruntfile has no CSS task.
Recorded as its own backlog item.

🤖 Generated with Claude Code

Restoring the real sass-embedded (dart-sass) toolchain in item 3 surfaced
deprecation warnings in four categories. This clears three of them:
color-functions, global-builtin and slash-div. Only @import remains.

- lighten()/darken() -> color.adjust() with explicit percentages
- bare `/` division -> math.div()
- global built-ins namespaced: round() -> math.round(),
  unquote() -> string.unquote()

Remove the minima theme. It contributed no layouts (all six in _layouts/
are standalone with no parent layout), no includes, and no styles the site
loads -- only an assets/main.css that nothing references. Removing it cleared
roughly 40% of the warnings and dropped three dead artifacts from the built
site. The gem goes too, which also removes its unused jekyll-seo-tag
dependency; no {% seo %} tag exists anywhere in the site.

Font Awesome and Magnific Popup under _sass/vendor/ are patched in place,
each with a comment noting the patch must be re-applied if the library is
updated.

Every change was verified by rebuilding and byte-comparing the compiled
assets/css/main.css against a baseline: byte-identical at every step, with
no HTML page changed. The only output difference across the whole site is
the removal of the three unused minima artifacts.

Deliberately unchanged: three declarations in _sass/forms.scss of the form
`margin-bottom: 5px / 2`. Sass never evaluated these -- two literals with no
parentheses emit the slash verbatim, so the published CSS carries an invalid
`margin-bottom:5px/2` that browsers discard. Converting them would newly
apply a margin that has never been in effect, which is a styling decision
rather than a deprecation fix. They emit no warning.

The @import migration is deferred: it would touch ~25 files including 13
imports inside the frozen vendored libraries, and migrating only our own
files would not clear the category. @import is functional until Dart Sass
3.0, which has no release date.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@amjjbonvin

Copy link
Copy Markdown
Member Author

Copilot review:

Merge Readiness and Risk Assessment

Overall status: low risk and in good shape for merge
Why I’m comfortable:
the fix is narrow and mechanical
the generated CSS was checked for byte equivalence
no HTML output changed
the remaining @import migration is clearly deferred and documented rather than silently left out
No blocking issues found in the code changes themselves

@amjjbonvin
amjjbonvin merged commit d6f3ad0 into master Sep 29, 2026
2 checks passed
@amjjbonvin
amjjbonvin deleted the fix/sass-deprecations branch September 29, 2026 20:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant