@autional/ui 0.0.0-stage → 0.1.0-rc.43

package/src/molecules/AppShell.tsx

@@ -0,0 +1,122 @@
+'use client';
+
+import React from 'react';
+import { X } from 'lucide-react';
+
+// AppShell —— 控制台/门户的**外壳**：侧栏 + 顶栏 + 内容区 + 移动端抽屉。
+//
+// 为什么要有它（实测，2026-10-04）：四个门户各自把同一套外壳写了一遍 ——
+//   admin  Header 88 + Sidebar 609 · platform Header 50 + Sidebar 178 ·
+//   security AppLayout 203 · user AppLayout 341   → 5 个文件 / 约 1470 行
+// 其中**真正重复的是外壳本身**（外层 flex 框架、固定侧栏、sticky 顶栏、移动端遮罩与抽屉、
+// 内容区的滚动容器），而**不重复的是内容**（导航项、品牌文案、右上角那几个控件）。
+// 于是这里的边界就是这条：**外壳拥有 chrome 与行为，站点拥有内容**。
+//
+// 它刻意**不**依赖 antd：user 门户的 antd 入口已经是 0，让它为了一个外壳回去装 antd，
+// 是拿「一致性」换「多一份依赖」—— 而三个控制台要的是「别再各写一遍框架」，
+// 不是「必须用 antd 的 Layout」。所以：
+//   · 外壳是原生 HTML + 设计系统令牌（深色模式由令牌自己切换，不需要 dark: 变体）；
+//   · nav / headerRight 这类**内容**由站点以 ReactNode 传入 —— 控制台可以照旧塞 antd Menu 与 UserMenu。
+//
+// 顶栏高度走 var(--layout-header-height)：第 13 道闸门（顶栏契约）认这个令牌，
+// 写死 h-16 会被它判红 —— 外壳必须满足同一份契约。
+//
+// **页面外框也归外壳**（第 28 轮）：沟槽（p-6）+ 内容面（白色圆角面板）。
+// 这条边界不是审美选择，是「同一个东西只能有一个所有者」：外框原本分散在 4 个布局文件里，
+// 结果三个控制台各抄了一份逐字相同的面板、user 一份都没有，而 34 个页面又在面板里再补一层内边距
+// —— 页面内缩因此在 24px 与 48px 之间随机，同一个门户的相邻两页都能不一样。
+
+export interface AppShellProps {
+	/** 侧栏顶部的品牌区。 */
+	brand: React.ReactNode;
+	/** 侧栏导航区。控制台传 antd Menu，user 传自定义列表 —— 外壳不关心里面是什么。 */
+	nav: React.ReactNode;
+	/** 品牌区下方、导航上方的附加区（如租户切换器）。 */
+	sidebarExtra?: React.ReactNode;
+	/** 顶栏左侧（移动端菜单按钮、折叠按钮、页面标题…）。 */
+	headerLeft?: React.ReactNode;
+	/** 顶栏右侧（PortalSwitcher / 语言 / 主题 / UserMenu…）。 */
+	headerRight?: React.ReactNode;
+	/** 内容区。 */
+	children: React.ReactNode;
+	/** 移动端抽屉是否打开（受控）。 */
+	mobileOpen?: boolean;
+	/** 请求关闭移动端抽屉（点遮罩 / 点关闭按钮都会走到这里）。 */
+	onMobileClose?: () => void;
+	/** 关闭按钮的无障碍标签。 */
+	closeLabel?: string;
+	/** 桌面端侧栏是否收起（只影响宽度：w-64 ↔ w-16）。 */
+	sidebarCollapsed?: boolean;
+	/** 追加类名。 */
+	className?: string;
+}
+
+export const AppShell = React.memo(function AppShell({
+	brand,
+	nav,
+	sidebarExtra,
+	headerLeft,
+	headerRight,
+	children,
+	mobileOpen = false,
+	onMobileClose,
+	closeLabel = 'Close menu',
+	sidebarCollapsed = false,
+	className = '',
+}: AppShellProps) {
+	return (
+		<div className={`flex h-screen bg-[var(--color-bg-muted)] ${className}`}>
+			{/* 移动端遮罩：点它关闭抽屉。桌面端不渲染（lg:hidden）。 */}
+			{mobileOpen && (
+				<div
+					className="fixed inset-0 z-40 bg-black/30 lg:hidden"
+					onClick={onMobileClose}
+					aria-hidden="true"
+				/>
+			)}
+
+			<aside
+				className={`fixed inset-y-0 left-0 z-50 flex transform flex-col border-r border-[var(--color-border-subtle)] bg-[var(--color-bg-surface)] transition-transform duration-200 lg:static lg:translate-x-0 ${
+					mobileOpen ? 'translate-x-0' : '-translate-x-full'
+				} ${sidebarCollapsed ? 'w-64 lg:w-16' : 'w-64'}`}
+			>
+				<div className="flex h-[var(--layout-header-height)] shrink-0 items-center justify-between gap-2 border-b border-[var(--color-border-subtle)] px-4">
+					<div className="flex min-w-0 items-center gap-2">{brand}</div>
+					<button
+						type="button"
+						className="text-[var(--color-text-muted)] hover:text-[var(--color-text-primary)] lg:hidden"
+						onClick={onMobileClose}
+						aria-label={closeLabel}
+					>
+						<X size={20} />
+					</button>
+				</div>
+
+				{sidebarExtra}
+
+				<nav className="flex min-h-0 flex-1 flex-col overflow-y-auto">{nav}</nav>
+			</aside>
+
+			<div className="flex min-w-0 flex-1 flex-col">
+				<header className="sticky top-0 z-10 flex h-[var(--layout-header-height)] shrink-0 items-center justify-between gap-4 border-b border-[var(--color-border-subtle)] bg-[var(--color-bg-surface)] px-4 lg:px-8">
+					<div className="flex min-w-0 items-center gap-4">{headerLeft}</div>
+					<div className="flex shrink-0 items-center gap-3">{headerRight}</div>
+				</header>
+
+				{/* 内容面：沟槽之内那张白色圆角面板。三个控制台此前各自在自己的 App 里写了一遍
+				    （逐字相同的 `min-h-[calc(100vh-112px)] rounded-lg bg-surface p-6`），user 没有 ——
+				    于是四个门户的页面外框有两种：有面 / 无面，且页面还得自己再补一层内边距（实测 34 个页面这么干，
+				    内缩因此从 24px 变成 48px）。外框属于外壳，搬进来之后站点侧只留内容。
+
+				    min-height 用顶栏令牌表达：112px = 顶栏 64px + 内容区上下沟槽各 24px（p-6），
+				    写成 calc 之后顶栏高度一变它跟着变 —— 写死的 112 会在顶栏改高度那天悄悄错位。 */}
+				{/* 沟槽写死在外壳里：它同时是四站唯一的留白来源。放在调用方手里 = 又允许四个门户各调各的。 */}
+				<main className="min-h-0 flex-1 overflow-auto p-6">
+					<div className="min-h-[calc(100vh-var(--layout-header-height)-3rem)] rounded-lg bg-[var(--color-bg-surface)] p-6">
+						{children}
+					</div>
+				</main>
+			</div>
+		</div>
+	);
+});

package/src/molecules/CodeBlock.tsx

@@ -0,0 +1,55 @@
+import React, { useState, useCallback } from 'react';
+import { Check, Copy } from 'lucide-react';
+
+interface CodeBlockProps {
+	code: string;
+	language?: string;
+	filename?: string;
+	className?: string;
+}
+
+export const CodeBlock = React.memo(function CodeBlock({
+	code,
+	language = 'bash',
+	filename,
+	className = '',
+}: CodeBlockProps) {
+	const [copied, setCopied] = useState(false);
+
+	const handleCopy = useCallback(() => {
+		navigator.clipboard.writeText(code).then(() => {
+			setCopied(true);
+			setTimeout(() => setCopied(false), 2000);
+		});
+	}, [code]);
+
+	return (
+		<div
+			className={`overflow-hidden rounded-lg border border-neutral-200 bg-neutral-900 dark:border-neutral-800 ${className}`}
+		>
+			{(filename || language) && (
+				<div className="flex items-center justify-between border-b border-neutral-800 bg-neutral-950 px-4 py-2">
+					<div className="flex items-center gap-2">
+						{filename && <span className="text-xs text-neutral-400">{filename}</span>}
+						{!filename && <span className="text-xs uppercase text-neutral-500">{language}</span>}
+					</div>
+					<button
+						onClick={handleCopy}
+						className="inline-flex items-center gap-1 rounded-md px-2 py-1 text-xs text-neutral-400 transition-colors hover:bg-neutral-800 hover:text-neutral-200"
+						aria-label="复制代码"
+					>
+						{copied ? (
+							<Check className="h-3.5 w-3.5 text-success" />
+						) : (
+							<Copy className="h-3.5 w-3.5" />
+						)}
+						{copied ? '已复制' : '复制'}
+					</button>
+				</div>
+			)}
+			<pre className="overflow-x-auto p-4 text-sm leading-relaxed">
+				<code className="font-mono text-neutral-200">{code}</code>
+			</pre>
+		</div>
+	);
+});

package/src/molecules/ConfirmDialog.tsx

@@ -0,0 +1,101 @@
+import React, { useCallback, useEffect } from 'react';
+import { AlertTriangle, X } from 'lucide-react';
+
+interface ConfirmDialogProps {
+	open: boolean;
+	title: string;
+	description: string;
+	confirmText?: string;
+	cancelText?: string;
+	variant?: 'danger' | 'warning' | 'neutral';
+	onConfirm: () => void;
+	onCancel: () => void;
+}
+
+const variantStyles = {
+	danger: {
+		icon: 'bg-danger-soft text-danger-text',
+		confirm: 'bg-danger text-white hover:opacity-90',
+	},
+	warning: {
+		icon: 'bg-warning-soft text-warning-text',
+		confirm: 'bg-warning text-white hover:opacity-90',
+	},
+	neutral: {
+		icon: 'bg-brand-soft text-brand',
+		confirm: 'bg-[var(--color-brand)] text-white hover:opacity-90',
+	},
+};
+
+export const ConfirmDialog = React.memo(function ConfirmDialog({
+	open,
+	title,
+	description,
+	confirmText = '确认',
+	cancelText = '取消',
+	variant = 'neutral',
+	onConfirm,
+	onCancel,
+}: ConfirmDialogProps) {
+	const handleKeyDown = useCallback(
+		(e: KeyboardEvent) => {
+			if (e.key === 'Escape') onCancel();
+		},
+		[onCancel],
+	);
+
+	useEffect(() => {
+		if (open) {
+			document.addEventListener('keydown', handleKeyDown);
+			document.body.style.overflow = 'hidden';
+		}
+		return () => {
+			document.removeEventListener('keydown', handleKeyDown);
+			document.body.style.overflow = '';
+		};
+	}, [open, handleKeyDown]);
+
+	if (!open) return null;
+
+	const style = variantStyles[variant];
+
+	return (
+		<div className="fixed inset-0 z-50 flex items-center justify-center p-4">
+			<div className="absolute inset-0 bg-black/40 backdrop-blur-sm" onClick={onCancel} />
+			<div className="relative w-full max-w-md rounded-xl border border-[var(--color-border-subtle)] bg-[var(--color-bg-surface)] p-6 shadow-brand">
+				<button
+					onClick={onCancel}
+					className="absolute right-4 top-4 text-[var(--color-text-muted)] hover:text-[var(--color-text-secondary)]"
+					aria-label="关闭"
+				>
+					<X className="h-4 w-4" />
+				</button>
+				<div className="flex items-start gap-4">
+					<div
+						className={`flex h-10 w-10 shrink-0 items-center justify-center rounded-full ${style.icon}`}
+					>
+						<AlertTriangle className="h-5 w-5" />
+					</div>
+					<div>
+						<h3 className="text-base font-semibold text-[var(--color-text-primary)]">{title}</h3>
+						<p className="mt-1 text-sm text-[var(--color-text-secondary)]">{description}</p>
+					</div>
+				</div>
+				<div className="mt-6 flex justify-end gap-3">
+					<button
+						onClick={onCancel}
+						className="rounded-md border border-[var(--color-border-subtle)] bg-[var(--color-bg-surface)] px-4 py-2 text-sm font-medium text-[var(--color-text-primary)] transition-colors hover:bg-[var(--color-bg-muted)]"
+					>
+						{cancelText}
+					</button>
+					<button
+						onClick={onConfirm}
+						className={`rounded-md px-4 py-2 text-sm font-medium transition-colors ${style.confirm}`}
+					>
+						{confirmText}
+					</button>
+				</div>
+			</div>
+		</div>
+	);
+});

package/src/molecules/ConsolePageHeader.tsx

@@ -0,0 +1,45 @@
+'use client';
+
+import React from 'react';
+
+// ConsolePageHeader —— 控制台页面的页头：左对齐标题 + 右侧操作槽 + 可选副标题。
+//
+// 为什么不是 DS 里已有的 PageHeader：那是**营销 hero**（text-center + text-3xl/sm:text-4xl），
+// 落地页在用；控制台页头是另一种东西（左对齐 + text-xl/font-semibold + 右侧操作槽）。
+// 两者**同名不同物**，互相替换会把控制台的密度打散 —— 所以这里另立一件，PageHeader 保持原样（D5）。
+//
+// 收敛前实测（2026-10）：三个控制台在 **106 个页面**里把这段页头内联写了 106 遍，
+// 包裹容器的 className 有 **11 种**（mb-4 / mb-6、有没有 justify-between、有没有响应式断点各不相同）。
+// 这里固定成一种：窄屏纵向堆叠、sm 起横向两端对齐、gap-3、下边距 mb-6 —— 与其中 55 处的多数派一致。
+
+export interface ConsolePageHeaderProps {
+	/** 页面标题。 */
+	title: React.ReactNode;
+	/** 标题下方的说明文字（可选）。 */
+	description?: React.ReactNode;
+	/** 右侧操作区（查询 / 导出 / 新建…）。窄屏时落到标题下方。 */
+	actions?: React.ReactNode;
+	/** 追加类名。用于个别页面的例外情况；**间距由组件自己定**，不通过这个口子改。 */
+	className?: string;
+}
+
+export const ConsolePageHeader = React.memo(function ConsolePageHeader({
+	title,
+	description,
+	actions,
+	className = '',
+}: ConsolePageHeaderProps) {
+	return (
+		<div
+			className={`mb-6 flex flex-col items-start gap-3 sm:flex-row sm:items-center sm:justify-between ${className}`}
+		>
+			<div className="min-w-0">
+				<h1 className="text-xl font-semibold">{title}</h1>
+				{description ? (
+					<div className="mt-1 text-sm text-[var(--color-text-secondary)]">{description}</div>
+				) : null}
+			</div>
+			{actions ? <div className="flex flex-wrap items-center gap-2 sm:shrink-0">{actions}</div> : null}
+		</div>
+	);
+});

package/src/molecules/EmptyState.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+import { Inbox } from 'lucide-react';
+
+interface EmptyStateProps {
+	title?: string;
+	description?: string;
+	icon?: React.ReactNode;
+}
+
+export const EmptyState = React.memo(function EmptyState({
+	title = '暂无数据',
+	description = '当前没有可显示的内容。',
+	icon,
+}: EmptyStateProps) {
+	return (
+		<div className="flex flex-col items-center justify-center rounded-xl border border-dashed border-[var(--color-border-subtle)] bg-[var(--color-bg-muted)] px-4 py-12 text-center">
+			<div className="flex h-12 w-12 items-center justify-center rounded-full bg-[var(--color-bg-muted)] text-[var(--color-text-muted)]">
+				{icon ?? <Inbox className="h-6 w-6" />}
+			</div>
+			<h3 className="mt-4 text-base font-semibold text-[var(--color-text-primary)]">{title}</h3>
+			<p className="mt-1 text-sm text-[var(--color-text-secondary)]">{description}</p>
+		</div>
+	);
+});

package/src/molecules/ErrorBoundary.tsx

@@ -0,0 +1,142 @@
+/**
+ * 权威版 ErrorBoundary —— 由 pnpm sync:consumers 下发到各站点的 packages/ui/src/molecules/。
+ *
+ * 为什么放在设计系统仓库里：
+ *   packages/ui 是共享组件库，却在 9 个站点各存一份。逐文件比对（2026-09）后 29 个文件里
+ *   只有这一个真正不同，而且差异只在界面默认文案上：
+ *     7 个站点用英文（Something went wrong / An unexpected error occurred… / Reload Page）
+ *     admin 用「出现错误 / 发生意外错误，请刷新页面重试。/ 重新加载页面」
+ *     platform 用「页面出错了 / 发生了未知错误，请刷新页面重试。/ 刷新页面」
+ *   三份都是 97 行、导出与逻辑完全相同。同一个错误组件在不同 portal 显示不同措辞，
+ *   这是文案不统一而非实现分叉（ui 仓库 KI-013）。
+ *
+ * 语言判定为什么不用 react-i18next：
+ *   packages/ui 里 LanguageSwitcher 确实用了 useTranslation，但各 portal 的 t() 约定并不统一——
+ *   例如 auth 的 useI18n 走的是 t('flat.' + key)（前缀 flat.），而那个 wrapper 位于
+ *   各 portal 的 apps 目录下（apps slash 站点名 slash src slash lib），不在 packages/ui 内，
+ *   组件够不着；键前缀约定也不一致。
+ *   所以这里改用**零依赖信号**：document.documentElement.lang。
+ *
+ *   ⚠ 2026-10-03 实测更正：原注释写「各 portal 的 I18nProvider 都在 languageChanged 时调用 syncHtmlLang 同步它」——
+ *   **那是不成立的**：全舰队当时只有 authenticator 有这段同步，user/admin/platform 都没有。
+ *   后果很具体：它们的错误页只会在中文与英文之间**永远停在 index.html 的 zh-CN**，
+ *   而 user 当时靠一层本地包装用 i18n 覆盖文案绕过了这一点。
+ *   现在四个门户都补上了这 7 行同步（user 因此可以删掉那层包装），这条断言才真正成立 ——
+ *   但**依赖它的组件不该假设它天然成立**：将来新增门户若忘了同步，错误页会静默地只显示一种语言。
+ *   代价：语言切换时错误页不会实时重渲染（错误边界本就只在出错时渲染一次，可接受）。
+ *   若将来统一了跨 portal 的键约定，应改为走 i18n，而不是继续在组件里放文案。
+ *
+ * 对外 API 不变：<ErrorBoundary>{children}</ErrorBoundary>，仍可传 title / message / retryLabel
+ * 覆盖默认文案（props 优先于内置字典）。
+ */
+import { Component, type ReactNode } from 'react';
+import { AlertTriangle } from 'lucide-react';
+
+interface ErrorBoundaryProps {
+	children: ReactNode;
+	fallback?: ReactNode;
+	title?: string;
+	message?: string;
+	retryLabel?: string;
+	devMode?: boolean;
+}
+
+interface ErrorBoundaryState {
+	hasError: boolean;
+	error?: Error;
+}
+
+const TEXT = {
+	zh: {
+		devTitle: '开发模式错误边界',
+		unknown: '未知错误',
+		title: '页面出错了',
+		message: '发生了未知错误，请刷新页面重试。',
+		retry: '刷新页面',
+		reload: '刷新',
+	},
+	en: {
+		devTitle: 'Dev Error Boundary',
+		unknown: 'Unknown error',
+		title: 'Something went wrong',
+		message: 'An unexpected error occurred. Please try refreshing the page.',
+		retry: 'Reload Page',
+		reload: 'Reload',
+	},
+};
+
+/** 各 portal 由 I18nProvider 同步 <html lang>（zh-CN / en-US），以此判定文案语言。 */
+function text(): typeof TEXT.zh {
+	if (typeof document === 'undefined') return TEXT.zh;
+	const lang = (document.documentElement.getAttribute('lang') || '').toLowerCase();
+	return lang.startsWith('zh') ? TEXT.zh : TEXT.en;
+}
+
+export class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+	constructor(props: ErrorBoundaryProps) {
+		super(props);
+		this.state = { hasError: false };
+	}
+
+	static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+		return { hasError: true, error };
+	}
+
+	componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
+		if (this.props.devMode) {
+			console.error('[ErrorBoundary] caught:', error, errorInfo);
+		}
+	}
+
+	render() {
+		const { children, fallback, title, message, retryLabel, devMode } = this.props;
+		const T = text();
+
+		if (this.state.hasError) {
+			if (fallback) return fallback;
+
+			if (devMode) {
+				return (
+					<div className="flex min-h-[50vh] flex-col items-center justify-center p-8 text-center" role="alert">
+						<div className="flex h-16 w-16 items-center justify-center rounded-full bg-rose-50">
+							<AlertTriangle size={32} className="text-rose-600" />
+						</div>
+						<h2 className="mt-4 text-lg font-semibold text-neutral-900 dark:text-neutral-100">{T.devTitle}</h2>
+						<p className="mt-2 max-w-lg text-sm text-neutral-500 dark:text-neutral-400">
+							{this.state.error?.message || T.unknown}
+						</p>
+						{this.state.error?.stack && (
+							<pre className="mt-4 max-h-60 max-w-2xl overflow-auto rounded-xs bg-neutral-100 p-3 text-left text-xs text-neutral-600 dark:bg-neutral-800 dark:text-neutral-400">
+								{this.state.error.stack}
+							</pre>
+						)}
+						<button
+							onClick={() => window.location.reload()}
+							className="mt-6 rounded-md bg-primary-600 px-4 py-2 text-sm font-medium text-white hover:bg-primary-700 transition-colors"
+						>
+							{T.reload}
+						</button>
+					</div>
+				);
+			}
+
+			return (
+				<div className="flex min-h-[50vh] flex-col items-center justify-center p-8 text-center" role="alert">
+					<div className="flex h-16 w-16 items-center justify-center rounded-full bg-rose-50 dark:bg-rose-900/20">
+						<AlertTriangle size={32} className="text-rose-600" />
+					</div>
+					<h2 className="mt-4 text-lg font-semibold text-neutral-900 dark:text-neutral-100">{title || T.title}</h2>
+					<p className="mt-2 text-sm text-neutral-500 dark:text-neutral-400">{message || T.message}</p>
+					<button
+						onClick={() => window.location.reload()}
+						className="mt-6 rounded-md bg-primary-600 px-4 py-2 text-sm font-medium text-white hover:bg-primary-700 transition-colors"
+					>
+						{retryLabel || T.retry}
+					</button>
+				</div>
+			);
+		}
+
+		return children;
+	}
+}

package/src/molecules/ErrorState.tsx

@@ -0,0 +1,52 @@
+import { AlertTriangle, RefreshCw } from 'lucide-react';
+
+export interface ErrorStateProps {
+	title?: string;
+	description?: string;
+	message?: string;
+	onRetry?: () => void;
+	action?: { label: string; onClick: () => void };
+	className?: string;
+}
+
+export function ErrorState({
+	title,
+	description,
+	message,
+	onRetry,
+	action,
+	className = '',
+}: ErrorStateProps) {
+	const displayTitle = title || '加载失败';
+	const displayMessage = description || message || '请稍后重试';
+
+	return (
+		<div
+			className={`flex flex-col items-center justify-center gap-3 rounded-lg border border-danger-soft bg-danger-soft px-4 py-8 text-center ${className}`}
+		>
+			<div className="flex h-14 w-14 items-center justify-center rounded-full bg-danger-soft">
+				<AlertTriangle className="h-7 w-7 text-danger" />
+			</div>
+			<div>
+				<p className="text-sm font-medium text-[var(--color-text-primary)]">{displayTitle}</p>
+				<p className="mt-1 text-xs text-[var(--color-text-secondary)]">{displayMessage}</p>
+			</div>
+			{action ? (
+				<button
+					onClick={action.onClick}
+					className="inline-flex items-center gap-1.5 rounded-md border border-[var(--color-border-subtle)] bg-[var(--color-bg-surface)] px-3 py-1.5 text-xs text-[var(--color-text-primary)] hover:bg-[var(--color-bg-muted)]"
+				>
+					{action.label}
+				</button>
+			) : onRetry ? (
+				<button
+					onClick={onRetry}
+					className="inline-flex items-center gap-1.5 rounded-md border border-danger-soft bg-[var(--color-bg-surface)] px-3 py-1.5 text-xs text-danger-text hover:bg-danger-soft"
+				>
+					<RefreshCw className="h-3.5 w-3.5" />
+					重试
+				</button>
+			) : null}
+		</div>
+	);
+}

package/src/molecules/FormField.tsx

@@ -0,0 +1,89 @@
+'use client';
+
+// FormField —— 一个字段的外壳：标签 + 控件槽 + 帮助/错误文本 + 无障碍接线。
+//
+// 为什么需要它：设计系统有 Input / Label 两个 atom，但**没有「一个字段」这个概念**。
+// 于是每个站点自己拼：label 的 htmlFor 常常不写、错误文本的 id 与 aria-describedby 从来没接上、
+// 必填标记各写各的。实测全舰队 50 处 react-hook-form 的 register( 调用点（user 10 / auth 34 / status 4 / trust 2），
+// 每一处都在重新决定「标签怎么摆、错误颜色是什么、读屏器怎么念」。
+//
+// 它**不依赖任何表单库**：配合 react-hook-form 的 register、配合 Controller、配合自研控件都能用。
+// 绑定 react-hook-form 的那一组（把 useController 也包掉）在 @autional/ui/rhf 入口。
+
+import * as React from 'react';
+
+export interface FormFieldProps {
+	/** 标签文案。不给就只渲染控件与错误/帮助文本。 */
+	label?: string;
+	/** 常显的帮助文本。有错误时被错误文本取代（不会同时显示两行）。 */
+	hint?: string;
+	/** 错误文案。有值即视为无效：控件会拿到 aria-invalid，读屏器会念到这条。 */
+	error?: string;
+	/** 必填标记。只影响外观与 `aria-required`，**不做校验** —— 校验归表单库。 */
+	required?: boolean;
+	/** 覆盖自动生成的控件 id。仅在同一个字段需要被外部引用时才需要。 */
+	id?: string;
+	className?: string;
+	children: React.ReactNode;
+}
+
+interface FieldA11y {
+	id: string;
+	describedBy?: string;
+	invalid: boolean;
+}
+
+const FieldA11yContext = React.createContext<FieldA11y | null>(null);
+
+/** 供控件取用外壳生成的 id 与 aria 接线（@autional/ui/rhf 的绑定控件已经替你接了）。 */
+export function useFormFieldA11y(): FieldA11y | null {
+	return React.useContext(FieldA11yContext);
+}
+
+export function FormField({
+	label,
+	hint,
+	error,
+	required = false,
+	id,
+	className = '',
+	children,
+}: FormFieldProps) {
+	const autoId = React.useId();
+	const fieldId = id ?? autoId;
+	const errorId = fieldId + '-error';
+	const hintId = fieldId + '-hint';
+	const invalid = !!error;
+	// 帮助文本与错误文本用同一个 aria-describedby 槽位：错误出现时它取代帮助文本，
+	// 于是读屏器不会同时念两条互相矛盾的说明。
+	const describedBy = invalid ? errorId : hint ? hintId : undefined;
+	const a11y = React.useMemo<FieldA11y>(
+		() => ({ id: fieldId, describedBy, invalid }),
+		[fieldId, describedBy, invalid],
+	);
+
+	return (
+		<div className={'space-y-1.5 ' + className}>
+			{label && (
+				<label htmlFor={fieldId} className="block text-sm font-medium text-[var(--color-text-primary)]">
+					{label}
+					{required && (
+						<span className="ml-0.5 text-[var(--color-danger)]" aria-hidden="true">
+							*
+						</span>
+					)}
+				</label>
+			)}
+			<FieldA11yContext.Provider value={a11y}>{children}</FieldA11yContext.Provider>
+			{invalid ? (
+				<p id={errorId} role="alert" className="text-xs text-[var(--color-danger)]">
+					{error}
+				</p>
+			) : hint ? (
+				<p id={hintId} className="text-xs text-[var(--color-text-secondary)]">
+					{hint}
+				</p>
+			) : null}
+		</div>
+	);
+}

package/src/molecules/LanguageSwitcher.tsx

@@ -0,0 +1,39 @@
+import { useTranslation } from 'react-i18next';
+import { Globe } from 'lucide-react';
+
+interface LanguageSwitcherProps {
+	className?: string;
+	labelEn?: string;
+	labelZh?: string;
+	showIcon?: boolean;
+	currentLang?: string;
+	onToggle?: (nextLang: string) => void;
+}
+
+export function LanguageSwitcher({
+	className = '',
+	labelEn,
+	labelZh,
+	showIcon = false,
+	currentLang,
+	onToggle,
+}: LanguageSwitcherProps) {
+	const { i18n } = useTranslation();
+	const lang = currentLang ?? i18n.language;
+
+	const toggle = () => {
+		const next = lang === 'zh-CN' ? 'en-US' : 'zh-CN';
+		if (onToggle) {
+			onToggle(next);
+		} else {
+			i18n.changeLanguage(next);
+		}
+	};
+
+	return (
+		<button type="button" onClick={toggle} className={`text-xs transition-colors ${className}`}>
+			{showIcon && <Globe className="h-3.5 w-3.5 shrink-0" />}
+			{lang === 'zh-CN' ? labelEn || 'EN' : labelZh || '中文'}
+		</button>
+	);
+}