Paper Gravity Studio

A React component library for paper-inspired card interfaces and GSAP-powered motion effects.

中文 | English

---

中文

Paper Gravity Studio 是一个可复用的 React 纸质感卡片动效组件库，适合用来构建编辑型卡片、桌面散落卡片、文件堆叠、杂志封面流、报告展开和档案墙等界面。

这个项目也可以作为前端作品集展示：它体现了组件化架构、GSAP 动效设计、Props 驱动的 React API、统一视觉系统，以及方便复制集成的组件文档。

项目亮点

• 所有核心组件都支持外部 Props，同时保留内置演示数据。
• 纸质感视觉系统：色调预设、细腻纹理、多层阴影和编辑排版。
• 使用 GSAP 实现滚动、视差、散落、堆叠、翻页和展开动效。
• 文档结构清晰，便于复制到其他项目中复用。
• 支持 reduced motion 和指针能力检测，交互更稳妥。

项目结构

路径	说明
paper-gravity-studio/	React 18 + GSAP 组件库和演示应用
card-motion-gallery/	独立 HTML 动效预览页，适合快速查看效果

快速开始

cd paper-gravity-studio<img width="3161" height="3869" alt="PixPin_2026-06-05_22-38-39" src="https://github.com/user-attachments/assets/98cdf0cf-6067-4408-a4be-42cfca3a1e22" />

npm install
npm run dev
npm run build

组件使用示例

import {
  HeroSection,
  DeskScatter,
  FolderStack,
  HERO_CARDS,
  SCATTER_CARDS,
} from 'paper-gravity-studio';
import 'paper-gravity-studio/styles';

export default function App() {
  return (
    <>
      <HeroSection cards={HERO_CARDS} />
      <DeskScatter cards={SCATTER_CARDS} initialLayout="scatter" height={360} />
      <FolderStack />
    </>
  );
}

核心组件

组件	Props	说明
HeroSection	cards	首页漂浮纸张卡片，支持鼠标视差
EditorialCascade	cards	编辑风格卡片网格，滚动入场并支持展开
DeskScatter	cards, initialLayout, height	桌面散落到网格切换，支持指针推开效果
FolderStack	cards	滚动展开的文件堆叠卡片
MagazineFlip	pages	横向杂志封面流
ReportExpand	report	滚动驱动的双栏报告展开
ArchiveRoom	cards, title, subtitle	全屏档案卡片墙

所有 Props 都是可选的。不传入数据时，组件会使用 src/data/cards.js 中的演示数据。

文档入口

从 paper-gravity-studio/docs/COMPONENTS.md 开始查看组件索引；每个组件的详细说明位于 paper-gravity-studio/docs/components/。

构建产物

文件	格式
dist/paper-gravity-studio.esm.js	ESM
dist/paper-gravity-studio.cjs.js	CommonJS
dist/style.css	共享样式

---

English

Paper Gravity Studio is a reusable React component library for high-end paper card motion effects. It provides editorial cards, desk scatters, folder stacks, magazine cover flows, report expansion, and archive wall layouts.

The project is designed as a front-end portfolio piece: it demonstrates component architecture, motion design, props-driven React APIs, reusable visual systems, and documentation for copying the components into other projects.

Highlights

• Props-driven React components with built-in demo data fallbacks.
• Paper-inspired visual system with tint presets, subtle texture, layered shadows, and editorial typography.
• GSAP-powered scroll, parallax, scatter, stack, flip, and reveal animations.
• Component documentation designed for quick reuse.
• Reduced-motion and pointer-capability checks for responsible interaction design.

Project Structure

Path	Purpose
paper-gravity-studio/	React 18 + GSAP component library and demo app
card-motion-gallery/	Standalone HTML motion gallery for quick browser previews

Quick Start

cd paper-gravity-studio
npm install
npm run dev
npm run build

Library Usage

import {
  HeroSection,
  DeskScatter,
  FolderStack,
  HERO_CARDS,
  SCATTER_CARDS,
} from 'paper-gravity-studio';
import 'paper-gravity-studio/styles';

export default function App() {
  return (
    <>
      <HeroSection cards={HERO_CARDS} />
      <DeskScatter cards={SCATTER_CARDS} initialLayout="scatter" height={360} />
      <FolderStack />
    </>
  );
}

Core Components

Component	Props	Description
HeroSection	cards	Floating paper cards with cursor parallax
EditorialCascade	cards	Editorial card grid with scroll entry and expandable cards
DeskScatter	cards, initialLayout, height	Scatter-to-grid desk layout with pointer nudge
FolderStack	cards	Scroll-revealed folder pile with manual next control
MagazineFlip	pages	Horizontal cover flow for magazine-style pages
ReportExpand	report	Scroll-driven two-panel report reveal
ArchiveRoom	cards, title, subtitle	Full-screen archive card wall with central copy

All props are optional. When omitted, components use the demo data from src/data/cards.js.

Documentation

Start with paper-gravity-studio/docs/COMPONENTS.md, then open the matching file in paper-gravity-studio/docs/components/ for component-specific API notes and data shape examples.

Build Output

File	Format
dist/paper-gravity-studio.esm.js	ESM
dist/paper-gravity-studio.cjs.js	CommonJS
dist/style.css	Shared styles

License

MIT