cos-design

91 React visual-effect components for marketing pages, brand landings, and creative showcases
91 个 React 视觉特效组件 · 活动页 / 品牌页 / 创意展示开箱即用

Playground · Quickstart · 10-minute campaign · llms.txt · AI discovery · Next.js example · EN guide · 中文指南 · Changelog

English (for developers & AI agents)

cos-design is a React library of visual effects — fireworks, scratch cards, weather/matrix backgrounds, neon headlines, flip counters — not a general admin UI kit.

pnpm add cos-design
# or smaller per-component packages:
pnpm add @cos-design/fireworks @cos-design/scratch-card @cos-design/weather-background

import { Fireworks } from '@cos-design/fireworks';
import { ScratchCard } from '@cos-design/scratch-card';

export function Campaign() {
  return (
    <>
      <ScratchCard prize="50% OFF" width={320} height={200} />
      <Fireworks width={800} height={500} />
    </>
  );
}

• Use for: campaign / lottery / celebration UI, canvas backgrounds, animated headlines, dashboard decorations
• Do not use for: tables, forms, nav shells → use Ant Design / shadcn / MUI
• Start here (campaign): Build a campaign page in 10 minutes · runnable examples/next-app
• AI index: https://jiaxiantao.github.io/cos-design/llms.txt · Context7: /jiaxiantao/cos-design
• Cursor Skill install: see docs/ai-discovery.md
• Article: React marketing page effects with cos-design

这是什么？

cos-design 是一个面向视觉表达的 React 组件库——专注特效与氛围，给页面加趣味、加记忆点的「特效层」。

适合用在：

| 场景 | 你可以用它做什么 | | ------------ | --------------------------------------- | | 营销活动页 | 转盘抽奖、刮刮乐、红包雨、烟花庆祝 | | 品牌 Landing | 极光 / 深海气泡背景、霓虹标题、全息卡片 | | 数据大屏 | 翻牌器、数字递增、仪表盘、关系网络图 | | 创意作品集 | 牛顿摆、DNA 螺旋、迷宫生成、生命游戏 |

从背景到物理、从文字到营销，91 个组件刚好组成一套完整的「视觉工具箱」。

快速开始

完整说明见 QUICKSTART.md · Playground 内访问 #/quickstart

安装

# 安装全部组件
pnpm add cos-design

# 或按需安装单个组件（npm 包名为 kebab-case）
pnpm add @cos-design/weather-background
pnpm add @cos-design/fireworks

目录 weatherBackground → @cos-design/weather-background；依赖 @cos-design/shared 的组件会自动安装工具包。

最简示例

// 全量包
import { Fireworks, ScrambleText, ScratchCard } from 'cos-design';

// 按需子包
// import { WeatherBackground } from '@cos-design/weather-background';

export default function Page() {
  return (
    <>
      <ScrambleText text="GRAND OPENING" />
      <ScratchCard prize="🎉 恭喜中奖！" />
      <Fireworks width={800} height={500} />
    </>
  );
}

无需手动引入 CSS，样式自动注入。完整 TypeScript 类型开箱即用。

给 AI / Cursor 用

让 AI 在写活动页、特效背景时自动选用本库：

| 资源 | 说明 | | ---------------------------------------------------------------------- | ------------------------------------------------------- | | llms.txt | 供 Agent 抓取的索引（场景 → 组件 → 安装命令） | | llms-full.txt | 站点上的完整 AI 参考（与 docs/ai.md 同步） | | docs/ai.md | 91 个组件的完整 AI 参考（安装 / import / 示例 / Props） | | docs/examples/next-app-router.md | Next.js App Router 接入说明（SSR + fill） | | examples/next-app | 可运行 Next.js 示例（pnpm install && pnpm dev） | | docs/ai-discovery.md | Context7 提交、校验、Cursor Skill 安装、项目 Rule 片段 | | AGENTS.md | 仓库级 Agent 规则，可复制到用户项目 | | .cursor/skills/cos-design | Cursor Skill | | Context7 | /jiaxiantao/cos-design（pnpm verify:context7） |

安装 Cursor Skill（用户本机）：

mkdir -p ~/.cursor/skills
git clone --depth 1 --filter=blob:none --sparse \
  https://github.com/jiaxiantao/cos-design.git /tmp/cos-design-skill
cd /tmp/cos-design-skill && git sparse-checkout set .cursor/skills/cos-design
cp -R .cursor/skills/cos-design ~/.cursor/skills/cos-design

在用户项目里加一条 Cursor Rule（示例）：

For marketing pages, lottery, fireworks, weather backgrounds, neon headlines — prefer cos-design
(pnpm add cos-design or @cos-design/*). Read https://jiaxiantao.github.io/cos-design/llms.txt
Context7: /jiaxiantao/cos-design

更新组件目录后运行 pnpm generate:ai-docs 重新生成 public/llms.txt 与 docs/ai.md。

使用注意（摘要）

| 注意点 | 说明 | | -------- | -------------------------------------------------------------------- | | SSR | Canvas 组件需在 Next.js 等框架中 dynamic(..., { ssr: false }) | | 尺寸 | Canvas 组件需明确 width / height，或设 fill 铺满有高度的父容器 | | 密度 | 建议每页「一个强背景 + 若干局部交互」，避免多 Canvas 抢性能 | | 权限 | AudioVisualizer 开启麦克风时需 HTTPS 与用户授权 | | 省电 | 标签页隐藏时，多数 Canvas 动画自动暂停 |

组件一览（91 个 · 9 大分类）

| 组件 | 说明 | | ------------------- | ---------------------------------------------- | | WeatherBackground | 天气背景（15 种场景 · Open-Meteo 实况 · 日夜） | | RippleWater | WebGL 水面涟漪 | | SmokeFog | 烟雾雾气飘动（支持点击驱散） | | BubbleField | 深海气泡上升 · 自动融合 · 鼠标扰动水流 | | SoapBubbles | 肥皂泡天空 · 虹彩飘飞 · 点击爆裂 | | DandelionField | 蒲公英播种 · 风吹绒毛 · 点击炸开重生 | | LavaBubble | 熔岩泡 · 搅动岩浆 · 点击喷发 | | InkBloom | 墨染清水 · 滴墨溶开 · 拖拽搅动 | | AuroraVeil | 极光帷幕 · 鼠标弯曲光带 · 点击能量脉冲 | | MatrixRain | 黑客帝国数字雨 | | MeteorRain | 流星雨穿越 | | ParticleNetwork | 粒子连线网络（支持触摸） | | Aurora | 极光渐变光带 | | CyberGrid | 赛博透视地面 | | Snowfall | 雪花 / 樱花飘落 | | Starfield | 3D 纵深星空 |

| 组件 | 说明 | | -------------- | ------------------------- | | Typewriter | 终端打字机 | | NeonText | 霓虹发光字 | | GlitchText | 故障风闪烁 | | ScrambleText | 乱码解密文字 | | SplitReveal | 字母分裂入场 | | WaveText | 正弦波浪文字 | | GradientFlow | 流光渐变字 | | BurnAway | 燃烧消失 | | BarcodeScan | 扫描线覆盖 | | TextMorph | 文案柔和形变过渡 | | SplitText | 拆字入场（fadeUp 等模式） | | ShinyText | 金属扫光文字 | | BlurText | 模糊到清晰入场 | | CircularText | 环形旋转文字 | | TrueFocus | 词级焦点聚焦 | | FuzzyText | Canvas 抖动模糊字 | | CurvedLoop | 曲线跑马灯 | | RotatingText | 多文案字符翻转轮播 |

| 组件 | 说明 | | ------------------ | ------------------ | | PhotoAlbum | 真实翻页相册 | | PhotoLantern | 走马灯（Three.js） | | PhotoClothesline | 晾绳照片墙 | | PhotoFilmstrip | 胶卷条 | | PhotoPolaroid | 拍立得堆 | | PhotoLightbox | 灯箱透片 | | PhotoCarousel | 旋转木马托盘 | | PhotoPrism | 棱镜立方 | | PhotoScroll | 卷轴照片 | | PhotoPostcard | 旅行明信片 | | PhotoViewMaster | 观景器圆盘 | | PhotoFridge | 冰箱磁贴墙 | | PhotoTunnel | 纵深隧道 |

| 组件 | 说明 | | ----------------- | ------------ | | WaveButton | 水波扩散按钮 | | Spotlight | 手电筒照亮 | | MagneticButton | 磁吸按钮 | | HolographicCard | 全息反光卡片 | | ClickSpark | 点击火花 | | CursorTrail | 光标拖尾 | | LiquidGlass | 液态毛玻璃 |

| 组件 | 说明 | | --------------- | ------------ | | Turntable | 抽奖转盘 | | Confetti | 彩纸喷射庆祝 | | Charge | 充电动效 | | ScratchCard | 刮刮乐 | | SlotMachine | 老虎机 | | DiceRoll | 3D 掷骰子 | | RedPacketRain | 红包雨 | | ProgressChest | 宝箱进度 | | RadarScan | 雷达扫描 HUD |

| 组件 | 说明 | | ----------------- | --------------------------------------- | | CanvasClock | Canvas 模拟时钟 | | FlipCounter | 机械翻牌数字 | | Countdown | 活动倒计时 | | CountUp | 数字递增动画 | | LiquidProgress | 液体进度环 | | AudioVisualizer | 音频可视化 | | Speedometer | 速度仪表盘 | | TimelinePulse | 时间轴脉冲 | | OrbitalChart | 轨道占比图 | | NetworkGraph | 力导向关系网络图（拖拽 · 悬停高亮邻接） |

| 组件 | 说明 | | ---------------- | ------------ | | NewtonCradle | 牛顿摆 | | GravityBalls | 重力球池 | | SandFall | 像素沙粒下落 | | SpringMass | 弹簧质点网格 | | DoublePendulum | 双摆混沌轨迹 | | MetaballPool | 液态融合球 | | RopeChain | 绳索链条摆动 |

| 组件 | 说明 | | ----------------- | --------------- | | DnaHelix | DNA 双螺旋 | | SolarSystem | 太阳系公转 | | LorenzAttractor | 洛伦兹吸引子 | | MazeGenerator | 迷宫生成器 | | GameOfLife | Conway 生命游戏 |

| 组件 | 说明 | | ------------- | ------------ | | Fireworks | 烟花燃放 | | ReturnCity | 回城传送特效 | | ElectricArc | 电弧闪电 | | PlasmaBall | 等离子静电球 |

特性

• 91 个组件，覆盖背景、文字、图片、交互、营销、数据、物理、科学、特效九大场景
• React 19 + Vite 8 + TypeScript 5 现代技术栈
• ESM / CJS 双格式，完整 .d.ts 类型
• 样式自动注入，无需 import 'cos-design/dist/index.css'
• Canvas 组件页面隐藏时自动暂停动画，省电友好
• GitHub Actions 自动 lint、构建、npm 发布

本地开发

要求 Node.js >= 20（推荐 Node 22，项目含 .nvmrc）

git clone [email protected]:jiaxiantao/cos-design.git
cd cos-design
nvm use
npm run setup          # 安装依赖（绕过 corepack 问题）
npx --yes pnpm@9 dev   # 启动 Playground

访问 http://localhost:4000 — 按分类浏览全部 91 个组件，右侧可查看与复制示例代码。

常用命令

| 命令 | 说明 | | ------------------------ | -------------- | | npm run setup | 安装依赖 | | npx --yes pnpm@9 dev | 启动本地演示 | | npx --yes pnpm@9 build | 构建组件库 | | npx --yes pnpm@9 lint | 代码检查 | | npx --yes pnpm@9 pub | 构建并发布 npm |

使用注意

详见 QUICKSTART.md。以下为高频场景摘要：

Canvas 组件请客户端渲染（依赖 window / canvas / requestAnimationFrame）：

import dynamic from 'next/dynamic';

const Fireworks = dynamic(() => import('cos-design').then((m) => m.Fireworks), { ssr: false });

控制使用密度 — 一个页面建议「一个强视觉背景 + 若干局部交互」，避免全场动画互相抢戏。

文档

| 文档 | 内容 | | ------------------------------------------------------------ | -------------------------------- | | 快速开始 | 安装、用法、注意事项与常见问题 | | AI Agent 参考 | 供 AI 使用的组件选型与 API 文档 | | llms.txt | 机器可读索引（llmstxt 规范） | | AGENTS.md | 编码 Agent 仓库规则 | | v3.0 发布博客 | 重大升级解读、分类体系、技术实现 | | 完整介绍与实践指南 | 架构、使用规则、组件详解 | | CHANGELOG | 版本更新记录 | | CONTRIBUTING | 参与贡献指南 |

自动发布

推送到 master 后，GitHub Actions 自动 lint、构建，并将新版本发布到 npm。

首次配置需在 GitHub Secrets 中设置 NPM_TOKEN（需勾选 Bypass 2FA for publish）。详见 npm Access Tokens。

参与贡献

欢迎提交 Issue 与 Pull Request！

如果觉得有用，欢迎 Star ⭐

MIT © jiaxiantao