# Contributing to GSAP Animation Helper Skill

Thank you for your interest in contributing! This modular skill helps Claude AI provide better guidance on GSAP animations.

## 📁 New Modular Structure

Before contributing, understand our new structure:

```
gsap-skill/
├── SKILL.md                  # Main entry point
├── plugins/                  # Individual plugin documentation (~150 lines each)
├── frameworks/               # Framework-specific guides
├── reference/                # Core API reference
└── examples/                 # Working code examples
```

This structure allows efficient agent usage - Claude reads only the files needed for each query.

---

## 🤝 Types of Contributions

### 1. Fix or Improve Documentation

**In existing files:**
- Fix typos or unclear explanations
- Add missing examples
- Improve formatting

**Files to edit:**
- `SKILL.md` - Only change decision tree, core concepts, or common patterns
- Any file in `plugins/`, `frameworks/`, `reference/`
- `README.md`, `QUICKSTART.md`

```bash
git checkout -b fix-scrolltrigger-docs
# Edit plugins/scroll-trigger.md
git add plugins/scroll-trigger.md
git commit -m "Fix ScrollTrigger boundary explanation"
```

### 2. Add New Plugin Documentation

When GSAP adds new plugins:

1. **Create new file** in `plugins/`: `plugins/new-plugin-name.md`
2. **Follow template:**
   ```markdown
   # New Plugin Name

   Brief description (1-2 lines).

   ## Installation
   ## Basic Usage
   ## Configuration
   ## Common Patterns
   ## Tips
   ```
3. **Limit to ~200 lines**
4. **Include examples** for 3-5 common use cases
5. **Update SKILL.md decision tree** to reference new plugin

### 3. Improve Framework Guides

**Files:** `frameworks/react.md`, `frameworks/nextjs.md`, `frameworks/vanilla.md`

Add:
- New patterns
- Gotchas and solutions
- Performance tips
- Testing approaches

### 4. Add Working Examples

**Location:** `examples/`

Create focused examples showing:
- One specific use case
- Working code
- Comments explaining key points
- How to run it

**File naming:** `{framework}-{feature}.{ext}`
- `react-split-text.jsx`
- `nextjs-scroll-trigger.jsx`
- `vanilla-timeline.js`

### 5. Add Reference Material

**Add to `reference/`** when there's significant new content:
- New utility functions
- New easing types
- New core methods

---

## ✅ Contribution Guidelines

### Documentation Standards
- **Keep it focused** - One file = one topic
- **Concise examples** - Each example does one thing well
- **Clear explanations** - Explain the "why"
- **Include code blocks** - Every concept needs examples
- **Add comments** - Code should be self-documenting

### Code Examples
- **Test first** - Verify with GSAP 3.12+
- **Keep it simple** - Solve one problem per example
- **Include comments** - Explain the approach
- **Working code** - Copy-paste should work
- **Modern syntax** - ES6+, async/await

### Framework-Specific
- **Vanilla JS** - No framework dependencies
- **React** - Use `useGSAP` hook
- **Next.js** - Include `"use client"`, SSR considerations
- **TypeScript** - Optional but appreciated

### Testing
- ✅ GSAP 3.12+ compatible
- ✅ Works in Chrome, Firefox, Safari
- ✅ Mobile tested for scroll animations
- ✅ No console warnings
- ✅ No breaking changes

---

## 🔄 Pull Request Process

### 1. Fork & Branch
```bash
git clone https://github.com/yourusername/gsap-skill-template.git
cd gsap-skill-template
git checkout -b add-new-feature
```

### 2. Make Your Changes
- Edit or create files
- Follow guidelines above
- Keep commits focused

### 3. Test
```bash
# Verify examples work
# Check formatting with your editor
# Ensure no broken links
```

### 4. Commit
```bash
git add .
git commit -m "Add ScrollSmoother parallax example"
```

**Good commit messages:**
- "Fix typo in ScrollTrigger docs"
- "Add viewport-based animation example"
- "Improve React SSR explanation"

### 5. Push & Create PR
```bash
git push origin add-new-feature
# Go to GitHub and create pull request
```

**In your PR description:**
```markdown
## What changed?
Brief description of what you added/fixed

## Why?
Explain the benefit

## Testing
How you tested the changes

## Files changed
- plugins/scroll-trigger.md
- frameworks/react.md
```

---

## 📋 Contribution Ideas

We're especially interested in:

- [ ] **New plugin docs** - When GSAP releases new plugins
- [ ] **Common patterns** - "How do I X with Y?"
- [ ] **Troubleshooting** - "Why doesn't this work?"
- [ ] **Performance tips** - Mobile optimization, best practices
- [ ] **Framework patterns** - New ways to use with React/Next.js
- [ ] **TypeScript examples** - TS versions of JS examples
- [ ] **Accessibility** - Animation best practices for a11y
- [ ] **Error handling** - Common gotchas and solutions
- [ ] **Migration guides** - Coming from other libraries

---

## ❌ Don't

- ❌ Submit outdated GSAP syntax (v2 or older)
- ❌ Untested code examples
- ❌ Overly complex examples without explanation
- ❌ Change SKILL.md structure without discussion
- ❌ Add duplicate content across files
- ❌ Promote paid GSAP plugins only (focus on free tools)

---

## 🚀 Quick Wins

Good first contributions:

1. **Fix a typo** - Search for obvious mistakes
2. **Clarify an example** - Add helpful comments to existing code
3. **Add missing pattern** - E.g., "Hover animation" in `reference/core-methods.md`
4. **Improve formatting** - Better code highlighting, clearer structure
5. **Add resource links** - Link to official GSAP docs for topics

---

## ❓ Questions?

- **GSAP questions?** → https://gsap.com/community/
- **About this skill?** → Check existing issues
- **General JS help?** → MDN Web Docs

---

## 📝 File Structure Template

When creating new files, follow this structure:

### Plugin Template
```markdown
# Plugin Name

1-2 line description.

**Note:** If premium, mention "Club GSAP membership required"

## Installation
## Basic Usage
## Configuration
## Common Patterns
- Pattern 1
- Pattern 2
- Pattern 3
## Tips
```

### Framework Template
```markdown
# Framework Name

## Installation
## Basic Setup
## Core Pattern
## Common Patterns
- Pattern 1
- Pattern 2
## Troubleshooting
## Tips
```

### Reference Template
```markdown
# Topic Name

### Method/Function Name
Description and basic usage.

```javascript
// Example
```

### Another Method
...
```

---

## 🎉 Recognition

Contributors are appreciated! We'll:
- ✅ Credit you in commit messages
- ✅ Thank you in README
- ✅ Add you to CONTRIBUTORS list (if desired)

---

**Thank you for making this skill better! Together we create an amazing GSAP learning resource.** 🚀

---

*Last updated: 2026*