cos-design

English (for developers & AI agents)

cos-design is a multi-framework library of visual effects — fireworks, scratch cards, weather/matrix backgrounds, neon headlines, flip counters — not a general admin UI kit. React is the default entry; Vue 3, Core APIs, and Web Components use the same package names via subpaths.

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} />
    </>
  );
}

<script setup>
import { Fireworks } from '@cos-design/fireworks/vue';
</script>
<template>
  <Fireworks :width="800" :height="500" />
</template>

<script type="module">
  import '@cos-design/fireworks/element';
</script>
<cos-fireworks auto fill></cos-fireworks>

• 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
• v4 migration: docs/migration-v4.md
• Start here (campaign): Build a campaign page in 10 minutes · runnable examples/next-app · examples/vue-app · examples/vanilla
• 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 默认入口，同时支持 Vue 3 / 原生命令式 API / Web Components）——专注特效与氛围，给页面加趣味、加记忆点的「特效层」。

适合用在：

从背景到物理、从文字到营销，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 在写活动页、特效背景时自动选用本库：

安装 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。

使用注意（摘要）

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

特性

• 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 git@github.com:jiaxiantao/cos-design.git
cd cos-design
nvm use
npm run setup          # 安装依赖（绕过 corepack 问题）
npx --yes pnpm@9 dev   # 启动 Playground

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

常用命令

使用注意

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

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

import dynamic from 'next/dynamic';

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

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

文档

自动发布

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

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

参与贡献

欢迎提交 Issue 与 Pull Request！