refactor!: migrate theme assets from css to scss and centralize deprecation detection (#735)

**Breaking changes**:

1. Legacy custom style/script files are no longer loaded automatically.
2. Users must migrate custom files to:
   - `custom.scss`
   - `override.scss`
   - `_variables.scss`
   - `assets/js/custom.js`

**Migration guide**:

1. Move `assets/css/_custom.scss` to `assets/scss/custom.scss`.
2. Move `assets/css/_override.scss` to `assets/scss/override.scss`.
3. Keep variables in `assets/scss/_variables.scss`.
4. Move `assets/js/_custom.js` to `assets/js/custom.js`.
5. Rebuild site and verify no deprecation warnings remain.

.github/copilot-instructions.md

@@ -41,15 +41,9 @@ FixIt/
 
 ### 文件组织结构
 
-1. **主入口文件**: `assets/css/style.scss`
-2. **变量文件**: `assets/css/_variables.scss` - 全局变量定义
-3. **覆写文件**: `assets/css/_override.scss` - 用户自定义覆写
-4. **组织结构**:
-   - `_core/`: 核心样式（基础、布局、媒体查询等）
-   - `_mixin/`: SCSS mixins 和函数
-   - `_page/`: 页面特定样式
-   - `_partials/`: 组件样式
-   - `_shortcodes/`: 短代码样式
+1. **主入口文件**: `assets/scss/main.scss`
+2. **变量文件**: `assets/scss/_variables.scss` - 全局变量定义
+3. **覆写文件**: `assets/scss/_override.scss` - 用户自定义覆写
 
 ### 命名约定
 
@@ -111,7 +105,7 @@ FixIt/
 ### 文件组织
 
 1. **主题核心**: `assets/js/theme.js` - 主题核心逻辑
-2. **工具函数**: `assets/js/util.js` - 通用工具函数
+2. **工具函数**: `assets/js/utils/` - 通用工具函数
 3. **特定功能**: 按功能划分独立模块
 
 ### 编码实例

CONTRIBUTING.md

@@ -84,7 +84,7 @@ FixIt/
 │   └── test/           # Test site
 ├── archetypes/         # Content templates
 ├── assets/             # Theme assets
-│   ├── css/            # SCSS stylesheets
+│   ├── scss/           # SCSS stylesheets
 │   ├── js/             # JavaScript files
 │   ├── images/         # Image assets
 │   └── lib/            # Third-party libraries

assets/css/_core/_base.scss

@@ -1,98 +0,0 @@
-@import "../../lib/normalize/normalize";
-
-html {
-  font-family: fi-var(global-font-family);
-  font-weight: fi-var(global-font-weight);
-  font-display: swap;
-  font-size: fi-var(global-font-size);
-  line-height: fi-var(global-line-height);
-  width: 100%;
-  scroll-behavior: smooth;
-  overflow: auto;
-  container-type: scroll-state;
-  container-name: scroller;
-
-  &:has(dialog[open]) {
-    overflow: hidden;
-  }
-
-  @include media('reduce-motion') {
-    scroll-behavior: auto;
-  }
-}
-
-::selection {
-  background-color: fi-var(selection-color);
-}
-
-body {
-  background-color: fi-var(global-background-color);
-  color: fi-var(global-font-color);
-  @include overflow-wrap(break-word);
-}
-
-iframe {
-  border: 0;
-  @include border-radius;
-}
-
-button {
-  padding: 0;
-  border: 0;
-  background: transparent;
-  color: inherit;
-  appearance: none;
-  cursor: pointer;
-}
-
-button:disabled {
-  opacity: 0.65;
-  cursor: not-allowed;
-}
-
-summary {
-  cursor: pointer;
-}
-
-abbr[title] {
-  cursor: help;
-  text-decoration-skip-ink: none;
-}
-
-img {
-  object-fit: cover;
-}
-
-img,
-video {
-  max-width: 100%;
-  height: auto;
-  @include border-radius;
-}
-
-dialog {
-  padding: 0;
-}
-
-details {
-  &.center {
-    summary {
-      text-align: center;
-    }
-  }
-}
-
-%code {
-  padding: 0.2em 0.4em;
-  margin: 0;
-  font-size: fi-var(code-font-size);
-  line-height: fi-var(code-font-size);
-  font-family: fi-var(code-font-family);
-  color: fi-var(code-color);
-  background-color: fi-var(code-inline-background-color);
-  text-decoration: inherit;
-  @include border-radius;
-  @include overflow-wrap(break-word);
-}
-
-@include link(true, true);

assets/css/_core/_index.scss

@@ -1,7 +0,0 @@
-@import "_function";
-@import "_mixin";
-@import "_base";
-@import "_common";
-@import "_root";
-@import "_layout";
-@import '_widgets';

assets/css/style.scss

@@ -1,7 +0,0 @@
-@charset "utf-8";
-
-@import "_variables";
-@import "_override";
-@import "_core";
-@import "_page";
-@import "_custom";

assets/lib/normalize/normalize.css

@@ -1,349 +0,0 @@
-/*! normalize.css v8.0.1 | MIT License | github.com/necolas/normalize.css */
-
-/* Document
-   ========================================================================== */
-
-/**
- * 1. Correct the line height in all browsers.
- * 2. Prevent adjustments of font size after orientation changes in iOS.
- */
-
-html {
-  line-height: 1.15; /* 1 */
-  -webkit-text-size-adjust: 100%; /* 2 */
-}
-
-/* Sections
-   ========================================================================== */
-
-/**
- * Remove the margin in all browsers.
- */
-
-body {
-  margin: 0;
-}
-
-/**
- * Render the `main` element consistently in IE.
- */
-
-main {
-  display: block;
-}
-
-/**
- * Correct the font size and margin on `h1` elements within `section` and
- * `article` contexts in Chrome, Firefox, and Safari.
- */
-
-h1 {
-  font-size: 2em;
-  margin: 0.67em 0;
-}
-
-/* Grouping content
-   ========================================================================== */
-
-/**
- * 1. Add the correct box sizing in Firefox.
- * 2. Show the overflow in Edge and IE.
- */
-
-hr {
-  box-sizing: content-box; /* 1 */
-  height: 0; /* 1 */
-  overflow: visible; /* 2 */
-}
-
-/**
- * 1. Correct the inheritance and scaling of font size in all browsers.
- * 2. Correct the odd `em` font sizing in all browsers.
- */
-
-pre {
-  font-family: monospace, monospace; /* 1 */
-  font-size: 1em; /* 2 */
-}
-
-/* Text-level semantics
-   ========================================================================== */
-
-/**
- * Remove the gray background on active links in IE 10.
- */
-
-a {
-  background-color: transparent;
-}
-
-/**
- * 1. Remove the bottom border in Chrome 57-
- * 2. Add the correct text decoration in Chrome, Edge, IE, Opera, and Safari.
- */
-
-abbr[title] {
-  border-bottom: none; /* 1 */
-  text-decoration: underline; /* 2 */
-  text-decoration: underline dotted; /* 2 */
-}
-
-/**
- * Add the correct font weight in Chrome, Edge, and Safari.
- */
-
-b,
-strong {
-  font-weight: bolder;
-}
-
-/**
- * 1. Correct the inheritance and scaling of font size in all browsers.
- * 2. Correct the odd `em` font sizing in all browsers.
- */
-
-code,
-kbd,
-samp {
-  font-family: monospace, monospace; /* 1 */
-  font-size: 1em; /* 2 */
-}
-
-/**
- * Add the correct font size in all browsers.
- */
-
-small {
-  font-size: 80%;
-}
-
-/**
- * Prevent `sub` and `sup` elements from affecting the line height in
- * all browsers.
- */
-
-sub,
-sup {
-  font-size: 75%;
-  line-height: 0;
-  position: relative;
-  vertical-align: baseline;
-}
-
-sub {
-  bottom: -0.25em;
-}
-
-sup {
-  top: -0.5em;
-}
-
-/* Embedded content
-   ========================================================================== */
-
-/**
- * Remove the border on images inside links in IE 10.
- */
-
-img {
-  border-style: none;
-}
-
-/* Forms
-   ========================================================================== */
-
-/**
- * 1. Change the font styles in all browsers.
- * 2. Remove the margin in Firefox and Safari.
- */
-
-button,
-input,
-optgroup,
-select,
-textarea {
-  font-family: inherit; /* 1 */
-  font-size: 100%; /* 1 */
-  line-height: 1.15; /* 1 */
-  margin: 0; /* 2 */
-}
-
-/**
- * Show the overflow in IE.
- * 1. Show the overflow in Edge.
- */
-
-button,
-input { /* 1 */
-  overflow: visible;
-}
-
-/**
- * Remove the inheritance of text transform in Edge, Firefox, and IE.
- * 1. Remove the inheritance of text transform in Firefox.
- */
-
-button,
-select { /* 1 */
-  text-transform: none;
-}
-
-/**
- * Correct the inability to style clickable types in iOS and Safari.
- */
-
-button,
-[type="button"],
-[type="reset"],
-[type="submit"] {
-  -webkit-appearance: button;
-}
-
-/**
- * Remove the inner border and padding in Firefox.
- */
-
-button::-moz-focus-inner,
-[type="button"]::-moz-focus-inner,
-[type="reset"]::-moz-focus-inner,
-[type="submit"]::-moz-focus-inner {
-  border-style: none;
-  padding: 0;
-}
-
-/**
- * Restore the focus styles unset by the previous rule.
- */
-
-button:-moz-focusring,
-[type="button"]:-moz-focusring,
-[type="reset"]:-moz-focusring,
-[type="submit"]:-moz-focusring {
-  outline: 1px dotted ButtonText;
-}
-
-/**
- * Correct the padding in Firefox.
- */
-
-fieldset {
-  padding: 0.35em 0.75em 0.625em;
-}
-
-/**
- * 1. Correct the text wrapping in Edge and IE.
- * 2. Correct the color inheritance from `fieldset` elements in IE.
- * 3. Remove the padding so developers are not caught out when they zero out
- *    `fieldset` elements in all browsers.
- */
-
-legend {
-  box-sizing: border-box; /* 1 */
-  color: inherit; /* 2 */
-  display: table; /* 1 */
-  max-width: 100%; /* 1 */
-  padding: 0; /* 3 */
-  white-space: normal; /* 1 */
-}
-
-/**
- * Add the correct vertical alignment in Chrome, Firefox, and Opera.
- */
-
-progress {
-  vertical-align: baseline;
-}
-
-/**
- * Remove the default vertical scrollbar in IE 10+.
- */
-
-textarea {
-  overflow: auto;
-}
-
-/**
- * 1. Add the correct box sizing in IE 10.
- * 2. Remove the padding in IE 10.
- */
-
-[type="checkbox"],
-[type="radio"] {
-  box-sizing: border-box; /* 1 */
-  padding: 0; /* 2 */
-}
-
-/**
- * Correct the cursor style of increment and decrement buttons in Chrome.
- */
-
-[type="number"]::-webkit-inner-spin-button,
-[type="number"]::-webkit-outer-spin-button {
-  height: auto;
-}
-
-/**
- * 1. Correct the odd appearance in Chrome and Safari.
- * 2. Correct the outline style in Safari.
- */
-
-[type="search"] {
-  -webkit-appearance: textfield; /* 1 */
-  outline-offset: -2px; /* 2 */
-}
-
-/**
- * Remove the inner padding in Chrome and Safari on macOS.
- */
-
-[type="search"]::-webkit-search-decoration {
-  -webkit-appearance: none;
-}
-
-/**
- * 1. Correct the inability to style clickable types in iOS and Safari.
- * 2. Change font properties to `inherit` in Safari.
- */
-
-::-webkit-file-upload-button {
-  -webkit-appearance: button; /* 1 */
-  font: inherit; /* 2 */
-}
-
-/* Interactive
-   ========================================================================== */
-
-/*
- * Add the correct display in Edge, IE 10+, and Firefox.
- */
-
-details {
-  display: block;
-}
-
-/*
- * Add the correct display in all browsers.
- */
-
-summary {
-  display: list-item;
-}
-
-/* Misc
-   ========================================================================== */
-
-/**
- * Add the correct display in IE 10+.
- */
-
-template {
-  display: none;
-}
-
-/**
- * Add the correct display in IE 10.
- */
-
-[hidden] {
-  display: none;
-}

assets/scss/_variables.scss

@@ -193,4 +193,4 @@ $github-corner-fill: $header-background-color-dark !default;
 $github-corner-fill-dark: $header-background-color !default;
 // ========== GitHub Corners ========== //
 
-@import '_maps';
+@import 'core/maps';

assets/scss/core/_index.scss

@@ -0,0 +1,6 @@
+@import "functions";
+@import "mixins";
+@import "common";
+@import "reboot";
+@import "root";
+@import "layouts";

assets/scss/core/_reboot.scss

@@ -0,0 +1,357 @@
+/// Reboot
+///
+/// Normalization of HTML elements, manually forked from Normalize.css to remove
+/// styles targeting irrelevant browsers while applying new styles.
+///
+/// Normalize is licensed MIT. https://github.com/necolas/normalize.css
+
+
+// 1. Correct the line height in all browsers.
+
+:root {
+  font-family: fi-var(global-font-family);
+  font-weight: fi-var(global-font-weight);
+  font-display: swap;
+  font-size: fi-var(global-font-size);
+  line-height: fi-var(global-line-height); // 1
+  width: 100%;
+  scroll-behavior: smooth;
+  overflow: auto;
+  container-type: scroll-state;
+  container-name: scroller;
+
+  &:has(dialog[open]) {
+    overflow: hidden;
+  }
+
+  @include media('reduce-motion') {
+    scroll-behavior: auto;
+  }
+}
+
+// 1. Remove the margin in all browsers.
+// 2. As a best practice, apply a default `background-color`.
+// 3. Prevent adjustments of font size after orientation changes in iOS.
+// 4. Change the default tap highlight to be completely transparent in iOS.
+
+body {
+  margin: 0; // 1
+  background-color: fi-var(global-background-color); // 2
+  color: fi-var(global-font-color);
+  -webkit-text-size-adjust: 100%; // 3
+  -webkit-tap-highlight-color: rgba(#000, 0); // 4
+  @include overflow-wrap(break-word);
+}
+
+// Correct the font size and margin on `h1` elements within `section` and
+// `article` contexts in Chrome, Firefox, and Safari.
+
+h1 {
+  font-size: 2em;
+  margin: 0.67em 0;
+}
+
+// 1. Add the correct box sizing in Firefox.
+
+hr {
+  box-sizing: content-box; // 1
+  height: 0; // 1
+}
+
+// 1. Correct the inheritance and scaling of font size in all browsers.
+// 2. Correct the odd `em` font sizing in all browsers.
+
+pre {
+  font-family: monospace, monospace; // 1
+  font-size: 1em; // 2
+}
+
+// 1. Add the correct text decoration in Chrome, Edge, Opera, and Safari.
+// 2. Add explicit cursor to indicate changed behavior.
+// 3. Prevent the text-decoration to be skipped.
+
+abbr[title] {
+  text-decoration: underline dotted; // 1
+  cursor: help; // 2
+  text-decoration-skip-ink: none; // 3
+}
+
+// Add the correct font weight in Chrome, Edge, and Safari.
+
+b,
+strong {
+  font-weight: bolder;
+}
+
+// 1. Correct the inheritance and scaling of font size in all browsers.
+// 2. Correct the odd `em` font sizing in all browsers.
+
+code,
+kbd,
+samp {
+  font-family: monospace, monospace; // 1
+  font-size: 1em; // 2
+}
+
+// Add the correct font size in all browsers.
+
+small {
+  font-size: 80%;
+}
+
+// Prevent `sub` and `sup` elements from affecting the line height in
+// all browsers.
+
+sub,
+sup {
+  font-size: 75%;
+  line-height: 0;
+  position: relative;
+  vertical-align: baseline;
+}
+
+sub {
+  bottom: -0.25em;
+}
+
+sup {
+  top: -0.5em;
+}
+
+img {
+  object-fit: cover;
+}
+
+img,
+video {
+  max-width: 100%;
+  height: auto;
+  @include border-radius;
+}
+
+// 1. Remove the default `border-radius` that macOS Chrome adds.
+
+button {
+  border-radius: 0; // 1
+  padding: 0;
+  border: 0;
+  background: transparent;
+  color: inherit;
+}
+
+// Explicitly remove focus outline in Chromium when it shouldn't be
+// visible (e.g. as result of mouse click or touch tap). It already
+// should be doing this automatically, but seems to currently be
+// confused and applies its very visible two-tone outline anyway.
+
+button:focus:not(:focus-visible) {
+  outline: 0;
+}
+
+// 1. Change the font styles in all browsers.
+// 2. Remove the margin in Firefox and Safari.
+
+button,
+input,
+optgroup,
+select,
+textarea {
+  font-family: inherit; // 1
+  font-size: inherit; // 1
+  line-height: 1.15; // 1
+  margin: 0; // 2
+}
+
+// Remove the inheritance of text transform in Firefox
+
+button,
+select {
+  text-transform: none;
+}
+
+// 1. Prevent a WebKit bug where (2) destroys native `audio` and `video`
+//    controls in Android 4.
+// 2. Correct the inability to style clickable types in iOS and Safari.
+// 3. Opinionated: add "hand" cursor to non-disabled button elements.
+
+button,
+[type="button"], // 1
+[type="reset"],
+[type="submit"] {
+  -webkit-appearance: button; // 2
+
+  &:disabled {
+    opacity: 0.65;
+    cursor: not-allowed;
+  }
+
+  &:not(:disabled) {
+    cursor: pointer; // 3
+  }
+}
+
+// Remove inner border and padding from Firefox, but don't restore the outline like Normalize.
+
+::-moz-focus-inner {
+  padding: 0;
+  border-style: none;
+}
+
+// 1. Browsers set a default `min-width: min-content;` on fieldsets,
+//    unlike e.g. `<div>`s, which have `min-width: 0;` by default.
+//    So we reset that to ensure fieldsets behave more like a standard block element.
+//    See https://html.spec.whatwg.org/multipage/#the-fieldset-and-legend-elements
+// 2. Reset the default outline behavior of fieldsets so they don't affect page layout.
+
+fieldset {
+  min-width: 0; // 1
+  padding: 0; // 2
+  margin: 0; // 2
+  border: 0; // 2
+}
+
+
+// 1. By using `float: left`, the legend will behave like a block element.
+//    This way the border of a fieldset wraps around the legend if present.
+// 2. Fix wrapping bug.
+
+legend {
+  float: left; // 1
+  width: 100%;
+  padding: 0;
+  margin-bottom: 0.5rem;
+  font-weight: null;
+  line-height: inherit;
+  font-size: 1.5rem;
+
+  + * {
+    clear: left; // 2
+  }
+}
+
+// Add the correct vertical alignment in Chrome, Firefox, and Opera.
+
+progress {
+  vertical-align: baseline;
+}
+
+// 1. Textareas should really only resize vertically so they don't break their (horizontal) containers.
+
+textarea {
+  overflow: vertical; // 1
+}
+
+// Fix height of inputs with a type of datetime-local, date, month, week, or time
+
+::-webkit-datetime-edit-fields-wrapper,
+::-webkit-datetime-edit-text,
+::-webkit-datetime-edit-minute,
+::-webkit-datetime-edit-hour-field,
+::-webkit-datetime-edit-day-field,
+::-webkit-datetime-edit-month-field,
+::-webkit-datetime-edit-year-field {
+  padding: 0;
+}
+
+::-webkit-inner-spin-button {
+  height: auto;
+}
+
+// 1. This overrides the extra rounded corners on search inputs in iOS so that our
+//    `.form-control` class can properly style them. Note that this cannot simply
+//    be added to `.form-control` as it's not specific enough.
+// 2. Correct the outline style in Safari.
+
+[type='search'] {
+  -webkit-appearance: textfield; // 1
+  outline-offset: -2px; // 2
+
+  // 3. Better affordance and consistent appearance for search cancel button
+  &::-webkit-search-cancel-button {
+    cursor: pointer;
+    filter: grayscale(1);
+  }
+}
+
+// 1. A few input types should stay LTR
+// See https://rtlstyling.com/posts/rtl-styling#form-inputs
+// 2. RTL only output
+// See https://rtlcss.com/learn/usage-guide/control-directives/#raw
+
+/* rtl:raw:
+[type="tel"],
+[type="url"],
+[type="email"],
+[type="number"] {
+  direction: ltr;
+}
+*/
+
+// Remove the inner padding in Chrome and Safari on macOS.
+
+::-webkit-search-decoration {
+  -webkit-appearance: none;
+}
+
+// Remove padding around color pickers in webkit browsers
+
+::-webkit-color-swatch-wrapper {
+  padding: 0;
+}
+
+// Correct element displays
+
+output {
+  display: inline-block;
+}
+
+// 1. Remove border from iframe
+
+iframe {
+  border: 0; // 1
+  @include border-radius;
+}
+
+details {
+  &.center {
+    summary {
+      text-align: center;
+    }
+  }
+}
+
+// 1. Add the correct display in all browsers.
+
+summary {
+  display: list-item; // 1
+  cursor: pointer;
+}
+
+dialog {
+  padding: 0;
+}
+
+// Always hide an element with the `hidden` HTML attribute.
+
+[hidden] {
+  display: none;
+}
+
+::selection {
+  background-color: fi-var(selection-color);
+}
+
+%code {
+  padding: 0.2em 0.4em;
+  margin: 0;
+  font-size: fi-var(code-font-size);
+  line-height: fi-var(code-font-size);
+  font-family: fi-var(code-font-family);
+  color: fi-var(code-color);
+  background-color: fi-var(code-inline-background-color);
+  text-decoration: inherit;
+  @include border-radius;
+  @include overflow-wrap(break-word);
+}
+
+@include link(true, true);

assets/scss/core/layouts/_breadcrumb.scss

@@ -53,7 +53,7 @@
   .breadcrumb {
     display: flex;
     flex-wrap: nowrap;
-    padding: 0.5rem;
+    padding: 0.5rem 2px;
     margin: 0 auto;
     list-style: none;
     box-shadow: inset 0 -1px 0 fi-var(global-border-color);

assets/scss/core/layouts/_comment.scss

@@ -14,7 +14,6 @@
   }
 
   .comment {
-    padding-inline: 0.5rem;
     @extend %page-style;
 
     iframe {

assets/scss/core/layouts/_header.scss

@@ -62,6 +62,7 @@ header {
   display: flex;
   justify-content: space-between;
   align-items: center;
+  gap: 0.75rem;
   box-sizing: border-box;
   width: 100%;
 }

assets/scss/main.scss

@@ -0,0 +1,8 @@
+@charset "utf-8";
+
+@import "variables";
+@import "override";
+@import "core";
+@import "pages";
+@import 'widgets';
+@import "custom";

assets/scss/pages/_index.scss

@@ -1,5 +1,6 @@
 .page {
   padding-inline: 0.5rem;
+  box-sizing: border-box;
   @extend %page-style;
 
   .content {
@@ -38,9 +39,9 @@
   }
 }
 
-@import '_single';
-@import '_special';
-@import '_archive';
+@import 'single';
+@import 'specials';
+@import 'archives';
 @import '404';
 @import 'home';
 @import 'link';

assets/scss/pages/single/_code.scss

@@ -520,7 +520,7 @@ pre {
   }
 }
 
-@import './_code-syntax';
+@import './code-syntax';
 
 // gist shortcode
 .gist {
@@ -565,7 +565,7 @@ pre {
   }
 
   @include dark-mode {
-    @import './_code-syntax/github-dark-dimmed';
+    @import './code-syntax/github-dark-dimmed';
   }
 }
 

assets/scss/pages/single/_index.scss

@@ -535,7 +535,7 @@
     }
   }
 
-  @import '_shortcodes';
+  @import 'shortcodes';
   @import 'alert';
   @import 'code';
   @import 'diagram-copy-btn';

assets/scss/pages/single/code-syntax/_index.scss

@@ -4,8 +4,8 @@
  * To generate syntax highlighting styles from the command line,
  * See https://gohugo.io/quick-reference/syntax-highlighting-styles/#styles
  * For example:
- *   hugo gen chromastyles --style=github > assets/css/_partials/_code-syntax/light.scss
- *   hugo gen chromastyles --style=github-dark > assets/css/_partials/_code-syntax/dark.scss
+ *   hugo gen chromastyles --style=github > assets/css/pages/single/code-syntax/light.scss
+ *   hugo gen chromastyles --style=github-dark > assets/css/pages/single/code-syntax/dark.scss
  */
 .highlight {
   /* LineLink */