@linhey/rhine-design 0.3.0 → 0.4.0

package/preview/theme-arknights.css

@@ -0,0 +1,234 @@
+/* Gallery-only chrome and decoration. Not imported by the public theme entry. */
+/* ================= 全局质感 ================= */
+
+/* 坐标网格底纹 + 顶部扫描线氛围 */
+.rhine-theme[data-rhine-theme="arknights"] .ds-workspace {
+  background-image:
+    linear-gradient(var(--ak-gridline) 1px, transparent 1px),
+    linear-gradient(90deg, var(--ak-gridline) 1px, transparent 1px);
+  background-size: 56px 56px;
+}
+
+/* ================= 字体性格 ================= */
+/* 标签、编号、说明全部等宽化，正文保持无衬线可读性 */
+.rhine-theme[data-rhine-theme="arknights"] .ds-caption,
+.rhine-theme[data-rhine-theme="arknights"] .ds-component-title>span,
+.rhine-theme[data-rhine-theme="arknights"] .ds-notes {
+  font-family: var(--rhine-mono);
+  letter-spacing: .04em;
+}
+
+/* ================= 顶栏 ================= */
+.rhine-theme[data-rhine-theme="arknights"] .ds-workspace-head {
+  position: relative;
+  background: rgba(11, 13, 16, .85);
+  border-bottom-color: var(--rhine-line);
+}
+.rhine-theme[data-rhine-theme="arknights"] .ds-workspace-head::after {
+  content: '';
+  position: absolute;
+  left: 32px;
+  bottom: -1px;
+  width: 160px;
+  height: 4px;
+  background: var(--ak-hazard);
+}
+
+/* ================= 侧栏：深色舱室 ================= */
+.rhine-theme[data-rhine-theme="arknights"] .ds-sidebar {
+  background: #08090c;
+  border-right-color: var(--rhine-line);
+}
+.rhine-theme[data-rhine-theme="arknights"] .ds-sidebar-brand {
+  border-bottom: 1px solid var(--rhine-line);
+  background: repeating-linear-gradient(-45deg, rgba(255, 212, 0, .07) 0 10px, transparent 10px 20px);
+}
+.rhine-theme[data-rhine-theme="arknights"] .ds-sidebar-brand>a { color: var(--rhine-ink); }
+.rhine-theme[data-rhine-theme="arknights"] .ds-sidebar-brand small { color: var(--ak-accent); letter-spacing: .18em; }
+.rhine-theme[data-rhine-theme="arknights"] .ds-sidebar-foot>span:first-child { color: var(--ak-accent); }
+
+/* ================= 主视觉 Hero ================= */
+.rhine-theme[data-rhine-theme="arknights"] .ds-kicker {
+  color: var(--ak-accent);
+  letter-spacing: 3px;
+}
+.rhine-theme[data-rhine-theme="arknights"] .ds-kicker::before { content: '// '; }
+.rhine-theme[data-rhine-theme="arknights"] .ds-hero h1 {
+  font-size: 56px;
+  font-weight: 700;
+  letter-spacing: 0;
+  line-height: 1.2;
+}
+.rhine-theme[data-rhine-theme="arknights"] .ds-hero h1>span {
+  color: var(--ak-accent);
+  /* 黄色高光下划线块 */
+  background: linear-gradient(transparent 62%, rgba(255, 212, 0, .22) 62%);
+}
+@media(max-width:760px) {
+  .rhine-theme[data-rhine-theme="arknights"] .ds-hero h1 { font-size: 34px; }
+}
+
+/* 总览卡片：大号幽灵编号 + 斜切 */
+.rhine-theme[data-rhine-theme="arknights"] .ds-overview-links { counter-reset: ak-link; }
+.rhine-theme[data-rhine-theme="arknights"] .ds-overview-links>a {
+  counter-increment: ak-link;
+  position: relative;
+  background: var(--ak-panel);
+  clip-path: polygon(0 0, calc(100% - var(--ak-cut)) 0, 100% var(--ak-cut), 100% 100%, 0 100%);
+  overflow: hidden;
+}
+.rhine-theme[data-rhine-theme="arknights"] .ds-overview-links>a::after {
+  content: counter(ak-link, decimal-leading-zero);
+  position: absolute;
+  right: 12px;
+  bottom: -14px;
+  font: 700 72px/1 var(--rhine-mono);
+  color: rgba(238, 240, 236, .05);
+  pointer-events: none;
+}
+.rhine-theme[data-rhine-theme="arknights"] .ds-overview-links>a:hover {
+  border-color: var(--ak-accent);
+  background: var(--ak-panel-hi);
+}
+.rhine-theme[data-rhine-theme="arknights"] .ds-overview-links>a:hover>span { color: var(--ak-accent); }
+
+/* ================= 章节标题 ================= */
+.rhine-theme[data-rhine-theme="arknights"] .ds-section-title { align-items:center; }
+.rhine-theme[data-rhine-theme="arknights"] .ds-section-title>span {
+  background: var(--ak-accent);
+  color: var(--ak-accent-ink);
+  font: 700 12px/1 var(--rhine-mono);
+  padding: 5px 8px;
+  clip-path: polygon(0 0, 100% 0, calc(100% - 6px) 100%, 0 100%);
+}
+.rhine-theme[data-rhine-theme="arknights"] .ds-section-title h2 { letter-spacing: .02em; }
+
+/* 组件标题等宽化 */
+.rhine-theme[data-rhine-theme="arknights"] .ds-component-title h3 { letter-spacing: .06em; }
+
+/* ================= 面板与容器：斜切 + 角标框架 ================= */
+.rhine-theme[data-rhine-theme="arknights"] .ds-logo-stage {
+  background: var(--ak-panel);
+  clip-path: polygon(0 0, calc(100% - var(--ak-cut)) 0, 100% var(--ak-cut), 100% 100%, 0 100%);
+}
+
+/* ================= Logo 展台 ================= */
+.rhine-theme[data-rhine-theme="arknights"] .ds-logo-stage--dark { background: #08090c; border-color: var(--rhine-line); }
+.rhine-theme[data-rhine-theme="arknights"] .ds-logo-stage>span:last-child { letter-spacing: 3px; color: var(--rhine-muted); }
+
+/* ================= 页脚 ================= */
+.rhine-theme[data-rhine-theme="arknights"] .ds-footer {
+  border-top: 0;
+  position: relative;
+  font-family: var(--rhine-mono);
+  letter-spacing: .06em;
+}
+.rhine-theme[data-rhine-theme="arknights"] .ds-footer::before {
+  content: '';
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 200px;
+  height: 4px;
+  background: var(--ak-hazard);
+}
+
+/* ================= 调色板展示 ================= */
+.rhine-theme[data-rhine-theme="arknights"] .ds-palette>div>div { border-color: var(--rhine-control); }
+
+/* ================= 进阶：HUD 视框 / 扫描 / 开机 ================= */
+
+/* 终端读数（默认隐藏，仅本主题显示） */
+.ak-readout { display: none; }
+.rhine-theme[data-rhine-theme="arknights"] .ak-readout {
+  display: block;
+  margin-top: 8px;
+  padding-top: 8px;
+  border-top: 1px dashed var(--rhine-line);
+  color: var(--ak-accent);
+  font: 11px/18px var(--rhine-mono);
+  letter-spacing: .08em;
+  font-variant-numeric: tabular-nums;
+}
+
+/* 四角 HUD 取景框 */
+.ak-hud { display: none; }
+.rhine-theme[data-rhine-theme="arknights"] .ak-hud {
+  display: block;
+  position: fixed;
+  inset: 10px;
+  z-index: 90;
+  pointer-events: none;
+}
+.rhine-theme[data-rhine-theme="arknights"] .ak-hud i {
+  position: absolute;
+  width: 26px;
+  height: 26px;
+  border: 2px solid rgba(255, 212, 0, .5);
+}
+.rhine-theme[data-rhine-theme="arknights"] .ak-hud i:nth-child(1) { top: 0; left: 0; border-right: 0; border-bottom: 0; }
+.rhine-theme[data-rhine-theme="arknights"] .ak-hud i:nth-child(2) { top: 0; right: 0; border-left: 0; border-bottom: 0; }
+.rhine-theme[data-rhine-theme="arknights"] .ak-hud i:nth-child(3) { bottom: 0; left: 0; border-right: 0; border-top: 0; }
+.rhine-theme[data-rhine-theme="arknights"] .ak-hud i:nth-child(4) { bottom: 0; right: 0; border-left: 0; border-top: 0; }
+
+/* 主题切换开机闪屏 */
+.rhine-theme[data-rhine-theme="arknights"].ds-shell::after {
+  content: '';
+  position: fixed;
+  inset: 0;
+  z-index: 200;
+  pointer-events: none;
+  background:
+    repeating-linear-gradient(0deg, rgba(255, 212, 0, .06) 0 2px, transparent 2px 4px),
+    #050608;
+  animation: ak-boot 520ms steps(3, end) both;
+}
+@keyframes ak-boot {
+  0% { opacity: 1; }
+  55% { opacity: .55; }
+  100% { opacity: 0; visibility: hidden; }
+}
+
+/* 屏幕右缘竖排标识 */
+.rhine-theme[data-rhine-theme="arknights"].ds-shell::before {
+  content: 'RHINE // TACTICAL TERMINAL';
+  position: fixed;
+  right: 6px;
+  top: 50%;
+  transform: translateY(-50%);
+  writing-mode: vertical-rl;
+  font: 10px/1 var(--rhine-mono);
+  letter-spacing: 5px;
+  color: rgba(238, 240, 236, .16);
+  z-index: 50;
+  pointer-events: none;
+}
+@media(max-width:760px) {
+  .rhine-theme[data-rhine-theme="arknights"].ds-shell::before { content: none; }
+}
+
+/* Hero 扫描线 */
+.rhine-theme[data-rhine-theme="arknights"] .ds-hero { position: relative; overflow: hidden; }
+.rhine-theme[data-rhine-theme="arknights"] .ds-hero::after {
+  content: '';
+  position: absolute;
+  left: 0;
+  right: 0;
+  top: -120px;
+  height: 120px;
+  background: linear-gradient(180deg, transparent, rgba(255, 212, 0, .07), transparent);
+  pointer-events: none;
+  animation: ak-scan 4.5s linear infinite;
+}
+@keyframes ak-scan {
+  from { top: -120px; }
+  to { top: 100%; }
+}
+
+/* 减少动态：关闭扫描与开机闪屏 */
+@media(prefers-reduced-motion:reduce) {
+  .rhine-theme[data-rhine-theme="arknights"] .ds-hero::after { animation: none; content: none; }
+  .rhine-theme[data-rhine-theme="arknights"].ds-shell::after { animation: none; content: none; }
+}
+.rhine-theme[data-rhine-theme="arknights"][data-rhine-motion=reduced] .ds-hero::after,
+.rhine-theme[data-rhine-theme="arknights"][data-rhine-motion=reduced].ds-shell::after { animation: none; content: none; }

package/preview/theme-neo-brutalism.css

@@ -0,0 +1,11 @@
+/* Gallery-only chrome and decoration. Not imported by the public theme entry. */
+/* Gallery chrome uses the same theme; application layout stays with its host. */
+.rhine-theme[data-rhine-theme="neo-brutalism"] .ds-sidebar { border-right-width: 2px; border-color: var(--rhine-ink); }
+.rhine-theme[data-rhine-theme="neo-brutalism"] .ds-workspace-head { background: var(--rhine-surface); border-bottom: 2px solid var(--rhine-ink); flex-wrap: wrap; }
+.rhine-theme[data-rhine-theme="neo-brutalism"] .ds-overview-links>a { border: 2px solid var(--rhine-ink); border-radius: 22px; box-shadow: var(--rhine-hard-shadow); }
+.rhine-theme[data-rhine-theme="neo-brutalism"] .ds-hero h1 { font-weight: 800; }
+.rhine-theme[data-rhine-theme="neo-brutalism"] .ds-hero h1>span { color: var(--rhine-ink); text-decoration: underline; text-decoration-color: var(--rhine-signal); text-decoration-thickness: 6px; text-underline-offset: 8px; }
+.rhine-theme[data-rhine-theme="neo-brutalism"] .ds-logo-stage { border: 2px solid var(--rhine-ink); border-radius: 22px; }
+@media(max-width:760px) {
+  .rhine-theme[data-rhine-theme="neo-brutalism"] .ds-sidebar { border-right: 0; border-bottom: 2px solid var(--rhine-ink); }
+}

package/skills/rhine-design/SKILL.md

@@ -2,7 +2,7 @@
 name: rhine-design
 description: Use Rhine Design components and specifications to design, implement, or review React UI, typography, themes, and motion. Apply when a project uses Rhine Design or the user requests its visual language or component system.
 metadata:
-  version: "0.3.0"
+  version: "0.4.0"
 ---
 
 # Rhine Design · 莱茵设计
@@ -11,7 +11,7 @@ Use the installed version's components and contracts to build consistent interfa
 
 ## Locate the matching source
 
-Package: `@linhey/rhine-design`. GitHub: `linhay/rhine-design` (different account spelling). This skill targets 0.3.0.
+Package: `@linhey/rhine-design`. GitHub: `linhay/rhine-design` (different account spelling). This skill targets 0.4.0, including theme, navigation, form and timeline APIs. Never assume those APIs exist in an installed 0.3.0 package.
 
 Find the package in the host's dependencies, normally `node_modules/@linhey/rhine-design/`, or its registered source checkout. Verify `package.json` name/version before using the paths below. Paths in references are relative to that package root, not the copied skill directory. Read installed types and source when versions differ; do not infer a new API from this skill. If the package is unavailable, use the task's supplied design sources and identify the missing implementation evidence.
 
@@ -23,7 +23,7 @@ Find the package in the host's dependencies, normally `node_modules/@linhey/rhin
 
 ## Design before implementation
 
-1. Inventory existing components and tokens for the requested behavior. Compose them before creating a new component or duplicating styles.
+1. Identify the task, interruption cost, information lifetime and recovery path using `docs/INTERACTION_PATTERNS.md` when present. Choose navigation, form, notification or overlay patterns before styling. Inventory existing components and tokens for the requested behavior. Compose them before creating a new component or duplicating styles.
 2. Update the host's page mockup or the library's real `preview/` showcase first. A new shared capability includes its contract and a usable example.
 3. Verify the changed states and interaction in the preview; then integrate into the app when implementation is in scope. Continue both stages when already authorized; a design-only request does not authorize an app migration.
 4. For library changes run `npm run check`; for visual changes inspect relevant widths (400/520/880), 200% zoom, keyboard/focus and reduced motion. For consumer changes run that project's checks. Documentation-only edits need link, example and version consistency checks, not an unrelated UI test campaign.
@@ -33,5 +33,7 @@ Find the package in the host's dependencies, normally `node_modules/@linhey/rhin
 - Use public exports, the `.rhine-theme` root and existing tokens. Use the `rhine-` namespace for CSS variables, classes, animation names and motion data attributes; do not introduce host-product prefixes.
 - Read the actual component signature before using it. Keep semantic headings separate from visual text variants.
 - Host state determines data, selection and operation outcomes. Search and pagination remain host/server responsibilities; busy indicators never imply success.
+- For multi-field failures, preserve input and focus a summary only after failed submission; links return to fields without changing routing. Use SideNav/Breadcrumbs/Steps only when exported by the installed source.
+- Monitoring shows units, freshness and stale/unknown states; errors must not rely on color, flashing or transient toasts.
 - Motion explains a change. Respect reduced motion, cancellation and replay; startup decoration never blocks real readiness. Preview-only experiments are not exported components.
 - Keep independent release boundaries: do not change unrelated products or publish packages merely because this skill was invoked.

package/skills/rhine-design/references/API_MAP.md

@@ -1,9 +1,10 @@
 # API map
 
-All paths are relative to the matching package root. `components/index.ts` is the public export authority. This index locates APIs; exact props come from the installed source, not from remembered examples.
+All paths are relative to the matching package root. `package.json` exports, `components/index.ts` and the separate `components/theme.tsx` entry are the public export authority. This index locates APIs; exact props come from the installed source, not from remembered examples.
 
 | Exports | Source |
 | --- | --- |
+| ThemeProvider, useTheme, themes, ThemeName, ThemeProviderProps (0.4.0；`@linhey/rhine-design/theme`) | `components/theme.tsx`；契约 `docs/THEMING.md` |
 | Logo | `components/Logo.tsx` |
 | Text | `components/Typography.tsx` |
 | Select | `components/Select.tsx` |
@@ -12,7 +13,10 @@ All paths are relative to the matching package root. `components/index.ts` is th
 | Divider, Stack, Inline, Grid | `components/Layout.tsx` |
 | Metric, KeyValue, DataTable, Pagination | `components/Data.tsx` |
 | Checkbox, RadioGroup, Switch, Textarea, SearchField, Combobox | `components/Forms.tsx` |
-| Dialog, ConfirmDialog, Popover, Menu, Tooltip | `components/Overlays.tsx` |
+| Dialog, Drawer (0.4.0), ConfirmDialog, Popover, Menu, Tooltip | `components/Overlays.tsx` |
+| StatusTimeline, TimelineLegend (0.4.0) | `components/StatusTimeline.tsx`；历史证据，不计算健康评分 |
+| SideNav, Breadcrumbs, Steps (0.4.0) | `components/Navigation.tsx` |
+| Fieldset, ErrorSummary (0.4.0) | `components/FormWorkflow.tsx` |
 | Toast | `components/Toast.tsx` |
 | Button, Badge, Surface, SelectionCard, TextField, Tabs, SegmentedControl, Notice, Progress, Skeleton, Disclosure, EmptyState | `components/components.tsx` |
 
@@ -31,4 +35,4 @@ API decisions that commonly matter:
 - `Text`'s `as` chooses semantics; `variant` chooses visual hierarchy.
 - `Logo` accepts `wordmark` and `label`; its `theme` affects the logo, not the full component library.
 - `Toast` presents one notification, not a global queue. `DataTable` is not a query or table-state engine.
-- Components in `preview/` are demonstrations unless re-exported through `components/index.ts`.
+- Components in `preview/` are demonstrations. Public API must resolve through a `package.json` export; theme APIs use the separate `/theme` entry.

package/skills/rhine-design/references/TASK_MAP.md

@@ -4,8 +4,11 @@ Resolve the matching package root as described in SKILL.md. Open the first relev
 
 | Task | First reference (relative to package root) | Implementation / example |
 | --- | --- | --- |
+| Theme integration, switching, controlled preferences | `docs/THEMING.md` (0.4.0) | `components/theme.tsx`, `preview/GalleryShell.tsx` |
+| Scenario selection, navigation, form recovery, monitoring | `docs/INTERACTION_PATTERNS.md` (0.4.0; check installed version) | `preview/PatternGallery.tsx`; research in `docs/REFERENCE_RESEARCH.md` |
 | Visual direction, colors, spacing, layout | `docs/DESIGN_SYSTEM.md` | `components/tokens.css`, `components/Layout.tsx` |
-| Text hierarchy, Chinese/Latin text, metrics | `components/TYPOGRAPHY.md` | `components/Typography.tsx` |
+| Spacing, grouping, card composition | `components/SPACING.md` (0.4.0 docs; existing gap API works in 0.3.0) | `components/Layout.tsx`, `preview/SpacingGallery.tsx`; `/#spacing` |
+| Text hierarchy, line height, paragraphs, Chinese/Latin text, metrics | `components/TYPOGRAPHY.md` | `components/Typography.tsx`, `preview/LineHeightGallery.tsx`; `/#typography` |
 | Logo, light/dark variants, wordmark | `components/README.md` → 品牌标志 | `components/Logo.tsx`, `components/assets/logo.svg` |
 | Buttons, navigation, basic states | `components/README.md` → 组件契约 | `components/components.tsx` |
 | Forms, selection, combobox, data tables | `components/COMMON_COMPONENTS.md` | Use API_MAP for the source file |

package/skills/rhine-design/references/integration.md

@@ -2,7 +2,7 @@
 
 ## Supported baseline
 
-Rhine Design 0.3.0 ships TypeScript/TSX, CSS and SVG source for React 19 + Vite. Install `@linhey/rhine-design`; GitHub remains `linhay/rhine-design`. Check the installed package's engine and peer dependencies. Node 24 is the development baseline. Do not assume precompiled JavaScript, arbitrary SSR support or a complete dark theme.
+Rhine Design 0.4.0 ships TypeScript/TSX, CSS and SVG source for React 19 + Vite. Install `@linhey/rhine-design`; GitHub remains `linhay/rhine-design`. Check the installed package's engine and peer dependencies. Node 24 is the development baseline. Do not assume precompiled JavaScript, arbitrary SSR support or a complete dark theme.
 
 ```tsx
 import { Button, Surface, Text } from '@linhey/rhine-design';
@@ -21,11 +21,13 @@ export function Example() {
 
 ## Integration invariants
 
+Version 0.4.0 also exports `ThemeProvider`, `useTheme`, `themes`, `ThemeName` and `ThemeProviderProps` from `@linhey/rhine-design/theme` (not in npm 0.3.0). See [the theme contract](../../../docs/THEMING.md). This entry loads base and built-in theme CSS and renders the `.rhine-theme` root. Use `defaultTheme` for local state, or `theme` with `onThemeChange` for host state; storage and URL preferences remain with the host. Sibling providers are supported; nested providers throw. Do not wrap it in another themed root or key the subtree by theme. Gallery decoration is excluded from the public theme CSS.
+
 - The entry imports CSS automatically. Keep the package's entry and CSS `sideEffects` declarations so production tree shaking retains styles.
 - Put `.rhine-theme` at the page root. Do not transform, clip or apply containment to it: overlays portal to the nearest theme root and need its variables and reduced-motion settings.
 - For a locally linked checkout, use Vite `resolve.dedupe: ['react', 'react-dom']`. Duplicate React can break hooks; do not patch component state to mask this.
 - Preserve SVG `?no-inline` handling. Logo uses a shared geometric master; missing symbols in production warrant checking the emitted SVG asset before replacing the logo.
-- Reuse tokens for layout and state styling. Full dark theme is not exported in 0.3.0; the logo's dark variant alone does not establish dark-mode support.
+- Reuse tokens for layout and state styling. The arknights preset uses a dark palette; a general light/dark/system color-mode API is not provided. Logo color remains independent of the component theme.
 
 ## Host responsibilities
 

package/tests/GalleryShell.test.tsx

@@ -0,0 +1,98 @@
+import { useState } from 'react';
+import { act, fireEvent, render, screen } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { GalleryShell } from '../preview/GalleryShell';
+import { themes } from '@linhey/rhine-design/theme';
+
+function Demo() {
+  const [motion, setMotion] = useState('system');
+  return <GalleryShell motion={motion} onMotionChange={setMotion}>{section => <h1>{section}</h1>}</GalleryShell>;
+}
+function navigate(hash: string) {
+  act(() => {
+    window.history.replaceState(null, '', hash);
+    window.dispatchEvent(new HashChangeEvent('hashchange'));
+  });
+}
+afterEach(() => {
+  vi.restoreAllMocks();
+  window.history.replaceState(null, '', '/');
+  window.localStorage.clear();
+});
+
+describe('gallery theme integration', () => {
+  it('uses public metadata, prioritizes URL theme and persists choices without losing the chapter', () => {
+    window.localStorage.setItem('rhine-preview-theme', 'rhine');
+    window.history.replaceState(null, '', '/?theme=arknights&other=keep#forms');
+    render(<Demo />);
+    const picker = screen.getByRole('combobox', { name: '界面主题' });
+    expect(picker).toHaveValue('arknights');
+    expect(screen.getAllByRole('option').map(option => option.textContent)).toEqual(themes.map(item => item.label));
+    const main = screen.getByRole('main');
+    main.scrollTop = 120;
+    fireEvent.change(picker, { target: { value: 'neo-brutalism' } });
+    expect(main.closest('.rhine-theme')).toHaveAttribute('data-rhine-theme', 'neo-brutalism');
+    expect(main.scrollTop).toBe(120);
+    expect(screen.getByRole('heading')).toHaveTextContent('forms');
+    expect(window.localStorage.getItem('rhine-preview-theme')).toBe('neo-brutalism');
+    expect(window.location.search).toBe('?other=keep');
+    expect(window.location.hash).toBe('#forms');
+  });
+
+  it('restores a stored theme when the URL is invalid and falls back for unknown stored values', () => {
+    window.localStorage.setItem('rhine-preview-theme', 'neo-brutalism');
+    window.history.replaceState(null, '', '/?theme=unknown');
+    const { unmount } = render(<Demo />);
+    expect(screen.getByRole('combobox', { name: '界面主题' })).toHaveValue('neo-brutalism');
+    unmount();
+    window.localStorage.setItem('rhine-preview-theme', 'unknown');
+    render(<Demo />);
+    expect(screen.getByRole('combobox', { name: '界面主题' })).toHaveValue('rhine');
+  });
+
+  it('still switches when browser storage is unavailable', () => {
+    vi.spyOn(Storage.prototype, 'getItem').mockImplementation(() => { throw new Error('Storage disabled'); });
+    vi.spyOn(Storage.prototype, 'setItem').mockImplementation(() => { throw new Error('Storage disabled'); });
+    render(<Demo />);
+    const picker = screen.getByRole('combobox', { name: '界面主题' });
+    fireEvent.change(picker, { target: { value: 'arknights' } });
+    expect(picker).toHaveValue('arknights');
+    expect(screen.getByRole('main').closest('.rhine-theme')).toHaveAttribute('data-rhine-theme', 'arknights');
+  });
+});
+
+describe('gallery chapter navigation', () => {
+  it('opens deep links and follows history changes with one chapter and a current link', () => {
+    window.history.replaceState(null, '', '#typography');
+    render(<Demo />);
+    expect(screen.getByRole('heading')).toHaveTextContent('typography');
+    expect(screen.getByRole('link', {name:'字体与文字'})).toHaveAttribute('aria-current', 'page');
+    navigate('#motion');
+    expect(screen.getAllByRole('heading')).toHaveLength(1);
+    expect(screen.getByRole('heading')).toHaveTextContent('motion');
+    expect(screen.getByRole('main')).toHaveFocus();
+    navigate('#typography');
+    expect(screen.getByRole('heading')).toHaveTextContent('typography');
+    navigate('#unknown');
+    expect(screen.getByRole('heading')).toHaveTextContent('top');
+  });
+  it('keeps motion preferences while closing navigation on chapter changes', () => {
+    render(<Demo />);
+    fireEvent.click(screen.getByRole('radio', {name:'减少动态'}));
+    fireEvent.click(screen.getByRole('button', {name:'目录'}));
+    expect(screen.getByRole('button', {name:'目录'})).toHaveAttribute('aria-expanded','true');
+    navigate('#startup');
+    expect(screen.getByRole('button', {name:'目录'})).toHaveAttribute('aria-expanded','false');
+    expect(screen.getByRole('main').closest('.rhine-theme')).toHaveAttribute('data-rhine-motion','reduced');
+  });
+  it('closes the compact directory with Escape and returns focus to its trigger', () => {
+    render(<Demo />);
+    const trigger = screen.getByRole('button', {name:'目录'});
+    fireEvent.click(trigger);
+    const link = screen.getByRole('link', {name:'字体与文字'});
+    link.focus();
+    fireEvent.keyDown(link, {key:'Escape'});
+    expect(trigger).toHaveAttribute('aria-expanded','false');
+    expect(trigger).toHaveFocus();
+  });
+});

package/tests/Patterns.test.tsx

@@ -0,0 +1,75 @@
+import { fireEvent, render, screen, waitFor, within } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import { Breadcrumbs, Drawer, ErrorSummary, Fieldset, SideNav, Steps, TextField } from '../components';
+import { PatternGallery } from '../preview/PatternGallery';
+
+describe('navigation and form workflow contracts', () => {
+  it('keeps split dialog selection and preview in one accessible modal', async () => {
+    render(<PatternGallery section="patterns"/>);
+    fireEvent.change(screen.getByRole('combobox',{name:'我正在设计什么场景'}),{target:{value:'monitor'}});
+    fireEvent.click(screen.getByRole('button',{name:'左右分栏预览'}));
+    const dialog=await screen.findByRole('dialog',{name:'选择范围'});
+    expect(dialog).toHaveClass('rhine-dialog--split');
+    fireEvent.change(within(dialog).getByRole('combobox',{name:'范围'}),{target:{value:'backup'}});
+    expect(within(dialog).getByRole('heading',{name:'备用资源 · 健康记录'})).toBeVisible();
+    expect(within(dialog).getByRole('slider')).toHaveAttribute('aria-valuetext','时段 96 · 未知 / 无数据');
+    fireEvent.keyDown(document.activeElement!,{key:'Escape'});
+    await waitFor(()=>expect(screen.queryByRole('dialog')).not.toBeInTheDocument());
+  });
+  it('preserves real navigation links and identifies the current location', () => {
+    const navigate = vi.fn();
+    render(<><SideNav groups={[{label:'工作区',items:[{id:'a',label:'概览',href:'/overview',icon:'chart'},{id:'b',label:'记录',href:'/records'}]}]} currentId="b" onNavigate={(item,event)=>{event.preventDefault();navigate(item.id);}}/><Breadcrumbs items={[{label:'首页',href:'/'},{label:'记录'}]}/></>);
+    expect(screen.getByRole('link',{name:'记录'})).toHaveAttribute('href','/records');
+    expect(screen.getByRole('link',{name:'记录'})).toHaveAttribute('aria-current','page');
+    fireEvent.click(screen.getByRole('link',{name:'概览'})); expect(navigate).toHaveBeenCalledWith('a');
+    expect(within(screen.getByRole('navigation',{name:'当前位置'})).getByText('记录')).toHaveAttribute('aria-current','page');
+  });
+  it('only permits returning to completed steps and exposes current/error/completed states', () => {
+    const change=vi.fn(), items=[{id:'a',label:'输入'},{id:'b',label:'核对'},{id:'c',label:'完成'}];
+    const {rerender}=render(<Steps items={items} current={1} onStepChange={change} error="信息不完整"/>);
+    expect(screen.getAllByRole('button')).toHaveLength(1);
+    fireEvent.click(screen.getByRole('button',{name:'返回输入'}));expect(change).toHaveBeenCalledWith(0);
+    expect(screen.getByText('核对').closest('li')).toHaveAttribute('aria-current','step');
+    expect(screen.getByText(/需要修正/)).toHaveTextContent('信息不完整');
+    rerender(<Steps items={items} current={3}/>);
+    expect(screen.getAllByText('已完成')).toHaveLength(3);
+    expect(document.querySelector('[aria-current=step]')).toBeNull();
+  });
+  it('groups fields semantically and supports native disabled fieldsets', () => {
+    render(<Fieldset legend="连接" hint="只读任务暂不可编辑" disabled><TextField label="地址"/></Fieldset>);
+    expect(screen.getByRole('group',{name:'连接'})).toHaveAccessibleDescription('只读任务暂不可编辑');
+    expect(screen.getByRole('textbox',{name:'地址'})).toBeDisabled();
+  });
+  it('focuses an error summary only for submissions and links back without changing routes', () => {
+    const errors=[{fieldId:'workspace',message:'请输入名称'}];
+    const {rerender}=render(<><ErrorSummary errors={errors} focusKey={1}/><TextField id="workspace" label="名称"/></>);
+    expect(screen.getByRole('region',{name:'请修正以下问题'})).toHaveFocus();
+    const before=window.location.hash;fireEvent.click(screen.getByRole('link',{name:'请输入名称'}));
+    expect(screen.getByRole('textbox')).toHaveFocus();expect(window.location.hash).toBe(before);
+    rerender(<><ErrorSummary errors={[...errors]} focusKey={1}/><TextField id="workspace" label="名称"/></>);
+    expect(screen.getByRole('textbox')).toHaveFocus();
+    rerender(<><ErrorSummary errors={errors} focusKey={2}/><TextField id="workspace" label="名称"/></>);
+    expect(screen.getByRole('region')).toHaveFocus();
+  });
+  it('opens a themed drawer and restores the trigger focus on Escape', async () => {
+    render(<div className="rhine-theme" data-rhine-motion="reduced"><Drawer trigger={<button>查看详情</button>} title="详情" description="记录信息"><TextField label="备注"/></Drawer></div>);
+    const trigger=screen.getByRole('button',{name:'查看详情'}); trigger.focus();fireEvent.click(trigger);
+    const dialog=await screen.findByRole('dialog'); expect(dialog).toHaveClass('rhine-drawer');
+    expect(dialog.closest('.rhine-theme')).toHaveAttribute('data-rhine-motion','reduced');
+    expect(dialog).toContainElement(document.activeElement as HTMLElement);
+    fireEvent.keyDown(document.activeElement!,{key:'Escape'});
+    await waitFor(()=>expect(screen.queryByRole('dialog')).not.toBeInTheDocument());
+    await waitFor(()=>expect(trigger).toHaveFocus());
+  });
+  it('retains form input on failure and clears the summary only after valid resubmission', () => {
+    render(<PatternGallery section="form-workflow"/>);
+    fireEvent.change(screen.getByRole('textbox',{name:'工作区名称'}),{target:{value:'研究'}});
+    fireEvent.click(screen.getByRole('button',{name:'验证配置'}));
+    expect(screen.getByRole('textbox',{name:'工作区名称'})).toHaveValue('研究');
+    expect(screen.getByRole('region')).toHaveFocus();
+    fireEvent.change(screen.getByRole('textbox',{name:'服务地址'}),{target:{value:'https://example.com'}});
+    fireEvent.click(screen.getByRole('button',{name:'验证配置'}));
+    expect(screen.queryByRole('region')).not.toBeInTheDocument();
+    expect(screen.getByRole('status')).toHaveTextContent('没有保存到服务端');
+  });
+});

package/tests/StatusTimeline.test.tsx

@@ -0,0 +1,15 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import { expect, it } from 'vitest';
+import { StatusTimeline, TimelineLegend } from '../components';
+
+it('announces time and evidence with a single native range control, including unknown and empty states',()=>{
+  const {rerender}=render(<><StatusTimeline label="账号历史" startLabel="昨天" endLabel="今天" segments={[{id:'a',label:'10:00',status:'failed'},{id:'b',label:'10:15',status:'unknown'}]}/><TimelineLegend/></>);
+  const slider=screen.getByRole('slider',{name:'账号历史'});
+  expect(slider).toHaveAttribute('aria-valuetext','10:15 · 未知 / 无数据');
+  fireEvent.change(slider,{target:{value:'0'}});
+  expect(slider).toHaveAttribute('aria-valuetext','10:00 · 存在最终失败');
+  expect(screen.getByRole('list',{name:'健康记录图例'})).toHaveTextContent('重试已恢复');
+  rerender(<StatusTimeline label="账号历史" startLabel="昨天" endLabel="今天" segments={[]}/>);
+  expect(screen.getByRole('slider')).toBeDisabled();
+  expect(screen.getByText('暂无记录')).toBeVisible();
+});