@xihan-ui/styles 1.0.0 → 2.0.0

package/css/form.css

@@ -1,3 +1,13 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 form 样式。 */
+
+/* Form 独立皮肤同时传递引入提交 / 重置钮的动作控件配方；full bundle 递归去重。 */
+@import '../family/action-control.css';
+
 @layer xihan.components {
   /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
   [data-scope='form'] {
@@ -12,16 +22,20 @@
     margin: 0;
   }
 
+  /* 网格：字段排进等宽列，各列下限写 0，一段长文本不会把自己那列撑宽。
+     列数由 data-columns 逐档给，换档只改 --xh-_form-cols 这一个槽 */
+  [data-scope='form'][data-part='root'][data-layout='grid'] {
+    display: grid;
+    grid-template-columns: repeat(var(--xh-_form-cols), minmax(0, 1fr));
+
+    --xh-_form-cols: 1;
+  }
+
   /* 只要声明了 display 就盖掉了 UA 的 [hidden]{display:none}，收起态得自己还回去 */
   [data-scope='form'][data-part='root'][hidden] {
     display: none;
   }
 
-  /* 标签左置：标签列宽的缺省档在这儿，labelWidth 会以行内样式盖过它 */
-  [data-scope='form'][data-part='root'][data-layout='horizontal'] {
-    --xh-form-label-w: 30%;
-  }
-
   /* 横排一行流：字段并肩排，放不下自动折行 */
   [data-scope='form'][data-part='root'][data-layout='inline'] {
     flex-flow: row wrap;
@@ -29,6 +43,96 @@
     column-gap: var(--xh-form-inline-gap, var(--xh-space-4));
   }
 
+  /* 一列是网格档的缺省，这里从两列起逐档写 */
+  [data-scope='form'][data-part='root'][data-columns='2'] {
+    --xh-_form-cols: 2;
+  }
+
+  [data-scope='form'][data-part='root'][data-columns='3'] {
+    --xh-_form-cols: 3;
+  }
+
+  [data-scope='form'][data-part='root'][data-columns='4'] {
+    --xh-_form-cols: 4;
+  }
+
+  /* 逐档列数：移动优先，先按 data-columns 排定，视口每宽到一档就换成那一档的列数，
+     没写的档沿用比它窄的那一档。四档自窄到宽依次写，只用 min-width：媒体查询不改选择器权重，
+     宽视口上同时命中好几档时由源码序决定谁生效。
+     宽度写字面量：自定义属性在 @media 条件里不参与求值。
+     每档都从一列写起：base 分多列、某一档收回一列同样是合法的一档 */
+  @media (min-width: 640px) {
+    [data-scope='form'][data-part='root'][data-columns-sm='1'] {
+      --xh-_form-cols: 1;
+    }
+
+    [data-scope='form'][data-part='root'][data-columns-sm='2'] {
+      --xh-_form-cols: 2;
+    }
+
+    [data-scope='form'][data-part='root'][data-columns-sm='3'] {
+      --xh-_form-cols: 3;
+    }
+
+    [data-scope='form'][data-part='root'][data-columns-sm='4'] {
+      --xh-_form-cols: 4;
+    }
+  }
+
+  @media (min-width: 768px) {
+    [data-scope='form'][data-part='root'][data-columns-md='1'] {
+      --xh-_form-cols: 1;
+    }
+
+    [data-scope='form'][data-part='root'][data-columns-md='2'] {
+      --xh-_form-cols: 2;
+    }
+
+    [data-scope='form'][data-part='root'][data-columns-md='3'] {
+      --xh-_form-cols: 3;
+    }
+
+    [data-scope='form'][data-part='root'][data-columns-md='4'] {
+      --xh-_form-cols: 4;
+    }
+  }
+
+  @media (min-width: 1024px) {
+    [data-scope='form'][data-part='root'][data-columns-lg='1'] {
+      --xh-_form-cols: 1;
+    }
+
+    [data-scope='form'][data-part='root'][data-columns-lg='2'] {
+      --xh-_form-cols: 2;
+    }
+
+    [data-scope='form'][data-part='root'][data-columns-lg='3'] {
+      --xh-_form-cols: 3;
+    }
+
+    [data-scope='form'][data-part='root'][data-columns-lg='4'] {
+      --xh-_form-cols: 4;
+    }
+  }
+
+  @media (min-width: 1280px) {
+    [data-scope='form'][data-part='root'][data-columns-xl='1'] {
+      --xh-_form-cols: 1;
+    }
+
+    [data-scope='form'][data-part='root'][data-columns-xl='2'] {
+      --xh-_form-cols: 2;
+    }
+
+    [data-scope='form'][data-part='root'][data-columns-xl='3'] {
+      --xh-_form-cols: 3;
+    }
+
+    [data-scope='form'][data-part='root'][data-columns-xl='4'] {
+      --xh-_form-cols: 4;
+    }
+  }
+
   /* 字段容器只管排版与状态标记：标题、控件、描述、错误文案都是里面那个 Field 的活儿 */
   [data-scope='form'][data-part='field-group'] {
     display: flex;
@@ -40,6 +144,29 @@
     display: none;
   }
 
+  /* 网格排布下这一格占多宽，不写就占一列 */
+  [data-scope='form'][data-part='root'][data-layout='grid'] [data-scope='form'][data-part='field-group'] {
+    grid-column: var(--xh-_form-span, auto);
+  }
+
+  /* 占一列是上面的缺省，这里从跨两列起逐档写 */
+  [data-scope='form'][data-part='field-group'][data-span='2'] {
+    --xh-_form-span: auto / span 2;
+  }
+
+  [data-scope='form'][data-part='field-group'][data-span='3'] {
+    --xh-_form-span: auto / span 3;
+  }
+
+  [data-scope='form'][data-part='field-group'][data-span='4'] {
+    --xh-_form-span: auto / span 4;
+  }
+
+  /* 占满整行：从第一条列线排到最后一条，列数换档时不必跟着改跨度 */
+  [data-scope='form'][data-part='field-group'][data-span='full'] {
+    --xh-_form-span: 1 / -1;
+  }
+
   /* 出错的字段在起始缘竖一条色带：读屏之外还得有一眼看得见的定位标记。
      用逻辑属性，RTL 下自动换到右侧 */
   [data-scope='form'][data-part='field-group'][data-invalid] {
@@ -47,13 +174,6 @@
     border-inline-start: var(--xh-stroke-thick) solid var(--xh-form-field-invalid-border, var(--xh-border-invalid));
   }
 
-  /* 容器带着 tabindex=-1：控件全禁用时焦点会落在它自己身上，
-     那一刻必须画环，否则键盘用户看不出自己被送到了哪儿 */
-  [data-scope='form'][data-part='field-group']:focus-visible {
-    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
-    outline-offset: var(--xh-ring-offset);
-  }
-
   /* 提交失败后的错误汇总。role=alert 常挂，靠 hidden 显隐 */
   [data-scope='form'][data-part='error-summary'] {
     display: flex;
@@ -67,7 +187,8 @@
     color: var(--xh-form-summary-fg, var(--xh-fg-danger));
     font-size: var(--xh-form-summary-font-size, var(--xh-text-body-size));
     line-height: var(--xh-leading-normal);
-    box-shadow: var(--xh-form-summary-shadow, var(--xh-elevation-raised));
+    /* 静态反馈面：边界由描边承担，不带落影（§8 solid 无影） */
+    box-shadow: var(--xh-form-summary-shadow, none);
   }
 
   /* 漏了这条，摘要一旦出现过就再也撤不下去（上面那条 display 盖掉了 UA 的 [hidden] 规则） */
@@ -83,17 +204,24 @@
   /* 从收起翻成显出的那一下给一小段入场：读屏靠 role=alert 播报，
      视觉这边也得有个"它是刚冒出来的"的交代，否则像一直杵在那儿 */
   [data-scope='form'][data-part='error-summary'][data-state='invalid'] {
-    animation: xh-form-summary-enter var(--xh-motion-duration-enter) var(--xh-motion-ease-enter);
+    animation: xh-form-summary-enter var(--xh-motion-duration-enter) var(--xh-motion-ease-enter-strong);
   }
 
-  /* 摘要里的每一条是一个真链接，指向对应字段容器 */
+  /* 摘要里的每一条是一个真链接，指向对应字段容器。铺满一行的集合行（§9.2）：悬停 / 按下只换面不缩放，
+     底面坐在摘要的 surface 白底上，走白底承载阶梯 100 → 200；换面走按压时间线，释放回 release 档 */
   [data-scope='form'][data-part='error-summary-item'] {
     display: block;
+    padding-inline: var(--xh-form-summary-item-px, var(--xh-space-1));
+    border-radius: var(--xh-form-summary-item-radius, var(--xh-shape-control));
+    background: var(--xh-form-summary-item-bg, transparent);
     color: inherit;
     font-size: var(--xh-form-summary-item-font-size, var(--xh-text-secondary-size));
     text-decoration: underline;
-    text-underline-offset: 2px;
+    text-underline-offset: var(--xh-form-summary-item-underline-offset, var(--xh-space-0_5));
     cursor: pointer;
+    transition:
+      background-color var(--xh-motion-duration-release) var(--xh-motion-ease-release),
+      color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
   }
 
   /* 没有对应错误的条目由连接层给 hidden；上面那条 display 已把 UA 规则盖掉 */
@@ -101,87 +229,136 @@
     display: none;
   }
 
-  [data-scope='form'][data-part='error-summary-item']:hover {
-    color: var(--xh-form-summary-item-fg-hover, var(--xh-fg-danger-hover));
+  /* 摘要显出时条目逐条入场，越靠后起步越晚。
+     backwards 让还没轮到的条目停在首帧，不是先显出再重播 */
+  [data-scope='form'][data-part='error-summary'][data-state='invalid'] [data-part='error-summary-item'] {
+    animation: xh-form-summary-enter var(--xh-motion-duration-enter) var(--xh-motion-ease-enter-strong) backwards;
   }
 
-  [data-scope='form'][data-part='error-summary-item']:focus-visible {
-    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
-    outline-offset: var(--xh-ring-offset);
+  /* 排序按"前面有几条露面的"数，不按 nth-child：作者一次把所有字段的条目都写上，
+     没出错的那些带着 hidden 留在 DOM 里，按位置数会把空号也算进去。
+     每多一节 ~ 就多要求前面多一条露面的条目，链越长的规则排得越后、赢过短链 */
+  [data-scope='form'][data-part='error-summary'][data-state='invalid']
+    [data-part='error-summary-item']:not([hidden])
+    ~ [data-part='error-summary-item']:not([hidden]) {
+    animation-delay: var(--xh-motion-stagger-step);
   }
 
-  /* 两颗按钮共用一份底子：它们是同一种东西，只是干的活不同，
-     分开写迟早会改了一颗忘了另一颗 */
-  [data-scope='form'][data-part='submit-trigger'],
-  [data-scope='form'][data-part='reset-trigger'] {
-    display: inline-flex;
-    flex: none;
-    align-items: center;
-    justify-content: center;
-    block-size: var(--xh-form-trigger-h, var(--xh-control-h-md));
-    padding-block: 0;
-    padding-inline: var(--xh-form-trigger-px, var(--xh-control-px-md));
-    border: var(--xh-stroke-thin) solid var(--xh-form-trigger-border, var(--xh-border-control));
-    border-radius: var(--xh-form-trigger-radius, var(--xh-shape-control));
-    background: var(--xh-form-trigger-bg, var(--xh-bg-subtle));
-    color: var(--xh-form-trigger-fg, var(--xh-fg-default));
-    /* 表单控件不继承页面字体，只给字号会让按钮用 UA 默认字族，与周围文本对不上 */
-    font-family: inherit;
-    font-size: var(--xh-form-trigger-font-size, var(--xh-text-body-size));
-    line-height: var(--xh-leading-none);
-    white-space: nowrap;
-    cursor: pointer;
-    user-select: none;
-    transition: background var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  [data-scope='form'][data-part='error-summary'][data-state='invalid']
+    [data-part='error-summary-item']:not([hidden])
+    ~ [data-part='error-summary-item']:not([hidden])
+    ~ [data-part='error-summary-item']:not([hidden]) {
+    animation-delay: calc(var(--xh-motion-stagger-step) * 2);
   }
 
-  [data-scope='form'][data-part='submit-trigger'][hidden],
-  [data-scope='form'][data-part='reset-trigger'][hidden] {
-    display: none;
+  [data-scope='form'][data-part='error-summary'][data-state='invalid']
+    [data-part='error-summary-item']:not([hidden])
+    ~ [data-part='error-summary-item']:not([hidden])
+    ~ [data-part='error-summary-item']:not([hidden])
+    ~ [data-part='error-summary-item']:not([hidden]) {
+    animation-delay: calc(var(--xh-motion-stagger-step) * 3);
   }
 
-  [data-scope='form'][data-part='submit-trigger']:hover:not(:disabled),
-  [data-scope='form'][data-part='reset-trigger']:hover:not(:disabled) {
-    border-color: var(--xh-form-trigger-border-hover, var(--xh-border-control-hover));
-    background: var(--xh-form-trigger-bg-hover, var(--xh-bg-subtle-hover));
+  [data-scope='form'][data-part='error-summary'][data-state='invalid']
+    [data-part='error-summary-item']:not([hidden])
+    ~ [data-part='error-summary-item']:not([hidden])
+    ~ [data-part='error-summary-item']:not([hidden])
+    ~ [data-part='error-summary-item']:not([hidden])
+    ~ [data-part='error-summary-item']:not([hidden]) {
+    animation-delay: calc(var(--xh-motion-stagger-step) * 4);
   }
 
-  [data-scope='form'][data-part='submit-trigger']:active:not(:disabled),
-  [data-scope='form'][data-part='reset-trigger']:active:not(:disabled) {
-    background: var(--xh-form-trigger-bg-active, var(--xh-bg-subtle-active));
+  /* 第 6 条起共用同一档延迟：这条要求前面有五条露面的，第七条往后同样命中，
+     错误多时整批的等待时间不再随条数增长 */
+  [data-scope='form'][data-part='error-summary'][data-state='invalid']
+    [data-part='error-summary-item']:not([hidden])
+    ~ [data-part='error-summary-item']:not([hidden])
+    ~ [data-part='error-summary-item']:not([hidden])
+    ~ [data-part='error-summary-item']:not([hidden])
+    ~ [data-part='error-summary-item']:not([hidden])
+    ~ [data-part='error-summary-item']:not([hidden]) {
+    animation-delay: calc(var(--xh-motion-stagger-step) * 5);
   }
 
-  [data-scope='form'][data-part='submit-trigger']:focus-visible,
-  [data-scope='form'][data-part='reset-trigger']:focus-visible {
-    outline: var(--xh-ring-width) solid var(--xh-ring-focus);
-    outline-offset: var(--xh-ring-offset);
+  [data-scope='form'][data-part='error-summary-item']:hover {
+    background: var(--xh-form-summary-item-bg-hover, var(--xh-bg-subtle));
+    color: var(--xh-form-summary-item-fg-hover, var(--xh-fg-danger-hover));
   }
 
-  /* 单体控件用 :disabled（集合条目才用 [data-disabled]）：
-     整表禁用时提交键置灰，只读时重置键也一并落到这条上 */
-  [data-scope='form'][data-part='submit-trigger']:disabled,
-  [data-scope='form'][data-part='reset-trigger']:disabled {
-    border-color: var(--xh-form-trigger-border-disabled, var(--xh-border-subtle));
-    background: var(--xh-form-trigger-bg-disabled, var(--xh-bg-muted));
-    color: var(--xh-fg-disabled);
-    cursor: not-allowed;
+  /* 指针 :active 与 Headless 投影的 data-pressed（Space / Enter 与触屏按住）看见同一副按压面 */
+  [data-scope='form'][data-part='error-summary-item']:is(:active, [data-pressed]) {
+    background: var(--xh-form-summary-item-bg-pressed, var(--xh-bg-subtle-hover));
+    color: var(--xh-form-summary-item-fg-hover, var(--xh-fg-danger-hover));
+    transition-duration: var(--xh-motion-duration-press);
+    transition-timing-function: var(--xh-motion-ease-press);
   }
 
-  /* 提交是这一组里的主操作，给它一层实心底色区分开 */
-  [data-scope='form'][data-part='submit-trigger']:not(:disabled) {
-    border-color: var(--xh-form-submit-border, var(--xh-form-submit-bg, var(--xh-bg-brand)));
-    background: var(--xh-form-submit-bg, var(--xh-bg-brand));
-    color: var(--xh-form-submit-fg, var(--xh-fg-on-brand));
+  /* 高对比档里底色被系统换掉，按下那一档用系统高亮反色画回 */
+  @media (forced-colors: active) {
+    [data-scope='form'][data-part='error-summary-item']:is(:active, [data-pressed]) {
+      background: Highlight;
+      color: HighlightText;
+    }
   }
 
-  [data-scope='form'][data-part='submit-trigger']:hover:not(:disabled) {
-    border-color: var(--xh-form-submit-border-hover, var(--xh-form-submit-bg-hover, var(--xh-bg-brand-hover)));
-    background: var(--xh-form-submit-bg-hover, var(--xh-bg-brand-hover));
+  /* 两颗按钮是离散动作控件：盒几何、悬停 / 按下与 0.97 按压、焦点环、禁用面全由 Action Control 的 text 档给，
+     组件只映射既有使用者槽。提交走 solid 档：表单提交是这一组里的主要动作，与 Button 缺省同为品牌实心；
+     重置走 outline 档：非 Button 的触发器缺省中性描边（§7.2.2）。两颗共用的几何与字号写在一起 */
+  [data-scope='form'][data-part='submit-trigger'],
+  [data-scope='form'][data-part='reset-trigger'] {
+    --xh-action-visual-size: var(--xh-form-trigger-h, var(--xh-_action-profile-visual-size));
+    --xh-action-padding-inline: var(--xh-form-trigger-px, var(--xh-_action-profile-padding-inline));
+    --xh-action-radius: var(--xh-form-trigger-radius, var(--xh-shape-control));
+    --xh-action-font-size: var(--xh-form-trigger-font-size, var(--xh-text-body-size));
+
+    /* 按钮不参与弹性伸缩 */
+    flex: none;
+  }
+
+  /* 家族那条 display 会把 UA 的 [hidden]{display:none} 盖掉 */
+  [data-scope='form'][data-part='submit-trigger'][hidden],
+  [data-scope='form'][data-part='reset-trigger'][hidden] {
+    display: none;
+  }
+
+  /* 重置钮：中性描边，底 / 边 / 字与禁用面映到 outline 档的桥接槽（透明底 → 100 → 200） */
+  [data-scope='form'][data-part='reset-trigger'] {
+    --xh-action-bg-rest: var(--xh-form-trigger-bg, var(--xh-_action-variant-bg-rest));
+    --xh-action-bg-hover: var(--xh-form-trigger-bg-hover, var(--xh-_action-variant-bg-hover));
+    --xh-action-bg-pressed: var(--xh-form-trigger-bg-active, var(--xh-_action-variant-bg-pressed));
+    --xh-action-bg-disabled: var(--xh-form-trigger-bg-disabled, var(--xh-_action-variant-bg-disabled));
+    --xh-action-fg-rest: var(--xh-form-trigger-fg, var(--xh-_action-variant-fg-rest));
+    --xh-action-fg-hover: var(--xh-form-trigger-fg, var(--xh-_action-variant-fg-hover));
+    --xh-action-fg-pressed: var(--xh-form-trigger-fg, var(--xh-_action-variant-fg-pressed));
+    --xh-action-border-rest: var(--xh-form-trigger-border, var(--xh-_action-variant-border-rest));
+    --xh-action-border-hover: var(--xh-form-trigger-border-hover, var(--xh-_action-variant-border-hover));
+    --xh-action-border-disabled: var(--xh-form-trigger-border-disabled, var(--xh-_action-variant-border-disabled));
+    --xh-action-highlight-rest: transparent;
+    --xh-action-shadow-rest: none;
+    --xh-action-shadow-hover: none;
+    --xh-action-shadow-pressed: none;
   }
 
-  [data-scope='form'][data-part='submit-trigger']:active:not(:disabled) {
-    border-color: var(--xh-form-submit-border-active, var(--xh-form-submit-bg-active, var(--xh-bg-brand-active)));
-    background: var(--xh-form-submit-bg-active, var(--xh-bg-brand-active));
+  /* 提交钮：品牌实心，顶边一条极浅的内高光把这块面衬出厚度（三态同一支，禁用面由家族收掉）。
+     面是实心的，环色与面同族，画在面里就看不出来；环改取面自己的前景色——
+     那一族色本来就要在这块面上把字读清楚，与面的对比是按可读性定的 */
+  [data-scope='form'][data-part='submit-trigger'] {
+    --xh-action-bg-rest: var(--xh-form-submit-bg, var(--xh-_action-variant-bg-rest));
+    --xh-action-bg-hover: var(--xh-form-submit-bg-hover, var(--xh-_action-variant-bg-hover));
+    --xh-action-bg-pressed: var(--xh-form-submit-bg-active, var(--xh-_action-variant-bg-pressed));
+    --xh-action-bg-disabled: var(--xh-form-trigger-bg-disabled, var(--xh-_action-variant-bg-disabled));
+    --xh-action-fg-rest: var(--xh-form-submit-fg, var(--xh-_action-variant-fg-rest));
+    --xh-action-fg-hover: var(--xh-form-submit-fg, var(--xh-_action-variant-fg-hover));
+    --xh-action-fg-pressed: var(--xh-form-submit-fg, var(--xh-_action-variant-fg-pressed));
+    --xh-action-border-rest: var(--xh-form-submit-border, var(--xh-_action-variant-border-rest));
+    --xh-action-border-hover: var(--xh-form-submit-border-hover, var(--xh-_action-variant-border-hover));
+    --xh-action-border-pressed: var(--xh-form-submit-border-active, var(--xh-_action-variant-border-pressed));
+    --xh-action-border-disabled: var(--xh-form-trigger-border-disabled, var(--xh-_action-variant-border-disabled));
+    --xh-action-highlight-rest: transparent;
+    --xh-action-shadow-rest: var(--xh-form-submit-shadow, var(--xh-_highlight-brand));
+    --xh-action-shadow-hover: var(--xh-form-submit-shadow, var(--xh-_highlight-brand));
+    --xh-action-shadow-pressed: var(--xh-form-submit-shadow, var(--xh-_highlight-brand));
+    --xh-action-ring-color-focus-visible: currentColor;
   }
 }
 

package/css/gradient-text.css

@@ -1,4 +1,21 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 gradient text 样式。 */
+
 @layer xihan.components {
+  /* 轴边界只路由简单前景值，渐变本身仍在组件根用本地 direction/from/to 计算。
+     这样内层 default/more 能双向重置，也不会把未解析的组件变量冻结在祖先上。 */
+  :where(:root, [data-contrast='default']) {
+    --xh-_gradient-text-fg: transparent;
+  }
+
+  :where([data-contrast='more']) {
+    --xh-_gradient-text-fg: var(--xh-fg-default);
+  }
+
   /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
   [data-scope='gradient-text'] {
     --xh-gradient-text-skin: 1;
@@ -10,24 +27,23 @@
   [data-scope='gradient-text'][data-part='root'] {
     /* 走向由 data-direction 换掉这一个槽，背景那条声明只写一遍 */
     --xh-_gradient-text-dir: to right;
+    /* 两端颜色各收一个私有槽：语气档换的是这两支，使用者槽仍排在它们前面 */
+    --xh-_gradient-text-from: var(--xh-gradient-brand-from);
+    --xh-_gradient-text-to: var(--xh-gradient-brand-to);
 
     background-image: linear-gradient(
       var(--xh-_gradient-text-dir),
-      var(--xh-gradient-text-from, var(--xh-color-brand-500)),
-      var(--xh-gradient-text-to, var(--xh-color-brand-700))
+      var(--xh-gradient-text-from, var(--xh-_gradient-text-from)),
+      var(--xh-gradient-text-to, var(--xh-_gradient-text-to))
     );
     -webkit-background-clip: text;
     background-clip: text;
-    color: transparent;
-    -webkit-text-fill-color: transparent;
+    color: var(--xh-_gradient-text-fg);
+    -webkit-text-fill-color: currentColor;
   }
 
   /* —— 走向 —— */
   /* 逐档换算成 CSS 的 to <边或角>，四条边加四个角 */
-  [data-scope='gradient-text'][data-part='root'][data-direction='to-right'] {
-    --xh-_gradient-text-dir: to right;
-  }
-
   [data-scope='gradient-text'][data-part='root'][data-direction='to-left'] {
     --xh-_gradient-text-dir: to left;
   }
@@ -56,8 +72,16 @@
     --xh-_gradient-text-dir: to top left;
   }
 
-  /* 强制色模式下系统会禁掉背景图，留着透明前景整段字就彻底看不见了，这里把填充色还回去 */
-  @media (forced-colors: active) {
+  /* —— 语气 —— */
+  /* 两端取该族主色与它压深一档的取值，深浅两态自动跟随。
+     排在使用者槽之后：作者写了 from / to，六族语气一并让位 */
+  [data-scope='gradient-text'][data-part='root'][data-tone] {
+    --xh-_gradient-text-from: var(--xh-_tone);
+    --xh-_gradient-text-to: var(--xh-_tone-active);
+  }
+
+  /* 无 JS 时的系统高对比、强制色与打印统一退回单色；显式局部轴由上面的最近作用域标记负责。 */
+  @media (prefers-contrast: more), (forced-colors: active), print {
     [data-scope='gradient-text'][data-part='root'] {
       background-image: none;
       color: inherit;