@xihan-ui/styles 3.1.0 → 4.0.0

package/dist/css/marquee.css

@@ -0,0 +1,378 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 marquee 样式。 */
+
+/* 暂停开关走动作控件配方；独立皮肤同时传递引入，full bundle 递归去重。 */
+@import '../family/action-control.css';
+
+@layer xihan.motion {
+  /*
+   * 横轴一条、纵轴一条。四个方向乘两种铺法共八组起止点，若不外提就要写八份几乎一样的关键帧。
+   * 关键帧里的自定义属性取元素上的计算值，一圈跑下来它不变，所以两条就够。
+   */
+  @keyframes xh-marquee-x {
+    from {
+      transform: translateX(var(--xh-_marquee-from));
+    }
+
+    to {
+      transform: translateX(var(--xh-_marquee-to));
+    }
+  }
+
+  @keyframes xh-marquee-y {
+    from {
+      transform: translateY(var(--xh-_marquee-from));
+    }
+
+    to {
+      transform: translateY(var(--xh-_marquee-to));
+    }
+  }
+}
+
+@layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  .xh-scope-marquee {
+    --xh-marquee-skin: 1;
+  }
+
+  /*
+   * 窗口：只露出轨道的一段。
+   *
+   * 方向、轴与铺法全部换成根上的私有槽，轨道与每一份内容各自只有一条规则去取值。
+   * 这样写不只是为了短：轨道那条选择器因此能写成 [data-scope][data-part] 的复合式，
+   * 而不是从根往下够的后代式——marquee 里嵌一个同样有 content 部件的组件时，
+   * 后代式会一路匹配到别人家的节点上去。
+   *
+   * 一圈的时长 = 一份内容的长度 ÷ 每秒像素数。--xh-_marquee-span 是一份内容在滚动轴上的长度，
+   * 单位像素、写成纯数字：连接层挂载后实测、写成内联的 --xh-_marquee-measured-span，量到之前
+   * （无布局宿主、首帧）退回缺省值。使用者写了 --xh-marquee-span 以它为准。
+   */
+  .xh-scope-marquee[data-part='root'] {
+    /* 暂停开关的边长：开关用它定尺，两端渐隐按它给开关留出位置，两处同源 */
+    --xh-_marquee-trigger-size: var(--xh-control-h-md);
+    --xh-_marquee-span: var(--xh-marquee-span, var(--xh-_marquee-measured-span, 600));
+    --xh-_marquee-speed: var(--xh-marquee-speed, 60);
+
+    /* 铺一份时一圈走两倍自身长度：从窗口一侧整段进来，再整段出到另一侧 */
+    --xh-_marquee-duration: calc(2 * var(--xh-_marquee-span) / var(--xh-_marquee-speed) * 1s);
+    --xh-_marquee-play: running;
+    --xh-_marquee-flow: row;
+    --xh-_marquee-name: xh-marquee-x;
+    --xh-_marquee-track-inline: max-content;
+    --xh-_marquee-track-block: auto;
+
+    /* 轨道自身至少铺满窗口，起点那一跳才真的落在窗口外面 */
+    --xh-_marquee-fill-inline: 100%;
+    --xh-_marquee-fill-block: auto;
+    --xh-_marquee-copy-inline: auto;
+    --xh-_marquee-copy-block: auto;
+    --xh-_marquee-gap-inline: var(--xh-marquee-gap, var(--xh-space-6));
+    --xh-_marquee-gap-block: 0;
+    --xh-_marquee-from: 100%;
+    --xh-_marquee-to: -100%;
+
+    /* 暂停开关压在窗口一端，定位基准是窗口；isolation 把开关的层号关在本组件内，不参与页面级层序 */
+    position: relative;
+    isolation: isolate;
+    display: flex;
+    overflow: hidden;
+    max-inline-size: 100%;
+  }
+
+  /* 声明了 display 就盖掉了 UA 的 [hidden]{display:none}，补这条兜住收起态 */
+  .xh-scope-marquee[data-part='root'][hidden] {
+    display: none;
+  }
+
+  /* 竖着滚要有一个定高的窗口，否则内容自己把窗口撑到一样高，一格都走不动 */
+  .xh-scope-marquee[data-part='root'][data-orientation='vertical'] {
+    --xh-_marquee-flow: column;
+    --xh-_marquee-name: xh-marquee-y;
+    --xh-_marquee-track-inline: auto;
+    --xh-_marquee-track-block: max-content;
+    --xh-_marquee-fill-inline: auto;
+    --xh-_marquee-fill-block: 100%;
+    --xh-_marquee-gap-inline: 0;
+    --xh-_marquee-gap-block: var(--xh-marquee-gap, var(--xh-space-6));
+
+    block-size: var(--xh-marquee-block-size, 10rem);
+  }
+
+  /* 往右、往下是同一条轨迹倒过来走 */
+  .xh-scope-marquee[data-part='root'][data-direction='right'],
+  .xh-scope-marquee[data-part='root'][data-direction='down'] {
+    --xh-_marquee-from: -100%;
+    --xh-_marquee-to: 100%;
+  }
+
+  /*
+   * 铺两份：一圈只走一份的长度，走完那一刻第二份正好压在起点上，看不出接缝。
+   * 这条排在竖轴那条之后：两者同权，铺两份时轨道自己不必铺满窗口，改由每一份各自铺满。
+   */
+  .xh-scope-marquee[data-part='root'][data-auto-fill] {
+    --xh-_marquee-duration: calc(var(--xh-_marquee-span) / var(--xh-_marquee-speed) * 1s);
+    --xh-_marquee-fill-inline: auto;
+    --xh-_marquee-fill-block: auto;
+  }
+
+  /* 内容短于窗口时每份自己先铺满一整窗，两份接起来才不会在接缝处露出空白 */
+  .xh-scope-marquee[data-part='root'][data-auto-fill][data-orientation='horizontal'] {
+    --xh-_marquee-copy-inline: 100%;
+  }
+
+  .xh-scope-marquee[data-part='root'][data-auto-fill][data-orientation='vertical'] {
+    --xh-_marquee-copy-block: 100%;
+  }
+
+  /* 起止点逐档写全：铺法与方向同权，交叉的四种情形各写一条才不看书写顺序 */
+  .xh-scope-marquee[data-part='root'][data-auto-fill][data-direction='left'],
+  .xh-scope-marquee[data-part='root'][data-auto-fill][data-direction='up'] {
+    --xh-_marquee-from: 0%;
+    --xh-_marquee-to: -50%;
+  }
+
+  .xh-scope-marquee[data-part='root'][data-auto-fill][data-direction='right'],
+  .xh-scope-marquee[data-part='root'][data-auto-fill][data-direction='down'] {
+    --xh-_marquee-from: -50%;
+    --xh-_marquee-to: 0%;
+  }
+
+  /*
+   * 两端渐隐：窗口沿滚动方向两端各留一段遮罩，内容从一端淡入、从另一端淡出。
+   * 遮罩只画在窗口上，轨道照常整段移动；遮罩是静态的，不参与动画。
+   * 遮罩的几层取值都经私有槽下发，真正写 mask 的只有这一条：减弱动效与打印只需在同一特指度上盖掉它。
+   */
+  .xh-scope-marquee[data-part='root'][data-fade] {
+    --xh-_marquee-fade-size: var(--xh-marquee-fade-size, var(--xh-space-6));
+    /* 横排沿行内方向：角度乘方向符号，rtl 下行首在右，两端各自仍是淡入与淡出 */
+    --xh-_marquee-fade-dir: calc(90deg * var(--xh-direction-sign));
+    /* 行尾那一段收到哪里为止：没有暂停开关时收到窗口尽头 */
+    --xh-_marquee-fade-reserve: 0px;
+    --xh-_marquee-fade-reserve-size: 0 0;
+    --xh-_marquee-fade-reserve-at: var(--xh-direction-end) center;
+    /* 两层：沿滚动方向的 alpha 坡道，与给暂停开关留出的实心块；两种写法共用这一份 */
+    --xh-_marquee-fade-mask:
+      linear-gradient(var(--xh-_marquee-fade-dir), transparent 0, black var(--xh-_marquee-fade-size), black calc(100% - var(--xh-_marquee-fade-reserve) - var(--xh-_marquee-fade-size)), transparent calc(100% - var(--xh-_marquee-fade-reserve))),
+      linear-gradient(black, black);
+
+    -webkit-mask-image: var(--xh-_marquee-fade-mask);
+    mask-image: var(--xh-_marquee-fade-mask);
+    -webkit-mask-size: 100% 100%, var(--xh-_marquee-fade-reserve-size);
+    mask-size: 100% 100%, var(--xh-_marquee-fade-reserve-size);
+    -webkit-mask-position: 0 0, var(--xh-_marquee-fade-reserve-at);
+    mask-position: 0 0, var(--xh-_marquee-fade-reserve-at);
+    -webkit-mask-repeat: no-repeat;
+    mask-repeat: no-repeat;
+  }
+
+  .xh-scope-marquee[data-part='root'][data-fade][data-orientation='vertical'] {
+    --xh-_marquee-fade-dir: to bottom;
+  }
+
+  /*
+   * 暂停开关压在行尾一端：行尾那段渐隐收到开关之前，第二层实心遮罩把开关所在那一块整块露出来，
+   * 开关不被淡掉，开关与淡出段之间也不留一条没淡的缝。竖排时开关在块末那一角，露出的是那一角的方块。
+   */
+  .xh-scope-marquee[data-part='root'][data-fade]:has(> .xh-scope-marquee[data-part='autoplay-trigger']:not([hidden])) {
+    --xh-_marquee-fade-reserve: calc(var(--xh-marquee-trigger-inset, var(--xh-space-1)) + var(--xh-_marquee-trigger-size));
+    --xh-_marquee-fade-reserve-size: var(--xh-_marquee-fade-reserve) 100%;
+  }
+
+  .xh-scope-marquee[data-part='root'][data-fade][data-orientation='vertical']:has(> .xh-scope-marquee[data-part='autoplay-trigger']:not([hidden])) {
+    --xh-_marquee-fade-reserve-size: var(--xh-_marquee-fade-reserve) var(--xh-_marquee-fade-reserve);
+    --xh-_marquee-fade-reserve-at: var(--xh-direction-end) bottom;
+  }
+
+  /*
+   * 悬停暂停：只在能用指针的设备上生效，触摸端不留一个按不掉的悬停态。
+   * 指针停在暂停开关上不算：那里显示的是开关自己的状态，按下「继续」时指针还在开关上，
+   * 若照样算悬停，轨道要等指针挪开才动，这一下按了像没按。
+   */
+  @media (hover: hover) {
+    .xh-scope-marquee[data-part='root'][data-pause-on-hover]:hover:not(:has(> .xh-scope-marquee[data-part='autoplay-trigger']:hover)) {
+      --xh-_marquee-play: paused;
+    }
+  }
+
+  /* 键盘用户没有悬停：焦点落进窗口时同样停住，否则轨道里的链接刚聚焦就被带走了；焦点在暂停开关上同理不算 */
+  .xh-scope-marquee[data-part='root'][data-pause-on-hover]:focus-within:not(:has(> .xh-scope-marquee[data-part='autoplay-trigger']:focus)) {
+    --xh-_marquee-play: paused;
+  }
+
+  /* 受控暂停：作者说了停就停，排在悬停两条之后，指针离开也不会把它带回去走 */
+  .xh-scope-marquee[data-part='root'][data-paused] {
+    --xh-_marquee-play: paused;
+  }
+
+  /*
+   * 暂停开关：压在窗口行尾一端、上下居中；竖排时落在块末那一角。
+   * 窗口是裁切内容的单行，开关放进去会被轨道挤出视野，只能浮在上面。
+   * 盒型、描边、字色与 0.97 按压由动作控件配方按 icon 档的描边档给出；描边档静息不填底，
+   * 这里把底换成不透明的面，悬停 / 按下走同一承载面的不透明阶梯，后面走过的内容才透不上来。
+   */
+  .xh-scope-marquee[data-part='autoplay-trigger'] {
+    --xh-action-bg-rest: var(--xh-marquee-trigger-bg, var(--xh-bg-surface));
+    --xh-action-bg-hover: var(--xh-marquee-trigger-bg-hover, var(--xh-bg-subtle-opaque));
+    --xh-action-bg-pressed: var(--xh-marquee-trigger-bg-active, var(--xh-bg-subtle-hover-opaque));
+    --xh-action-bg-focus-visible: var(--xh-marquee-trigger-bg, var(--xh-bg-surface));
+    /* 作者塞进来的图标跟着 icon 档走，与皮肤画的兜底字形同一把尺 */
+    --xh-icon-size: var(--xh-marquee-icon-size, var(--xh-_action-profile-glyph-size));
+    /* 边长与两端渐隐给开关留的位置同源，都读根上那一支 */
+    --xh-action-visual-size: var(--xh-_marquee-trigger-size);
+
+    position: absolute;
+    z-index: 1;
+    inset-block: 0;
+    inset-inline-end: var(--xh-marquee-trigger-inset, var(--xh-space-1));
+    margin-block: auto;
+  }
+
+  .xh-scope-marquee[data-part='root'][data-orientation='vertical'] > .xh-scope-marquee[data-part='autoplay-trigger'] {
+    inset-block-start: auto;
+    inset-block-end: var(--xh-marquee-trigger-inset, var(--xh-space-1));
+    margin-block: 0;
+  }
+
+  .xh-scope-marquee[data-part='autoplay-trigger'][hidden] {
+    display: none;
+  }
+
+  /* 不给内容时画图标：在走画暂停，停住画播放；图标随动作，与可及名同一口径 */
+  .xh-scope-marquee[data-part='autoplay-trigger']:empty::before {
+    content: '';
+    display: inline-block;
+    inline-size: var(--xh-icon-size, var(--xh-glyph-size-md));
+    block-size: var(--xh-icon-size, var(--xh-glyph-size-md));
+    vertical-align: var(--xh-glyph-baseline-shift);
+    background-color: currentColor;
+    -webkit-mask: var(--xh-glyph-mark-pause) center / contain no-repeat;
+    mask: var(--xh-glyph-mark-pause) center / contain no-repeat;
+  }
+
+  .xh-scope-marquee[data-part='autoplay-trigger'][data-state='paused']:empty::before {
+    -webkit-mask-image: var(--xh-glyph-mark-play);
+    mask-image: var(--xh-glyph-mark-play);
+  }
+
+  /* 轨道：走的是这一层，一圈走完立刻回到起点接着走 */
+  .xh-scope-marquee[data-part='content'] {
+    display: flex;
+    flex: none;
+    flex-direction: var(--xh-_marquee-flow);
+    inline-size: var(--xh-_marquee-track-inline);
+    min-inline-size: var(--xh-_marquee-fill-inline);
+    block-size: var(--xh-_marquee-track-block);
+    min-block-size: var(--xh-_marquee-fill-block);
+    animation-name: var(--xh-_marquee-name);
+    animation-duration: var(--xh-_marquee-duration);
+    animation-timing-function: var(--xh-motion-ease-loop);
+    animation-iteration-count: infinite;
+    animation-play-state: var(--xh-_marquee-play);
+  }
+
+  /*
+   * 一份内容。份与份之间的空白做成每份自己的收尾内边距，而不是轨道上的 gap：
+   * gap 只加在中间那一道，两份就不等长了，而接缝对不对得上看的正是"走完的距离等于一份的长度"。
+   */
+  .xh-scope-marquee[data-part='content'] > [data-xh-copy] {
+    display: flex;
+    flex: none;
+    flex-direction: var(--xh-_marquee-flow);
+    align-items: center;
+    min-inline-size: var(--xh-_marquee-copy-inline);
+    min-block-size: var(--xh-_marquee-copy-block);
+    padding-inline-end: var(--xh-_marquee-gap-inline);
+    padding-block-end: var(--xh-_marquee-gap-block);
+  }
+
+  /*
+   * 减少动效：轨道停在起点不再走。一段自己动起来、不停到底的横移正是最容易引发不适的那一类，
+   * 这里不能只把速度压到很慢——慢速横移仍然是横移。
+   * 停下后窗口外那段就够不着了，故窗口同时改成可滚，内容仍然读得全。
+   * 两组规则是同一件事的两个触发条件：系统偏好与作者打的 data-motion。
+   */
+  @media (prefers-reduced-motion: reduce) {
+    .xh-scope-marquee[data-part='content'] {
+      animation: none;
+    }
+
+    .xh-scope-marquee[data-part='root'] {
+      overflow: auto;
+    }
+
+    /* 停下后窗口改成可滚：两端再淡就把可滚内容的首尾藏起来了 */
+    .xh-scope-marquee[data-part='root'][data-fade] {
+      -webkit-mask-image: none;
+      mask-image: none;
+    }
+
+    /* 轨道已经停在起点：没有可停的东西，开关只会挡住可滚的内容 */
+    .xh-scope-marquee[data-part='autoplay-trigger'] {
+      display: none;
+    }
+  }
+
+  :where([data-motion='reduce']) .xh-scope-marquee[data-part='content'] {
+    animation: none;
+  }
+
+  :where([data-motion='reduce']) .xh-scope-marquee[data-part='root'] {
+    overflow: auto;
+  }
+
+  :where([data-motion='reduce']) .xh-scope-marquee[data-part='root'][data-fade] {
+    -webkit-mask-image: none;
+    mask-image: none;
+  }
+
+  :where([data-motion='reduce']) .xh-scope-marquee[data-part='autoplay-trigger'] {
+    display: none;
+  }
+
+  @media print {
+    /* 打印：动画会被定格在任意一帧——转了一半的圈、扫到一半的微光。这里换成静止的表达，
+       取值与减弱动效那一档相同。两档各写一块、不并进一条媒体查询列表：减弱动效另有一份
+       :where([data-motion='reduce']) 的钩子版本与它成对，打印没有对应的钩子可配，
+       并成一条之后这层配对关系在文本上就断了。 */
+    .xh-scope-marquee[data-part='content'] {
+      animation: none;
+    }
+
+    .xh-scope-marquee[data-part='root'] {
+      overflow: auto;
+    }
+
+    .xh-scope-marquee[data-part='root'][data-fade] {
+      -webkit-mask-image: none;
+      mask-image: none;
+    }
+
+    .xh-scope-marquee[data-part='autoplay-trigger'] {
+      display: none;
+    }
+  }
+
+  @media (forced-colors: active) {
+    /* 兜底字形是 mask 挖出来的一块底色，这一档里底色被系统换成 Canvas，字形跟着消失。
+       字形退出强制换色、直接写系统色（不能取 currentColor：退出强制换色的伪元素读到的是被系统换掉之前的作者色）：
+       按钮面上取 ButtonText，悬停与按下时家族把按钮涂成 Highlight、字形换 HighlightText；
+       禁用取 GrayText */
+    .xh-scope-marquee[data-part='autoplay-trigger']:empty::before {
+      forced-color-adjust: none;
+      background-color: ButtonText;
+    }
+
+    .xh-scope-marquee[data-part='autoplay-trigger']:not([data-disabled]):not([data-loading]):is(:hover, :active, [data-pressed]):empty::before {
+      background-color: HighlightText;
+    }
+
+    .xh-scope-marquee[data-part='autoplay-trigger'][data-disabled]:empty::before {
+      background-color: GrayText;
+    }
+  }
+}

package/dist/css/masonry.css

@@ -0,0 +1,70 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 masonry 样式。 */
+
+@layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  .xh-scope-masonry {
+    --xh-masonry-skin: 1;
+  }
+
+  .xh-scope-masonry[data-part='root'] {
+    display: flex;
+    /* 各列按自己的内容收高，不被最高的那列拉平——列不等高正是瀑布流的样子 */
+    align-items: flex-start;
+    gap: var(--xh-_masonry-gap);
+
+    /* 列间距与列内的项间距共用这一份取值，声明在根上、由列继承下去；
+       不写 gap 档位就不留间距。使用者槽位排在档位之前，写死一个值即盖过所有档 */
+    --xh-_masonry-gap: var(--xh-masonry-gap, var(--xh-space-0));
+  }
+
+  /* 声明了 display 就盖掉了 UA 的 [hidden] 规则，这里还回去 */
+  .xh-scope-masonry[data-part='root'][hidden] {
+    display: none;
+  }
+
+  .xh-scope-masonry[data-part='column'] {
+    display: flex;
+    flex-direction: column;
+    /* 各列等宽；下限写 0 而不是 auto，一段长内容才不会把自己那列撑宽 */
+    flex: 1 1 0;
+    min-inline-size: 0;
+    gap: var(--xh-_masonry-gap);
+  }
+
+  /* 当前档位用不上的那几列由适配器收起；这条兜住作者自己写 hidden 的情形 */
+  .xh-scope-masonry[data-part='column'][hidden] {
+    display: none;
+  }
+
+  /* 项不发话，高度由内容定；只兜住一件事——不被列的弹性压缩，压缩了量到的高度就不是它真实的高度 */
+  .xh-scope-masonry[data-part='item'] {
+    flex: none;
+  }
+
+  /* —— 间距档位 —— */
+  /* 每一档指向一个间距令牌，列之间与列内项之间吃同一份间距 */
+  .xh-scope-masonry[data-part='root'][data-gap='xs'] {
+    --xh-_masonry-gap: var(--xh-masonry-gap, var(--xh-layout-gap-xs));
+  }
+
+  .xh-scope-masonry[data-part='root'][data-gap='sm'] {
+    --xh-_masonry-gap: var(--xh-masonry-gap, var(--xh-layout-gap-sm));
+  }
+
+  .xh-scope-masonry[data-part='root'][data-gap='md'] {
+    --xh-_masonry-gap: var(--xh-masonry-gap, var(--xh-layout-gap-md));
+  }
+
+  .xh-scope-masonry[data-part='root'][data-gap='lg'] {
+    --xh-_masonry-gap: var(--xh-masonry-gap, var(--xh-layout-gap-lg));
+  }
+
+  .xh-scope-masonry[data-part='root'][data-gap='xl'] {
+    --xh-_masonry-gap: var(--xh-masonry-gap, var(--xh-layout-gap-xl));
+  }
+}

package/dist/css/matrix-code.css

@@ -0,0 +1,67 @@
+/*
+ * Copyright (c) 2021-Present XiHanFun and contributors.
+ * Licensed under the MIT License. See LICENSE in the project root for license information.
+ */
+
+/* 定义 matrix code 样式。 */
+
+@layer xihan.components {
+  /* 皮肤在场的标记：开发模式下按 scope 探一次，取不到就说明这份皮肤没被引入。 */
+  .xh-scope-matrix-code {
+    --xh-matrix-code-skin: 1;
+  }
+
+  /*
+   * 根 <svg>。深浅两色取固定档而不是语义前景/背景：语义色跟着主题走，深色主题下整张码
+   * 会翻成浅底深模块的反相图，一部分读码器不认反相码。要换配色改下面这三个覆盖槽。
+   *
+   * 换色只有一条硬约束：码点必须比底色深，且两者对比要足。反相（浅码点深底）与
+   * 深浅相近都会让一部分读码器扫不出来，而这件事肉眼看不出来。
+   *
+   *   --xh-matrix-code-fg      码点色，同时经 currentColor 传给码眼
+   *   --xh-matrix-code-bg      底色，挖空矩形也用它
+   *   --xh-matrix-code-eye-fg  码眼色，缺省跟随码点色
+   */
+  .xh-scope-matrix-code[data-part='root'] {
+    display: block;
+    border-radius: var(--xh-matrix-code-radius, var(--xh-shape-control));
+    background: var(--xh-matrix-code-bg, var(--xh-color-neutral-0));
+
+    /* 模块那条 path 不带自己的填充色，从这里继承下去 */
+    color: var(--xh-matrix-code-fg, var(--xh-color-neutral-950));
+    fill: currentColor;
+
+    /* 占位与码面之间来回时，底色与那圈描边淡变 */
+    transition:
+      background-color var(--xh-motion-duration-micro) var(--xh-motion-ease-enter),
+      box-shadow var(--xh-motion-duration-micro) var(--xh-motion-ease-enter);
+  }
+
+  /* 声明了 display 就盖掉了 UA 的 [hidden]{display:none}，收起态得自己还回去 */
+  .xh-scope-matrix-code[data-part='root'][hidden] {
+    display: none;
+  }
+
+  /* 码眼那条 path 恒在（与形状无关），没单独指定就退回 currentColor，跟码点同色 */
+  .xh-scope-matrix-code[data-part='root'] > [data-xh-geom='eyes'] {
+    fill: var(--xh-matrix-code-eye-fg, currentColor);
+  }
+
+  /*
+   * logo 底下那块挖空：填的必须与根的背景逐字同一个表达式，两处一起改。
+   * 差一点就会在 logo 四周露出一圈色差，读码器会把那圈当成模块边界。
+   */
+  .xh-scope-matrix-code[data-part='root'] > [data-xh-geom='logo-clear'] {
+    fill: var(--xh-matrix-code-bg, var(--xh-color-neutral-0));
+  }
+
+  /*
+   * 没有可编码的内容、以及内容超出容量：两种情形都一个模块不铺，留一块带描边的占位。
+   * 占位用的是语义色——它是界面元素不是码面，跟着主题走才对。
+   */
+  .xh-scope-matrix-code[data-part='root'][data-state='empty'],
+  .xh-scope-matrix-code[data-part='root'][data-state='error'] {
+    background: var(--xh-matrix-code-placeholder-bg, var(--xh-bg-subtle));
+    box-shadow: inset 0 0 0 var(--xh-stroke-thin) var(--xh-matrix-code-placeholder-border, var(--xh-border-default));
+  }
+}