{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://cssdoc.dev/cssdoc.schema.json",
  "title": "cssdoc.json",
  "description": "Configuration for cssdoc: custom tags, lint rules, and markdown render options.",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "$schema": {
      "type": "string"
    },
    "extends": {
      "description": "Paths to other cssdoc.json files (or packages) to inherit tag definitions from.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "noStandardTags": {
      "description": "Disable every built-in standard tag; only tagDefinitions remain supported.",
      "type": "boolean"
    },
    "tagDefinitions": {
      "description": "Custom tags to register.",
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "tagName",
          "syntaxKind"
        ],
        "properties": {
          "tagName": {
            "type": "string",
            "pattern": "^@?[a-zA-Z][a-zA-Z0-9-]*$"
          },
          "syntaxKind": {
            "enum": [
              "record",
              "block",
              "modifier",
              "inline"
            ]
          },
          "allowMultiple": {
            "type": "boolean"
          },
          "recordKind": {
            "enum": [
              "component",
              "utility",
              "declaration",
              "layout"
            ]
          },
          "aliasFor": {
            "type": "string"
          }
        }
      }
    },
    "supportForTags": {
      "description": "Enable or disable specific tags by name.",
      "type": "object",
      "additionalProperties": {
        "type": "boolean"
      }
    },
    "modifierConvention": {
      "description": "How modifier classes are spelled: a preset name (bem, rscss, bare) or a custom convention.",
      "oneOf": [
        {
          "enum": [
            "bem",
            "rscss",
            "bare"
          ]
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "structure",
            "separator"
          ],
          "properties": {
            "structure": {
              "enum": [
                "chained",
                "suffix",
                "attribute"
              ]
            },
            "separator": {
              "oneOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "elementSeparator": {
              "description": "BEM-style element delimiter (e.g. \"__\"); matched classes become parts.",
              "oneOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "statePrefixes": {
              "description": "Class prefixes that mark a state (e.g. [\"is-\",\"has-\"]).",
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "statePseudoClasses": {
              "description": "Native pseudo-classes (without the colon) recognized as states, e.g. [\"disabled\",\"checked\"]. Overrides the built-in default set.",
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "pseudoElements": {
              "description": "Native pseudo-elements (without the ::) to document, e.g. [\"before\",\"after\"]. Overrides the built-in default set.",
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "propValue": {
              "type": "boolean"
            },
            "propValueSeparator": {
              "type": "string"
            }
          }
        }
      ]
    },
    "inlineComments": {
      "description": "How a /* … */ comment on a member's rule combines with its tag prose: append (default), prepend, replace, or ignore.",
      "enum": [
        "append",
        "prepend",
        "replace",
        "ignore"
      ]
    },
    "providers": {
      "description": "Upstream cssdoc providers this config consumes, so their components resolve in this scope's lint/hover/docs. Each points at a provider's model.json or a source stylesheet.",
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "path"
        ],
        "properties": {
          "path": {
            "type": "string",
            "description": "Path to the provider's model.json or a source stylesheet — relative (starts with .) or a package specifier."
          },
          "baseHref": {
            "type": "string",
            "description": "URL prefix for links to the provider's rendered doc pages."
          },
          "prefix": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "from"
            ],
            "description": "Rewrite the provider's base-class prefix before merging its records (e.g. a published `instui-` consumed under a different spelling). `to` is used verbatim — no separator is added or assumed.",
            "properties": {
              "from": {
                "type": "string",
                "description": "The prefix as published, matched from the start of the class name — a literal string, or a regex source when isRegExp is true."
              },
              "to": {
                "type": "string",
                "description": "The literal replacement text (verbatim, no separator assumed). Omit or use \"\" to strip the prefix to a bare class."
              },
              "isRegExp": {
                "type": "boolean",
                "description": "Treat `from` as a regex source instead of a literal string."
              }
            }
          }
        }
      }
    },
    "rules": {
      "description": "Per-rule severity overrides (off/warn/error).",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "missing-summary": {
          "enum": [
            "off",
            "warn",
            "error"
          ]
        },
        "undocumented-modifier": {
          "enum": [
            "off",
            "warn",
            "error"
          ]
        },
        "deprecated-requires-canonical": {
          "enum": [
            "off",
            "warn",
            "error"
          ]
        },
        "alias-requires-canonical": {
          "enum": [
            "off",
            "warn",
            "error"
          ]
        },
        "name-not-in-css": {
          "enum": [
            "off",
            "warn",
            "error"
          ]
        },
        "unknown-modifier": {
          "enum": [
            "off",
            "warn",
            "error"
          ]
        },
        "deprecated-modifier": {
          "enum": [
            "off",
            "warn",
            "error"
          ]
        },
        "disallowed-element": {
          "enum": [
            "off",
            "warn",
            "error"
          ]
        },
        "unknown-state": {
          "enum": [
            "off",
            "warn",
            "error"
          ]
        },
        "unknown-part": {
          "enum": [
            "off",
            "warn",
            "error"
          ]
        },
        "undocumented-part": {
          "enum": [
            "off",
            "warn",
            "error"
          ]
        },
        "undocumented-css-part": {
          "enum": [
            "off",
            "warn",
            "error"
          ]
        },
        "component-name-case": {
          "enum": [
            "off",
            "warn",
            "error"
          ]
        },
        "part-name-case": {
          "enum": [
            "off",
            "warn",
            "error"
          ]
        },
        "duplicate-record-id": {
          "enum": [
            "off",
            "warn",
            "error"
          ]
        },
        "duplicate-record-id-cross-kind": {
          "enum": [
            "off",
            "warn",
            "error"
          ]
        },
        "structure-unknown-selector": {
          "enum": [
            "off",
            "warn",
            "error"
          ]
        },
        "structure-unknown-record": {
          "enum": [
            "off",
            "warn",
            "error"
          ]
        },
        "structure-ambiguous-record": {
          "enum": [
            "off",
            "warn",
            "error"
          ]
        },
        "invalid-default-value": {
          "enum": [
            "off",
            "warn",
            "error"
          ]
        },
        "invalid-property-value": {
          "enum": [
            "off",
            "warn",
            "error"
          ]
        },
        "invalid-fallback-value": {
          "enum": [
            "off",
            "warn",
            "error"
          ]
        },
        "unknown-custom-property": {
          "enum": [
            "off",
            "warn",
            "error"
          ]
        },
        "unknown-annotation-ref": {
          "enum": [
            "off",
            "warn",
            "error"
          ]
        },
        "readonly-redefinition": {
          "enum": [
            "off",
            "warn",
            "error"
          ]
        },
        "sealed-reset-value": {
          "enum": [
            "off",
            "warn",
            "error"
          ]
        },
        "cssdoc-directive": {
          "enum": [
            "off",
            "warn",
            "error"
          ]
        },
        "conflicting-global-modifier": {
          "enum": [
            "off",
            "warn",
            "error"
          ]
        }
      }
    },
    "overrides": {
      "description": "Per-glob rule severity overrides. Globs are relative to this config file.",
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "files",
          "rules"
        ],
        "properties": {
          "files": {
            "description": "One or more glob patterns relative to this config file.",
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            ]
          },
          "rules": {
            "description": "Per-rule severity overrides for matching files (off/warn/error).",
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "missing-summary": {
                "enum": [
                  "off",
                  "warn",
                  "error"
                ]
              },
              "undocumented-modifier": {
                "enum": [
                  "off",
                  "warn",
                  "error"
                ]
              },
              "deprecated-requires-canonical": {
                "enum": [
                  "off",
                  "warn",
                  "error"
                ]
              },
              "alias-requires-canonical": {
                "enum": [
                  "off",
                  "warn",
                  "error"
                ]
              },
              "name-not-in-css": {
                "enum": [
                  "off",
                  "warn",
                  "error"
                ]
              },
              "unknown-modifier": {
                "enum": [
                  "off",
                  "warn",
                  "error"
                ]
              },
              "deprecated-modifier": {
                "enum": [
                  "off",
                  "warn",
                  "error"
                ]
              },
              "disallowed-element": {
                "enum": [
                  "off",
                  "warn",
                  "error"
                ]
              },
              "unknown-state": {
                "enum": [
                  "off",
                  "warn",
                  "error"
                ]
              },
              "unknown-part": {
                "enum": [
                  "off",
                  "warn",
                  "error"
                ]
              },
              "undocumented-part": {
                "enum": [
                  "off",
                  "warn",
                  "error"
                ]
              },
              "undocumented-css-part": {
                "enum": [
                  "off",
                  "warn",
                  "error"
                ]
              },
              "component-name-case": {
                "enum": [
                  "off",
                  "warn",
                  "error"
                ]
              },
              "part-name-case": {
                "enum": [
                  "off",
                  "warn",
                  "error"
                ]
              },
              "duplicate-record-id": {
                "enum": [
                  "off",
                  "warn",
                  "error"
                ]
              },
              "duplicate-record-id-cross-kind": {
                "enum": [
                  "off",
                  "warn",
                  "error"
                ]
              },
              "structure-unknown-selector": {
                "enum": [
                  "off",
                  "warn",
                  "error"
                ]
              },
              "structure-unknown-record": {
                "enum": [
                  "off",
                  "warn",
                  "error"
                ]
              },
              "structure-ambiguous-record": {
                "enum": [
                  "off",
                  "warn",
                  "error"
                ]
              },
              "invalid-default-value": {
                "enum": [
                  "off",
                  "warn",
                  "error"
                ]
              },
              "invalid-property-value": {
                "enum": [
                  "off",
                  "warn",
                  "error"
                ]
              },
              "invalid-fallback-value": {
                "enum": [
                  "off",
                  "warn",
                  "error"
                ]
              },
              "unknown-custom-property": {
                "enum": [
                  "off",
                  "warn",
                  "error"
                ]
              },
              "unknown-annotation-ref": {
                "enum": [
                  "off",
                  "warn",
                  "error"
                ]
              },
              "readonly-redefinition": {
                "enum": [
                  "off",
                  "warn",
                  "error"
                ]
              },
              "sealed-reset-value": {
                "enum": [
                  "off",
                  "warn",
                  "error"
                ]
              },
              "cssdoc-directive": {
                "enum": [
                  "off",
                  "warn",
                  "error"
                ]
              },
              "conflicting-global-modifier": {
                "enum": [
                  "off",
                  "warn",
                  "error"
                ]
              }
            }
          }
        }
      }
    },
    "ruleOptions": {
      "description": "Policy options for rule behavior families.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "values": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "allowInherit": {
              "type": "boolean",
              "description": "Allow `inherit` in sealed/frozen value checks (default false)."
            }
          }
        },
        "sealed": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "mode": {
              "enum": [
                "strict",
                "compat"
              ],
              "description": "strict flags full reset-keyword set; compat limits to unset/initial."
            }
          }
        }
      }
    },
    "naming": {
      "description": "Enforce a name case on class names: a preset (pascalCase, camelCase, lowercase) or a custom regex.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "component": {
          "type": "string"
        },
        "part": {
          "type": "string"
        }
      }
    },
    "structureIgnore": {
      "description": "Class names to exempt from the structure-unknown-selector rule — legitimately-external classes (utilities, cross-component refs) referenced in @structure. Literal names or simple globs where * matches any run of characters (e.g. util-*).",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "globalPrecedence": {
      "description": "Precedence model when multiple records define the same modifier, with at least one marked @global: \"base\" (explicit modifiers override global; default) or \"global\" (global overrides explicit).",
      "enum": [
        "base",
        "global"
      ]
    },
    "render": {
      "description": "Presentation options for CSS API pages and editor hovers. Explicit emitter options still override these.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "includeInternal": {
          "description": "Include records marked @visibility internal in generated API pages.",
          "type": "boolean",
          "default": false
        },
        "exampleFilters": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "markdown": {
              "description": "Select examples by label; null disables an inherited filter.",
              "oneOf": [
                {
                  "type": "null"
                },
                {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "labels"
                  ],
                  "properties": {
                    "labels": {
                      "type": "array",
                      "uniqueItems": true,
                      "items": {
                        "type": "string",
                        "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
                      }
                    },
                    "includeUnlabeled": {
                      "type": "boolean",
                      "default": true
                    }
                  }
                }
              ]
            },
            "html": {
              "description": "Select examples by label; null disables an inherited filter.",
              "oneOf": [
                {
                  "type": "null"
                },
                {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "labels"
                  ],
                  "properties": {
                    "labels": {
                      "type": "array",
                      "uniqueItems": true,
                      "items": {
                        "type": "string",
                        "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
                      }
                    },
                    "includeUnlabeled": {
                      "type": "boolean",
                      "default": true
                    }
                  }
                }
              ]
            },
            "hover": {
              "description": "Select examples by label; null disables an inherited filter.",
              "oneOf": [
                {
                  "type": "null"
                },
                {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "labels"
                  ],
                  "properties": {
                    "labels": {
                      "type": "array",
                      "uniqueItems": true,
                      "items": {
                        "type": "string",
                        "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
                      }
                    },
                    "includeUnlabeled": {
                      "type": "boolean",
                      "default": true
                    }
                  }
                }
              ]
            }
          }
        },
        "sectionOrder": {
          "description": "Order (and inclusion) of the reorderable ## sections on a record page; omitted keys are dropped.",
          "type": "array",
          "items": {
            "enum": [
              "demo",
              "examples",
              "usage",
              "annotations",
              "modifiers",
              "parts",
              "shadowParts",
              "pseudoElements",
              "states",
              "slots",
              "structure",
              "subcomponents",
              "cssProperties",
              "functions",
              "animations",
              "layers",
              "conditions",
              "tokensConsumed",
              "compat",
              "accessibility",
              "related",
              "see"
            ]
          }
        },
        "headingPrefix": {
          "description": "Prefix for each record page title, e.g. \"CSS:\".",
          "type": "string"
        },
        "baseHref": {
          "description": "Base href for @related cross-links and the sidebar/index links.",
          "type": "string"
        },
        "structureView": {
          "description": "Which Structure representation(s) to emit: \"text\" tree, \"diagram\" flowchart, or \"both\" (default).",
          "enum": [
            "text",
            "diagram",
            "both"
          ]
        },
        "structureVariantView": {
          "description": "How alternative DOM shapes (from top-level @variant blocks in @structure) render: \"diagram\" (default) emits one combined flowchart with a labelled subgraph per variant; \"sections\" emits a \"### Variant: <name>\" subsection per variant.",
          "enum": [
            "diagram",
            "sections"
          ]
        },
        "groups": {
          "description": "Explicit sidebar/index group order. Listed group labels come first, in this order; unlisted groups follow the default order (record kinds, then custom @group groups).",
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    }
  }
}
