Introducing Spark UI v1: An Open-Source React Component Registry with an Agent Skill ⚡
I’m excited to share Spark UI v1, the first public version of an open-source component collection built for modern React applications.
Spark UI currently includes 35 reusable components, ranging from familiar UI primitives such as buttons, dialogs, tables, and form controls to more visual and interactive components such as kanban boards, shimmer text, image trails, animated gradients, Spotify cards, and branded interface elements.
The project is designed around a simple idea:
Developers should be able to install a component, read its source code, customize it freely, and keep full ownership of the final implementation.
Spark UI is not intended to be a closed component package that hides its implementation behind an npm dependency. It follows a shadcn-compatible source registry approach, which means the component source code is copied directly into your project.
That makes the components easier to understand, modify, debug, and adapt to the needs of a real application.
What is Spark UI?
Spark UI is an open-source component registry built with:
- React 19
- Next.js App Router
- TypeScript
- Tailwind CSS v4
- shadcn design tokens and registry conventions
- Radix UI primitives
- class-variance-authority
- Framer Motion for selected animated components
The library includes both practical application components and more expressive interface elements.
Some examples include:
- Buttons and form controls
- Dialogs and overlays
- Tables and layout primitives
- Kanban boards
- Shimmer text
- Animated gradients
- Image trails
- QR-related components
- Spotify-inspired cards
- Navigation components
- Responsive interface patterns
The goal is not only to provide attractive components, but also to make them useful in real projects where maintainability, accessibility, and customization matter.
Why a source registry instead of a traditional package?
Many UI libraries are distributed as npm packages.
That approach can be useful, but it also means your project depends on the library’s published API, internal implementation, release cycle, and styling decisions.
Spark UI takes a different approach.
When you install a Spark UI component, the component source is added directly to your project.
This gives you several advantages:
- You can inspect the complete implementation
- You can modify the component without forking a package
- You can remove code you do not need
- You can adapt styling to your own design system
- You can update accessibility behavior when necessary
- You are not locked into a hidden runtime implementation
- The component becomes part of your own codebase
This model works especially well for design systems, dashboards, SaaS applications, portfolios, landing pages, and internal tools where developers often need to make targeted changes.
Installing a Spark UI component
Spark UI uses the shadcn CLI workflow.
Before installing a component, you can inspect the registry item:
npx shadcn@latest view https://spark-ui-olive.vercel.app/r/kanban.json
After reviewing the files and dependencies, install it with:
npx shadcn@latest add https://spark-ui-olive.vercel.app/r/kanban.json
The component source is then copied into your project, where you can import and customize it like any other local component.
For example, a component may be imported from a path similar to:
import { Kanban } from "@/components/spark-ui/kanban";
The exact path depends on the project configuration and the registry item being installed.
Because the code is local, you can immediately:
- Change the component layout
- Replace icons
- Update Tailwind classes
- Add or remove animations
- Integrate application state
- Connect it to your backend
- Adapt it to your project’s component conventions
Spark UI includes an Agent Skill 🤖
One of the main additions in Spark UI v1 is an Agent Skill.
The Agent Skill is designed for compatible AI coding agents such as Claude Code and other tools that support the open Agent Skills ecosystem.
It gives the agent structured guidance about how Spark UI works.
Instead of forcing the agent to guess component names, registry paths, imports, or composition rules, the skill teaches it how to work with the library more accurately.
Install the skill with:
npx skills add codeweb-dev/spark-ui --skill spark-ui
The skill helps compatible agents understand how to:
- Discover available Spark UI components
- Inspect registry items before installation
- Use the official Spark UI registry
- Avoid inventing component names or import paths
- Install only the components that are missing
- Read and understand the installed source
- Compose compound components correctly
- Work with shadcn design tokens
- Preserve accessibility behavior
- Customize components safely
- Troubleshoot common installation problems
- Review dependency and file changes after installation
The Agent Skill also includes supply-chain guidance.
It instructs agents to treat downloaded source code as code that should be reviewed, not as trusted instructions that should be executed automatically.
This is important because a source registry intentionally downloads files into a project. The skill encourages the agent to inspect the registry item first, use the official registry origin, review generated changes, and avoid following instructions embedded inside downloaded source files.
Why add an Agent Skill to a component library?
AI coding tools are becoming part of many developers’ daily workflows.
However, AI agents often make predictable mistakes when working with component libraries:
- They invent exports that do not exist
- They use the wrong import path
- They recreate a component that is already available
- They install the same component twice
- They forget required providers
- They break compound-component structure
- They use hard-coded colors instead of design tokens
- They omit accessibility requirements
- They treat examples as exact APIs without checking the source
A dedicated skill gives the agent project-specific instructions.
For Spark UI, that means the agent can understand not only what components exist, but also how they are expected to be installed, composed, styled, and validated.
The goal is to make AI-assisted development more reliable and reduce the amount of correction needed after generated code.
Security improvements in Version 1
Because Spark UI distributes source code through a remote registry, security and transparency are important.
The project now documents the official registry origin:
https://spark-ui-olive.vercel.app/r
The recommended workflow is:
- Inspect the registry item
- Review the files and dependencies
- Install only from the official registry
- Inspect the resulting Git diff
- Run the project’s validation commands
Spark UI does not require users to upload environment variables, secrets, local files, tokens, or private project data to install a component.
The project also hardened the Spotify metadata functionality to reduce SSRF risk.
Instead of allowing arbitrary server-side URL fetching, the implementation validates Spotify track identifiers and constructs the Spotify URL on the server. Redirects, retries, timeout behavior, and response-size limits are also controlled.
These changes were made because open-source components should be easy to inspect and safe to integrate.
Designed for customization
Spark UI components are intended to be starting points, not untouchable black boxes.
You can use them as they are, but the source-first approach makes customization one of the main features.
You can change:
- Typography
- Spacing
- Border radius
- Shadows
- Colors
- Motion behavior
- Responsive breakpoints
- Icons
- Component states
- Data structures
- Event handling
- Accessibility labels
- Layout composition
Where possible, components use semantic shadcn and Tailwind design tokens such as:
--background
--foreground
--primary
--muted
--muted-foreground
--border
This allows components to adapt more naturally to light mode, dark mode, and custom themes.
Looking for developers to try Spark UI v1
Spark UI is now available publicly, and I’m looking for developers who are willing to try the first version.
You do not need to use every component.
Even testing one component and sharing your experience would be useful.
Feedback is especially welcome in these areas:
- Installation experience
- Registry reliability
- Documentation clarity
- Component APIs
- TypeScript support
- Dark and light themes
- Mobile responsiveness
- Accessibility
- Animation performance
- Browser compatibility
- Agent Skill behavior
- Missing components
- Bugs and unexpected behavior
Useful feedback can be as simple as:
- “This component installed successfully.”
- “The import path in the docs was unclear.”
- “The component breaks on mobile.”
- “The dark mode colors need improvement.”
- “The Agent Skill used the wrong component.”
- “This component should support another variant.”
- “I would like to see a component for this use case.”
Real usage feedback will help shape the next version.
Open source and open for contributions
Spark UI is open source and welcomes contributions.
You can contribute by:
- Adding a new component
- Improving an existing component
- Fixing a bug
- Improving accessibility
- Adding keyboard interactions
- Improving responsive behavior
- Updating documentation
- Creating a new demo
- Improving TypeScript types
- Adding validation
- Reviewing existing pull requests
- Suggesting new features
- Reporting installation issues
Before opening a pull request, please read the project’s CONTRIBUTING.md.
The contribution guide explains:
- Repository structure
- Component source requirements
- Demo requirements
- Registry configuration
- Documentation expectations
- Naming conventions
- Accessibility considerations
- Theme compatibility
- Validation commands
- Pull request expectations
Following the contribution guide helps keep the registry consistent and makes reviews easier.
How to try Spark UI
1. Visit the documentation
Explore the available components and examples on the Spark UI website:
https://spark-ui-olive.vercel.app
2. Inspect a registry item
npx shadcn@latest view https://spark-ui-olive.vercel.app/r/kanban.json
3. Install a component
npx shadcn@latest add https://spark-ui-olive.vercel.app/r/kanban.json
4. Install the Agent Skill
npx skills add codeweb-dev/spark-ui --skill spark-ui
5. Share feedback
You can open an issue, start a discussion, or submit a pull request in the GitHub repository.
Project links
- Website: spark-ui-olive.vercel.app
- GitHub repository: codeweb-dev/spark-ui
- Contribution guide: CONTRIBUTING.md
What comes next?
Spark UI v1 is the foundation.
Future improvements may include:
- More application-focused components
- More layout and dashboard patterns
- Better installation examples
- Additional themes
- More accessibility testing
- Expanded Agent Skill documentation
- Improved component previews
- More community-contributed components
- Better test coverage
- More complete usage examples
The project will grow based on real feedback and contributions rather than only adding components for the sake of having a larger catalog.
Final thoughts
Spark UI started as an attempt to build a practical, customizable, and developer-friendly component collection.
Version 1 is now public, but it is still the beginning.
My goal is to make Spark UI useful for developers who want:
- Components they can fully own
- Source code they can inspect
- Styling they can customize
- AI-assisted workflows that understand the library
- An open project they can contribute to
I would appreciate any feedback from developers who try it.
GitHub stars, issues, suggestions, testing, and pull requests are all welcome.
Thanks for checking out Spark UI v1! ⚡
Top comments (0)