@zhang_jifan/fanui 2.1.0

package/src/_mixins.scss

@@ -0,0 +1,1202 @@
+// =============================================================================
+// fanUI · 混合宏与工具函数层 (Mixins)
+// -----------------------------------------------------------------------------
+// 所有 mixin 统一以 `fanui-` 为前缀，用法：@include fanui-flex(...)
+// =============================================================================
+
+@use "sass:math";
+@use "sass:map";
+@use "sass:list";
+@use "sass:meta";
+@use "sass:string";
+@use "functions" as fn;
+@use "variables" as v;
+
+// -----------------------------------------------------------------------------
+// 1. 布局 · Flexbox
+// -----------------------------------------------------------------------------
+
+/// Flex 容器快捷方式。
+/// @example @include fanui-flex(row, space-between, center, nowrap, 12px);
+@mixin fanui-flex(
+  $direction: row,
+  $justify: flex-start,
+  $align: stretch,
+  $wrap: nowrap,
+  $gap: null,
+  $inline: false
+) {
+  @if $inline {
+    display: inline-flex;
+  } @else {
+    display: flex;
+  }
+  flex-direction: $direction;
+  justify-content: $justify;
+  align-items: $align;
+  flex-wrap: $wrap;
+  @if $gap != null {
+    gap: $gap;
+  }
+}
+
+/// 行内 Flex 容器。
+@mixin fanui-inline-flex(
+  $direction: row,
+  $justify: flex-start,
+  $align: stretch,
+  $wrap: nowrap,
+  $gap: null
+) {
+  @include fanui-flex($direction, $justify, $align, $wrap, $gap, $inline: true);
+}
+
+/// 主轴/交叉轴居中（最常用组合）。
+@mixin fanui-center-flex($direction: row, $gap: null) {
+  @include fanui-flex($direction, center, center, nowrap, $gap);
+}
+
+/// Flex 子项简写。
+@mixin fanui-flex-item($grow: 0, $shrink: 1, $basis: auto) {
+  flex: $grow $shrink $basis;
+}
+
+/// 占满剩余空间（等价 flex: 1 1 0%）。
+@mixin fanui-flex-fill($min-width: 0) {
+  flex: 1 1 0%;
+  min-width: $min-width;
+}
+
+// -----------------------------------------------------------------------------
+// 2. 布局 · Grid
+// -----------------------------------------------------------------------------
+
+/// CSS Grid 容器。
+/// @example @include fanui-grid(repeat(3, 1fr), 16px, 16px);
+@mixin fanui-grid($columns: null, $column-gap: null, $row-gap: null, $auto-flow: null) {
+  display: grid;
+  @if $columns != null    { grid-template-columns: $columns; }
+  @if $column-gap != null { column-gap: $column-gap; }
+  @if $row-gap != null    { row-gap: $row-gap; }
+  @if $auto-flow != null  { grid-auto-flow: $auto-flow; }
+}
+
+/// 自适应卡片网格（auto-fit + minmax），无需媒体查询。
+/// @example @include fanui-grid-auto(280px, 16px);
+@mixin fanui-grid-auto($min-width: 280px, $gap: 16px, $fill: auto-fit) {
+  display: grid;
+  grid-template-columns: repeat(#{$fill}, minmax(#{$min-width}, 1fr));
+  gap: $gap;
+}
+
+/// 12 栅格体系下的列宽计算。
+@mixin fanui-make-col($size, $columns: v.$fanui-grid-columns) {
+  @if $size == 0 {
+    display: none;
+  } @else if $size == "auto" {
+    flex: 0 0 auto;
+    width: auto;
+    max-width: 100%;
+  } @else {
+    flex: 0 0 auto;
+    width: fn.fanui-percentage($size, $columns);
+  }
+}
+
+/// 栅格行容器。
+@mixin fanui-make-row($gutter-x: v.$fanui-grid-gutter-x, $gutter-y: v.$fanui-grid-gutter-y) {
+  --fanui-gutter-x: #{$gutter-x};
+  --fanui-gutter-y: #{$gutter-y};
+  display: flex;
+  flex-wrap: wrap;
+  margin-top: fn.fanui-negate($gutter-y);
+  margin-inline-end: calc(fn.fanui-negate($gutter-x) * 0.5);
+  margin-inline-start: calc(fn.fanui-negate($gutter-x) * 0.5);
+
+  > * {
+    box-sizing: border-box;
+    flex-shrink: 0;
+    width: 100%;
+    max-width: 100%;
+    padding-inline-end: calc(var(--fanui-gutter-x, #{$gutter-x}) * 0.5);
+    padding-inline-start: calc(var(--fanui-gutter-x, #{$gutter-x}) * 0.5);
+    margin-top: var(--fanui-gutter-y, #{$gutter-y});
+  }
+}
+
+// -----------------------------------------------------------------------------
+// 3. 响应式
+// -----------------------------------------------------------------------------
+
+/// min-width 媒体查询（移动优先）。
+/// @example @include fanui-media("md") { ... }
+@mixin fanui-media($breakpoint, $type: min) {
+  $width: fn.fanui-breakpoint(v.$fanui-breakpoints, $breakpoint);
+  @if $type == min {
+    @if $width == 0 {
+      @content;
+    } @else {
+      @media (min-width: $width) { @content; }
+    }
+  } @else if $type == max {
+    @if $width != 0 {
+      @media (max-width: fn.fanui-negate(math.div(1px, 20)) + $width) { @content; }
+    }
+  }
+}
+
+/// max-width 媒体查询（向下覆盖）。
+@mixin fanui-media-down($breakpoint) {
+  @include fanui-media($breakpoint, max) { @content; }
+}
+
+/// 区间媒体查询。
+@mixin fanui-media-between($from, $to) {
+  $min: fn.fanui-breakpoint(v.$fanui-breakpoints, $from);
+  $max: fn.fanui-breakpoint(v.$fanui-breakpoints, $to);
+  @if $min != 0 {
+    @media (min-width: $min) and (max-width: fn.fanui-negate(math.div(1px, 20)) + $max) {
+      @content;
+    }
+  } @else {
+    @media (max-width: fn.fanui-negate(math.div(1px, 20)) + $max) { @content; }
+  }
+}
+
+/// 仅当前断点区间。
+@mixin fanui-media-only($breakpoint) {
+  $keys: map.keys(v.$fanui-breakpoints);
+  $index: list.index($keys, $breakpoint);
+  @if $index == null {
+    @error "fanUI: 未知断点 `#{$breakpoint}`，可用值：#{$keys}。";
+  }
+  @if $index == list.length($keys) {
+    @include fanui-media($breakpoint, min) { @content; }
+  } @else {
+    @include fanui-media-between($breakpoint, list.nth($keys, $index + 1)) { @content; }
+  }
+}
+
+/// 遍历所有（或指定）断点，生成响应式工具类。
+/// @example @include fanui-each-breakpoint("md" "lg") { ... }
+@mixin fanui-each-breakpoint($breakpoints: map.keys(v.$fanui-breakpoints)) {
+  @each $name in $breakpoints {
+    @include fanui-media($name, min) {
+      $fanui-infix: fn.fanui-bp-infix($name);
+      @content;
+    }
+  }
+}
+
+/// 生成带断点中缀的类名后缀。配合 fanui-each-breakpoint 使用。
+@mixin fanui-breakpoint-infix($name) {
+  @if $name != "xs" {
+    -#{$name} {
+      @content;
+    }
+  } @else {
+    @content;
+  }
+}
+
+/// 深浅模式（媒体查询自动跟随系统）。
+@mixin fanui-prefers-dark {
+  @media (prefers-color-scheme: dark) { @content; }
+}
+
+// -----------------------------------------------------------------------------
+// 4. 容器
+// -----------------------------------------------------------------------------
+
+/// 固定宽度容器（各断点最大宽度）。
+@mixin fanui-container($gutter: v.$fanui-container-padding-x) {
+  width: 100%;
+  padding-inline-end: $gutter;
+  padding-inline-start: $gutter;
+  margin-inline-end: auto;
+  margin-inline-start: auto;
+  box-sizing: border-box;
+
+  @each $name, $max in v.$fanui-container-max-widths {
+    @include fanui-media($name, min) {
+      max-width: $max;
+    }
+  }
+}
+
+/// 全宽容器。
+@mixin fanui-container-fluid($gutter: v.$fanui-container-padding-x) {
+  width: 100%;
+  padding-inline-end: $gutter;
+  padding-inline-start: $gutter;
+  margin-inline-end: auto;
+  margin-inline-start: auto;
+  box-sizing: border-box;
+}
+
+// -----------------------------------------------------------------------------
+// 5. 尺寸与定位
+// -----------------------------------------------------------------------------
+
+/// 同时设置宽高。
+@mixin fanui-size($width, $height: $width) {
+  width: $width;
+  height: $height;
+}
+
+/// 宽高相等。
+@mixin fanui-square($size) {
+  @include fanui-size($size, $size);
+}
+
+/// 绝对定位四向铺满。
+@mixin fanui-absolute-fill($offset: 0) {
+  position: absolute;
+  top: $offset;
+  right: $offset;
+  bottom: $offset;
+  left: $offset;
+}
+
+/// 绝对居中（支持横向/纵向）。
+/// @example @include fanui-abs-center(both);
+@mixin fanui-abs-center($axis: both, $translate: -50%) {
+  position: absolute;
+  @if $axis == both or $axis == x {
+    left: 50%;
+  }
+  @if $axis == both or $axis == y {
+    top: 50%;
+  }
+  @if $axis == both {
+    transform: translate($translate, $translate);
+  } @else if $axis == x {
+    transform: translateX($translate);
+  } @else if $axis == y {
+    transform: translateY($translate);
+  }
+}
+
+/// 固定定位铺满（常用于遮罩层）。
+@mixin fanui-fixed-fill() {
+  position: fixed;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  left: 0;
+}
+
+/// 维持宽高比。
+@mixin fanui-aspect-ratio($width: 16, $height: 9) {
+  aspect-ratio: math.div($width, $height);
+}
+
+// -----------------------------------------------------------------------------
+// 6. 文本处理
+// -----------------------------------------------------------------------------
+
+/// 单行 / 多行省略。
+/// @example @include fanui-truncate(2);
+@mixin fanui-truncate($lines: 1) {
+  @if $lines == 1 {
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  } @else {
+    display: -webkit-box;
+    -webkit-line-clamp: $lines;
+    -webkit-box-orient: vertical;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+}
+
+/// 无衬线/等宽字体栈。
+@mixin fanui-font($family: base, $size: null, $weight: null, $line-height: null) {
+  @if $family == base   { font-family: v.$fanui-font-family-base; }
+  @else if $family == sans  { font-family: v.$fanui-font-family-sans; }
+  @else if $family == serif { font-family: v.$fanui-font-family-serif; }
+  @else if $family == mono  { font-family: v.$fanui-font-family-mono; }
+  @if $size != null        { font-size: $size; }
+  @if $weight != null      { font-weight: $weight; }
+  @if $line-height != null { line-height: $line-height; }
+}
+
+/// 文本渐变填充。
+@mixin fanui-text-gradient($from, $to, $direction: to right) {
+  background-image: linear-gradient($direction, $from, $to);
+  -webkit-background-clip: text;
+  background-clip: text;
+  color: transparent;
+  -webkit-text-fill-color: transparent;
+}
+
+/// 屏幕阅读器可见、视觉隐藏（可聚焦时显示）。
+@mixin fanui-visually-hidden($focusable: false) {
+  position: absolute !important;
+  width: 1px !important;
+  height: 1px !important;
+  padding: 0 !important;
+  margin: -1px !important;
+  overflow: hidden !important;
+  clip: rect(0, 0, 0, 0) !important;
+  white-space: nowrap !important;
+  border: 0 !important;
+
+  @if $focusable {
+    &:active,
+    &:focus {
+      position: static !important;
+      width: auto !important;
+      height: auto !important;
+      margin: 0 !important;
+      overflow: visible !important;
+      clip: auto !important;
+      white-space: normal !important;
+    }
+  }
+}
+
+/// 输入框 placeholder 样式（跨浏览器）。
+@mixin fanui-placeholder($color: null, $opacity: 1) {
+  @if $color != null {
+    &::placeholder { color: $color; opacity: $opacity; }
+  } @else {
+    &::placeholder { opacity: $opacity; }
+  }
+  &::-webkit-input-placeholder { @if $color != null { color: $color; } opacity: $opacity; }
+  &::-moz-placeholder { @if $color != null { color: $color; } opacity: $opacity; }
+  &:-ms-input-placeholder { @if $color != null { color: $color; } opacity: $opacity; }
+}
+
+/// 清除浮动。
+@mixin fanui-clearfix() {
+  &::after {
+    display: block;
+    clear: both;
+    content: "";
+  }
+}
+
+// -----------------------------------------------------------------------------
+// 7. 外观
+// -----------------------------------------------------------------------------
+
+/// 去掉原生外观。
+@mixin fanui-appearance-none() {
+  appearance: none;
+  -webkit-appearance: none;
+  -moz-appearance: none;
+  background-clip: padding-box;
+}
+
+/// 焦点环（无障碍）。
+/// @example @include fanui-focus-ring();                    // 使用主题色（运行时可变）
+/// @example @include fanui-focus-ring(v.$fanui-danger);     // 指定固定颜色
+@mixin fanui-focus-ring($color: null, $width: null, $offset: null) {
+  // C3：焦点环三参数全部走运行时令牌（--fanui-focus-ring-*），
+  // 业务方可整体覆盖焦点环颜色 / 宽度 / 偏移，无需改 SCSS。
+  // 注：这里用 @if/@else 而不是 if() 函数——后者在新版 Sass 中已弃用
+  // （DEPRECATION WARNING [if-function]），@if 控制指令无弃用风险且语义等价。
+  $ring: null;
+  @if $color != null {
+    $ring: fn.fanui-alpha($color, v.$fanui-focus-ring-alpha);
+  } @else {
+    $ring: fn.fanui-var("focus-ring-color", fn.fanui-alpha(v.$fanui-primary, v.$fanui-focus-ring-alpha));
+  }
+  $w: null;
+  @if $width != null {
+    $w: $width;
+  } @else {
+    $w: fn.fanui-var("focus-ring-width", v.$fanui-focus-ring-width);
+  }
+  $o: null;
+  @if $offset != null {
+    $o: $offset;
+  } @else {
+    $o: fn.fanui-var("focus-ring-offset", v.$fanui-focus-ring-offset);
+  }
+
+  outline: 0;
+  box-shadow: 0 0 0 $o fn.fanui-var("color-surface", #fff),
+              0 0 0 calc(#{$o} + #{$w}) #{$ring};
+
+  // 高对比度模式下回退为系统 outline
+  @media (forced-colors: active) {
+    outline: 2px solid transparent;
+    outline-offset: 2px;
+  }
+}
+
+/// 仅在键盘聚焦时显示焦点环（默认主题色，运行时可变）。
+@mixin fanui-focus-ring-visible($color: null) {
+  &:focus-visible {
+    @include fanui-focus-ring($color);
+  }
+}
+
+/// 阴影层级。
+@mixin fanui-elevation($level: "base") {
+  @if $level == 0 or $level == "none" or $level == null {
+    box-shadow: none;
+  } @else {
+    box-shadow: map.get(v.$fanui-shadows, $level);
+  }
+}
+
+/// 圆角（可单独指定四角）。
+@mixin fanui-border-radius($radius: v.$fanui-radius-base, $corners: all) {
+  @if $corners == all {
+    border-radius: $radius;
+  } @else if $corners == top {
+    border-start-start-radius: $radius;
+    border-start-end-radius: $radius;
+  } @else if $corners == bottom {
+    border-end-start-radius: $radius;
+    border-end-end-radius: $radius;
+  } @else if $corners == start {
+    border-start-start-radius: $radius;
+    border-end-start-radius: $radius;
+  } @else if $corners == end {
+    border-start-end-radius: $radius;
+    border-end-end-radius: $radius;
+  }
+}
+
+/// 边框。
+@mixin fanui-border($color: fn.fanui-var("color-border"), $width: v.$fanui-border-width, $style: solid, $sides: all) {
+  @if $sides == all {
+    border: $width $style $color;
+  } @else {
+    @each $side in $sides {
+      border-#{$side}: $width $style $color;
+    }
+  }
+}
+
+/// 过渡（统一动效语言）。
+@mixin fanui-transition($props: all, $duration: v.$fanui-duration-base, $timing: v.$fanui-ease-base, $delay: 0s) {
+  @if v.$fanui-enable-transitions {
+    $list: ();
+    @each $p in $props {
+      $list: list.append($list, #{$p} #{$duration} #{$timing} #{$delay}, comma);
+    }
+    transition: $list;
+  }
+}
+
+/// 禁用状态统一样式。
+@mixin fanui-disabled($opacity: 0.55, $cursor: not-allowed) {
+  &:disabled,
+  &.is-disabled,
+  &[aria-disabled="true"] {
+    opacity: $opacity;
+    cursor: $cursor;
+    pointer-events: none;
+    box-shadow: none;
+  }
+}
+
+/// 自定义滚动条。
+@mixin fanui-scrollbar($size: 8px, $thumb: fn.fanui-alpha(#64748b, 0.45), $track: transparent, $radius: v.$fanui-radius-full) {
+  scrollbar-width: thin;
+  scrollbar-color: #{$thumb} #{$track};
+
+  &::-webkit-scrollbar {
+    width: $size;
+    height: $size;
+  }
+  &::-webkit-scrollbar-track {
+    background: $track;
+  }
+  &::-webkit-scrollbar-thumb {
+    background: $thumb;
+    border-radius: $radius;
+
+    &:hover { background: fn.fanui-alpha(#64748b, 0.7); }
+  }
+}
+
+/// 隐藏滚动条但完全保留滚动能力（跨浏览器）。
+@mixin fanui-no-scrollbar() {
+  scrollbar-width: none;
+  -ms-overflow-style: none;
+
+  &::-webkit-scrollbar {
+    width: 0;
+    height: 0;
+    display: none;
+  }
+}
+
+/// 渐变背景。
+@mixin fanui-gradient($from, $to, $direction: to bottom) {
+  background-image: linear-gradient($direction, $from, $to);
+}
+
+/// 点击反馈（水波纹替代方案：轻微缩放）。
+@mixin fanui-pressable($scale: 0.97) {
+  @include fanui-transition((transform, box-shadow), v.$fanui-duration-fast);
+  &:active:not(:disabled):not(.is-disabled) {
+    transform: scale($scale);
+  }
+}
+
+// -----------------------------------------------------------------------------
+// 8. 组件级生成器
+// -----------------------------------------------------------------------------
+
+/// 按钮变体生成器：一次性产出 背景/边框/前景/hover/active/focus/outline。
+/// @example @include fanui-button-variant(v.$fanui-primary);
+@mixin fanui-button-variant($bg, $fg: null, $border: null, $hover-bg: null, $active-bg: null) {
+  @if $fg == null        { $fg: fn.fanui-contrast($bg); }
+  @if $border == null    { $border: $bg; }
+  @if $hover-bg == null  { $hover-bg: fn.fanui-shade($bg, 10%); }
+  @if $active-bg == null { $active-bg: fn.fanui-shade($bg, 18%); }
+
+  --fanui-btn-bg: #{$bg};
+  --fanui-btn-fg: #{$fg};
+  --fanui-btn-border: #{$border};
+  --fanui-btn-hover-bg: #{$hover-bg};
+  --fanui-btn-hover-fg: #{$fg};
+  --fanui-btn-hover-border: #{$hover-bg};
+  --fanui-btn-active-bg: #{$active-bg};
+  --fanui-btn-active-fg: #{$fg};
+  --fanui-btn-active-border: #{$active-bg};
+  --fanui-btn-ring: #{fn.fanui-alpha($bg, v.$fanui-focus-ring-alpha)};
+}
+
+/// 描边（outline）按钮变体。
+@mixin fanui-button-outline-variant($color, $hover-fg: null) {
+  @if $hover-fg == null { $hover-fg: fn.fanui-contrast($color); }
+  --fanui-btn-bg: transparent;
+  --fanui-btn-fg: #{$color};
+  --fanui-btn-border: #{$color};
+  --fanui-btn-hover-bg: #{$color};
+  --fanui-btn-hover-fg: #{$hover-fg};
+  --fanui-btn-hover-border: #{$color};
+  --fanui-btn-active-bg: #{fn.fanui-shade($color, 18%)};
+  --fanui-btn-active-fg: #{$hover-fg};
+  --fanui-btn-active-border: #{fn.fanui-shade($color, 18%)};
+  --fanui-btn-ring: #{fn.fanui-alpha($color, v.$fanui-focus-ring-alpha)};
+}
+
+/// 文字（text/link）按钮变体。
+@mixin fanui-button-text-variant($color) {
+  --fanui-btn-bg: transparent;
+  --fanui-btn-fg: #{$color};
+  --fanui-btn-border: transparent;
+  --fanui-btn-hover-bg: #{fn.fanui-alpha($color, 0.10)};
+  --fanui-btn-hover-fg: #{fn.fanui-shade($color, 8%)};
+  --fanui-btn-hover-border: transparent;
+  --fanui-btn-active-bg: #{fn.fanui-alpha($color, 0.18)};
+  --fanui-btn-active-fg: #{fn.fanui-shade($color, 16%)};
+  --fanui-btn-active-border: transparent;
+  --fanui-btn-ring: #{fn.fanui-alpha($color, v.$fanui-focus-ring-alpha)};
+}
+
+/// 按钮尺寸。
+@mixin fanui-button-size($height, $padding-x, $font-size, $radius: null) {
+  --fanui-btn-height: #{$height};
+  --fanui-btn-padding-x: #{$padding-x};
+  --fanui-btn-font-size: #{$font-size};
+  @if $radius != null {
+    --fanui-btn-radius: #{$radius};
+  }
+}
+
+/// 徽标变体。
+@mixin fanui-badge-variant($bg, $fg: null) {
+  @if $fg == null { $fg: fn.fanui-contrast($bg); }
+  background-color: $bg;
+  color: $fg;
+  border-color: transparent;
+}
+
+/// 柔和（soft）徽标变体。
+@mixin fanui-badge-soft-variant($color) {
+  background-color: fn.fanui-alpha($color, 0.12);
+  color: fn.fanui-shade($color, 12%);
+  border-color: fn.fanui-alpha($color, 0.22);
+}
+
+/// 警告框（alert）变体。
+@mixin fanui-alert-variant($color) {
+  $bg: fn.fanui-alpha($color, 0.10);
+  $border: fn.fanui-alpha($color, 0.28);
+  background-color: $bg;
+  border-color: $border;
+  color: fn.fanui-shade($color, 22%);
+
+  .fanui-alert__title { color: fn.fanui-shade($color, 30%); }
+
+  [data-fanui-theme="dark"] & {
+    background-color: fn.fanui-alpha($color, 0.16);
+    border-color: fn.fanui-alpha($color, 0.34);
+    color: fn.fanui-tint($color, 42%);
+  }
+}
+
+/// 表单控件样式（输入框/选择器/文本域共用）。
+@mixin fanui-form-control($height: v.$fanui-control-height-base, $padding-x: v.$fanui-control-padding-x, $font-size: v.$fanui-control-font-size, $radius: v.$fanui-control-radius) {
+  display: block;
+  width: 100%;
+  min-height: $height;
+  padding: math.div($height - $font-size * v.$fanui-control-line-height - v.$fanui-control-border-width * 2, 2) $padding-x;
+  font-family: inherit;
+  font-size: $font-size;
+  line-height: v.$fanui-control-line-height;
+  color: fn.fanui-var("color-text");
+  background-color: fn.fanui-var("color-surface");
+  border: v.$fanui-control-border-width solid fn.fanui-var("color-border");
+  border-radius: $radius;
+  box-sizing: border-box;
+  @include fanui-appearance-none();
+  @include fanui-transition((border-color, box-shadow, background-color), v.$fanui-duration-fast);
+
+  @include fanui-placeholder(fn.fanui-var("color-text-subtle"));
+
+  &:hover:not(:disabled):not(.is-disabled) {
+    border-color: fn.fanui-var("color-border-strong");
+  }
+
+  &:focus,
+  &:focus-visible {
+    border-color: fn.fanui-var("primary");
+    @include fanui-focus-ring();
+  }
+
+  &:disabled,
+  &.is-disabled {
+    background-color: fn.fanui-var("color-disabled-bg");
+    color: fn.fanui-var("color-disabled-text");
+    cursor: not-allowed;
+    resize: none;
+  }
+
+  &[readonly] {
+    background-color: fn.fanui-var("color-surface-sunken");
+  }
+}
+
+/// 校验状态（成功/警告/错误）。
+@mixin fanui-form-validation($color) {
+  $ring: fn.fanui-alpha($color, v.$fanui-focus-ring-alpha);
+
+  .fanui-form-control,
+  .fanui-select,
+  .fanui-textarea {
+    border-color: $color;
+
+    &:focus,
+    &:focus-visible {
+      border-color: $color;
+      box-shadow: 0 0 0 v.$fanui-focus-ring-offset fn.fanui-var("color-surface", #fff),
+                  0 0 0 (v.$fanui-focus-ring-offset + v.$fanui-focus-ring-width) $ring;
+    }
+  }
+
+  .fanui-form-feedback { color: $color; }
+}
+
+/// 卡片变体。
+@mixin fanui-card-variant($bg, $border: null, $fg: null, $shadow: null) {
+  background-color: $bg;
+  @if $border != null { border-color: $border; }
+  @if $fg != null     { color: $fg; }
+  @if $shadow != null { @include fanui-elevation($shadow); }
+}
+
+/// 交互式容器（卡片/列表项）的 hover / active / focus 统一行为。
+@mixin fanui-interactive-surface($radius: v.$fanui-radius-base) {
+  cursor: pointer;
+  @include fanui-transition((background-color, border-color, box-shadow, transform), v.$fanui-duration-fast);
+
+  &:hover {
+    background-color: fn.fanui-var("color-hover");
+  }
+  &:active {
+    background-color: fn.fanui-var("color-active");
+  }
+  &:focus-visible {
+    @include fanui-focus-ring();
+  }
+  &.is-selected,
+  &[aria-selected="true"] {
+    background-color: fn.fanui-var("primary-soft");
+    border-color: fn.fanui-var("primary-border");
+    color: fn.fanui-var("primary-ink");
+  }
+}
+
+/// 遮罩层。
+@mixin fanui-backdrop($bg: fn.fanui-var("backdrop-bg", v.$fanui-backdrop-bg), $blur: fn.fanui-var("backdrop-blur", v.$fanui-backdrop-blur)) {
+  @include fanui-fixed-fill();
+  background-color: $bg;
+  @if $blur != null and $blur != 0 {
+    backdrop-filter: blur($blur);
+    -webkit-backdrop-filter: blur($blur);
+  }
+  z-index: fn.fanui-var("z-backdrop", v.$fanui-zindex-backdrop);
+}
+
+/// 表格变体。
+@mixin fanui-table-variant($striped-bg: fn.fanui-var("color-surface-sunken"), $hover-bg: fn.fanui-var("color-hover"), $border-color: fn.fanui-var("color-border")) {
+  --fanui-table-striped-bg: #{$striped-bg};
+  --fanui-table-hover-bg: #{$hover-bg};
+  --fanui-table-border-color: #{$border-color};
+}
+
+/// 进度条变体。
+@mixin fanui-progress-variant($bg, $fg: null, $stripes: true) {
+  @if $fg == null { $fg: fn.fanui-contrast($bg); }
+  --fanui-progress-bg: #{$bg};
+  --fanui-progress-fg: #{$fg};
+
+  @if $stripes {
+    background-image: linear-gradient(
+      45deg,
+      rgba(255, 255, 255, 0.18) 25%, transparent 25%,
+      transparent 50%, rgba(255, 255, 255, 0.18) 50%,
+      rgba(255, 255, 255, 0.18) 75%, transparent 75%, transparent
+    );
+    background-size: 1rem 1rem;
+  }
+}
+
+/// 开关（switch）变体。
+@mixin fanui-switch-variant($checked-bg: v.$fanui-primary, $thumb: #ffffff) {
+  &:checked + .fanui-switch__track,
+  &.is-checked .fanui-switch__track {
+    background-color: $checked-bg;
+    border-color: $checked-bg;
+
+    .fanui-switch__thumb {
+      background-color: $thumb;
+      transform: translateX(var(--fanui-switch-travel, 18px));
+    }
+  }
+}
+
+// -----------------------------------------------------------------------------
+// 9. 主题输出
+// -----------------------------------------------------------------------------
+
+/// 输出一组主题令牌为 CSS 自定义属性。
+@mixin fanui-emit-theme($tokens, $prefix: "fanui") {
+  @each $name, $value in $tokens {
+    --#{$prefix}-#{$name}: #{$value};
+  }
+}
+
+/// 输出调色板为 CSS 自定义属性（如 --fanui-primary-500）。
+@mixin fanui-emit-palette($palette, $prefix: "fanui") {
+  @each $name, $tones in $palette {
+    @each $tone, $value in $tones {
+      --#{$prefix}-#{$name}-#{$tone}: #{$value};
+    }
+  }
+}
+
+/// 输出语义色快捷变量（--fanui-primary / --fanui-primary-fg / --fanui-primary-soft ...）。
+@mixin fanui-emit-semantic-colors($colors, $prefix: "fanui") {
+  @each $name, $value in $colors {
+    --#{$prefix}-#{$name}: #{$value};
+    --#{$prefix}-#{$name}-hover: #{fn.fanui-shade($value, 10%)};
+    --#{$prefix}-#{$name}-active: #{fn.fanui-shade($value, 18%)};
+    --#{$prefix}-#{$name}-soft: #{fn.fanui-alpha($value, 0.12)};
+    --#{$prefix}-#{$name}-border: #{fn.fanui-alpha($value, 0.28)};
+    --#{$prefix}-#{$name}-fg: #{fn.fanui-contrast($value)};
+    --#{$prefix}-#{$name}-ring: #{fn.fanui-alpha($value, v.$fanui-focus-ring-alpha)};
+  }
+}
+
+// -----------------------------------------------------------------------------
+// 9.1 色彩角色令牌生成器（12 主题色 × 全套派生令牌的统一出口）
+// -----------------------------------------------------------------------------
+
+/// 一次性输出某个颜色名称的「全套角色令牌」。
+///
+/// 这是设计系统的核心出口：无论语义色（success/danger…）还是 12 套主题色，
+/// 都通过同一 mixin 产出完全一致的令牌面，保证全组件引用口径统一。
+///
+/// 产出令牌：
+///   --fanui-<name>            基准色（实心按钮 / 链接 / 描边）
+///   --fanui-<name>-fg         基准色上的前景色（自动取对比度更高者）
+///   --fanui-<name>-hover      悬停态（浅色压暗 / 深色提亮）
+///   --fanui-<name>-active     激活态
+///   --fanui-<name>-vivid      鲜亮色（渐变 / 光晕 / 图表 / 装饰，不保证白字对比度）
+///   --fanui-<name>-vivid-2    次级鲜亮色（渐变止点）
+///   --fanui-<name>-soft       柔和背景（浅色=50 阶，深色=低透明度）
+///   --fanui-<name>-soft-2     次级柔和背景
+///   --fanui-<name>-border     柔和描边
+///   --fanui-<name>-ink        柔和背景上的文字色
+///   --fanui-<name>-ring       焦点环
+///   --fanui-<name>-glow       外发光阴影
+///   --fanui-<name>-grad-a/b   品牌渐变端点
+///
+/// @param $name   角色名（primary / accent / success / …）
+/// @param $base   基准色（必须是对比度合规的深阶或浅阶）
+/// @param $vivid  鲜亮色，默认同 $base
+/// @param $vivid-2 次鲜亮色，默认同 $vivid
+/// @param $soft / $soft-2 / $border / $ink  可显式指定，未指定则由 $vivid 派生
+/// @param $mode   light | dark —— 决定 hover/active 的方向与默认派生策略
+@mixin fanui-emit-color-roles(
+  $name,
+  $base,
+  $vivid: null,
+  $vivid-2: null,
+  $soft: null,
+  $soft-2: null,
+  $border: null,
+  $ink: null,
+  $mode: light,
+  $prefix: "fanui"
+) {
+  @if $vivid == null   { $vivid: $base; }
+  @if $vivid-2 == null { $vivid-2: $vivid; }
+
+  @if $mode == dark {
+    @if $soft == null    { $soft: fn.fanui-alpha($vivid, 0.16); }
+    @if $soft-2 == null  { $soft-2: fn.fanui-alpha($vivid, 0.26); }
+    @if $border == null  { $border: fn.fanui-alpha($vivid, 0.38); }
+    @if $ink == null     { $ink: fn.fanui-tint($vivid, 46%); }
+  } @else {
+    @if $soft == null    { $soft: fn.fanui-alpha($vivid, 0.10); }
+    @if $soft-2 == null  { $soft-2: fn.fanui-alpha($vivid, 0.18); }
+    @if $border == null  { $border: fn.fanui-alpha($vivid, 0.30); }
+    @if $ink == null     { $ink: $base; }
+  }
+
+  --#{$prefix}-#{$name}: #{$base};
+  --#{$prefix}-#{$name}-fg: #{fn.fanui-best-fg($base)};
+  --#{$prefix}-#{$name}-hover: #{fn.fanui-state-color($base, $mode, 9%)};
+  --#{$prefix}-#{$name}-active: #{fn.fanui-state-color($base, $mode, 17%)};
+  --#{$prefix}-#{$name}-vivid: #{$vivid};
+  --#{$prefix}-#{$name}-vivid-2: #{$vivid-2};
+  --#{$prefix}-#{$name}-soft: #{$soft};
+  --#{$prefix}-#{$name}-soft-2: #{$soft-2};
+  --#{$prefix}-#{$name}-border: #{$border};
+  --#{$prefix}-#{$name}-ink: #{$ink};
+  --#{$prefix}-#{$name}-ring: #{fn.fanui-alpha($vivid, v.$fanui-focus-ring-alpha)};
+  --#{$prefix}-#{$name}-glow: #{fn.fanui-alpha($vivid, 0.42)};
+  --#{$prefix}-#{$name}-grad-a: #{$vivid};
+  --#{$prefix}-#{$name}-grad-b: #{$vivid-2};
+}
+
+/// 从调色板自动推导出「合规基准色阶」并输出全套角色令牌。
+///
+/// 自动择优规则（这是「可获得性由构造保证」的关键）：
+///   浅色模式 → 在 (600,700,800,900,500) 中选第一个「白字对比度 ≥ 4.5」的色阶
+///              （既保证实心按钮白字合规，也保证该色作为正文文字压在白底上合规）
+///   深色模式 → 在 (500,400,600,300) 中选第一个「与深色底对比度 ≥ 4.5」的色阶
+///              （保证品牌色作为文字/图标出现在深色底上依然合规）
+/// 因此 12 套主题色无需人工逐个调校，任何新增调色板都能自动得到合规主题。
+///
+/// @param $name    角色名
+/// @param $palette 11 阶调色板（50…950）
+/// @param $mode    light | dark
+@mixin fanui-emit-accent-roles($name, $palette, $mode: light, $prefix: "fanui") {
+  $candidates: (600, 700, 800, 900, 500);
+  $against: #ffffff;
+  $vivid-tone: 500;
+  $vivid-tone-2: 600;
+
+  @if $mode == dark {
+    $candidates: (500, 400, 600, 300);
+    $against: #0f172a;
+    $vivid-tone: 400;
+    $vivid-tone-2: 300;
+  }
+
+  $tone: fn.fanui-pick-tone($palette, $candidates, 4.5, $against, list.nth($candidates, 1));
+
+  $base: map.get($palette, $tone);
+  $vivid: map.get($palette, $vivid-tone);
+  $vivid-2: map.get($palette, $vivid-tone-2);
+
+  // 柔和面 / 描边 / 墨色：浅色模式取真实浅阶，深色模式取半透明（叠加玻璃与纹理更自然）
+  $soft: null;
+  $soft-2: null;
+  $border: null;
+  $ink: null;
+
+  @if $mode == dark {
+    $ink: map.get($palette, 200);
+  } @else {
+    $soft: map.get($palette, 50);
+    $soft-2: map.get($palette, 100);
+    $border: map.get($palette, 200);
+    $ink: map.get($palette, fn.fanui-pick-tone($palette, (800, 700, 900, 600), 4.5, #ffffff, 800));
+  }
+
+  @include fanui-emit-color-roles($name, $base, $vivid, $vivid-2, $soft, $soft-2, $border, $ink, $mode, $prefix);
+
+  // 原始色阶重映射，使调色板工具类（.fanui-bg-primary-100…）随主题色联动
+  @each $t, $value in $palette {
+    --#{$prefix}-#{$name}-#{$t}: #{$value};
+  }
+}
+
+// -----------------------------------------------------------------------------
+// 9.2 液态玻璃 (Liquid Glass)
+// -----------------------------------------------------------------------------
+
+/// 液态玻璃基面。
+///
+/// 所有参数均通过 CSS 自定义属性驱动，因此可以：
+///   · 全局调强度：--fanui-glass-intensity
+///   · 全局关效果：<html data-fanui-glass="off">
+///   · 单点覆盖：任意元素上写 --fanui-glass-blur-base / --fanui-glass-tint-base …
+///
+/// 分层策略（关键设计决策）：
+///   内容层 —— 永远在最上，不受影响
+///   高光层 —— 镜面光斑 + 水感渐变，作为 background-image 叠加，
+///             因此天然位于内容之下、玻璃底色之上，不会糊掉文字
+///   底色层 —— 半透明色调（受强度与明暗模式共同调制）
+///   折射层 —— backdrop-filter 一次性模糊/饱和/提亮背后的画面
+///   边缘层 —— ::after 渐变描边（mask-composite 挖空中心），模拟玻璃厚度切面
+///
+/// 注意：刻意不使用 z-index 负值伪元素承载高光 —— 那会被自身背景遮住，
+/// 是这类效果常见的失效点。
+// -----------------------------------------------------------------------------
+// 液态玻璃材质
+// -----------------------------------------------------------------------------
+// 全部公式在此内联展开，而不是引用 :root 上的合成令牌。
+// 原因：CSS 自定义属性在被继承时已在声明元素上完成 var() 替换，
+//       若写成 `--fanui-glass-bg: rgba(var(--tint-rgb), calc(base + k * var(--intensity)))`，
+//       元素上再覆盖 --fanui-glass-intensity 不会重算 → 预设/局部调参失效。
+// -----------------------------------------------------------------------------
+
+/// ① 玻璃底色：alpha = tint-base + tint-k × intensity
+@mixin fanui-glass-tint() {
+  background-color: rgba(
+    var(--fanui-glass-tint-rgb),
+    calc(var(--fanui-glass-tint-base) + var(--fanui-glass-tint-k) * var(--fanui-glass-intensity))
+  );
+}
+
+/// ② 水感高光渐变（仅 sheen，用于只需一层亮面的组件）
+@mixin fanui-glass-sheen() {
+  background-image: linear-gradient(
+    180deg,
+    rgba(255, 255, 255, calc(var(--fanui-glass-sheen-a) * var(--fanui-glass-intensity))) 0%,
+    rgba(255, 255, 255, 0) 46%
+  );
+}
+
+/// ③ 完整高光层：指针镜面光斑 + 水感渐变；$flow 追加品牌色流体层
+/// @param $flow 是否叠加品牌色流体（配合 .fanui-glass--flow 的位移动画）
+@mixin fanui-glass-layer($flow: false) {
+  @if $flow {
+    background-image:
+      radial-gradient(38% 44% at 24% 30%, var(--fanui-brand-aura-a), transparent 62%),
+      radial-gradient(32% 40% at 76% 70%, var(--fanui-brand-aura-b), transparent 60%),
+      radial-gradient(
+        calc(var(--fanui-glass-specular-size-base) + var(--fanui-glass-specular-size-k) * var(--fanui-glass-intensity))
+          circle at var(--fanui-glass-mx, 30%) var(--fanui-glass-my, 0%),
+        rgba(
+          var(--fanui-glass-specular-rgb),
+          calc(var(--fanui-glass-specular-a) * var(--fanui-glass-intensity) * var(--fanui-glass-specular-alpha))
+        ),
+        transparent 70%
+      ),
+      linear-gradient(
+        180deg,
+        rgba(255, 255, 255, calc(var(--fanui-glass-sheen-a) * var(--fanui-glass-intensity))) 0%,
+        rgba(255, 255, 255, 0) 46%
+      );
+  } @else {
+    background-image:
+      radial-gradient(
+        calc(var(--fanui-glass-specular-size-base) + var(--fanui-glass-specular-size-k) * var(--fanui-glass-intensity))
+          circle at var(--fanui-glass-mx, 30%) var(--fanui-glass-my, 0%),
+        rgba(
+          var(--fanui-glass-specular-rgb),
+          calc(var(--fanui-glass-specular-a) * var(--fanui-glass-intensity) * var(--fanui-glass-specular-alpha))
+        ),
+        transparent 70%
+      ),
+      linear-gradient(
+        180deg,
+        rgba(255, 255, 255, calc(var(--fanui-glass-sheen-a) * var(--fanui-glass-intensity))) 0%,
+        rgba(255, 255, 255, 0) 46%
+      );
+  }
+}
+
+/// ④ 折射：blur / saturate / brightness 三者同受 intensity 驱动
+@mixin fanui-glass-refraction() {
+  backdrop-filter: blur(calc(var(--fanui-glass-blur-base) * var(--fanui-glass-intensity) * var(--fanui-glass-blur-mode-k, 1)))
+    saturate(calc(100% + var(--fanui-glass-sat-k) * var(--fanui-glass-intensity)))
+    brightness(calc(100% + var(--fanui-glass-bri-k) * var(--fanui-glass-intensity)));
+  -webkit-backdrop-filter: blur(calc(var(--fanui-glass-blur-base) * var(--fanui-glass-intensity) * var(--fanui-glass-blur-mode-k, 1)))
+    saturate(calc(100% + var(--fanui-glass-sat-k) * var(--fanui-glass-intensity)))
+    brightness(calc(100% + var(--fanui-glass-bri-k) * var(--fanui-glass-intensity)));
+}
+
+/// ⑤ 描边色：alpha = border-a + border-k × intensity
+@mixin fanui-glass-border-color() {
+  border-color: rgba(
+    var(--fanui-glass-border-rgb),
+    calc(var(--fanui-glass-border-a) + var(--fanui-glass-border-k) * var(--fanui-glass-intensity))
+  );
+}
+
+/// ⑥ 厚度阴影：投影随强度变长变深 + 顶部内高光
+@mixin fanui-glass-depth() {
+  box-shadow:
+    0 calc(var(--fanui-glass-shadow-y-k) * var(--fanui-glass-intensity))
+      calc(var(--fanui-glass-shadow-blur-k) * var(--fanui-glass-intensity))
+      calc(var(--fanui-glass-shadow-spread-k) * var(--fanui-glass-intensity))
+      rgba(var(--fanui-glass-shadow-rgb), calc(var(--fanui-glass-shadow-a) + var(--fanui-glass-shadow-k) * var(--fanui-glass-intensity))),
+    inset 0 1px 0 rgba(255, 255, 255, calc(var(--fanui-glass-inner-hi) * min(1, var(--fanui-glass-intensity))));
+}
+
+/// ⑦ 材质叠加：只换「材质层」，不动布局与圆角（供既有组件复用同一套玻璃令牌）
+@mixin fanui-glass-surface($sheen: true, $shadow: true, $border: true, $refraction: true) {
+  @include fanui-glass-tint();
+
+  @if $sheen {
+    @include fanui-glass-sheen();
+  }
+
+  @if $refraction {
+    @include fanui-glass-refraction();
+  }
+
+  @if $border {
+    @include fanui-glass-border-color();
+  }
+
+  @if $shadow {
+    @include fanui-glass-depth();
+  }
+
+  @supports not ((backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))) {
+    background-color: var(--fanui-glass-fallback-bg);
+    background-image: none;
+  }
+}
+
+/// ⑧ 液态玻璃主体材质（.fanui-glass / @include fanui-liquid-glass()）
+///
+/// @param $radius    圆角（null 时取 --fanui-glass-radius，再退回 $fanui-radius-lg）
+/// @param $highlight 是否启用指针镜面高光
+/// @param $edge      是否绘制边缘流光（::after 遮罩描边）
+/// @param $flow      是否叠加品牌色流体层
+@mixin fanui-glass-material($radius: null, $highlight: true, $edge: true, $flow: false) {
+  position: relative;
+  isolation: isolate;
+
+  @if $radius != null { --fanui-glass-radius: #{$radius}; }
+
+  @include fanui-glass-tint();
+  @include fanui-glass-layer($flow);
+  background-repeat: no-repeat;
+  background-size: 100% 100%;
+  border: 1px solid rgba(
+    var(--fanui-glass-border-rgb),
+    calc(var(--fanui-glass-border-a) + var(--fanui-glass-border-k) * var(--fanui-glass-intensity))
+  );
+  border-radius: var(--fanui-glass-radius, #{v.$fanui-radius-lg});
+  color: var(--fanui-color-text);
+  @include fanui-glass-refraction();
+  @include fanui-glass-depth();
+  @include fanui-transition((background-color, box-shadow, border-color, transform), v.$fanui-duration-slow);
+
+  @if not $highlight {
+    --fanui-glass-specular-alpha: 0;
+  }
+
+  @if $edge {
+    &::after {
+      content: "";
+      position: absolute;
+      inset: 0;
+      z-index: 1;
+      border-radius: inherit;
+      pointer-events: none;
+      padding: var(--fanui-glass-edge-width, calc(1px + 0.5px * var(--fanui-glass-intensity)));
+      background: linear-gradient(
+        var(--fanui-glass-edge-angle, 150deg),
+        rgba(255, 255, 255, calc(var(--fanui-glass-edge-hi-a) * min(1, var(--fanui-glass-intensity)))) 0%,
+        rgba(255, 255, 255, calc(var(--fanui-glass-edge-lo-a) * var(--fanui-glass-intensity))) 38%,
+        rgba(255, 255, 255, calc(var(--fanui-glass-edge-lo-a) * var(--fanui-glass-intensity))) 62%,
+        rgba(255, 255, 255, calc(var(--fanui-glass-edge-hi-a) * min(1, var(--fanui-glass-intensity)))) 100%
+      );
+      -webkit-mask: linear-gradient(#000 0 0) content-box, linear-gradient(#000 0 0);
+      mask: linear-gradient(#000 0 0) content-box, linear-gradient(#000 0 0);
+      -webkit-mask-composite: xor;
+      mask-composite: exclude;
+      opacity: var(--fanui-glass-edge-alpha, 1);
+    }
+  }
+
+  // 无 backdrop-filter 支持时降级为实体表面，保证内容始终可读
+  @supports not ((backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))) {
+    background-color: var(--fanui-glass-fallback-bg);
+    background-image: none;
+  }
+}
+
+/// 兼容别名（v1 API）：@include fanui-liquid-glass(...)
+@mixin fanui-liquid-glass($radius: null, $highlight: true, $edge: true, $flow: false) {
+  @include fanui-glass-material($radius, $highlight, $edge, $flow);
+}
+
+/// 关闭液态玻璃：退回实体表面（用于强制单点关闭；全局开关走令牌覆盖）。
+@mixin fanui-glass-off() {
+  background-color: var(--fanui-glass-fallback-bg);
+  background-image: none;
+  backdrop-filter: none;
+  -webkit-backdrop-filter: none;
+  border-color: var(--fanui-color-border);
+
+  &::after {
+    display: none;
+  }
+}
+
+/// 液态玻璃上的内容可读性保护：为文字添加极轻的投影，避免透过玻璃后对比度下降。
+@mixin fanui-glass-legibility() {
+  text-shadow: var(--fanui-glass-text-shadow, 0 1px 1px rgba(0, 0, 0, 0.04));
+}
+
+/// 玻璃浮层的「可读性地板」：在玻璃底色之上再叠一层近实色的 overlay 渐变，
+/// 把浮层有效不透明度抬到 ~0.85+，保证内部次级文字（desc / hint / subtle 令牌）
+/// 在任何页面背景（亮色 hero、品牌色渐变、图片）上都满足 WCAG AA。
+/// 仅用于承载正文的玻璃浮层：modal / command / dropdown / popover。
+/// 不支持 color-mix 的浏览器会整条丢弃该声明，安全回退为普通玻璃。
+@mixin fanui-glass-readable-floor($alpha: 0.55) {
+  $a1: $alpha;
+  $a2: $alpha + 0.15;
+
+  background-image: linear-gradient(
+    color-mix(in srgb, var(--fanui-color-overlay) #{math.percentage($a1)}, transparent),
+    color-mix(in srgb, var(--fanui-color-overlay) #{math.percentage($a2)}, transparent)
+  );
+}
+
+/// 玻璃浮层内的次级文字整体上调一档（subtle → muted）：
+/// 浮层是「阅读面」，次级信息也不允许低于 AA。
+@mixin fanui-glass-readable-text() {
+  color: fn.fanui-var("color-text-muted");
+}
+
+/// 兼容旧 API：早期版本的简单毛玻璃。
+@mixin fanui-glass($bg: fn.fanui-alpha(#ffffff, 0.72), $blur: 12px, $saturate: 180%) {
+  background-color: $bg;
+  backdrop-filter: blur($blur) saturate($saturate);
+  -webkit-backdrop-filter: blur($blur) saturate($saturate);
+}
+
+/// 关键帧定义包装（便于统一命名）。
+@mixin fanui-keyframes($name) {
+  @keyframes #{$name} { @content; }
+}
+
+/// 减少动效偏好。
+@mixin fanui-motion-safe() {
+  @media (prefers-reduced-motion: reduce) { @content; }
+}