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

package/src/atoms/Button.tsx

@@ -0,0 +1,69 @@
+import * as React from 'react';
+
+export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+	variant?: 'primary' | 'secondary' | 'outline' | 'ghost' | 'danger';
+	size?: 'sm' | 'md' | 'lg';
+	isLoading?: boolean;
+	fullWidth?: boolean;
+}
+
+export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
+	(
+		{
+			variant = 'primary',
+			size = 'md',
+			isLoading,
+			fullWidth,
+			children,
+			className = '',
+			disabled,
+			...props
+		},
+		ref,
+	) => {
+		const base =
+			'inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50';
+
+		const variants: Record<string, string> = {
+			primary: 'bg-[var(--color-brand)] text-[var(--color-on-brand)] hover:bg-[var(--color-brand-hover)]',
+			secondary: 'bg-[var(--color-bg-muted)] text-[var(--color-text-primary)] hover:opacity-80',
+			outline:
+				'border border-[var(--color-border-subtle)] bg-transparent hover:bg-[var(--color-bg-muted)] text-[var(--color-text-primary)]',
+			ghost: 'bg-transparent hover:bg-[var(--color-bg-muted)] text-[var(--color-text-primary)]',
+			danger: 'bg-[var(--color-danger)] text-white hover:opacity-80',
+		};
+
+		const sizes: Record<string, string> = {
+			sm: 'h-8 px-3 text-xs',
+			md: 'h-10 px-4 text-sm',
+			lg: 'h-12 px-6 text-base',
+		};
+
+		const width = fullWidth ? 'w-full' : '';
+		const cls = `${base} ${variants[variant]} ${sizes[size]} ${width} ${className}`;
+
+		return (
+			<button ref={ref} className={cls} disabled={disabled || isLoading} {...props}>
+				{isLoading && (
+					<svg className="mr-2 h-4 w-4 animate-spin" viewBox="0 0 24 24" fill="none">
+						<circle
+							className="opacity-25"
+							cx="12"
+							cy="12"
+							r="10"
+							stroke="currentColor"
+							strokeWidth="4"
+						/>
+						<path
+							className="opacity-75"
+							fill="currentColor"
+							d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z"
+						/>
+					</svg>
+				)}
+				{children}
+			</button>
+		);
+	},
+);
+Button.displayName = 'Button';

package/src/atoms/Input.tsx

@@ -0,0 +1,19 @@
+import * as React from 'react';
+import { fieldControlClass, fieldControlHeight } from '../internal/field-styles';
+
+export interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {
+	error?: string;
+}
+
+// 外观来自 ../internal/field-styles —— 与 @autional/ui/rhf 的绑定控件同一份，不各自维护。
+export const Input = React.forwardRef<HTMLInputElement, InputProps>(
+	({ className = '', error, ...props }, ref) => {
+		return (
+			<div className="w-full">
+				<input ref={ref} className={fieldControlClass(!!error, fieldControlHeight + ' ' + className)} {...props} />
+				{error && <p className="mt-1 text-xs text-[var(--color-danger)]">{error}</p>}
+			</div>
+		);
+	},
+);
+Input.displayName = 'Input';

package/src/atoms/Label.tsx

@@ -0,0 +1,18 @@
+import * as React from 'react';
+
+export interface LabelProps extends React.LabelHTMLAttributes<HTMLLabelElement> {
+	required?: boolean;
+}
+
+export const Label = React.forwardRef<HTMLLabelElement, LabelProps>(
+	({ children, className = '', required, ...props }, ref) => {
+		const cls = `text-sm font-medium leading-none ${className}`;
+		return (
+			<label ref={ref} className={cls} {...props}>
+				{children}
+				{required && <span className="text-danger ml-0.5">*</span>}
+			</label>
+		);
+	},
+);
+Label.displayName = 'Label';

package/src/atoms/StatusBadge.tsx

@@ -0,0 +1,27 @@
+import React from 'react';
+import { SOFT_TEXT } from '../internal/semantic-styles';
+
+export type StatusVariant = 'success' | 'warning' | 'danger' | 'info' | 'neutral';
+
+interface StatusBadgeProps {
+	variant?: StatusVariant;
+	children: React.ReactNode;
+	className?: string;
+}
+
+// 配对的唯一来源在 internal/semantic-styles.ts（Alert 与它共用同一份）。
+const variantStyles: Record<StatusVariant, string> = SOFT_TEXT;
+
+export const StatusBadge = React.memo(function StatusBadge({
+	variant = 'neutral',
+	children,
+	className = '',
+}: StatusBadgeProps) {
+	return (
+		<span
+			className={`inline-flex items-center gap-1 rounded-full px-2 py-0.5 text-xs font-medium ${variantStyles[variant]} ${className}`}
+		>
+			{children}
+		</span>
+	);
+});

package/src/atoms/Toggle.tsx

@@ -0,0 +1,43 @@
+import React from 'react';
+
+interface ToggleProps {
+	checked: boolean;
+	onChange: () => void;
+	disabled?: boolean;
+	size?: 'sm' | 'md';
+	className?: string;
+}
+
+const sizeClasses: Record<string, { track: string; circle: string; translate: string }> = {
+	md: { track: 'h-6 w-11', circle: 'h-5 w-5', translate: 'translate-x-5' },
+	sm: { track: 'h-5 w-9', circle: 'h-4 w-4', translate: 'translate-x-4' },
+};
+
+export const Toggle = React.memo(function Toggle({
+	checked,
+	onChange,
+	disabled = false,
+	size = 'md',
+	className = '',
+}: ToggleProps) {
+	const s = sizeClasses[size];
+
+	return (
+		<button
+			type="button"
+			role="switch"
+			aria-checked={checked}
+			disabled={disabled}
+			onClick={onChange}
+			className={`relative inline-flex shrink-0 items-center rounded-full transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 ${
+				checked ? 'bg-primary-600' : 'bg-neutral-200 dark:bg-neutral-600'
+			} ${s.track} ${className}`}
+		>
+			<span
+				className={`inline-block rounded-full bg-white shadow-soft transition-transform ${
+					checked ? s.translate : 'translate-x-0.5'
+				} ${s.circle}`}
+			/>
+		</button>
+	);
+});

package/src/atoms/index.ts

@@ -0,0 +1,9 @@
+export { Button } from './Button';
+export type { ButtonProps } from './Button';
+export { Input } from './Input';
+export type { InputProps } from './Input';
+export { Label } from './Label';
+export type { LabelProps } from './Label';
+export { StatusBadge } from './StatusBadge';
+export type { StatusVariant } from './StatusBadge';
+export { Toggle } from './Toggle';

package/src/context/ThemeProvider.tsx

@@ -0,0 +1,78 @@
+import React, { createContext, useContext, useState, useEffect, useCallback } from 'react';
+
+export type Theme = 'light' | 'dark';
+
+interface ThemeContextValue {
+	theme: Theme;
+	toggle: () => void;
+}
+
+const ThemeContext = createContext<ThemeContextValue>({
+	theme: 'light',
+	toggle: () => {},
+});
+
+interface ThemeProviderProps {
+	children: React.ReactNode;
+	storageKey?: string;
+	/**
+	 * 深色档写入 data-theme 的值（默认 'dark'）。
+	 * 站点若使用完整深色变体（如 authenticator 的 [data-theme="authenticator"]），
+	 * 在这里传变体名；其余站点不传，行为不变。
+	 */
+	darkThemeName?: string;
+	/**
+	 * 无存储值（首次访问）时的兜底档；缺省沿用 prefers-color-scheme → light 的既有行为。
+	 * dark-first 的站点传 'dark'（与站点 boot script 的兜底保持一致）。
+	 */
+	defaultTheme?: Theme;
+}
+
+export function ThemeProvider({
+	children,
+	storageKey = 'autional-theme',
+	darkThemeName = 'dark',
+	defaultTheme,
+}: ThemeProviderProps) {
+	const [theme, setTheme] = useState<Theme>(() => {
+		if (typeof window !== 'undefined') {
+			try {
+				const saved = localStorage.getItem(storageKey) as Theme;
+				if (saved === 'dark' || saved === 'light') return saved;
+			} catch (e) {
+				// 存储不可用（隐私模式/被禁用）：与站点 boot script 的兜底口径一致，继续走默认链
+			}
+			if (defaultTheme) return defaultTheme;
+			if (window.matchMedia('(prefers-color-scheme: dark)').matches) return 'dark';
+		}
+		return 'light';
+	});
+
+	useEffect(() => {
+		const root = document.documentElement;
+		if (theme === 'dark') {
+			root.classList.add('dark');
+		} else {
+			root.classList.remove('dark');
+		}
+		root.setAttribute('data-theme', theme === 'dark' ? darkThemeName : 'light');
+	}, [theme, darkThemeName]);
+
+	const toggle = useCallback(() => {
+		setTheme((prev) => {
+			const next = prev === 'dark' ? 'light' : 'dark';
+			try {
+				localStorage.setItem(storageKey, next);
+			} catch (e) {
+				// 存储不可用（隐私模式/被禁用）：本次切换仍生效，仅不持久化
+			}
+			return next;
+		});
+	}, [storageKey]);
+
+	return <ThemeContext.Provider value={{ theme, toggle }}>{children}</ThemeContext.Provider>;
+}
+
+export function useTheme() {
+	return useContext(ThemeContext);
+}

package/src/i18n/index.ts

@@ -0,0 +1,36 @@
+import { UI_I18N_NS, uiI18nResources } from './resources';
+
+export { UI_I18N_NS, uiI18nResources };
+
+/** 当前语言的内置文案；未收录的 key 返回 undefined（组件据此决定最终回落）。 */
+export function uiText(lang: string | undefined, key: string): string | undefined {
+	const bundle = (lang ?? '').toLowerCase().startsWith('zh')
+		? uiI18nResources['zh-CN']
+		: uiI18nResources['en-US'];
+	return bundle[key];
+}
+
+export interface UiI18nHost {
+	addResourceBundle(
+		lng: string,
+		ns: string,
+		resources: Record<string, unknown>,
+		deep?: boolean,
+		overwrite?: boolean,
+	): unknown;
+}
+
+/**
+ * 消费站在自己的 i18n 初始化时调用一次，将组件文案注册进 i18next（ns 'autional-ui'）。
+ * 注册后文案可经站点 i18next 覆盖/扩展（不注册也能工作——组件按站点语言回落内置表）：
+ *   i18n.addResourceBundle(lang, 'autional-ui', { 'portal.names.admin': '...' }, true, true)
+ * 短码 'zh'/'en' 一并注册：站点语言可能是裸码（如 navigator 检出的 'en'）。
+ */
+export function registerUiI18n(instance: UiI18nHost): void {
+	for (const lng of ['zh-CN', 'zh']) {
+		instance.addResourceBundle(lng, UI_I18N_NS, uiI18nResources['zh-CN'], true, false);
+	}
+	for (const lng of ['en-US', 'en']) {
+		instance.addResourceBundle(lng, UI_I18N_NS, uiI18nResources['en-US'], true, false);
+	}
+}

package/src/i18n/resources.ts

@@ -0,0 +1,56 @@
+/**
+ * @autional/ui 组件文案的单一出处（i18n 资源形态，扁平点键——对齐消费站
+ * `keySeparator: false` 的扁平键约定）。
+ *
+ * 消费站在自己的 i18n 初始化时调用 `registerUiI18n(i18n)` 注册本表；未注册时
+ * 组件按站点当前语言直接回落本表（i18next defaultValue），行为一致。
+ * 门户名措辞对齐 auth dashboard 的 `dashboard.*` 口径（同一门户一处名字）。
+ */
+
+export const UI_I18N_NS = 'autional-ui';
+
+export const uiI18nResources: Record<'zh-CN' | 'en-US', Record<string, string>> = {
+	'zh-CN': {
+		'portal.switcher': '切换门户',
+		'portal.names.admin': '管理后台',
+		'portal.names.auth': '登录中心',
+		'portal.names.security': '安全中心',
+		'portal.names.user': '用户中心',
+		'portal.names.authenticator': '身份验证器应用',
+		'portal.names.status': '状态页',
+		'portal.names.trust': '信任中心',
+		'portal.names.platform': '平台控制台',
+		'portal.names.developer': '开发者门户',
+		'portal.names.landing': '门户首页',
+		'portal.names.brand': '品牌站',
+		// 整页占位（控制台的 PageLoading / PageError）。文案与 admin 站点里原有的
+		// pageStatus.* 三键**逐字一致** —— 合并只许改实现，不许顺手改用户看到的字。
+		'modal.close': '关闭',
+		'pageStatus.loading': '加载中…',
+		'pageStatus.loadError': '数据加载失败',
+		'pageStatus.retry': '重试',
+		// ThemeToggle 默认文案（UP-04：原为组件内硬编码中文，EN 站点顶栏出现中文标签）
+		'theme.toggleDark': '切换到深色模式',
+		'theme.toggleLight': '切换到浅色模式',
+	},
+	'en-US': {
+		'portal.switcher': 'Switch portal',
+		'portal.names.admin': 'Admin Console',
+		'portal.names.auth': 'Sign-in',
+		'portal.names.security': 'Security Dashboard',
+		'portal.names.user': 'End-User Portal',
+		'portal.names.authenticator': 'Authenticator App',
+		'portal.names.status': 'Status Page',
+		'portal.names.trust': 'Trust Center',
+		'portal.names.platform': 'Platform Console',
+		'portal.names.developer': 'Developer Portal',
+		'portal.names.landing': 'Home',
+		'portal.names.brand': 'Brand Site',
+		'modal.close': 'Close',
+		'pageStatus.loading': 'Loading...',
+		'pageStatus.loadError': 'Data loading failed',
+		'pageStatus.retry': 'Retry',
+		'theme.toggleDark': 'Switch to dark mode',
+		'theme.toggleLight': 'Switch to light mode',
+	},
+};

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from './atoms';
+export * from './molecules';
+export { ThemeProvider, useTheme } from './context/ThemeProvider';
+export type { Theme } from './context/ThemeProvider';
+export { UI_I18N_NS, uiI18nResources, registerUiI18n } from './i18n';
+export type { UiI18nHost } from './i18n';
+import './styles/globals.css';

package/src/internal/field-styles.ts

@@ -0,0 +1,14 @@
+// 表单控件的外观只有一份 —— Input atom 与 @autional/ui/rhf 的绑定控件都用它。
+// 各自复制一份类名串的后果不是「看起来一样」，而是「改了一处、另一处没变」：
+// 那正是这一层要消灭的东西（与 antd 组件级令牌同理，只是这里是一段 Tailwind 类）。
+
+const BASE =
+	'flex w-full rounded-md border bg-[var(--color-bg-surface)] px-3 py-2 text-sm text-[var(--color-text-primary)] placeholder:text-[var(--color-text-muted)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-brand)] focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50';
+
+/** 单行控件的高度。textarea 不给（它要能长高）。 */
+export const fieldControlHeight = 'h-10';
+
+export function fieldControlClass(invalid?: boolean, extra = ''): string {
+	const border = invalid ? 'border-[var(--color-danger)]' : 'border-[var(--color-border-subtle)]';
+	return `${BASE} ${border} ${extra}`.trim();
+}

package/src/internal/semantic-styles.ts

@@ -0,0 +1,28 @@
+// 语义色的「浅底 + 深字」配对 —— **唯一一份**（第 31 轮从 StatusBadge 里提出来，Alert 与它共用）。
+//
+// 为什么必须成对，两个理由（第二个才是关键）：
+//   ① 机制：preset 把颜色定义成裸 var(--color-danger)，没有 <alpha-value> 槽，
+//      Tailwind **生成不出** .bg-danger/10 —— 类写了、产物里没有规则、静默无底色。
+//   ② 设计：-soft 是**模式感知**的（light #fce4e4 / dark #490909），而且每一档都与对应的
+//      -text 配过对比度（success 5.51 / warning 4.85 / danger 4.65 / info 6.70）。
+//      原来的 text-success #52c41a 铺白底只有 2.27:1 —— 即便底色能出来，文字也不达 AA。
+//
+// neutral 顺带带上 dark: 变体：slate 不在设计系统色阶里，那条类同样生成不出来。
+export const SOFT_TEXT = {
+	success: 'bg-success-soft text-success-text',
+	warning: 'bg-warning-soft text-warning-text',
+	danger: 'bg-danger-soft text-danger-text',
+	info: 'bg-info-soft text-info-text',
+	neutral: 'bg-neutral-100 text-neutral-600 dark:bg-neutral-800 dark:text-neutral-300'
+} as const;
+
+export type SemanticVariant = keyof typeof SOFT_TEXT;
+
+// 边框与浅底同族：这样「着色块」的边界也有唯一来源，而不是各站自己挑 border-neutral-200 / border-amber-200。
+export const SOFT_BORDER: Record<SemanticVariant, string> = {
+	success: 'border-success-soft',
+	warning: 'border-warning-soft',
+	danger: 'border-danger-soft',
+	info: 'border-info-soft',
+	neutral: 'border-neutral-200 dark:border-neutral-700'
+};

package/src/internal/use-menu-button.ts

@@ -0,0 +1,144 @@
+import { useCallback, useEffect, useId, useRef, useState } from 'react';
+import type React from 'react';
+
+/**
+ * W3C APG「menu button」最小实现：UserMenu / PortalSwitcher 共用。
+ * trigger 携带 aria-haspopup/aria-expanded/aria-controls；菜单内 Arrow/Home/End
+ * roving focus（条目 tabIndex=-1，由组件自行标注 role="menuitem"）、Esc 关闭并还焦、
+ * Tab 关闭放行走位、焦点离开 trigger/菜单时关闭、document mousedown 外部点击关闭。
+ */
+export interface UseMenuButtonResult {
+	open: boolean;
+	setOpen: (next: boolean) => void;
+	triggerId: string;
+	menuId: string;
+	triggerRef: React.RefObject<HTMLButtonElement | null>;
+	menuRef: React.RefObject<HTMLDivElement | null>;
+	triggerProps: React.ButtonHTMLAttributes<HTMLButtonElement>;
+	menuProps: React.HTMLAttributes<HTMLDivElement>;
+}
+
+export function useMenuButton(): UseMenuButtonResult {
+	const [open, setOpen] = useState(false);
+	const rawId = useId();
+	const triggerId = `${rawId}-trigger`;
+	const menuId = `${rawId}-menu`;
+	const triggerRef = useRef<HTMLButtonElement | null>(null);
+	const menuRef = useRef<HTMLDivElement | null>(null);
+	const focusOnOpenRef = useRef<'first' | 'last' | null>(null);
+
+	const getItems = () =>
+		Array.from(menuRef.current?.querySelectorAll<HTMLElement>('[role="menuitem"]') ?? []);
+
+	const openWith = (position: 'first' | 'last') => {
+		if (open) {
+			const items = getItems();
+			(position === 'first' ? items[0] : items[items.length - 1])?.focus();
+		} else {
+			focusOnOpenRef.current = position;
+			setOpen(true);
+		}
+	};
+
+	useEffect(() => {
+		if (!open) return;
+		const position = focusOnOpenRef.current;
+		if (!position) return;
+		focusOnOpenRef.current = null;
+		const items = getItems();
+		(position === 'first' ? items[0] : items[items.length - 1])?.focus();
+	}, [open]);
+
+	useEffect(() => {
+		if (!open) return;
+		const onMouseDown = (event: MouseEvent) => {
+			const target = event.target as Node;
+			if (triggerRef.current?.contains(target) || menuRef.current?.contains(target)) return;
+			setOpen(false);
+		};
+		document.addEventListener('mousedown', onMouseDown);
+		return () => document.removeEventListener('mousedown', onMouseDown);
+	}, [open]);
+
+	const toggle = useCallback(() => setOpen((value) => !value), []);
+
+	const triggerKeyDown = (event: React.KeyboardEvent<HTMLButtonElement>) => {
+		if (event.key === 'ArrowDown') {
+			event.preventDefault();
+			openWith('first');
+		} else if (event.key === 'ArrowUp') {
+			event.preventDefault();
+			openWith('last');
+		} else if (event.key === 'Escape' && open) {
+			event.preventDefault();
+			setOpen(false);
+		}
+	};
+
+	// 焦点离开 widget（trigger + 菜单）即收起：覆盖「鼠标开菜单 → Tab 走位」时
+	// 面板仍悬浮、而菜单内 Tab 分支不触发的场景。焦点转入菜单项（键盘开菜单）除外。
+	const triggerBlur = (event: React.FocusEvent<HTMLButtonElement>) => {
+		if (!open) return;
+		const next = event.relatedTarget as Node | null;
+		if (next && menuRef.current?.contains(next)) return;
+		setOpen(false);
+	};
+
+	const menuKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
+		const items = getItems();
+		if (items.length === 0) return;
+		const current = items.indexOf(document.activeElement as HTMLElement);
+		switch (event.key) {
+			case 'ArrowDown':
+				event.preventDefault();
+				items[(current + 1) % items.length]?.focus();
+				break;
+			case 'ArrowUp':
+				event.preventDefault();
+				items[(current - 1 + items.length) % items.length]?.focus();
+				break;
+			case 'Home':
+				event.preventDefault();
+				items[0]?.focus();
+				break;
+			case 'End':
+				event.preventDefault();
+				items[items.length - 1]?.focus();
+				break;
+			case 'Escape':
+				event.preventDefault();
+				setOpen(false);
+				triggerRef.current?.focus();
+				break;
+			case 'Tab':
+				// 不拦截：收起菜单，放行浏览器默认走位
+				setOpen(false);
+				break;
+		}
+	};
+
+	return {
+		open,
+		setOpen,
+		triggerId,
+		menuId,
+		triggerRef,
+		menuRef,
+		triggerProps: {
+			id: triggerId,
+			type: 'button',
+			'aria-haspopup': 'menu',
+			'aria-expanded': open,
+			'aria-controls': open ? menuId : undefined,
+			onClick: toggle,
+			onKeyDown: triggerKeyDown,
+			onBlur: triggerBlur,
+		},
+		menuProps: {
+			id: menuId,
+			role: 'menu',
+			'aria-labelledby': triggerId,
+			onKeyDown: menuKeyDown,
+		},
+	};
+}

package/src/molecules/Alert.tsx

@@ -0,0 +1,100 @@
+'use client';
+
+import React from 'react';
+import { AlertTriangle, CheckCircle2, Info, X, XCircle } from 'lucide-react';
+import { SOFT_BORDER, SOFT_TEXT, type SemanticVariant } from '../internal/semantic-styles';
+
+// Alert —— 区块级提示（着色块）。
+//
+// 为什么要有它（第 31 轮实测）：
+//   · user 门户 **30 处手写**着色提示块，是 26 种排列组合（`bg-info-soft border-info-soft`、
+//     `bg-amber-50 border-amber-200 text-amber-800`、`bg-primary-50`…），
+//     其中「警告」有三种写法（amber-50 / warning-soft / amber-800 文字）；
+//   · 其余站在用 antd 的 `<Alert>`（security 14 / platform 19 / admin 9 / status 18 / authenticator 15 /
+//     trust 9）—— 那是**组件**，但它给的是 antd 出厂的四档配色，而不是设计系统自己的语义槽位。
+//   两边合起来 = 同一个语义（一句提示）在舰队里有六七种长相。
+//
+// 配色只走 internal/semantic-styles.ts 那一份 `-soft` / `-text` 配对（与 StatusBadge 同源）：
+// 那一份是模式感知的、且每一档都做过对比度验证（success 5.51 / warning 4.85 / danger 4.65 / info 6.70）。
+// 这也是为什么**不提供** `variant="brand"`：品牌色不是语义色，硬塞进来会让「提示的语义」和「品牌曝光」
+// 混成一个属性，而且 brand 那一档没有配过 -text。
+//
+// 刻意不做的事：不做 `banner`（整条横幅）、不做 `action` 槽（antd 有，但 fleet 里 0 处用它）。
+// 没有消费者的能力不进设计系统。
+export type AlertVariant = SemanticVariant;
+
+export interface AlertProps {
+	/** 语义档位，默认 info。amber（品牌色阶里的暖色）在语义上属于 warning。 */
+	variant?: AlertVariant;
+	/** 加粗的第一行（可选）。 */
+	title?: React.ReactNode;
+	/** 正文。 */
+	children?: React.ReactNode;
+	/** 图标：默认按档位给一个；显式传 `null` 可以不要图标。 */
+	icon?: React.ReactNode | null;
+	/**
+	 * 右侧动作区（一个按钮/链接）。
+	 *
+	 * 第 39 轮补上：D18 当初写的是「`action` 在舰队里 0 处使用」，**那条证据是错的** ——
+	 * 它来自「数 `<Alert` 出现次数」，而从没数过这些 Alert 用了哪些属性。
+	 * 按属性数过之后：三个控制台里 `action` 有 **5 个**真实消费者（security 4 + admin 1），
+	 * 那 5 处因此一直收不过来（它们不是配色不同，是形态不同）。够「≥2 份」的口径，所以补上。
+	 */
+	action?: React.ReactNode;
+	/** 是否可关闭（受控：真正的关闭动作在 onClose 里）。 */
+	closable?: boolean;
+	/** 点关闭按钮时调用。 */
+	onClose?: () => void;
+	/** 关闭按钮的无障碍标签。 */
+	closeLabel?: string;
+	/** 追加类名（间距归调用方，配色归组件）。 */
+	className?: string;
+}
+
+const DEFAULT_ICONS: Record<AlertVariant, React.ReactNode> = {
+	success: <CheckCircle2 className="h-4 w-4" />,
+	warning: <AlertTriangle className="h-4 w-4" />,
+	danger: <XCircle className="h-4 w-4" />,
+	info: <Info className="h-4 w-4" />,
+	neutral: <Info className="h-4 w-4" />
+};
+
+export const Alert = React.memo(function Alert({
+	variant = 'info',
+	title,
+	children,
+	icon,
+	action,
+	closable = false,
+	onClose,
+	closeLabel = '关闭',
+	className = ''
+}: AlertProps) {
+	const glyph = icon === null ? null : (icon ?? DEFAULT_ICONS[variant]);
+	return (
+		// role="alert" 与 antd 的 Alert 一致：这些块绝大多数是**动作之后**才出现的（结果/失败原因），
+		// 屏幕阅读器应当主动播报；这与「静态的一行说明」不同，所以调用方若把它当纯装饰用，
+		// 应当显式传 role={undefined}。
+		<div
+			role="alert"
+			className={`flex items-start gap-3 rounded-lg border p-4 ${SOFT_TEXT[variant]} ${SOFT_BORDER[variant]} ${className}`}
+		>
+			{glyph ? <span className="mt-0.5 shrink-0">{glyph}</span> : null}
+			<div className="min-w-0 flex-1">
+				{title ? <p className="font-semibold">{title}</p> : null}
+				{children ? <div className={title ? 'mt-1' : ''}>{children}</div> : null}
+			</div>
+			{action ? <div className="ml-auto shrink-0 self-center pl-2">{action}</div> : null}
+			{closable ? (
+				<button
+					type="button"
+					onClick={onClose}
+					aria-label={closeLabel}
+					className="-mr-1 -mt-1 shrink-0 rounded-md p-1 opacity-70 transition-opacity hover:opacity-100 focus-visible:outline focus-visible:outline-2"
+				>
+					<X className="h-4 w-4" />
+				</button>
+			) : null}
+		</div>
+	);
+});