Get theme updates and move the styles to @use

.agents/tasks/dart-sass-site-styles.md

@@ -0,0 +1,59 @@
+---
+slug: dart-sass-site-styles
+branch: get-theme-updates-dart-sass
+owner: claude
+status: in-review
+started: 2026-10-30
+---
+
+## Goal
+
+The site builds on the Dart Sass `site-commons` theme, and its own styles use
+the Sass module system, so `hugo --minify` prints no Sass warnings and the CSS
+stays the same.
+
+## Context
+
+- SpineEventEngine/site-commons#38 — move the theme and its sites from LibSass
+  to Dart Sass. Hugo deprecated LibSass in v0.153.0; Dart Sass 3.0 removes `@import`.
+- The theme update brings in site-commons#39 (jQuery served as a file), #40
+  (Dart Sass) and #41 (`@use`/`@forward`). `theme-main.scss` forwards the theme
+  and Bootstrap, so `@use "theme-main" as *;` gives a partial what `@import` did.
+- Hugo sets `silenceDependencyDeprecations`, which hides deprecations in every
+  file except the entry one. The `sass` CLI with `--verbose` shows them all.
+- Also folds in the Dependabot bumps of #558 (`source-map-js`) and #560
+  (`postcss-selector-parser`, `@fullhuman/postcss-purgecss` 8). Nothing loads
+  PurgeCSS; the CSS is byte-identical with and without them.
+
+## Plan
+
+- [x] `hugo mod get -u github.com/SpineEventEngine/site-commons` in `site/`.
+- [x] Cherry-pick the bumps from #558 and #560.
+- [x] `main.scss` and its partials: `@import` → `@use`, in the same order.
+  - Partials that use theme or Bootstrap members: `@use "theme-main" as *;`.
+  - Partials that use another partial's members `@use` it by a relative path:
+    `base/colors` (variables), `base/common` (`%expandable-title`) and
+    `modules/forms` (`$form-error-color`). `main.scss` loads each of them
+    before its users, so no CSS moves.
+- [x] `map-get()` → `map.get()`, `fade-out()` → `color.adjust($alpha: …)`.
+- [x] Verify: Sass warnings, and the CSS rule by rule against the previous build.
+- [x] Keep Check Links passing. With jQuery no longer inlined (site-commons#39),
+  Lychee reads whole pages and finds 14 links that were already broken.
+  - Point the Gitter link of the 1.0 blog post to where Gitter redirects.
+  - `.lycheeignore` lists the 13 broken in the imported docs, as in
+    SpineEventEngine/documentation#96.
+
+## Log
+
+- 2026-10-30 — theme update: the only Sass warnings left are the 28 `@import`s
+  in `main.scss`. CSS differences are Dart Sass formatting and precision, folded
+  `calc()`, the code-tab indicator's `border-radius: 1px`, no `@extend`ed
+  `.h1`–`.h6`/`.small`/`.mark` selectors (no page uses them), and the medium
+  Roboto Mono `.eot` now pointing to `fonts/robotomono/` (site-commons#41).
+- 2026-10-30 — `@use` move: `hugo --minify` prints no Sass warnings. The `sass`
+  CLI reports 52 fewer deprecations (382 → 330), all the site's own; the rest
+  come from Bootstrap. The CSS has the same 12,764 declarations; one
+  `@extend`ed selector list lists its two selectors in the other order.
+- 2026-10-30 — the CSS now starts with the theme's license comment instead of
+  Bootstrap's. `@use "theme-main"` emits that file's `/*!` header first, and
+  the theme's PostCSS step keeps only the first comment. To fix in `site-commons`.

.github/workflows/check-links.yml

@@ -8,6 +8,7 @@ on:
       - 'docs/**'
       - 'site/**'
       - 'lychee.toml'
+      - '.lycheeignore'
       - '.github/workflows/check-links.yml'
   workflow_dispatch:
 
@@ -110,13 +111,13 @@ jobs:
         if: steps.docs.outputs.present == 'true'
         run: hugo env | grep 'github.com/sass/dart-sass'
 
-      # `actions/setup-node@v4` ships with built-in npm caching that hashes
+      # `actions/setup-node` ships with built-in npm caching that hashes
       # the lockfile and restores `~/.npm`. We use that instead of a
-      # standalone `actions/cache@v4` block so there is only one source of
+      # standalone `actions/cache` block so there is only one source of
       # truth for the cache key (no drift between two layers).
       - name: Setup Node
         if: steps.docs.outputs.present == 'true'
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v7
         with:
           node-version: '26'
           cache: 'npm'
@@ -128,7 +129,7 @@ jobs:
       # invalidates the cache deterministically regardless of site root.
       - name: Cache Hugo Modules
         if: steps.docs.outputs.present == 'true'
-        uses: actions/cache@v4
+        uses: actions/cache@v6
         with:
           path: /tmp/hugo_cache
           key: ${{ runner.os }}-hugomod-${{ hashFiles('docs/**/go.sum', 'site/**/go.sum') }}
@@ -152,7 +153,7 @@ jobs:
       # `max_cache_age` expires.
       - name: Cache Lychee results
         if: steps.docs.outputs.present == 'true'
-        uses: actions/cache@v4
+        uses: actions/cache@v6
         with:
           path: .lycheecache
           key: cache-lychee-${{ runner.os }}-${{ hashFiles('lychee.toml') }}
@@ -167,7 +168,7 @@ jobs:
       - name: Cache Lychee executable
         if: steps.docs.outputs.present == 'true'
         id: cache-lychee
-        uses: actions/cache@v4
+        uses: actions/cache@v6
         with:
           path: lychee
           key: ${{ runner.os }}-${{ env.LYCHEE_VERSION_TAG }}-${{ env.LYCHEE_RELEASE }}
@@ -187,7 +188,7 @@ jobs:
       # string when the file is absent, so this guard runs the download iff
       # neither the exact key nor any restore-key restored the binary.
       - name: Download Lychee executable
-        uses: robinraju/release-downloader@v1.7
+        uses: robinraju/release-downloader@v1.13
         if: steps.docs.outputs.present == 'true' && hashFiles('lychee/lychee') == ''
         with:
           repository: "lycheeverse/lychee"
@@ -239,9 +240,32 @@ jobs:
             exit 1
           fi
 
+      # Lychee prints broken links to this step's log only; the run page
+      # shows just "Process completed with exit code 2". `tee` keeps the
+      # report in the log and saves a copy, which the next step adds to the
+      # run summary. (`--output` would not do: it moves the report from the
+      # log to the file.) `pipefail` keeps Lychee's exit code. Without it,
+      # the step would take `tee`'s 0 and pass despite broken links.
       - name: Check links
         if: steps.docs.outputs.present == 'true'
         run: |
+          set -o pipefail
           ./lychee/lychee --config lychee.toml --timeout 60 \
           --base-url http://localhost:1313/ \
-          '${{ steps.docs.outputs.work_dir }}/public/**/*.html'
+          '${{ steps.docs.outputs.work_dir }}/public/**/*.html' \
+          | tee lychee-report.txt
+
+      # Runs after a failed `Check links` too, which is when the report
+      # matters most. `hashFiles` skips this step when Lychee never ran.
+      # `!cancelled()` needs the `${{ }}` wrapper: a bare leading `!` is
+      # a YAML tag.
+      - name: Publish link report
+        if: ${{ !cancelled() && hashFiles('lychee-report.txt') != '' }}
+        run: |
+          {
+            echo '## Link check'
+            echo
+            echo '```text'
+            cat lychee-report.txt
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"

.lycheeignore

@@ -0,0 +1,23 @@
+# Lychee skips the URLs matching these patterns. It reads this file from the
+# directory it runs in, the repository root. `lychee.toml` comes from `config`
+# and `./config/pull` overwrites it, so links specific to this site go here.
+#
+# Remove a pattern once the module update that fixes its link lands here.
+
+# Broken in the docs of `SpineEventEngine/documentation`, which
+# `site/config/_default/hugo.toml` imports as a module. Fixed by
+# https://github.com/SpineEventEngine/documentation/pull/96.
+^https://stackoverflow\.com/a/31814967/3183076$
+
+# Broken in the docs of `SpineEventEngine/validation`, which come in through
+# `SpineEventEngine/documentation`, so they can only be fixed there.
+# See https://github.com/SpineEventEngine/documentation/issues/97.
+^https://github\.com/SpineEventEngine/validation/blob/master/\.agents/running-builds\.md$
+^https://github\.com/SpineEventEngine/validation/blob/master/\.agents/documentation-guidelines\.md$
+^https://github\.com/SpineEventEngine/embed-code-go/blob/master/EMBEDDING\.md$
+^https://github\.com/SpineEventEngine/embed-code-go/tree/master/bin$
+^https://plugins\.gradle\.org/plugin/io\.spine\.validation$
+# Relative links that resolve outside the module's pages.
+^http://localhost:[0-9]+/06-developers-guide/$
+^http://localhost:[0-9]+/developer/$
+^http://localhost:[0-9]+/typical_custom_option\.jpg$

site/assets/scss/base/_colors.scss

@@ -12,6 +12,8 @@
  * and limitations under the License.
  */
 
+@use "theme-main" as *;
+
 /* Extends colors from `site-commons`. */
 
 $nav-blue-gradient: linear-gradient(152deg, #1378da 0%, #0b64cc 100%);

site/assets/scss/base/_common.scss

@@ -12,6 +12,9 @@
  * and limitations under the License.
  */
 
+@use "sass:color";
+@use "theme-main" as *;
+
 .intro-section {
   padding-top: 40px;
   padding-bottom: 48px;
@@ -24,7 +27,7 @@
 
 // Collapsible caret-icon in the mobile navigation and footer.
 .mobile-caret-icon {
-  background: fade-out($white, .97) url('img/icons/caret.svg') no-repeat center/cover;
+  background: color.adjust($white, $alpha: -.97) url('img/icons/caret.svg') no-repeat center/cover;
   opacity: 1;
   cursor: pointer;
   position: absolute;

site/assets/scss/main.scss

@@ -13,34 +13,34 @@
  */
 
 /* Styles from `SpineEventEngine/site-commons`. */
-@import "theme-main";
+@use "theme-main";
 
-@import "base/colors";
-@import "base/common";
+@use "base/colors";
+@use "base/common";
 
-@import "modules/navbar";
-@import "modules/nav-search";
-@import "modules/buttons";
-@import "modules/footer";
-@import "modules/hero";
-@import "modules/feature-cards";
-@import "modules/call-to-action";
-@import "modules/go-top-button";
-@import "modules/subscribe-container";
-@import "modules/checkbox";
-@import "modules/redirect-screen";
-@import "modules/loader";
-@import "modules/forms";
-@import "modules/result-panel";
-@import "modules/message-modal";
+@use "modules/navbar";
+@use "modules/nav-search";
+@use "modules/buttons";
+@use "modules/footer";
+@use "modules/hero";
+@use "modules/feature-cards";
+@use "modules/call-to-action";
+@use "modules/go-top-button";
+@use "modules/subscribe-container";
+@use "modules/checkbox";
+@use "modules/redirect-screen";
+@use "modules/loader";
+@use "modules/forms";
+@use "modules/result-panel";
+@use "modules/message-modal";
 
-@import "pages/landing";
-@import "pages/release-notes/release-notes";
-@import "pages/release-notes/sidenav";
-@import "pages/faq";
-@import "pages/getting-help";
-@import "pages/about";
-@import "pages/licenses";
-@import "pages/privacy";
-@import "pages/checkout";
-@import "pages/blog";
+@use "pages/landing";
+@use "pages/release-notes/release-notes";
+@use "pages/release-notes/sidenav";
+@use "pages/faq";
+@use "pages/getting-help";
+@use "pages/about";
+@use "pages/licenses";
+@use "pages/privacy";
+@use "pages/checkout";
+@use "pages/blog";

site/assets/scss/modules/_buttons.scss

@@ -12,6 +12,8 @@
  * and limitations under the License.
  */
 
+@use "theme-main" as *;
+
 $btn-font-size: 14px;
 $btn-border-radius: $border-radius-m;
 $btn-primary-color: $main-brand-color;

site/assets/scss/modules/_call-to-action.scss

@@ -12,6 +12,9 @@
  * and limitations under the License.
  */
 
+@use "../base/colors" as *;
+@use "theme-main" as *;
+
 .call-to-action {
   background-image: $nav-blue-gradient;
   padding: 80px 0 84px;

site/assets/scss/modules/_checkbox.scss

@@ -12,6 +12,8 @@
  * and limitations under the License.
  */
 
+@use "theme-main" as *;
+
 $checkbox-size: 18px;
 
 .checkbox-container {

site/assets/scss/modules/_feature-cards.scss

@@ -12,6 +12,9 @@
  * and limitations under the License.
  */
 
+@use "../base/colors" as *;
+@use "theme-main" as *;
+
 $feature-card-shadow: 0 1px 3px 0 rgba($footer-color, .08);
 
 .feature-section {

site/assets/scss/modules/_footer.scss

@@ -12,6 +12,10 @@
  * and limitations under the License.
  */
 
+@use "sass:color";
+@use "../base/colors" as *;
+@use "theme-main" as *;
+
 $footer-header-color: #54595c;
 $footer-link-color: #b4bcbf;
 $copyright-bg-color: #1e2021;
@@ -58,7 +62,7 @@ footer {
     }
 
     &:focus {
-      color: fade-out($white, .1);
+      color: color.adjust($white, $alpha: -.1);
     }
 
     &::after {
@@ -145,7 +149,7 @@ footer {
           .mobile-caret-icon {
             opacity: 1;
             background-size: contain;
-            background-color: fade-out($white, .97);
+            background-color: color.adjust($white, $alpha: -.97);
             border-radius: 50%;
           }
         }

site/assets/scss/modules/_forms.scss

@@ -12,6 +12,8 @@
  * and limitations under the License.
  */
 
+@use "theme-main" as *;
+
 $form-error-color: $red;
 $form-success-color: $green;
 

site/assets/scss/modules/_go-top-button.scss

@@ -12,6 +12,9 @@
  * and limitations under the License.
  */
 
+@use "sass:map";
+@use "theme-main" as *;
+
 #go-top-button {
   $top-button-size: 60px;
   $top-button-icon-size: $icon-size-l;
@@ -29,7 +32,7 @@
   height: $top-button-size;
   cursor: pointer;
   -webkit-transform: translate3d(0, 0, 0); // Prevents jumping on scroll in Chrome.
-  z-index: map_get($z-index, 'go-top-button');
+  z-index: map.get($z-index, 'go-top-button');
 
   &:after {
     content: "";

site/assets/scss/modules/_hero.scss

@@ -12,6 +12,9 @@
  * and limitations under the License.
  */
 
+@use "../base/colors" as *;
+@use "theme-main" as *;
+
 .nav-hero-container {
   background-image: $nav-blue-gradient;
   position: relative;

site/assets/scss/modules/_loader.scss

@@ -12,6 +12,8 @@
  * and limitations under the License.
  */
 
+@use "theme-main" as *;
+
 .loader-container {
   .loader {
     margin: 16px auto 12px;