About UI Potion

The Problem

Traditional UI component libraries have a fundamental problem: maintenance burden. Framework updates, new patterns, and bug fixes can require library upgrades or migrations. And developers still need to adapt the code to their specific project setup.

Our Approach

UI Potion takes a different approach: we don't provide code, we provide specifications.

Each "potion" is a comprehensive guide written specifically for AI coding assistants. It includes:

Detailed UI specifications (structure, behavior, states, and dimensions where relevant)
Responsive breakpoints and mobile patterns
Accessibility requirements (ARIA, keyboard navigation)
Framework-specific implementation patterns (React, Vue, Angular, etc.)
Styling approaches (Tailwind, CSS Modules, Chakra, Material-UI, etc.)
Animation specifications and timing
Testing checklists

How It Works

For Developers

Browse potions on this website to find what you need (e.g., dashboard layout, pricing table, dialog)
Copy the potion URL or JSON link
Tell your AI assistant: "Implement the dashboard layout from this UI Potion guide" + paste link
Specify your stack: "Use React with Tailwind CSS" (or whatever you're using)
The agent creates an implementation candidate adapted to the detected framework, styling system, and project conventions

For AI Agents

AI agents can discover potions automatically:

Load the manifest: https://uipotion.com/uipotion-manifest.json
Browse available potions: https://uipotion.com/potions-index.json
Load specific guide: https://uipotion.com/potions/[category]/[potion-id].json
Parse specifications and adapt to user's framework/styling choices
Generate implementation code

Skill-compatible agents can also load UI Potion skills:

UI Potion Consumer - implement from guides
UI Potion Discovery - find the best matching potion

Build with a chat: Potion Kit is a CLI that scaffolds and builds Harold + UI Potion sites with AI chat; it uses the UI Potion catalog and Harold conventions so the model only suggests components from real specs.

Example Workflow

Developer says:

"I need a dashboard layout with collapsible sidebar. I'm using React and Tailwind CSS. Here's the guide: https://uipotion.com/potions/layouts/dashboard"

AI agent:

Loads the dashboard.json guide
Understands the component structure and specifications
Adapts the patterns to React (useState, useEffect, etc.)
Uses Tailwind utility classes for styling
Creates a project-aligned implementation candidate that follows the accessibility requirements

Result: A project-aligned dashboard implementation to review, test, and refine before deployment.

Framework & Styling Agnostic

UI Potion keeps its core guidance stack-neutral. Agents adapt it to the tools already present in the project, including:

Frameworks

React
Vue
Angular
Svelte
Solid
Any other framework

Styling

Tailwind CSS
CSS Modules
Styled Components
Chakra UI
Material-UI
Vanilla CSS
Any styling approach

Benefits

No Library Upgrade Cycle

Nothing from UI Potion is installed as a runtime package

Project-Compatible

Agents adapt guidance to the framework versions and conventions detected in the project

Truly Flexible

No UI Potion runtime dependency tied to a framework version or styling library

Implementation Coverage

Includes accessibility, responsive behavior, edge cases, and testing guidance where relevant

Learning Resource

Understand the "why" behind UI patterns

JSON Structure

Each potion is available as JSON for programmatic access. The abbreviated example below shows the shared discovery fields; category schemas add required implementation structures. Use a same-category guide as the complete template.

{
  "$schema": "https://uipotion.com/schema/categories/layouts.schema.json",
  "id": "dashboard",
  "version": "1.0.0",
  "name": "Dashboard Layout",
  "category": "layouts",
  "tags": ["layouts", "dashboard"],
  "description": "Responsive dashboard specification",
  "aiAgentInstructions": {
    "summary": "Implementation goal",
    "keyFeatures": ["Collapsible navigation"],
    "implementationSteps": ["Detect the project stack before implementation"]
  },
  "meta": {
    "created": "YYYY-MM-DD",
    "updated": "YYYY-MM-DD",
    "webUrl": "https://uipotion.com/potions/layouts/dashboard"
  }
}

Contact & Support

Have questions or want to contribute?

GitHub Issues: Report bugs or request features
GitHub: github.com/uiPotion
X: @uipotion · @thejulianio

Get Started

Browse Potions Potion Kit

For legal information, please see our Disclaimer and Privacy Policy.