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/schema/ 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 build, refine the result, 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 + index entry) — see Creating a Potion below
3. Validate using the Schema Validator or npm run validate
4. Run npm run build to validate and generate the production site
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/schema/categories/ and an existing potion as template (e.g., navbar.json for components, dashboard.json for layouts). Every guide requires the base fields $schema, id, version, name, category, tags, description, aiAgentInstructions, and meta. Each category schema adds required structures of its own, so start from an existing potion in the same category rather than treating this list as a complete template. 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: 'YYYY-MM-DD'
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 Potions Index and Dates

Add the matching entry to src/statics/potions-index.json, including id, name, category, tags, excerpt, webUrl, agentGuideUrl, markdownUrl, created, and updated. Use pretty web URLs without .html. Update totalCount and top-level lastUpdated, keep index dates synchronized with the guide metadata, and update the manifest meta.updated.

Step 5: Build and Verify

Run npm run build. The build validates every potion, checks index consistency, regenerates static discovery files, builds the Harold site, and cleans temporary Markdown publishing copies.

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/schema/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

Treat the generated files as a draft: review them against a same-category potion, validate them, and refine them before submitting.

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
• Selects the category schema from the potion directory
• Validates each potion against its category schema
• Checks guide identity and metadata against potions-index.json
• 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 ci
npm start

Visit http://localhost:3000 to preview your changes. Before submitting, run npm run build; it validates the catalog, regenerates static files, and creates the production build.

Pull Request Guidelines

Before Submitting

• JSON validates with no errors (web validator or npm run validate)
• Markdown has correct front matter
• Ran npm run build
• 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

• For user-facing UI, specify the applicable WCAG target and requirements
• 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 where relevant — WCAG compliance, ARIA, keyboard navigation
• Include responsive specs where relevant — Mobile, tablet, desktop breakpoints
• Include testing checklist — What to verify after implementation

Questions?

• Check existing potions for examples
• Review AGENTS.md in the repository for detailed project 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!