Create Your First Experiment

The Creative Sandbox is open to everyone. This guide will walk you through adding your own experiment, even if you've never used GitHub before.

What You'll Learn

  • ✓How to fork this repository (make your own copy)
  • ✓How to create a new experiment folder and file
  • ✓How to add your experiment to the registry
  • ✓How to submit your changes (create a Pull Request)
1

Fork the Repository

"Forking" means making your own copy of the project on GitHub where you can make changes without affecting the original.

Steps:

  1. Go to github.com/shalomormsby/ecosystem
  2. Click the "Fork" button in the top-right corner
  3. Click "Create fork" (keep the default settings)
  4. You now have your own copy! The URL will be: github.com/YOUR-USERNAME/ecosystem
2

Create Your Experiment File

You'll create a new page for your experiment in the appropriate category folder.

Choose a category:

  • games/ - Playable interactive experiences
  • visualizations/ - Math and generative art
  • animations/ - Motion technique experiments
  • tools/ - Functional utilities

Steps:

  1. In your forked repo, navigate to: apps/creative-powerup/app/
  2. Click into your category folder (e.g., games/)
  3. Click "Add file" → "Create new file"
  4. Name it: my-experiment/page.tsx (replace "my-experiment" with your slug)
  5. Paste the template code below ↓

Template Code:

export default function MyExperiment() {
  return (
    <div className="min-h-screen bg-background flex items-center justify-center p-8">
      <div className="max-w-2xl">
        <h1 className="text-4xl font-bold text-foreground mb-4">
          My Experiment
        </h1>
        <p className="text-xl text-foreground/70">
          Replace this with your experiment code!
        </p>

        {/* Add your code here */}
      </div>
    </div>
  );
}

💡 Tip: Use design-system components for styling consistency:

import { Button, Card } from '@opencosmos/ui';
import { useMotionPreference } from '@opencosmos/ui/hooks';
3

Add to Registry

Now tell the gallery about your experiment by adding it to the registry file.

Steps:

  1. Navigate to: apps/creative-powerup/lib/experiments.ts
  2. Click the pencil icon to edit the file
  3. Find the experiments array
  4. Add your experiment entry at the end (copy template below)

Registry Entry Template:

{
  slug: 'my-experiment',
  title: 'My Cool Experiment',
  category: 'games', // or 'visualizations', 'animations', 'tools'
  description: 'A short description of what your experiment does (1-2 sentences).',
  author: 'Your Name',
  path: '/games/my-experiment', // match your category
  dateAdded: '2025-12-17', // today's date
  tags: ['creative', 'interactive'], // optional tags
},

⚠️ Important: Don't forget the comma at the end! Make sure your entry has the same formatting as the others.

4

Submit Your Changes (Pull Request)

A "Pull Request" (PR) is how you ask to add your changes to the main project.

Steps:

  1. After committing your changes, GitHub will show a yellow banner at the top
  2. Click "Compare & pull request"
  3. Write a title: "Add [your experiment name] to Creative Sandbox"
  4. In the description, explain what your experiment does and why it's cool
  5. Click "Create pull request"

🎉 That's it! A maintainer will review your PR and give feedback. Once approved, your experiment will appear in the gallery!

Need Help?

Stuck on a step? Have questions? We're here to help!

GitHub Discussions: Ask a question →
GitHub Issues: Report a bug →