{"$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}}}