{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://uipotion.com/schema/potion.base.schema.json",
  "title": "UI Potion Base Schema (v1)",
  "description": "Shared schema for all UI Potion potions. Category schemas extend this via allOf. Contracts are referenced for consistent a11y/state/interaction modeling.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "$schema",
    "id",
    "version",
    "name",
    "category",
    "tags",
    "description",
    "aiAgentInstructions",
    "meta"
  ],
  "properties": {
    "$schema": {
      "type": "string",
      "description": "Pointer to the category-specific UI Potion schema URL for validation. Must match the potion's category. Examples: https://uipotion.com/schema/categories/layouts.schema.json (for layouts), https://uipotion.com/schema/categories/components.schema.json (for components), etc. This is NOT the JSON Schema specification URL, but rather the UI Potion category schema that validates the potion structure."
    },
    "id": {
      "type": "string",
      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
      "description": "Unique potion identifier (kebab-case)."
    },
    "version": {
      "type": "string",
      "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-[0-9A-Za-z-.]+)?(?:\\+[0-9A-Za-z-.]+)?$",
      "description": "Potion version (SemVer)."
    },
    "name": {
      "type": "string",
      "minLength": 1
    },
    "category": {
      "type": "string",
      "enum": ["layouts", "components", "features", "patterns", "tooling"]
    },
    "tags": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "string",
        "minLength": 1
      }
    },
    "description": {
      "type": "string",
      "minLength": 1
    },
    "tokens": {
      "type": "object",
      "description": "Optional but recommended: normalized constants referenced throughout the spec.",
      "additionalProperties": true
    },
    "layoutPresets": {
      "type": "object",
      "description": "Optional: explicit preset variants (e.g., default/compact) for sizing or behavior.",
      "additionalProperties": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "aiAgentInstructions": {
      "type": "object",
      "additionalProperties": false,
      "required": ["summary", "keyFeatures", "implementationSteps"],
      "properties": {
        "summary": {
          "type": "string",
          "minLength": 1
        },
        "keyFeatures": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "string",
            "minLength": 1
          }
        },
        "implementationSteps": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "string",
            "minLength": 1
          }
        }
      },
      "description": "Human-readable instructions for AI agents. Should include styling enforcement rules (e.g., 'Styling MUST match the project's existing conventions. Do NOT introduce new styling systems.') and a step to detect project styling conventions before coding."
    },
    "frameworkPatterns": {
      "type": "object",
      "additionalProperties": true
    },
    "stylingApproaches": {
      "type": "object",
      "additionalProperties": true
    },
    "animations": {
      "type": "object",
      "additionalProperties": true
    },
    "accessibility": {
      "$ref": "https://uipotion.com/schema/contracts/accessibility.contract.schema.json"
    },
    "projectDetection": {
      "type": "object",
      "additionalProperties": false,
      "required": ["framework", "stylingSystem", "designTokens"],
      "description": "Guidance for AI agents to detect the project's framework, styling system, and design tokens before implementation. Agents MUST follow these detection steps before writing any code.",
      "properties": {
        "framework": {
          "type": "object",
          "additionalProperties": false,
          "required": ["description", "detectionSteps"],
          "properties": {
            "description": {
              "type": "string",
              "minLength": 1,
              "description": "Description of what framework detection entails."
            },
            "detectionSteps": {
              "type": "array",
              "minItems": 1,
              "items": {
                "type": "string",
                "minLength": 1
              },
              "description": "Step-by-step instructions for detecting the project's framework (React, Vue, Angular, Svelte, etc.)."
            }
          }
        },
        "stylingSystem": {
          "type": "object",
          "additionalProperties": false,
          "required": ["description", "detectionSteps", "adaptationRules"],
          "properties": {
            "description": {
              "type": "string",
              "minLength": 1,
              "description": "Description of what styling system detection entails."
            },
            "detectionSteps": {
              "type": "array",
              "minItems": 1,
              "items": {
                "type": "string",
                "minLength": 1
              },
              "description": "Step-by-step instructions for detecting the project's styling approach (Tailwind, SCSS, CSS, styled-components, etc.)."
            },
            "adaptationRules": {
              "type": "array",
              "minItems": 1,
              "items": {
                "type": "string",
                "minLength": 1
              },
              "description": "Rules for adapting code based on the detected styling system. Each rule specifies how to use a particular styling approach."
            }
          }
        },
        "designTokens": {
          "type": "object",
          "additionalProperties": false,
          "required": ["description", "detectionSteps"],
          "properties": {
            "description": {
              "type": "string",
              "minLength": 1,
              "description": "Description of what design token detection entails."
            },
            "detectionSteps": {
              "type": "array",
              "minItems": 1,
              "items": {
                "type": "string",
                "minLength": 1
              },
              "description": "Step-by-step instructions for identifying existing design tokens, color systems, spacing scales, and typography from the project."
            }
          }
        }
      }
    },
    "designSystem": {
      "type": "object",
      "additionalProperties": true
    },
    "dataStructures": {
      "type": "object",
      "additionalProperties": true
    },
    "commonVariations": {
      "type": "object",
      "additionalProperties": true
    },
    "edgeCases": {
      "type": "object",
      "additionalProperties": true
    },
    "testingChecklist": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "outputConstraints": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "must": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          },
          "description": "List of requirements that the generated code MUST satisfy (e.g., 'Use Tailwind utility classes only', 'Use project token classes')."
        },
        "mustNot": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          },
          "description": "List of forbidden patterns that the generated code MUST NOT include (e.g., 'No <style> blocks', 'No inline style attributes', 'No hardcoded hex/rgb colors')."
        }
      },
      "description": "Explicit constraints on code output that agents must self-check before finalizing implementation."
    },
    "aiImplementationPrompt": {
      "type": "string"
    },
    "implementationDetails": {
      "type": "object",
      "additionalProperties": true,
      "description": "Optional: Additional implementation details, edge cases, and technical notes for AI agents."
    },
    "accessibilityExamples": {
      "type": "object",
      "additionalProperties": true,
      "description": "Optional: Code examples demonstrating accessibility implementation patterns."
    },
    "meta": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "created",
        "updated",
        "webUrl"
      ],
      "properties": {
        "created": {
          "type": "string",
          "format": "date"
        },
        "updated": {
          "type": "string",
          "format": "date"
        },
        "webUrl": {
          "type": "string",
          "minLength": 1,
          "description": "URL to the human-readable documentation page (HTML)."
        },
        "agentGuideUrl": {
          "type": "string",
          "minLength": 1,
          "description": "Optional: URL to this JSON guide for AI agents."
        },
        "markdownUrl": {
          "type": "string",
          "minLength": 1,
          "description": "Optional: URL to the raw Markdown source (.md)."
        },
        "relatedPotions": {
          "type": "array",
          "description": "Optional: Array of related potions that complement or are used with this potion. These are suggestions, not requirements.",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": ["id", "category", "relationship", "description"],
            "properties": {
              "id": {
                "type": "string",
                "minLength": 1
              },
              "category": {
                "type": "string",
                "enum": ["layouts", "components", "features", "patterns", "tooling"]
              },
              "relationship": {
                "type": "string",
                "description": "Type of relationship: 'complements', 'used-in', 'extends', etc."
              },
              "description": {
                "type": "string",
                "minLength": 1
              },
              "required": {
                "type": "boolean",
                "description": "Whether this related potion is required (default: false, should always be false as potions are independent)"
              }
            }
          }
        }
      }
    },
    "layoutModel": { "type": "object", "additionalProperties": true },
    "structure": { "type": "object", "additionalProperties": true },
    "components": { "type": "object", "additionalProperties": true },
    "responsiveBreakpoints": { "type": "object", "additionalProperties": true },
    "stateManagement": { "type": "object", "additionalProperties": true },
    "persistence": { "type": "object", "additionalProperties": true },
    "overflowPolicy": { "type": "object", "additionalProperties": true },
    "zIndexLayers": { "type": "object", "additionalProperties": true },
    "modalOverlayBehavior": { "type": "object", "additionalProperties": true },
    "navigationBehavior": { "type": "object", "additionalProperties": true },
    "internationalization": { "type": "object", "additionalProperties": true },
    "mobileSafeArea": { "type": "object", "additionalProperties": true },
    "motionPreferences": { "type": "object", "additionalProperties": true },
    "componentSpec": { "type": "object", "additionalProperties": true },
    "featureSpec": { "type": "object", "additionalProperties": true },
    "patternSpec": { "type": "object", "additionalProperties": true },
    "toolingSpec": { "type": "object", "additionalProperties": true },
    "installation": { "type": "object", "additionalProperties": true },
    "versionDetection": { "type": "object", "additionalProperties": true },
    "templates": { "type": "object", "additionalProperties": true },
    "scripts": { "type": "object", "additionalProperties": true },
    "editorIntegration": { "type": "object", "additionalProperties": true },
    "cicdIntegration": { "type": "object", "additionalProperties": true },
    "troubleshooting": { "type": "object", "additionalProperties": true },
    "ecosystemTools": { "type": "object", "additionalProperties": true },
    "integrationPatterns": { "type": "object", "additionalProperties": true }
  }
}