Contribute to UI Potion

Try contributing with your AI assistant. Point your AI at this repo (or the uipotion-manifest and potions-index), give it the schemas in src/statics/schemas/ and existing potions in the same category as references, and ask it to draft a new potion (Markdown + JSON + index entry). Then run npm run validate, tweak if needed, and open a PR. Many contributors use AI for the first draft and refine from there.

Quick Start

Follow these steps to add your potion to the collection:

1. Fork this repository at github.com/uiPotion/uipotion
2. Create your potion (Markdown + JSON) — see Creating a Potion below
3. Validate using the Schema Validator or npm run validate
4. Run npm run static to update sitemap and redirects (automatic!)
5. Submit a pull request with your new potion

We'll review your potion for schema compliance and best practices, then merge and publish when ready.

Creating a Potion

Each potion consists of two files:

• Markdown file (src/potions/[category]/your-potion.md) — human-readable web version
• JSON file (src/statics/potions/[category]/your-potion.json) — AI-readable guide

Categories

Choose the appropriate category:

• layouts — Full-page layouts (dashboards, landing pages, app shells)
• components — Reusable UI elements (buttons, dialogs, forms, cards)
• features — Complete user flows (authentication, onboarding, checkout)
• patterns — Design patterns and guidelines
• tooling — Developer tools and infrastructure

Step 1: Create JSON File

Create src/statics/potions/[category]/your-potion.json

Use the category schema in src/statics/schemas/categories/ and an existing potion as template (e.g., navbar.json for components, dashboard.json for layouts). Include at least: id, name, version, category, tags, description, aiAgentInstructions, frameworkPatterns, stylingApproaches, accessibility, testingChecklist. See Available Schemas and Using Schemas with AI below for more.

Step 2: Create Markdown File

Create src/potions/[category]/your-potion.md

Required front matter: layout, title, publicationDate, excerpt, category, tags, agentManifest. The agentManifest must point to your JSON file (e.g. potions/components/your-potion.json). Then write comprehensive specifications in the body; see existing potions (e.g. navbar.md, dashboard.md) for format.

---
layout: 'potion'
title: 'Your Potion Name'
publicationDate: '2026-01-24'
excerpt: 'Brief description (1-2 sentences)'
category: 'Components'
tags:
  - components
  - tag1
  - tag2
agentManifest: 'potions/components/your-potion.json'
---

Step 3: Validate

Visit the Schema Validator or run npm run validate to validate your JSON. Fix any errors before continuing.

Step 4: Update Sitemap and Redirects

Run npm run static. This scans markdown files and updates src/statics/sitemap.xml and src/statics/_redirects. No manual editing needed.

Step 5: Update Potions Index

Add your potion to src/statics/potions-index.json (add an entry with id, name, category, tags, excerpt, webUrl, agentGuideUrl, created, updated). Update totalCount and lastUpdated at the top of the file.

Understanding Schemas

UI Potion uses JSON Schema to ensure all potions follow a consistent structure. Schemas define:

• Required fields - What every potion must include
• Data types - The format of each field
• Validation rules - Constraints and patterns
• Category-specific requirements - What's needed for layouts, components, features, etc.

You can use these schemas with AI assistants to generate potions! Simply provide the schema to your AI and ask it to create a potion that follows the structure.

Available Schemas

Each category has its own schema. Choose the one that matches your potion type:

Contract Schemas

These are reusable building blocks referenced by category schemas:

• Accessibility Contract - WCAG compliance, ARIA, keyboard navigation
• State Contract - State definitions and management
• Interactions Contract - User interaction patterns

Using Schemas with AI

You can use these schemas to generate potions with AI assistants. AI can help you create both the JSON and Markdown files:

Generating the JSON File

Create a UI Potion JSON file for a navigation bar component. 
Use this schema as a reference: https://uipotion.com/schemas/categories/components.schema.json

The component should:
- Have a logo on the left
- Navigation links in the center
- A user menu on the right
- Be responsive with a mobile hamburger menu
- Support sticky scroll behavior

Make sure the JSON follows the schema exactly and includes all required fields.

Generating the Markdown File

Once you have your JSON file, you can ask AI to create the Markdown version:

Create a Markdown file for a UI Potion based on this JSON file.
The Markdown should:
- Include YAML front matter with layout, title, publicationDate, excerpt, category, tags, and agentManifest
- Be human-readable and comprehensive
- Include detailed specifications, dimensions, states, accessibility requirements
- Be framework-agnostic in descriptions
- Follow the format of existing potions like navbar.md or dashboard.md

The agentManifest should point to: potions/components/your-potion-name.json

The AI will generate properly structured files that you can then validate and submit!

Validate Your Potion

Before submitting a pull request, always validate your potion JSON against the appropriate schema. You can use either the web-based validator or the CLI script:

Web-Based Validator

CLI Validation Script

For contributors working locally, you can also use the Node.js CLI validation script that validates all potions at once:

# Validate all potions
npm run validate

# Or run directly
node validate-potions.js

The CLI script:

• Automatically finds all potion JSON files
• Detects the category from the file path or $schema field
• Validates each potion against its category schema
• Shows detailed error messages for any issues
• Runs automatically before npm run build
• Exits with error code if validation fails (useful for CI/CD)

Both validators will:

• Check that all required fields are present
• Verify data types and formats
• Validate schema references
• Show detailed error messages if something is wrong

Testing Locally

Before submitting a PR, run the project locally:

npm install
npm start

Visit http://localhost:3000 to preview your changes. You can also run npm run build for a production build and npm run static to regenerate sitemap and redirects.

Pull Request Guidelines

Before Submitting

• JSON validates with no errors (web validator or npm run validate)
• Markdown has correct front matter
• Ran npm run static
• Updated potions-index.json
• Tested locally with npm start
• Followed existing potion format

PR Description Should Include

• Category and potion name
• Brief description of what it provides
• Confirmation that it passes validation
• Example use case — when would someone use this potion?

We'll review your potion for schema compliance and best practices, suggest improvements if needed, then merge and publish when ready.

Best Practices

Writing AI Agent Instructions

• Be specific about styling enforcement (e.g., "MUST use Tailwind if detected")
• Include detection steps for framework and styling system
• Provide clear implementation steps
• Include output constraints (what to avoid)

Framework Patterns

• Provide examples for React, Vue, Angular, and Svelte when possible
• Use framework-agnostic descriptions when patterns are similar
• Include state management patterns (useState, refs, etc.)

Accessibility

• Always specify WCAG compliance level (A, AA, or AAA)
• Include keyboard navigation requirements
• Document ARIA attributes needed
• Provide screen reader considerations

Testing

• Include a comprehensive testing checklist
• Cover functional, accessibility, and responsive testing
• Include edge cases and error states

Content Guidelines

• Be comprehensive — Include all necessary details for AI to implement
• Be framework-agnostic — Avoid framework-specific code in descriptions
• Include accessibility — WCAG compliance, ARIA, keyboard navigation
• Include responsive specs — Mobile, tablet, desktop breakpoints
• Include testing checklist — What to verify after implementation

Questions?

• Check existing potions for examples
• Review the .cursorrules file in the repo for detailed guidelines
• Ask in your pull request if unsure

Resources

• Schema Validator — Validate your potions before submitting
• GitHub Repository — View the codebase and submit PRs
• About UI Potion — Learn more about the project

Get Started

Ready to contribute? Start by exploring the schemas and validating your first potion!