About UI Potion

What You Get

UI Potion is a set of UI behavior guides your coding agent can apply to your existing project. Each guide spells out how the UI should behave, including details that are easy to miss in a short prompt. For example:

• A chat message that fails to send stays in the input with a retry, so nobody has to retype it (AI Agent Chat Layout).
• Closing a dialog returns focus to the control that opened it (Modal Dialog).
• Stopping a streamed AI response keeps the text that already arrived (AI Response Rendering).

Your agent keeps your framework, components, and styling. The guide gives it the behavior to build and a checklist to verify it against.

Our Approach

UI Potion provides specifications, not code.

Each "potion" is a guide written for AI coding assistants, which adapt it to the stack already in your project. 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

1. Browse potions on this website to find what you need (e.g., dashboard layout, pricing table, dialog)
2. Copy the prompt from the potion page. It points your agent to the guide and asks it to reuse your existing components, implement only what the task needs, and check its changes with your existing tests
3. Paste it into your coding agent and add any details about the task, such as the screen it's for
4. The agent creates an implementation candidate adapted to the detected framework, styling system, and project conventions. Review, test, and refine it before you ship it

Already have the UI? Use Copy check prompt on the potion page instead. The agent compares your existing implementation with the guide, lists the gaps by severity, and changes nothing until you ask.

For AI Agents

AI agents can discover potions automatically:

1. Load the manifest: https://uipotion.com/uipotion-manifest.json
2. Browse available potions: https://uipotion.com/potions-index.json
3. Load specific guide: https://uipotion.com/potions/[category]/[potion-id].json
4. Parse specifications and adapt to user's framework/styling choices
5. 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

Framework & Styling Agnostic

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

Benefits

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