agentcss 0.0.0-stage → 0.11.2

package/02-primitives/popover/popover.js

@@ -0,0 +1,331 @@
+/**
+ * popover.js — 气泡卡片的行为
+ * ============================================================================
+ * ⭐ 与 dialog 的根本区别：**非模态**
+ *   dialog  : 背景锁死、focus trap、必须处理完才能继续
+ *   popover : 背景**仍可交互**，用户可以"看一眼再关掉"
+ *   ⇒ 所以 popover **不**做 focus trap（那会让人出不去），
+ *     只做「焦点进入」+「Esc 关闭」+「焦点归还」。
+ *
+ * 参照：Radix Popover / MUI Popover
+ * ============================================================================
+ */
+(function (global) {
+  'use strict';
+
+  /* ==== BEHAVIOR INJECT BEGIN: dismissable ==== */
+  var flDismissable = function (opts) {
+    var opt = opts || {};
+    var escOn = opt.escOn || [];
+    var inside = opt.inside || [];
+    var when = opt.when || function () { return true; };
+    var onDismiss = opt.onDismiss || function () {};
+
+    var shared = window.__flDismiss || (window.__flDismiss = { stack: [], bound: false });
+
+    function isInside(node) {
+      if (!node) return false;
+      for (var i = 0; i < inside.length; i++) {
+        var el = inside[i];
+        if (!el || !el.contains) continue;
+        if (el === node || el.contains(node)) return true;
+      }
+      return false;
+    }
+
+    function onKey(e) {
+      if (!when()) return;
+      var k = e.key;
+      if (k !== 'Escape' && k !== 'Esc' && e.keyCode !== 27) return;
+      /* 🔴 为什么 onDismiss 在前、preventDefault/stopPropagation 在后
+         （0.8.8 改）：**分级 Esc** 需要核让组件有机会说"这次我没关"。
+         combobox 的 Esc 是三级的：
+           ① 列表开着 → 关列表
+           ② 列表关了、输入有字 → 清空输入
+           ③ 都没了 → 什么都不做（此时**不该**阻止默认行为，
+              让 Esc 能继续传给外层浮层）
+         而原实现是「无条件 preventDefault + stopPropagation，再调 onDismiss」
+         ⇒ 组件根本无法表达"这次我没关"。
+         ⇒ 改成：先问onDismiss，它返回 false 就**不干预**默认行为。
+         ⚠️ 顺序安全性：stopPropagation 只需在**本次监听器执行期间**被调用即可
+            阻止冒泡到外层，放在 onDismiss 之后仍然有效。
+      */
+      var closed = onDismiss(e, 'esc');
+      if (closed === false) return;
+      if (e.preventDefault) e.preventDefault();
+      if (e.stopPropagation) e.stopPropagation();
+    }
+
+    function onDocClick(e) {
+      var top = null;
+      for (var i = shared.stack.length - 1; i >= 0; i--) {
+        if (shared.stack[i].when()) { top = shared.stack[i]; break; }
+      }
+      if (!top || top.isInside(e.target)) return;
+      top.onDismiss(e, 'outside');
+    }
+
+    var rec = { when: when, isInside: isInside, onDismiss: onDismiss };
+
+    for (var j = 0; j < escOn.length; j++) {
+      if (escOn[j]) escOn[j].addEventListener('keydown', onKey);
+    }
+    shared.stack.push(rec);
+    if (!shared.bound) {
+      shared.bound = true;
+      document.addEventListener('click', onDocClick, true);
+    }
+
+    return {
+      destroy: function () {
+        for (var j = 0; j < escOn.length; j++) {
+          if (escOn[j]) escOn[j].removeEventListener('keydown', onKey);
+        }
+        var k = shared.stack.indexOf(rec);
+        if (k >= 0) shared.stack.splice(k, 1);
+      },
+    };
+  };
+  /* ==== BEHAVIOR INJECT END: dismissable ==== */
+
+  /* ==== BEHAVIOR INJECT BEGIN: focus-return ==== */
+  var flFocusReturn = function (opts) {
+    var opt = opts || {};
+    var saved = null;
+
+    return {
+      save: function () {
+        var a = document.activeElement;
+        saved = (a && a !== document.body && a.focus) ? a : null;
+        return saved;
+      },
+
+      restore: function () {
+        var target = saved;
+        /* ⚠️ 见文档 ②：不判 contains 的话，元素被移除后 focus() 不报错
+           但焦点不动 ⇒ 用户以为还回去了，其实掉在 body 上。 */
+        if (!target || !document.contains(target)) target = opt.fallback || null;
+        if (!target) { saved = null; return false; }
+        try {
+          target.focus();
+        } catch (e) {
+          saved = null;
+          return false;
+        }
+        var ok = document.activeElement === target;
+        saved = null;   /* 见文档 ③ */
+        return ok;
+      },
+
+      target: function () { return saved; },
+      clear: function () { saved = null; },
+    };
+  };
+  /* ==== BEHAVIOR INJECT END: focus-return ==== */
+  /* ==== BEHAVIOR INJECT BEGIN: emit ==== */
+  var flEmit = function (el, name, detail) {
+    if (!el || !el.dispatchEvent) return null;
+    var type = name.indexOf('fl-') === 0 ? name : 'fl-' + name;
+    var ev = null;
+    /* 老 WebView 没有 CustomEvent 构造函数 ⇒ 兜底走 createEvent（理由见文件头）*/
+    if (typeof window.CustomEvent === 'function') {
+      try {
+        ev = new window.CustomEvent(type, {
+          detail: detail || null, bubbles: true, cancelable: false
+        });
+      } catch (e) { ev = null; }
+    }
+    if (!ev) {
+      try {
+        ev = document.createEvent('CustomEvent');
+        ev.initCustomEvent(type, true, false, detail || null);
+      } catch (e2) { return null; }
+    }
+    el.dispatchEvent(ev);
+    return ev;
+  };
+  /* ==== BEHAVIOR INJECT END: emit ==== */
+
+  /* ⭐ 同一时间只开一个 popover —— 两个叠着会让用户不知道该关哪个 */
+  var current = null;
+
+  function focusableIn(root) {
+    var all = root.querySelectorAll(
+      'a[href], button:not([disabled]), input:not([disabled]), ' +
+      'select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
+    );
+    return Array.prototype.filter.call(all, function (el) {
+      var cs = global.getComputedStyle(el);
+      if (cs.display === 'none' || cs.visibility === 'hidden') return false;
+      var r = el.getBoundingClientRect();
+      return r.width >= 1 && r.height >= 1;
+    });
+  }
+
+  /**
+   * 绑定一个 popover
+   * @param {Element} trigger 触发元素
+   * @param {object}  opts
+   *   - place: 'bottom' | 'top' | 'end' | 'start'（默认 bottom）
+   *   - html:  浮层内容 HTML
+   *   - onOpen / onClose 回调
+   *   - closeOnOutsideClick（默认 true）
+   *   - closeOnEsc（默认 true）
+   */
+  function attach(trigger, opts) {
+    opts = opts || {};
+
+    /* ---- 建 DOM ---- */
+    var anchor = document.createElement('span');
+    anchor.className = 'popover-anchor';
+    trigger.parentNode.insertBefore(anchor, trigger);
+    anchor.appendChild(trigger);
+
+    var box = document.createElement('div');
+    box.className = 'popover popover--' + (opts.place || 'bottom');
+    box.setAttribute('data-open', 'false');
+    box.setAttribute('inert', '');   /* 初始关闭态即不可聚焦 */
+    /* 🔴 关键：popover 用 `dialog` 角色但**不加 aria-modal**
+       （加了就是模态，语义就错了）。 */
+    box.setAttribute('role', 'dialog');
+    box.setAttribute('aria-label', opts.label || '');
+    box.innerHTML =
+      '<span class="popover__arrow" aria-hidden="true"></span>' +
+      '<div class="popover__body">' + (opts.html || '') + '</div>';
+
+    /* 箭头要指向触发元素的中心，而不是浮层的中心 */
+    positionArrow(box, trigger);
+    anchor.appendChild(box);
+
+    /* 焦点归位走 focus-return 核（01-tokens/behavior/focus-return.js）。
+       fallback 给 trigger：万一打开它的那个元素被删了，焦点至少回到触发器，
+       而不是掉到 body 上（键盘用户要从页面开头重新 Tab）。 */
+    var fr = flFocusReturn({ fallback: trigger });
+
+    function open() {
+      if (current && current !== api) current.close();
+      fr.save();
+      box.setAttribute('data-open', 'true');
+      /* 🔴 关闭态必须用 **inert**，不能用 pointer-events ——
+       *   实测踩坑：`pointer-events:none` **拦不住 Tab**
+       *   （Tab 走的是 tabindex/focusability，不是命中测试）
+       *   ⇒ 关闭的浮层里的按钮仍能被 Tab 到，用户焦点会跑到"看不见"的地方。
+       *   inert 一次性解决：不可聚焦、不可点击、读屏也不读。 */
+      box.removeAttribute('inert');
+
+      /* 🔴 焦点**进入**浮层 —— 键盘用户要能直接操作里面的内容。
+       *    ⚠️ 与 dialog 不同：这里**不做 trap**（那会让人出不去）。 */
+      var f = focusableIn(box);
+      if (f.length) f[0].focus();
+      else box.setAttribute('tabindex', '-1'), box.focus();
+
+      current = api;
+      /* 先派发事件再调回调 ⇒ 回调抛异常也不连累其它订阅者（核文件头 ⑦）*/
+      flEmit(anchor, 'fl-open', null);
+      if (opts.onOpen) opts.onOpen();
+    }
+
+    function close() {
+      if (box.getAttribute('data-open') !== 'true') return;
+      box.setAttribute('data-open', 'false');
+      /* ⭐ 见 open() 的说明：必须 inert，不能只靠 pointer-events */
+      box.setAttribute('inert', '');
+      /* ⭐ 焦点归还 —— 否则键盘用户要从页面开头重新 Tab。 */
+      fr.restore();
+      if (current === api) current = null;
+      flEmit(anchor, 'fl-close', null);
+      if (opts.onClose) opts.onClose();
+    }
+
+    function toggle() {
+      if (box.getAttribute('data-open') === 'true') close();
+      else open();
+    }
+
+    /* ---- 触发器 ---- */
+    trigger.setAttribute('aria-haspopup', 'dialog');
+    trigger.setAttribute('aria-expanded', 'false');
+    trigger.addEventListener('click', function (e) {
+      /* ⭐ 不要把它交给"外部点击"判定：触发器在浮层**外面**，
+         但点它是"切换"不是"关闭"。dismissable 核的 `inside` 含 anchor，
+         anchor 又含 trigger ⇒ 已经算作内部；这里 stopPropagation 只是
+         顺手阻止更外层的组件（如 dropdown）也收到这次点击。 */
+      e.stopPropagation();
+      toggle();
+    });
+
+    /* ---- Esc / 点击外部关闭：走 dismissable 核（01-tokens/behavior/dismissable.js）
+       —— 手写的两个 Esc 分支与外部点击监听已删除，全库统一到一处。 ---- */
+    var dismiss = flDismissable({
+      escOn: [trigger, box],
+      inside: [box, anchor],   /* anchor 含 trigger ⇒ 点触发器不算"外部" */
+      when: function () { return box.getAttribute('data-open') === 'true'; },
+      onDismiss: function (e, reason) { close(); },
+    });
+
+    /* 🔴 Tab **不做任何处理** —— 这是修正后的行为，别"顺手"加回来。
+     *
+     *  第一版（错）：在浮层内循环 Tab（最后一个绕回第一个）。
+     *  实测焦点序列：近 7 天 → 近 30 天 → 取消 → 应用 → 近 7 天 → …
+     *  ⇒ 用户**被困住了**，出不去。
+     *
+     *  ⭐ 正确做法（Radix Popover 的默认 `trapFocus={false}`）：
+     *    popover 是**非模态**的，Tab 应当自然走到页面下一个可聚焦元素。
+     *    困住用户是 dialog 的行为，不是 popover 的。
+     *    焦点"进入"浮层已经由 open() 里的 focus() 保证了，
+     *    不需要用 trap 来维持。
+     */
+
+    /* ---- 关闭态的内容不可聚焦 ---- */
+    box.addEventListener('transitionend', function () {
+      if (box.getAttribute('data-open') === 'false') {
+        box.setAttribute('aria-hidden', 'true');
+      } else {
+        box.removeAttribute('aria-hidden');
+      }
+    });
+
+    var api = {
+      open: open,
+      close: close,
+      toggle: toggle,
+      destroy: function () {
+        dismiss.destroy();
+        close();
+        box.remove();
+        anchor.remove();
+      },
+      el: box,
+    };
+    return api;
+  }
+
+  /* 箭头对准触发元素中心（浮层可能比触发元素宽） */
+  function positionArrow(box, trigger) {
+    var arrow = box.querySelector('.popover__arrow');
+    if (!arrow) return;
+    var place = (box.className.match(/popover--(\w+)/) || [])[1];
+    if (place === 'start' || place === 'end') {
+      /* 左右方向：箭头固定垂直居中 */
+      arrow.style.top = '50%';
+      arrow.style.marginTop = '';
+      return;
+    }
+    var br = trigger.getBoundingClientRect();
+    var ar = box.getBoundingClientRect();
+    var offset = br.left + br.width / 2 - (ar.left + parseFloat(getComputedStyle(box).paddingLeft || 0));
+    /* 夹在浮层内，避免箭头跑出圆角外 */
+    var max = ar.width - 24;
+    arrow.style.marginLeft = Math.max(12, Math.min(offset, max)) + 'px';
+  }
+
+  var Popover = {
+    attach: function (trigger, opts) {
+      return attach(trigger, opts);
+    },
+    closeAll: function () { if (current) current.close(); },
+    get current() { return current; },
+  };
+
+  global.Popover = Popover;
+})(window);

package/02-primitives/progress/README.md

@@ -0,0 +1,82 @@
+# progress · 进度条
+
+> 进度**已知**时用它；进度**不知道**时用 [`skeleton`](../skeleton/)。
+> ⭐ 两者混用是常见错误：不知道进度却给一个假的百分比，**比不给更糟**。
+
+## 用法
+
+```html
+<link rel="stylesheet" href="progress.css">
+
+<!-- 线形（最常用）-->
+<span class="progress" role="progressbar" aria-valuenow="60"
+      aria-valuemin="0" aria-valuemax="100" aria-label="上传进度"
+      data-progress="60">
+  <span class="progress__bar"></span>
+</span>
+
+<!-- 语义色 -->
+<span class="progress progress--danger" ...>   <!-- success / warning / danger -->
+<!-- 尺寸 -->  <span class="progress progress--lg"> / progress--sm
+
+<!-- 环形（纯 CSS conic-gradient，零 SVG）-->
+<span class="progress-ring" data-progress="72" role="progressbar" aria-valuenow="72">
+  <span class="progress-ring__label" aria-hidden="true">72%</span>
+</span>
+
+<!-- 不确定进度（不知道要多久）-->
+<span class="progress progress--indeterminate" aria-busy="true" aria-label="正在处理">
+  <span class="progress__bar"></span>
+</span>
+
+<!-- 步骤分段（第 3 步 / 共 5 步）-->
+<span class="progress-steps" role="progressbar" aria-valuenow="3" aria-valuemax="5">
+  <span class="progress-steps__seg progress-steps__seg--done"></span>
+  <span class="progress-steps__seg progress-steps__seg--current"></span>
+  <span class="progress-steps__seg"></span>
+</span>
+```
+
+**动态进度用 JS 写**（比行内 `style` 便宜，只改一个自定义属性）：
+
+```js
+el.style.setProperty('--progress', '60%');
+```
+
+## 令牌
+
+| 令牌 | 默认 | 说明 |
+|---|---|---|
+| `--progress` | `0%` | **当前值**。默认 0% 是正确默认，不是占位 |
+| `--progress-h` | `6px` | 线形高度（`--sm` 4px / `--lg` 10px）|
+| `--progress-dur` | `240ms` | 宽度过渡 |
+| `--ease-out` | `cubic-bezier(.23,1,.32,1)` | ⭐ 独立于 `--ease`：进度要"向前"的 feel，匀速反而像卡住 |
+| `--r-full` | `999px` | 胶囊圆角 |
+| `--ring-size` / `--ring-thickness` | `64px` / `8px` | 环形尺寸 |
+
+## 无障碍（**红线**）
+
+```html
+<!-- ✅ 确定进度 -->
+role="progressbar" + aria-valuenow/min/max + aria-label
+
+<!-- ✅ 不确定进度：只标 aria-busy，**不要**给 valuenow -->
+role="progressbar" aria-busy="true" aria-label="正在处理"
+```
+
+⚠️ **不确定时不要显示百分比** —— 那是撒谎。读屏只会听到「正在处理，进度未知」，这才是事实。
+
+⚠️ `prefers-reduced-motion: reduce` 时扫光动画**停掉，但条子仍可见**（用户依然知道系统在忙）。
+
+## 何时**不该**用
+
+- ❌ **不知道进度时**（停在 0% 或乱跳的百分比）⇒ 用 `skeleton`
+- ❌ **不足 ~1 秒就完成**的操作 ⇒ 闪一下更伤体验，直接不显示
+- ❌ **代替"还剩多久"** ⇒ 百分比给的是"比例"，不是"时间"
+- ❌ **环形用在极小尺寸**（< 32px）⇒ 环太细，读不出进度
+- ❌ **在一个页面里同时出现 3 个以上进度条** ⇒ 用户不知道该看哪个
+
+## 相关
+
+- 未知进度 ⇒ [`skeleton`](../skeleton/)
+- 短反馈（"已保存"）⇒ `toast`（**尚未提供**）

package/02-primitives/progress/demo.html

@@ -0,0 +1,154 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<link rel="icon" href="data:,">
+<title>进度条 · progress</title>
+<link rel="stylesheet" href="../../01-tokens/tokens.css">
+<link rel="stylesheet" href="../../01-tokens/typography.css">
+<link rel="stylesheet" href="../../01-tokens/page.css">
+<link rel="stylesheet" href="progress.css">
+<style>
+.demo {
+    background: var(--surface);
+    border: 1px solid var(--border-decor);
+    border-radius: var(--r-md);
+    padding: var(--sp-4);
+    margin-bottom: var(--sp-4);
+  }
+.row { display: flex; align-items: center; gap: var(--sp-3); }
+.row+.row { margin-top: var(--sp-3); }
+.pct { font-size: var(--fs-sm); color: var(--text-secondary);
+         font-variant-numeric: tabular-nums; min-width: 3.2em; text-align: right; }
+.bad-demo { background: var(--danger-bg); border-color: var(--danger); }
+.bad { color: var(--danger); }
+</style>
+</head>
+<body class="page page">
+<main class="wrap">
+  <!-- 🔴 0.8.9：axe 报 landmark-one-main（moderate）—— 本页原本没有任何 landmark 容器。
+     加 <main> 是语义正确且不改布局的做法（<main> 默认不产生 box）。
+     ⚠️ 试过给 <body> 加 role="main"：axe 明确报 aria-allowed-role（该 role 对 <body>
+        是禁止的），而且也没解决 landmark 违规 ⇒ 已回退。 -->
+
+<h1>进度条 · progress</h1>
+<p class="lede">进度<strong>已知</strong>时用它；进度<strong>不知道</strong>时用 <code>skeleton</code>。混用是常见错误。</p>
+
+<h2>1 · 线形（最常用）</h2>
+<div class="demo">
+  <div class="row">
+    <span class="progress" role="progressbar" aria-valuenow="60" aria-valuemin="0" aria-valuemax="100" aria-label="上传进度" data-progress="60">
+      <span class="progress__bar"></span>
+    </span>
+    <span class="pct" aria-hidden="true">60%</span>
+  </div>
+  <p class="note">用 <code>--progress</code> 驱动宽度；<code>role="progressbar"</code> + <code>aria-valuenow</code> 是<b>必须</b>的（读屏要能念出进度）。</p>
+</div>
+
+<h2>2 · 语义色</h2>
+<div class="demo">
+  <div class="row">
+    <span class="progress progress--success" role="progressbar" aria-valuenow="100" aria-label="已完成" data-progress="100"><span class="progress__bar"></span></span>
+    <span class="pct" aria-hidden="true">完成</span>
+  </div>
+  <div class="row">
+    <span class="progress progress--warning" role="progressbar" aria-valuenow="85" aria-label="即将超时" data-progress="85"><span class="progress__bar"></span></span>
+    <span class="pct" aria-hidden="true">85%</span>
+  </div>
+  <div class="row">
+    <span class="progress progress--danger" role="progressbar" aria-valuenow="40" aria-label="失败" data-progress="40"><span class="progress__bar"></span></span>
+    <span class="pct" aria-hidden="true">40%</span>
+  </div>
+</div>
+
+<h2>3 · 尺寸</h2>
+<div class="demo">
+  <span class="progress progress--sm" role="progressbar" aria-valuenow="40" aria-label="小" data-progress="40"><span class="progress__bar"></span></span>
+  <div style="height:var(--sp-2)"></div>
+  <span class="progress" role="progressbar" aria-valuenow="40" aria-label="中" data-progress="40"><span class="progress__bar"></span></span>
+  <div style="height:var(--sp-2)"></div>
+  <span class="progress progress--lg" role="progressbar" aria-valuenow="40" aria-label="大" data-progress="40"><span class="progress__bar"></span></span>
+</div>
+
+<h2>4 · 环形</h2>
+<div class="demo">
+  <div class="row" style="gap:var(--sp-5)">
+    <span class="progress-ring" data-progress="72" role="progressbar" aria-valuenow="72" aria-label="环形进度">
+      <span class="progress-ring__label" aria-hidden="true">72%</span>
+    </span>
+    <span class="progress-ring progress-ring--success" data-progress="100" role="progressbar" aria-valuenow="100" aria-label="已完成">
+      <span class="progress-ring__label" aria-hidden="true">✓</span>
+    </span>
+    <span class="progress-ring progress-ring--danger" data-progress="35" role="progressbar" aria-valuenow="35" aria-label="失败">
+      <span class="progress-ring__label" aria-hidden="true">35%</span>
+    </span>
+  </div>
+  <p class="note">纯 CSS <code>conic-gradient</code>，零 SVG、零依赖。数字用 <code>tabular-nums</code>，变化时不会左右跳。</p>
+</div>
+
+<h2>5 · 不确定进度</h2>
+<div class="demo">
+  <span class="progress progress--indeterminate" role="progressbar" aria-label="正在处理（进度未知）" aria-busy="true">
+    <span class="progress__bar"></span>
+  </span>
+  <p class="note">
+    <b>不确定时不要显示百分比</b> —— 那是撒谎。
+    读屏只会听到「正在处理，进度未知」，这才是事实。
+  </p>
+</div>
+
+<h2>6 · 步骤分段</h2>
+<div class="demo">
+  <div class="progress-steps" role="progressbar" aria-valuenow="3" aria-valuemin="1" aria-valuemax="5" aria-label="第 3 步，共 5 步">
+    <span class="progress-steps__seg progress-steps__seg--done"></span>
+    <span class="progress-steps__seg progress-steps__seg--done"></span>
+    <span class="progress-steps__seg progress-steps__seg--current"></span>
+    <span class="progress-steps__seg"></span>
+    <span class="progress-steps__seg"></span>
+  </div>
+  <p class="note">流程类进度（"第 3 步 / 共 5 步"）比百分比更贴切。</p>
+</div>
+
+<h2>7 · 减少动态效果时</h2>
+<div class="demo">
+  <span class="progress progress--indeterminate" role="progressbar" aria-label="正在处理" aria-busy="true">
+    <span class="progress__bar"></span>
+  </span>
+  <p class="note">开启「减少动态效果」后扫光动画停掉，但条子<b>仍然可见</b> —— 用户依然知道系统在忙。</p>
+</div>
+
+<h2>反例 · 不该这样用</h2>
+<div class="demo bad-demo">
+  <span class="progress" role="progressbar" aria-valuenow="0" aria-label="反例" data-progress="0">
+    <span class="progress__bar"></span>
+  </span>
+  <p class="note bad">
+    <b>不要用进度条表示「不知道要多久」。</b><br>
+    停在 0% 或乱跳的百分比，比 <code>skeleton</code> 更让人困惑 ——
+    用户会盯着它算还剩多久。<br>
+    <b>也不知道进度时</b>，用 <code>skeleton</code>（形状提示"这里会有内容"）
+    或不确定进度条（明说"不知道"）。
+  </p>
+</div>
+
+<script>
+/* 🔴 I5：进度值用 **JS 写入**而不是行内 style
+ * ---------------------------------------------------------------
+ * ① 为什么不用行内 data-progress="60"：
+ *    真实场景里进度是**动态**的，行内 style 每次要重新渲染 DOM。
+ *    用 setProperty 只改一个自定义属性，成本最低。
+ * ② 门禁 deps.py 认 setProperty ⇒ 不会误报"未定义令牌"
+ *    （--progress 是**每个实例自己的值**，不是全局设计令牌）。
+ */
+document.querySelectorAll('.progress, .progress-ring, .progress-steps').forEach((el) => {
+  const m = el.getAttribute('data-progress');
+  if (m) {
+    el.style.setProperty('--progress', m + '%');     // 线形用（要带 %）
+    el.style.setProperty('--progress-num', m);      // 环形用（不能带 %）
+  }
+});
+</script>
+</main>
+</body>
+</html>