# `@tinyray/tiny-ui` 使用说明

这不是一个通用组件大全。它只收录从 Tiny Ray 当前个人网站提取、并已在真实页面验证过的模式。

## 安装与样式

```bash
npm install @tinyray/tiny-ui
```

在项目全局样式中导入：

```css
@import "@tinyray/tiny-ui/styles.css";
```

组件继承宿主项目字体；若需要完整的 Tiny 文案气质，请同时引入霞鹜文楷与小赖字体，并将正文设为霞鹜文楷。

## 最小示例

```tsx
import {
  MomentCarousel,
  TinyButton,
  WritingFolder,
  type WritingFolderData,
} from "@tinyray/tiny-ui";

import "@tinyray/tiny-ui/styles.css";

const folders: WritingFolderData[] = [
  {
    id: "notes",
    eyebrow: "FIELD NOTES",
    title: "随想",
    description: "先把还没有答案的想法留下来。",
    color: "#fff1d5",
    accent: "#c1842f",
    notes: [{ id: "one", title: "第一篇", description: "示例内容", tag: "NOTE", color: "#e7f1e3" }],
  },
];

export function Page() {
  return <>
    <TinyButton>开始</TinyButton>
    <WritingFolder folders={folders} onOpenArticle={(note) => console.log(note.href)} />
    <MomentCarousel items={[/* id, eyebrow, title, detail, image, imageAlt */]} />
  </>;
}
```

## 组件与不变行为

| 组件 | 数据入口 | 必须保持 |
| --- | --- | --- |
| `TinyButton` | `variant`, `href`, children | 最小 44px 点击区、主次层级、清晰焦点 |
| `SectionHeading` | `eyebrow`, `title`, `action` | 蓝色 eyebrow、标题优先、操作不抢主标题 |
| `PaperCard` | `tone`, children | 暖白纸面、细边、低对比阴影 |
| `WritingFolder` | `folders`, `onOpenArticle`, `openArticleInternally` | 文件夹 → 书架由点击位置展开；业务文章阅读器可由宿主项目负责 |
| `MomentCarousel` | `items`, `interval`, `autoPlay` | 始终横向切换、进入后暂停、旧新内容交叠、移动端不内滚动 |
| `WorkCard` | `image`, `title`, `description`, `href` | 固定媒体比例、完整可点击目标 |
| `FloatingAnchorNav` | `brand`, `items` | 当前位置清楚，手机保留核心锚点 |
| `StickerStage` / `StickerSlot` | 子元素、位置、尺寸 | 贴纸只是点缀，不能承载唯一关键信息 |
| `StickerForgeSticker` | `source`、`options`、`fallback` | Sticker Forge 是渐进增强；始终提供静态 `fallback`，不让外部脚本成为唯一呈现方式 |
| `PointerTrail` | `defaultLabel` | 只在页面根部挂载一次；用 `data-cursor-label` 改变提示文字；移动端与减少动态效果下不展示 |
| `SocialStack` | `items` | 每个块均为有效联系入口或明确的可复制动作 |
| `DotWordmark` | `word` | 静态文字兜底；点阵仅在可见区域运行 |

## 不该做的事

- 不把 Tiny 的个人文案、照片、付款信息或外链写进通用组件。
- 不用 hover 作为理解或完成操作的唯一方式。
- 不将轮播改为上下切，或在切换时先清空内容。
- 不让移动端在卡片内部滚动才能读到完整核心文案。
- 不把拼图、摄影沉浸页和全局指针特效作为所有项目的默认依赖。