@linhey/rhine-design 0.0.0-stage → 0.2.0

package/skills/rhine-design/SKILL.md

@@ -0,0 +1,37 @@
+---
+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.2.0"
+---
+
+# Rhine Design · 莱茵设计
+
+Use the installed version's components and contracts to build consistent interfaces. This is an independently versioned, general design system; retain the host product's identity and data ownership.
+
+## Locate the matching source
+
+Package: `@linhey/rhine-design`. GitHub: `linhay/rhine-design` (different account spelling). This skill targets 0.2.0.
+
+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.
+
+## Route the task
+
+- Screen design, interaction, typography, motion: start with [TASK_MAP.md](references/TASK_MAP.md), then read only the relevant contract.
+- A named component or prop: use [API_MAP.md](references/API_MAP.md), then inspect its exported type and implementation.
+- First integration, linking, theme or missing styles: read [integration.md](references/integration.md).
+
+## Design before implementation
+
+1. 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.
+
+## Preserve these contracts
+
+- Use public exports, the `.tod-theme` root and existing tokens. `tod-` is a retained CSS API, not a required product name.
+- 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.
+- 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/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Rhine Design · 莱茵设计"
+  short_description: "用莱茵设计组件与规范完成页面设计、字体排版、动效及应用接入"
+  default_prompt: "使用 $rhine-design，优先复用现有组件，先完成设计稿和交互验证，再按本次任务授权接入应用。"

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

@@ -0,0 +1,34 @@
+# 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.
+
+| Exports | Source |
+| --- | --- |
+| Logo | `components/Logo.tsx` |
+| Text | `components/Typography.tsx` |
+| Select | `components/Select.tsx` |
+| Toolbar | `components/Toolbar.tsx` |
+| Icon, IconButton, Link, CopyButton | `components/Actions.tsx` |
+| 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` |
+| Toast | `components/Toast.tsx` |
+| Button, Badge, Surface, SelectionCard, TextField, Tabs, SegmentedControl, Notice, Progress, Skeleton, Disclosure, EmptyState | `components/components.tsx` |
+
+Primary contracts: `components/README.md` and `components/COMMON_COMPONENTS.md`. Find behavioral evidence in `tests/` and composition examples in `preview/`.
+
+```sh
+# From the resolved package root:
+rg -n 'ConfirmDialog|DataTable|Combobox' components/index.ts components/*.tsx
+rg -n 'ConfirmDialog|DataTable|Combobox' tests preview
+```
+
+API decisions that commonly matter:
+
+- `Select` uses a native single-select; searchable candidates use `Combobox`.
+- `SelectionCard` uses checkbox semantics; the host determines single-selection policy. Do not nest other interactive controls in it.
+- `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`.

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

@@ -0,0 +1,20 @@
+# Task map
+
+Resolve the matching package root as described in SKILL.md. Open the first relevant source; expand only when the task crosses domains.
+
+| Task | First reference (relative to package root) | Implementation / example |
+| --- | --- | --- |
+| 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` |
+| 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 |
+| Modal, menu, popover, tooltip, feedback | `components/COMMON_COMPONENTS.md` | `components/Overlays.tsx`, `components/Toast.tsx` |
+| Transition, replay, cancellation, reduced motion | `components/MOTION.md` | `preview/`, `components/styles.css` |
+| Startup sequence, logo assembly, ready handoff | `components/STARTUP.md` | Search `startup` in `preview/`; not a public Startup component |
+| Missing capability or system coverage | `docs/DESIGN_SYSTEM_AUDIT.md` | Verify status against `components/index.ts` |
+| Version upgrade | `CHANGELOG.md` | Installed `package.json`, current types |
+
+Run the library showcase with `npm ci && npm run dev` in a source checkout. Default port is 18309; sections include `/#foundation`, `/#typography`, `/#brand`, `/#motion` and `/#startup`. Do not assume another project's server or local filesystem layout.
+
+For host pages, keep product-specific drafts in the host project. The library's `preview/` demonstrates reusable behavior, not business APIs. Labels such as “candidate” or “preview” in motion docs identify experiments; check whether the behavior is actually exported before integrating it.

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

@@ -0,0 +1,40 @@
+# Integration and diagnosis
+
+## Supported baseline
+
+Rhine Design 0.2.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';
+
+export function Example() {
+  return (
+    <div className="tod-theme">
+      <Surface>
+        <Text as="h2" variant="section">工作空间</Text>
+        <Button onClick={() => { /* host action */ }}>继续</Button>
+      </Surface>
+    </div>
+  );
+}
+```
+
+## Integration invariants
+
+- The entry imports CSS automatically. Keep the package's entry and CSS `sideEffects` declarations so production tree shaking retains styles.
+- Put `.tod-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.2.0; the logo's dark variant alone does not establish dark-mode support.
+
+## Host responsibilities
+
+Pass controlled form values, data, sorting/pagination intentions and operation results through the documented APIs. The host owns network requests, debouncing, IME composition, cancellation and stale-response protection. Do not replace server filtering with an unrequested full-data download.
+
+Await actual copy/confirm outcomes. Errors remain actionable; busy state preserves meaningful focus. Inspect overlay focus return, Escape and keyboard navigation in the browser when changing those interactions. Progress with unknown duration is indeterminate; startup animation ends when the host is ready rather than imposing a decorative delay.
+
+## Upgrade and feedback
+
+Check the installed version against this skill's metadata, then consult `CHANGELOG.md`. Refresh the copied skill together with the package; keep local customizations when comparing versions. If types and docs disagree, use source for the immediate API and repair the stale reference when in scope.
+
+For reproducible feedback record package version, component/API, relevant source or reference path, expected and actual behavior, and the smallest reproduction. Public reports need no private host payloads or credentials. Filing an external issue remains a user-directed action.

package/tests/CommonComponents.test.tsx

@@ -0,0 +1,71 @@
+import { useState } from 'react';
+import { act, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { Checkbox, Combobox, ConfirmDialog, CopyButton, DataTable, Metric, Pagination, RadioGroup, SearchField, Switch, Toast } from '../components';
+
+afterEach(() => vi.useRealTimers());
+describe('common design components', () => {
+  it('distinguishes zero from unknown metrics', () => {
+    render(<><Metric label="计数" value={0}/><Metric label="未知" value={null}/></>);
+    expect(screen.getByText('0')).toBeVisible(); expect(screen.getByText('—')).toBeVisible();
+  });
+  it('emits sort intent without sorting or dropping stale rows on failure', () => {
+    const sort=vi.fn();
+    render(<DataTable caption="请求" rows={[{id:'b'},{id:'a'}]} rowKey={row=>row.id} columns={[{key:'id',header:'标识',sortable:true,render:row=>row.id}]} onSortChange={sort} error="连接失败"/>);
+    fireEvent.click(screen.getByRole('button',{name:'标识'}));
+    expect(sort).toHaveBeenCalledWith({key:'id',direction:'asc'});
+    expect(screen.getAllByRole('cell').map(node=>node.textContent)).toEqual(['b','a']);
+    expect(screen.getByRole('alert')).toHaveTextContent('保留上次读取');
+  });
+  it('respects pagination boundaries, busy state and unknown totals', () => {
+    const change=vi.fn();const {rerender}=render(<Pagination page={1} pageSize={10} total={23} onPageChange={change}/>);
+    expect(screen.getByRole('button',{name:'上一页'})).toBeDisabled();fireEvent.click(screen.getByRole('button',{name:'下一页'}));expect(change).toHaveBeenCalledWith(2);
+    rerender(<Pagination page={3} pageSize={10} total={23} onPageChange={change}/>);expect(screen.getByRole('button',{name:'下一页'})).toBeDisabled();
+    rerender(<Pagination page={3} pageSize={10} hasNext loading onPageChange={change}/>);expect(screen.getAllByRole('button').every(b=>b.hasAttribute('disabled'))).toBe(true);
+    rerender(<Pagination page={3} pageSize={10} hasNext onPageChange={change}/>);expect(screen.getByText('第 3 页')).toBeVisible();expect(screen.getByRole('button',{name:'下一页'})).toBeEnabled();
+  });
+  it('reports copy success only after resolution and prevents duplicate writes', async () => {
+    let resolve!:()=>void;const copy=vi.fn(()=>new Promise<void>(done=>{resolve=done;}));
+    render(<CopyButton value="demo" copy={copy}/>);const button=screen.getByRole('button',{name:'复制'});button.focus();fireEvent.click(button);fireEvent.click(button);
+    expect(copy).toHaveBeenCalledTimes(1);expect(button).toHaveFocus();expect(screen.queryByText('已复制')).not.toBeInTheDocument();
+    await act(async()=>resolve());expect(screen.getByRole('status')).toHaveTextContent('已复制');
+  });
+  it('allows failed copies to retry and ignores stale completion after a value change', async () => {
+    const copy=vi.fn().mockRejectedValueOnce(new Error('test')).mockResolvedValue(undefined);
+    const {rerender}=render(<CopyButton value="a" copy={copy}/>);fireEvent.click(screen.getByRole('button',{name:'复制'}));await screen.findByRole('alert');fireEvent.click(screen.getByRole('button',{name:'复制'}));await waitFor(()=>expect(screen.getByRole('status')).toHaveTextContent('已复制'));
+    let resolve!:()=>void;const delayed=()=>new Promise<void>(done=>{resolve=done;});
+    rerender(<CopyButton value="b" copy={delayed}/>);fireEvent.click(screen.getByRole('button',{name:'复制'}));rerender(<CopyButton value="c" copy={delayed}/>);await act(async()=>resolve());expect(screen.getByRole('status')).toBeEmptyDOMElement();
+  });
+  it('exposes mixed checkbox state and separates native radio groups', () => {
+    render(<><Checkbox label="部分选择" indeterminate readOnly/><RadioGroup label="组一" value="a" onValueChange={()=>{}} items={[{value:'a',label:'A'}]}/><RadioGroup label="组二" value="a" onValueChange={()=>{}} items={[{value:'a',label:'A'}]}/></>);
+    expect(screen.getByRole('checkbox')).toBePartiallyChecked();const radios=screen.getAllByRole('radio');expect(radios[0].getAttribute('name')).not.toBe(radios[1].getAttribute('name'));
+  });
+  it('does not change a controlled switch before the caller updates it', () => {
+    const change=vi.fn();render(<Switch label="偏好" checked={false} onCheckedChange={change}/>);fireEvent.click(screen.getByRole('switch'));expect(change).toHaveBeenCalledWith(true);expect(screen.getByRole('switch')).not.toBeChecked();
+  });
+  it('does not submit searches while IME composition is active', () => {
+    const search=vi.fn();render(<SearchField label="搜索" value="研究" onValueChange={()=>{}} onSearch={search}/>);const input=screen.getByRole('searchbox');fireEvent.compositionStart(input);fireEvent.keyDown(input,{key:'Enter'});expect(search).not.toHaveBeenCalled();fireEvent.compositionEnd(input);fireEvent.keyDown(input,{key:'Enter'});expect(search).toHaveBeenCalledWith('研究');
+  });
+  it('navigates supplied combobox results, skips disabled items and blocks IME commit', () => {
+    const choose=vi.fn(),query=vi.fn();render(<Combobox label="模型" query="" onQueryChange={query} value={null} onValueChange={choose} options={[{value:'a',label:'A'},{value:'b',label:'B',disabled:true},{value:'c',label:'C'}]}/>);
+    const input=screen.getByRole('combobox');fireEvent.focus(input);fireEvent.keyDown(input,{key:'ArrowDown'});fireEvent.keyDown(input,{key:'ArrowDown'});expect(document.getElementById(input.getAttribute('aria-activedescendant')!)).toHaveTextContent('C');
+    fireEvent.compositionStart(input);fireEvent.change(input,{target:{value:'中'}});fireEvent.keyDown(input,{key:'Enter'});expect(choose).not.toHaveBeenCalled();expect(query).not.toHaveBeenCalled();fireEvent.compositionEnd(input);expect(query).toHaveBeenCalledWith('中');fireEvent.keyDown(input,{key:'End'});fireEvent.keyDown(input,{key:'Enter'});expect(choose).toHaveBeenCalledWith({value:'c',label:'C'});expect(input).toHaveAttribute('aria-expanded','false');
+  });
+  it('does not allow stale combobox results to be picked during loading', () => {
+    const choose=vi.fn();render(<Combobox label="模型" query="" value={null} onQueryChange={()=>{}} onValueChange={choose} options={[{value:'a',label:'A'}]} loading/>);const input=screen.getByRole('combobox');fireEvent.focus(input);fireEvent.keyDown(input,{key:'ArrowDown'});fireEvent.keyDown(input,{key:'Enter'});expect(choose).not.toHaveBeenCalled();expect(screen.queryByRole('option')).not.toBeInTheDocument();
+  });
+  it('pauses success notification countdown on hover and keeps errors persistent', () => {
+    vi.useFakeTimers();const close=vi.fn();const {rerender}=render(<Toast open onOpenChange={close} title="已完成" duration={5000}/>);
+    act(()=>vi.advanceTimersByTime(2000));fireEvent.mouseEnter(screen.getByRole('status'));act(()=>vi.advanceTimersByTime(10000));expect(close).not.toHaveBeenCalled();fireEvent.mouseLeave(screen.getByRole('status'));act(()=>vi.advanceTimersByTime(2999));expect(close).not.toHaveBeenCalled();act(()=>vi.advanceTimersByTime(1));expect(close).toHaveBeenCalledWith(false);
+    close.mockClear();rerender(<Toast open onOpenChange={close} title="失败" tone="error" duration={1000}/>);act(()=>vi.advanceTimersByTime(10000));expect(close).not.toHaveBeenCalled();
+  });
+  it('resets toast countdown when reopening', () => {
+    vi.useFakeTimers();function Demo(){const [open,setOpen]=useState(true);return <><button onClick={()=>setOpen(true)}>显示</button><Toast open={open} onOpenChange={setOpen} title="通知" duration={1000}/></>;}
+    render(<Demo/>);act(()=>vi.advanceTimersByTime(1000));expect(screen.queryByText('通知')).not.toBeInTheDocument();fireEvent.click(screen.getByRole('button',{name:'显示'}));act(()=>vi.advanceTimersByTime(999));expect(screen.getByText('通知')).toBeVisible();act(()=>vi.advanceTimersByTime(1));expect(screen.queryByText('通知')).not.toBeInTheDocument();
+  });
+  it('keeps a failed confirmation open and closes only after successful retry', async () => {
+    const confirm=vi.fn().mockRejectedValueOnce(new Error('demo')).mockResolvedValue(undefined);
+    render(<div className="tod-theme"><ConfirmDialog trigger={<button>打开</button>} title="确认任务" description="演示" onConfirm={confirm}/></div>);
+    fireEvent.click(screen.getByRole('button',{name:'打开'}));expect(await screen.findByRole('alertdialog')).toBeVisible();expect(screen.getByRole('button',{name:'取消'})).toHaveFocus();fireEvent.click(screen.getByRole('button',{name:'确认操作'}));expect(await screen.findByRole('alert')).toHaveTextContent('操作未完成');fireEvent.click(screen.getByRole('button',{name:'确认操作'}));await waitFor(()=>expect(screen.queryByRole('alertdialog')).not.toBeInTheDocument());
+  });
+});

package/tests/DesignSystem.test.tsx

@@ -0,0 +1,100 @@
+import { useState } from 'react';
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import { Button, Disclosure, Logo, Progress, SegmentedControl, Select, SelectionCard, Tabs, TextField } from '../components';
+
+describe('reusable design components', () => {
+  it('uses the independent library identity and accepts a host wordmark', () => {
+    const { rerender } = render(<Logo variant="lockup" />);
+    expect(screen.getByRole('img', { name: 'Rhine Design' })).toHaveTextContent('Rhine Design');
+    rerender(<Logo variant="lockup" wordmark="Studio" />);
+    expect(screen.getByRole('img', { name: 'Studio' })).toHaveTextContent('Studio');
+    rerender(<Logo variant="lockup" wordmark="Studio" label="Studio home" decorative />);
+    expect(screen.queryByRole('img')).not.toBeInTheDocument();
+  });
+  it('associates native selects with unique labels, hints, errors and caller descriptions', () => {
+    render(<><span id="context">当前工作区</span><Select label="页面" hint="请选择" error="页面不可用" aria-describedby="context"><option>用量</option></Select><Select label="场景" disabled><option>正常</option></Select></>);
+    const page = screen.getByRole('combobox', {name:'页面'});
+    const scene = screen.getByRole('combobox', {name:'场景'});
+    expect(page.id).not.toBe(scene.id);
+    expect(page).toHaveAttribute('aria-invalid','true');
+    expect(page).toHaveAccessibleDescription('当前工作区 请选择 页面不可用');
+    expect(scene).toBeDisabled();
+    expect(screen.getAllByRole('combobox')).toHaveLength(2);
+  });
+  it('keeps the selected value controlled by the caller', () => {
+    function Demo() {
+      const [value,setValue] = useState('a');
+      return <Select label="页面" value={value} onChange={event=>setValue(event.target.value)}><option value="a">同步</option><option value="b">用量</option></Select>;
+    }
+    render(<Demo />);
+    const select=screen.getByRole('combobox');
+    fireEvent.change(select,{target:{value:'b'}});
+    expect(select).toHaveValue('b');
+  });
+  it('retains focus while busy and blocks repeat submission', () => {
+    const submit = vi.fn();
+    const { rerender } = render(<Button onClick={submit}>保存</Button>);
+    const button = screen.getByRole('button'); button.focus(); fireEvent.click(button);
+    rerender(<Button busy busyLabel="保存中" onClick={submit}>保存</Button>);
+    fireEvent.click(button);
+    expect(submit).toHaveBeenCalledTimes(1);
+    expect(button).toHaveFocus(); expect(button).toHaveAttribute('aria-busy', 'true');
+    expect(button).not.toBeDisabled();
+  });
+  it('keeps disabled actions unavailable', () => {
+    const action = vi.fn(); render(<Button disabled onClick={action}>删除</Button>);
+    fireEvent.click(screen.getByRole('button')); expect(action).not.toHaveBeenCalled();
+  });
+  it('uses non-submit buttons by default inside forms', () => {
+    render(<form><Button>动作</Button></form>); expect(screen.getByRole('button')).toHaveAttribute('type', 'button');
+  });
+  it('tabs skip disabled entries, wrap, and preserve mounted input state', () => {
+    function Demo() {
+      const [value,setValue] = useState('a');
+      return <Tabs label="切换" value={value} onValueChange={setValue} items={[
+        {value:'a',label:'甲',content:<input aria-label="草稿" defaultValue=""/>},
+        {value:'b',label:'乙',disabled:true,content:null},
+        {value:'c',label:'丙',content:'第三页'},
+      ]}/>;
+    }
+    render(<Demo/>); fireEvent.change(screen.getByLabelText('草稿'),{target:{value:'保留草稿'}});
+    const first=screen.getByRole('tab',{name:'甲'}); first.focus(); fireEvent.keyDown(first,{key:'ArrowRight'});
+    const last=screen.getByRole('tab',{name:'丙'}); expect(last).toHaveFocus(); expect(last).toHaveAttribute('aria-selected','true');
+    fireEvent.keyDown(last,{key:'ArrowRight'}); expect(first).toHaveFocus();
+    expect(screen.getByLabelText('草稿')).toHaveValue('保留草稿');
+    fireEvent.keyDown(first,{key:'End'}); expect(last).toHaveFocus();
+    fireEvent.keyDown(last,{key:'Home'}); expect(first).toHaveFocus();
+  });
+  it('assigns unique ARIA associations to multiple tab groups', () => {
+    render(<>{['one','two'].map(label=><Tabs key={label} label={label} value="a" onValueChange={()=>{}} items={[{value:'a',label,content:label}]}/>)}</>);
+    const tabs=screen.getAllByRole('tab'); expect(tabs[0].id).not.toBe(tabs[1].id);
+    for(const tab of tabs) expect(document.getElementById(tab.getAttribute('aria-controls')!)).toHaveAttribute('aria-labelledby',tab.id);
+  });
+  it('keeps separate segmented controls in independent native radio groups', () => {
+    render(<>{['a','b'].map(label=><SegmentedControl key={label} label={label} value="one" onValueChange={()=>{}} items={[{value:'one',label:'一'},{value:'two',label:'二'}]}/>)}</>);
+    const radios=screen.getAllByRole('radio'); expect(radios[0].getAttribute('name')).not.toBe(radios[2].getAttribute('name'));
+  });
+  it('allows controlled selection to be cancelled', () => {
+    function Demo(){const [value,setValue]=useState(false);return <SelectionCard label="选择项" selected={value} onSelectedChange={setValue}>详情</SelectionCard>}
+    render(<Demo/>); const input=screen.getByRole('checkbox'); fireEvent.click(input); expect(input).toBeChecked();fireEvent.click(input);expect(input).not.toBeChecked();
+  });
+  it('associates input hints and errors with the actual field', () => {
+    render(<TextField label="名称" hint="必填" error="请填写名称" aria-describedby="external" />);
+    const input=screen.getByLabelText('名称'); expect(input).toHaveAttribute('aria-invalid','true');
+    const ids=input.getAttribute('aria-describedby')!.split(' '); expect(ids).toContain('external');
+    expect(ids.slice(1).map(id=>document.getElementById(id)?.textContent)).toEqual(['必填','请填写名称']);
+  });
+  it('does not invent a percentage for unknown progress and clamps known values', () => {
+    const {rerender}=render(<Progress label="进度" value={null}/>);
+    expect(screen.getByRole('progressbar')).not.toHaveAttribute('aria-valuenow');
+    rerender(<Progress label="进度" value={150}/>);expect(screen.getByRole('progressbar')).toHaveAttribute('aria-valuenow','100');
+    rerender(<Progress label="进度" value={NaN}/>);expect(screen.getByRole('progressbar')).not.toHaveAttribute('aria-valuenow');
+  });
+  it('disclosure works without animation support and closes keyboard content', () => {
+    render(<Disclosure title="详细信息"><button>内部按钮</button></Disclosure>);
+    const summary=screen.getByText('详细信息');const details=summary.closest('details')!;
+    expect(details.open).toBe(false);fireEvent.click(summary);expect(details.open).toBe(true);
+    fireEvent.click(summary);expect(details.open).toBe(false);expect(screen.getByText('内部按钮')).not.toBeVisible();
+  });
+});

package/tests/MotionGallery.test.tsx

@@ -0,0 +1,32 @@
+import { act, fireEvent, render, screen, within } from '@testing-library/react';
+import { afterEach, expect, it, vi } from 'vitest';
+import { MotionGallery } from '../preview/MotionGallery';
+
+afterEach(() => { vi.useRealTimers(); vi.unstubAllGlobals(); });
+function clock() {
+  vi.useFakeTimers();
+  vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) => setTimeout(()=>callback(0),16));
+  vi.stubGlobal('cancelAnimationFrame', (id: number) => clearTimeout(id));
+}
+it('replay cancels the old simulated completion and keeps the control focused', () => {
+  clock(); render(<MotionGallery reduced={false}/>);
+  const card=within(screen.getByRole('article',{name:'操作 → 结果'}));
+  fireEvent.click(card.getByRole('button',{name:'播放操作 → 结果'}));
+  act(()=>vi.advanceTimersByTime(400));
+  const replay=card.getByRole('button',{name:'重播操作 → 结果'}); replay.focus(); fireEvent.click(replay);
+  act(()=>vi.advanceTimersByTime(400));
+  expect(card.queryByText('已完成 · 演示')).not.toBeInTheDocument();
+  expect(replay).toHaveFocus();
+  act(()=>vi.advanceTimersByTime(400));
+  expect(card.getByRole('status')).toHaveTextContent('已完成 · 演示');
+});
+it('reset and unmount cancel pending demo timers without producing a result', () => {
+  clock(); const {unmount}=render(<MotionGallery reduced={false}/>);
+  const card=within(screen.getByRole('article',{name:'加载 → 内容'}));
+  fireEvent.click(card.getByRole('button',{name:'播放加载 → 内容'})); act(()=>vi.advanceTimersByTime(100));
+  fireEvent.click(card.getByRole('button',{name:'复位加载 → 内容'})); act(()=>vi.advanceTimersByTime(1000));
+  expect(card.queryByText('研究工作区')).not.toBeInTheDocument();
+  expect(card.getByRole('button',{name:'重播加载 → 内容'})).toBeDisabled();
+  fireEvent.click(card.getByRole('button',{name:'播放加载 → 内容'})); act(()=>vi.advanceTimersByTime(100)); unmount();
+  expect(vi.getTimerCount()).toBe(0);
+});

package/tests/StartupGallery.test.tsx

@@ -0,0 +1,55 @@
+import { act, fireEvent, render, screen } from '@testing-library/react';
+import { afterEach, expect, it, vi } from 'vitest';
+import { StartupGallery } from '../preview/StartupGallery';
+
+afterEach(() => vi.useRealTimers());
+
+it('replay cancels stale readiness and preserves control focus; reset clears the timer', () => {
+  vi.useFakeTimers();
+  const { unmount } = render(<StartupGallery reduced={false} />);
+  fireEvent.click(screen.getByRole('button', { name: '播放启动动画' }));
+  act(() => vi.advanceTimersByTime(1000));
+  const replay = screen.getByRole('button', { name: '重播启动动画' });
+  replay.focus(); fireEvent.click(replay);
+  act(() => vi.advanceTimersByTime(700));
+  expect(screen.queryByText('连接你的工作空间')).not.toBeInTheDocument();
+  expect(replay).toHaveFocus();
+  fireEvent.click(screen.getByRole('button', { name: '复位启动动画' }));
+  act(() => vi.advanceTimersByTime(2000));
+  expect(screen.queryByText('连接你的工作空间')).not.toBeInTheDocument();
+  fireEvent.click(screen.getByRole('button', { name: '播放启动动画' }));
+  unmount(); expect(vi.getTimerCount()).toBe(0);
+});
+
+it('reduced motion skips synthetic normal delay but does not turn waiting or failure into success', () => {
+  vi.useFakeTimers();
+  const { rerender } = render(<StartupGallery reduced={false} />);
+  fireEvent.click(screen.getByRole('button', { name: '播放启动动画' }));
+  rerender(<StartupGallery reduced />);
+  expect(screen.getByText('连接你的工作空间')).toBeInTheDocument();
+  expect(vi.getTimerCount()).toBe(0);
+  fireEvent.change(screen.getByLabelText('启动场景'), { target: { value: 'waiting' } });
+  fireEvent.click(screen.getByRole('button', { name: '播放启动动画' }));
+  act(() => vi.advanceTimersByTime(10000));
+  expect(screen.queryByText('连接你的工作空间')).not.toBeInTheDocument();
+  fireEvent.click(screen.getByRole('button', { name: '模拟就绪 · 立即进入' }));
+  expect(screen.getByText('连接你的工作空间')).toBeInTheDocument();
+  fireEvent.change(screen.getByLabelText('启动场景'), { target: { value: 'error' } });
+  fireEvent.click(screen.getByRole('button', { name: '播放启动动画' }));
+  expect(screen.getByRole('alert')).toHaveTextContent('暂时无法恢复会话');
+  expect(screen.queryByText('连接你的工作空间')).not.toBeInTheDocument();
+});
+
+it('keeps the same brand node when readiness arrives and makes the login preview usable immediately', () => {
+  vi.useFakeTimers();
+  const { container } = render(<StartupGallery reduced={false} />);
+  fireEvent.click(screen.getByRole('button', { name: '播放启动动画' }));
+  const logo = container.querySelector('.ds-startup-logo-anchor .tod-logo');
+  act(() => vi.advanceTimersByTime(300));
+  fireEvent.click(screen.getByRole('button', { name: '模拟就绪 · 立即进入' }));
+  expect(container.querySelector('.ds-startup-logo-anchor .tod-logo')).toBe(logo);
+  expect(container.querySelectorAll('.ds-startup-stage .tod-logo')).toHaveLength(1);
+  fireEvent.click(screen.getByRole('button', { name: '在浏览器中登录' }));
+  expect(screen.getByText('仅演示登录入口，不会打开授权页面。')).toBeInTheDocument();
+  expect(vi.getTimerCount()).toBe(0);
+});

package/tests/setup.ts

@@ -0,0 +1,4 @@
+import '@testing-library/jest-dom/vitest';
+import { afterEach } from 'vitest';
+import { cleanup } from '@testing-library/react';
+afterEach(cleanup);

package/tsconfig.json

@@ -0,0 +1,32 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": [
+      "ES2022",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "types": [
+      "vite/client",
+      "node"
+    ]
+  },
+  "include": [
+    "components",
+    "preview",
+    "tests",
+    "vite.config.ts",
+    "vitest.config.ts"
+  ]
+}

package/vite.config.ts

@@ -0,0 +1,3 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+export default defineConfig({ base: './', plugins: [react()], build: { target: ['es2022', 'safari15'], sourcemap: false } });

package/vitest.config.ts

@@ -0,0 +1,3 @@
+import { defineConfig } from 'vitest/config';
+import react from '@vitejs/plugin-react';
+export default defineConfig({ plugins: [react()], test: { include: ['tests/**/*.test.tsx'], environment: 'jsdom', setupFiles: ['./tests/setup.ts'], clearMocks: true } });