diff --git a/apps/demo/main.ts b/apps/demo/main.ts
index 89f2a4a..5a73ed9 100644
--- a/apps/demo/main.ts
+++ b/apps/demo/main.ts
@@ -283,9 +283,10 @@ const orgTree = [
{ key: 'qa', label: '质量中心', children: [{ key: 'reg', label: '回归测试', disabled: true }] },
];
-// —— 主题：优先读上次选择，其次跟随系统；写 html[data-theme] 让令牌换色 ——
+// —— 主题：优先读 URL 参数（文档站 iframe 联动入口），其次上次选择，最后跟随系统；写 html[data-theme] 让令牌换色 ——
const THEME_KEY = 'ua-demo-theme';
-const dark = signal((localStorage.getItem(THEME_KEY) ?? (matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light')) === 'dark');
+const themeParam = new URLSearchParams(location.search).get('theme'); // ?theme=dark|light，iframe 带参重载时生效
+const dark = signal(((themeParam === 'dark' || themeParam === 'light' ? themeParam : null) ?? localStorage.getItem(THEME_KEY) ?? (matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light')) === 'dark');
effect(() => {
const mode = dark() ? 'dark' : 'light';
document.documentElement.dataset.theme = mode; // 令牌按 data-theme 切换
diff --git a/packages/tools/cli/bin/ua.js b/packages/tools/cli/bin/ua.js
index 7ab70af..df541cc 100644
--- a/packages/tools/cli/bin/ua.js
+++ b/packages/tools/cli/bin/ua.js
@@ -300,7 +300,8 @@ function renderDocs(index, tokens) {
@ui-arch 组件库文档
-
+
@@ -421,6 +424,25 @@ document.getElementById('q').addEventListener('input',function(e){
var q=e.target.value.trim().toLowerCase();
render(q?ordered.filter(function(p){return norm(p).indexOf(q)>=0}):ordered);
});
+// —— 主题：默认跟随系统（不写 data-theme），用户选择后持久化；iframe 演示带参重载联动 ——
+var THEME_KEY='ua-docs-theme';
+var themeBtn=document.getElementById('theme');
+function paintTheme(t){ // t: 'light'|'dark'|null，null 表示跟随系统
+ if(t)document.documentElement.setAttribute('data-theme',t);else document.documentElement.removeAttribute('data-theme');
+ themeBtn.textContent=t==='dark'?'暗色':'亮色';
+}
+var savedTheme=null;try{savedTheme=localStorage.getItem(THEME_KEY)}catch(e){}
+paintTheme(savedTheme==='dark'||savedTheme==='light'?savedTheme:null);
+themeBtn.addEventListener('click',function(){
+ var cur=document.documentElement.getAttribute('data-theme')||(matchMedia('(prefers-color-scheme:dark)').matches?'dark':'light');
+ var next=cur==='dark'?'light':'dark';
+ try{localStorage.setItem(THEME_KEY,next)}catch(e){}
+ paintTheme(next);
+ document.querySelectorAll('iframe.demo').forEach(function(f){ // 带参重载：demo 读 ?theme= 切换
+ var parts=f.src.split('#');var anchor=parts.length>1?'#'+parts.slice(1).join('#'):'';
+ f.src=parts[0].split('?')[0]+'?theme='+next+anchor;
+ });
+});