spark

A conversational component generation system for Cursor IDE that creates production-ready UI components through natural language interaction.

Built by Fueled | Designed for Teams | Production-Ready Components

Quick Start

Installation

git clone https://github.com/devinle/spark.git
cd spark
chmod +x install.sh
./install.sh

Non-Interactive Installation

For automated environments (CI/CD, scripts), use the non-interactive mode:

# From your project directory
/path/to/spark/install.sh --non-interactive

# Or set environment variable
NON_INTERACTIVE=true /path/to/spark/install.sh

The installation script will:

Detect your project type (React, WordPress, HTML, etc.)
Create the necessary .cursor/rules directory structure
Install Spark rules for Cursor IDE
Set up proper permissions

Usage

⚠️ IMPORTANT: After installation, you must restart Cursor IDE for Spark to work!

Cursor IDE Restart Required

Spark works by installing rules in your project's .cursor/rules/spark/ directory. Cursor IDE loads these rules when it starts up, so a restart is required after installation for Spark to become available.

Step-by-Step Restart Process

1. Save Your Work

Before restarting, make sure to save any open files in Cursor IDE:

Mac: Cmd+S to save current file, or Cmd+Option+S to save all
Windows/Linux: Ctrl+S to save current file, or Ctrl+K+S to save all

2. Quit Cursor IDE Completely

Important: Don't just close the window - quit the application completely:

Mac:
- Press Cmd+Q to quit
- Or go to Cursor menu → Quit Cursor
- Or right-click Cursor in dock → Quit
Windows:
- Press Alt+F4 to close the window
- Or click the X button in the top-right corner
- Or right-click Cursor in taskbar → Close window
Linux:
- Press Alt+F4 to close the window
- Or click the X button in the top-right corner
- Or right-click Cursor in dock/taskbar → Quit

3. Reopen Cursor IDE

Open Cursor IDE again
Open your project (the one where you installed Spark)
Wait for Cursor to fully load

4. Verify Spark is Working

Open the chat panel:
- Mac: Cmd+L
- Windows/Linux: Ctrl+L
Type @spark help and press Enter
If you see Spark's help message, installation was successful!

Quick Start After Restart

Once Cursor IDE is restarted, you can start using Spark:

@spark                    # Let's chat about what you need
@spark accordion          # Create an accordion component
@spark faq                # Quick FAQ accordion
@spark product-card       # E-commerce product card
@spark help               # Show all options

What You Get

Four Production-Ready Components:

📋 Accordion - Collapsible sections for FAQs, content organization, step-by-step guides
⬜ Card - Content containers for blog posts, products, profiles, media displays
⭕ Carousel - Image sliders for galleries, testimonials, hero banners, content rotation
💬 Dialog - Modals and popups for confirmations, lightboxes, contact forms, alerts

Multiple Technology Stacks:

React (TypeScript & JavaScript)
Next.js (App Router, Server Components)
WordPress (Blocks, Patterns, FSE)
Vanilla HTML/CSS/JavaScript
Web Components

Built-in Best Practices:

WCAG 2.2 AA accessibility compliance
Mobile-first responsive design
Performance optimizations (CLS prevention, lazy loading)
Modern JavaScript patterns
BEM CSS methodology
Production-ready code quality
Context7 Integration - Automatically enhanced with latest framework documentation and best practices when available

Features

Conversational Interface: Natural language interaction with Cursor IDE
Smart Project Detection: Automatically detects Next.js, React, WordPress, and other project types
Accessibility First: WCAG 2.2 AA compliant components
Multiple Frameworks: Works with Next.js, React, WordPress, and vanilla HTML/CSS/JS
Modern Patterns: Server Components, FSE, App Router, and latest framework features
Production Ready: Optimized code with best practices built-in
Context7 Integration: Seamlessly enhanced with latest framework documentation and best practices when available

Installation Requirements

Cursor IDE (required) - Spark integrates with Cursor's Chat Agent interface
Git - For installation and updates
Node.js 16+ (for React/TypeScript components)
PHP 7.4+ (for WordPress components)

Important: How Spark Works with Cursor IDE

Spark is not a command-line tool. It works exclusively through Cursor IDE's chat interface:

@spark - Chat trigger within Cursor IDE (not a CLI command)
@cursor - Separate CLI tool to launch Cursor IDE (not related to Spark)
No terminal commands - All interaction happens in Cursor's chat panel

Works with any project type:

Next.js / React applications
WordPress themes and plugins
Static HTML sites
Node.js projects
Monorepos

Available Components

Spark generates four core UI components:

Accordion

Collapsible sections perfect for FAQs, product details, and step-by-step guides

Accessible keyboard navigation
Smooth animations
Multiple open/close patterns

Card

Content containers for products, blog posts, team profiles, and media displays

Responsive layouts
Image optimization
Action button support

Carousel

Image sliders for galleries, testimonials, hero banners, and content rotation

Touch/swipe support
Auto-play options
Navigation controls

Dialog

Modals and popups for confirmations, lightboxes, contact forms, and alerts

Focus management
Escape key handling
Backdrop interactions

Modern WordPress Support

Spark provides comprehensive support for modern WordPress development, including Full Site Editing (FSE), Gutenberg blocks, and block patterns.

Lean on Core Philosophy

Spark prioritizes WordPress core blocks over custom solutions:

Block Patterns First (Recommended)
- Uses WordPress core blocks (Group, Paragraph, etc.)
- Custom CSS for accordion behavior
- No custom PHP/JS maintenance
- FSE compatible out of the box
Custom Gutenberg Blocks (When Needed)
- Full control over functionality
- Complex interactions and data structures
- InnerBlocks for nested content
- Block API v3 (block.json)
Both Options (Maximum Flexibility)
- Pattern for simple use cases
- Custom block for advanced features
- Best of both approaches

10up Scaffold Alignment

When Spark detects the 10up WP Scaffold structure, it automatically follows their conventions:

Smart Directory Placement:

Functionality → mu-plugins/10up-plugin/
Blocks → themes/10up-theme/blocks/
Patterns → themes/10up-theme/patterns/
Components → themes/10up-theme/components/

Asset Bundling:

Integrates with 10up Toolkit
NPM workspaces support
Follows 10up package.json conventions

WordPress Component Generation

Example: Creating an Accordion

@spark accordion wordpress

Spark's Intelligent Analysis:

🔍 Analyzing your WordPress project...

✅ 10up scaffold detected
✅ Block theme (FSE enabled)
✅ Using 10up Toolkit for assets

Great! I can build this accordion in several ways:

**Recommended: Block Pattern** (uses core blocks)
✓ Fast to implement
✓ No custom code maintenance
✓ Works with any theme
✓ FSE compatible

Or I can create:
1. Custom Gutenberg Block (full control)
2. Dynamic Block with ACF (perfect for CMS editors)
3. Both pattern + custom block

Which approach? (default: Pattern)

WordPress Command Examples

# Let Spark analyze and recommend
@spark accordion wordpress

# Force block pattern (uses core blocks)
@spark accordion wordpress --as=pattern

# Force custom Gutenberg block
@spark accordion wordpress --as=block

# Both pattern and custom block
@spark accordion wordpress --as=both

# Advanced: Dynamic block with ACF integration
@spark accordion wordpress --as=block --dynamic=true --acf=true

# FSE-focused generation
@spark accordion wordpress --fse=true --theme-json=true

# Block with variations
@spark accordion wordpress --as=block --variations=faq,product,steps

Generated File Structures

Block Pattern (Recommended):

themes/10up-theme/
├── patterns/
│   └── accordion-faq.php           # Pattern registration
└── assets/css/patterns/
    └── accordion-faq.css           # Custom styling

Custom Gutenberg Block:

themes/10up-theme/blocks/accordion/
├── block.json                      # Block API v3
├── index.js                        # Block registration
├── edit.js                         # Editor (React)
├── render.php                      # PHP render callback
├── view.js                         # Frontend interactions
├── style.scss                      # Frontend + Editor styles
├── editor.scss                     # Editor-only styles
├── variations.js                   # Block variations
└── README.md                       # Documentation

Modern WordPress Features

✅ Block API v3 - Latest block registration standards
✅ Full Site Editing (FSE) - Compatible with block themes
✅ Block Patterns - Pre-configured block combinations
✅ Block Variations - Multiple configurations per block
✅ theme.json Integration - Global styles and design tokens
✅ ACF Integration - Automatic detection and field generation
✅ 10up Toolkit - Seamless asset bundling integration
✅ NPM Workspaces - Proper dependency management

WordPress Best Practices

Every WordPress component includes:

✅ Accessibility - WCAG 2.2 AA compliance
✅ Security - Proper escaping, sanitization, nonces
✅ Internationalization - Translation-ready with proper text domains
✅ Performance - Lazy loading, efficient queries
✅ Testing - PHPUnit tests for PHP, Jest for JavaScript
✅ Documentation - Complete usage examples and guidelines

How It Works

Spark integrates with Cursor IDE through a simple rule system that:

Detects your project type automatically
Provides conversational component generation
Supports multiple technology stacks
Follows accessibility best practices
Generates production-ready code
Context7 Integration: Automatically enhances components with latest framework documentation and best practices when available
Modern WordPress: Smart detection of FSE, blocks, and 10up scaffold patterns

Context7 Integration

Spark seamlessly integrates with the Context7 MCP server to provide enhanced component generation:

Automatic Detection: Silently checks for Context7 availability before generating components
Framework-Specific Enhancement: Uses latest documentation for React, Next.js, WordPress, and other frameworks
Library Integration: Leverages current best practices for Material-UI, Chakra UI, Tailwind, and more
Frictionless Experience: Works perfectly even when Context7 is unavailable - no interruption to your workflow
Natural Enhancement: Presents improvements as "latest patterns" without mentioning Context7 directly

What This Means for You:

Components are always generated with the most current patterns and best practices
Framework-specific optimizations are automatically applied
Library integrations follow the latest conventions
No additional setup or configuration required
Works seamlessly whether Context7 is available or not

Cursor IDE Integration Details

Spark works by installing rules in your project's .cursor/rules/spark/ directory. When you:

Open Cursor IDE in your project
Open the Chat panel (Cmd+L on Mac, Ctrl+L on Windows/Linux)
Type @spark followed by a component name
Spark responds with conversational component generation

Key Points:

Spark is not a command-line tool - it only works in Cursor's chat interface
The @spark trigger is not the same as @cursor CLI commands
All component generation happens through natural language conversation
No terminal or command-line interaction required

Project Detection

Spark automatically detects your project type and adapts accordingly:

React/Next.js: Generates TypeScript components with modern patterns
WordPress: Creates PHP components following WordPress standards
HTML/CSS: Produces vanilla JavaScript with accessibility features
Unknown: Works with any project type using best practices

Updates

Keep Spark current with the latest patterns and improvements:

# From the spark repository
./update.sh

# Check for updates manually
git pull origin main && ./install.sh

# Verify installation after updates
./verify.sh

Contributing

We welcome contributions! Spark is built by developers for developers.

Component Requests

Need a component that's not included? Open an issue with:

Component description and use case
Example implementations or designs
Technology stack requirements

Pattern Improvements

Found a better way to implement something? Submit a PR with:

Clear description of the improvement
Testing across multiple use cases
Documentation updates

Development Setup

git clone https://github.com/devinle/spark.git
cd spark

# Test installation locally
./install.sh

# Test in Cursor IDE
# Open a test project and try @spark commands

Support

Community

GitHub Issues - Report bugs, request features
GitHub Discussions - Ask questions, share tips

Troubleshooting

Spark not responding in Cursor?

First step: Restart Cursor IDE completely (quit and reopen)
Verify installation: ls .cursor/rules/spark/
Check that you're in a project directory with the rules installed
Make sure you're using @spark in Cursor's chat panel, not the terminal
Run verification script: ./verify.sh (from your project directory)

@spark not working in chat?

Ensure you're typing @spark (not @cursor)
Check that Cursor IDE is up to date
Verify the chat panel is open (Cmd+L / Ctrl+L)
Try typing just @spark first, then add component names

Installation issues?

Ensure you have Git installed
Check project permissions
Try running ./install.sh again
Make sure you're running the script from the spark repository

Need to reset installation?

rm -rf .cursor/rules/spark
cd path/to/spark && ./install.sh

Common Misconceptions:

❌ Spark is not a command-line tool
❌ @spark is not a terminal command
❌ You cannot run Spark from the terminal
✅ Spark only works in Cursor IDE's chat interface
✅ Use @spark in Cursor's chat panel, not the terminal

Advanced Troubleshooting

Spark Still Not Working After Restart?

Check Installation:
```
ls .cursor/rules/spark/
```
You should see files like spark.mdc and .restart-required
Run Verification Script:
```
./verify.sh
```
This will check your installation and provide specific guidance
Try Another Restart: Sometimes Cursor needs a second restart to pick up new rules
Check Cursor IDE Version: Make sure you're using a recent version of Cursor IDE
Verify Project Directory: Make sure you're in the correct project directory where Spark was installed

Common Issues

"@spark not found" in chat

This means Cursor hasn't loaded the rules yet
Try restarting Cursor IDE again
Make sure you're in the project directory where Spark was installed

"@spark" works but shows no response

Check that you're typing @spark (not @cursor)
Make sure the chat panel is open (Cmd+L / Ctrl+L)
Try typing just @spark first, then add component names

Installation verification fails

Run ./verify.sh to diagnose the issue
Check file permissions in .cursor/rules/spark/
Try reinstalling Spark

Alternative: Manual Rule Reload

If you can't restart Cursor IDE right now, you can try:

Close all Cursor IDE windows
Wait 5-10 seconds
Reopen Cursor IDE

This sometimes works as a "soft restart" for rule loading.

Still Having Issues?

If Spark still isn't working after following this guide:

Check the troubleshooting section above
Run the verification script: ./verify.sh
Open an issue on GitHub with:
- Your operating system
- Cursor IDE version
- Output from ./verify.sh
- Any error messages you see

Quick Reference

Action	Mac	Windows/Linux
Save file	Cmd+S	Ctrl+S
Save all	Cmd+Option+S	Ctrl+K+S
Quit Cursor	Cmd+Q	Alt+F4
Open chat	Cmd+L	Ctrl+L
Test Spark	Type `@spark help`	Type `@spark help`

Remember: Spark only works in Cursor IDE's chat interface, not in the terminal or command line!

Roadmap

v1.1 (Current)

Four core components (Accordion, Card, Carousel, Dialog)
Multi-stack support (React, WordPress, Vanilla)
Conversational component generation

v1.2 (Q1 2025)

Additional components (Button, Input, Navigation)
Theme system and design tokens
Component composition patterns

v1.3 (Q2 2025)

Visual component builder
Integration with design systems (Tailwind, Chakra, Material-UI)
Advanced testing patterns

Future Considerations

VS Code extension compatibility
Component marketplace
Team collaboration features

License

MIT License - feel free to use Spark in your projects and contribute back to the community.

Built by Fueled

Spark is developed by Fueled, a digital product agency focused on creating exceptional user experiences. We build internal tools that make our team more productive, and we're excited to share them with the broader development community.

Ready to build amazing components?

git clone https://github.com/devinle/spark.git
cd spark
chmod +x install.sh
./install.sh

Then open Cursor and type @spark to get started!

Name		Name	Last commit message	Last commit date
Latest commit History 23 Commits
.cursor		.cursor
.github/workflows		.github/workflows
assets		assets
README.md		README.md
config.sh		config.sh
install.sh		install.sh
package.json		package.json
update.sh		update.sh
verify.sh		verify.sh

devinle/spark

Folders and files

Latest commit

History

Repository files navigation