{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://quailpages.com/schema/qp.theme-extension.schema.json",
  "title": "Quail Pages Theme Extension Contract",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "version",
    "description",
    "variables"
  ],
  "properties": {
    "version": {
      "const": 1
    },
    "description": {
      "type": "string",
      "minLength": 1
    },
    "variables": {
      "type": "object",
      "propertyNames": {
        "pattern": "^--(?:qp|theme)-[a-z0-9_-]+$"
      },
      "additionalProperties": {
        "oneOf": [
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "kind",
              "value"
            ],
            "properties": {
              "kind": {
                "const": "override"
              },
              "value": {
                "type": "string",
                "minLength": 1
              }
            }
          },
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "kind",
              "description",
              "variableType",
              "designType",
              "value"
            ],
            "properties": {
              "kind": {
                "const": "theme-owned"
              },
              "description": {
                "type": "string",
                "minLength": 1
              },
              "variableType": {
                "enum": [
                  "enum",
                  "root",
                  "derived",
                  "inherited"
                ]
              },
              "designType": {
                "enum": [
                  "background",
                  "color",
                  "spacing",
                  "font-family",
                  "font-size",
                  "font-weight",
                  "line-height",
                  "radius",
                  "border",
                  "border-width",
                  "size",
                  "shadow",
                  "layer",
                  "layout",
                  "effect"
                ]
              },
              "value": {
                "type": "string",
                "minLength": 1
              },
              "derivedFrom": {
                "oneOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1,
                    "uniqueItems": true
                  }
                ]
              },
              "inheritsFrom": {
                "type": "string"
              }
            }
          }
        ]
      },
      "description": "Sparse theme declarations layered over Base. Use override for assignments to Base variables. Exact variable references assigned to Inherited variables are deterministically classified as remaps in the effective model. Declare theme-owned variables only when the theme has reusable vocabulary or mechanics that Base does not own."
    }
  },
  "description": "Sparse authored variable delta layered over Base. theme.config.json is the authored source of truth for theme variables; the compiler generates variables.css from this contract. Shared and private local themes use the same contract and compiler. This variable contract is available in both creation and edit modes; mode-specific permission to add markup/class hooks is defined by qp.architecture.json and qp.classes.json.",
  "$comment": "theme.config.json is authored truth. Never author or patch generated variables.css directly; revise this contract and regenerate it. style.config.json is optional package metadata; when present it requires the theme's intrinsic id and may contain a display name and font-preload intent. Filesystem discovery remains based on the canonical directory and required style.css, and validates that authored id exactly matches the directory ID. Resources and owner CSS derive from the package. Compiled standalone CSS, generated variables.css, and copied fonts/assets are reproducible artifacts. Declare only meaningful overrides and theme-owned reusable vocabulary; do not copy the complete effective Base model. Theme creation may freely use this variable contract while remaining within existing QP class hooks; potential new class hooks belong in the structured build report rather than the created theme."
}