Skip to content

Config reference ​

cssdoc.json and cssdoc.jsonc configure tag parsing, lint rules, providers, and rendered output. The configuration guide shows common setups; this page documents every field accepted by the schema.

The schema is published at https://cssdoc.dev/cssdoc.schema.json. Add it to a config file for editor validation and completion:

jsonc
{
  "$schema": "https://cssdoc.dev/cssdoc.schema.json",
}

Both file names accept JSON with comments and trailing commas. cssdoc.jsonc makes that format explicit. The schema rejects unknown fields, so misspellings are reported rather than silently ignored.

Top-level fields ​

FieldTypePurpose
$schemastringSchema URL used by editors.
extendsstring[]Config files or package exports to inherit. Relative paths resolve from the config that declares them.
noStandardTagsbooleanDisable all standard tags; only custom tagDefinitions remain enabled.
tagDefinitionsobject[]Add custom doc-comment tags.
supportForTagsobjectEnable or disable individual tags by name.
modifierConventionpreset or objectDescribe how modifier, part, and state selectors are spelled.
inlineComments"append" | "prepend" | "replace" | "ignore"Choose how a member's CSS comment combines with its tag prose.
providersobject[]Consume records from another CSS source or published model.
rulesobjectSet lint rule severities.
overridesobject[]Set rule severities for matching file globs.
ruleOptionsobjectTune behavior shared by related lint rules.
namingobjectEnforce naming conventions for component and part classes.
structureIgnorestring[]Exempt external class names from structure-unknown-selector.
globalPrecedence"base" | "global"Choose which modifier wins when a global and explicit definition conflict.
renderobjectSet defaults for rendered API pages and editor hovers. Explicit emitter options take precedence.

Unknown top-level and nested properties aren't allowed. See the complete schema for exact constraints.

Show examples
jsonc
{
  "$schema": "https://cssdoc.dev/cssdoc.schema.json",
  // Inherit from a preset configuration package
  "extends": ["@cssdoc/config/web-components"],
}
jsonc
{
  "$schema": "https://cssdoc.dev/cssdoc.schema.json",
  // Add a custom @author tag for author information
  "tagDefinitions": [
    {
      "tagName": "@author",
      "syntaxKind": "block",
    },
  ],
  // Configure rule severities
  "rules": {
    "missing-summary": "off", // Allow components without summaries
    "unknown-custom-property": "warn", // Warn about unknown CSS custom properties
  },
}
jsonc
{
  "$schema": "https://cssdoc.dev/cssdoc.schema.json",
  // Consume documentation from vendor stylesheets
  "providers": [
    {
      "path": "./vendor/external.css",
      "baseHref": "https://example.com/api/",
    },
  ],
  // Enforce naming conventions
  "naming": {
    "component": "pascalCase",
    "part": "camelCase",
  },
}
jsonc
{
  "$schema": "https://cssdoc.dev/cssdoc.schema.json",
  // Configure output rendering defaults
  "render": {
    "includeInternal": false, // Hide internally-marked records
    "structureView": "diagram", // Show component structure as a diagram
    "baseHref": "https://docs.example.com/", // Base URL for documentation links
  },
}

Inheritance ​

extends accepts paths to other config files or package specifiers resolved from the declaring file. Extended configs apply first; fields in the current file override them. Rule severities, naming, ruleOptions, and render settings merge with the current file taking precedence. Structure-ignore patterns are unioned, while rule overrides are appended and evaluated in order. providers belong to the current config and aren't inherited.

Basic extends ​

You can extend from local config files or published npm packages. When you extend, the base config loads first, then your config overrides or adds to it. Use multiple extends to layer configs in order of precedence.

Show examples
jsonc
{
  // Inherit from another config file in the project
  "extends": ["./cssdoc.base.json"],
  // Override specific fields
}
jsonc
{
  // Inherit from a published config preset
  "extends": ["@cssdoc/config/web-components"],
  // Add or override settings
  "rules": {
    "missing-summary": "off", // This overrides the inherited value
  },
}
jsonc
{
  // Extends are applied in order; later files override earlier ones
  "extends": [
    "@cssdoc/config/base", // Apply base rules first
    "@cssdoc/config/web-components", // Then web-component conventions
    "./cssdoc.local.json", // Finally, local overrides
  ],
  "rules": {
    "unknown-modifier": "error", // This overrides all inherited values
  },
}

Merge behavior ​

Most config fields merge with inherited values rather than replace them completely. When you specify a field, it overrides the inherited value for that specific key, but other keys from the base config are preserved. This applies to rules, naming, ruleOptions, and render.

Show examples
jsonc
{
  // Base config has:
  // "rules": { "unknown-part": "warn", "missing-summary": "off" }
  // "render": { "structureView": "both", "baseHref": "..." }

  "extends": ["./base.json"],

  // These fields MERGE with inherited ones:
  "rules": {
    "unknown-part": "error", // Overrides inherited value
    // "missing-summary" from base is kept
  },
  "render": {
    "structureView": "diagram", // Overrides inherited value
    // "baseHref" from base is kept
  },
}

Special merge behaviors ​

Some fields have unique merging semantics. structureIgnore patterns are combined into a single array, while overrides are appended in order and evaluated last-match-wins. These behaviors allow you to layer rules without replacing base configurations.

Show examples
jsonc
{
  // Base config has:
  // "structureIgnore": ["bootstrap-*", "vendor-*"]

  "extends": ["./base.json"],

  // Patterns are UNIONED (combined, not replaced):
  "structureIgnore": [
    "material-*", // Added to inherited patterns
  ],
  // Result: ["bootstrap-*", "vendor-*", "material-*"]
}
jsonc
{
  // Base config has overrides for "src/**/*.css"

  "extends": ["./base.json"],

  // Overrides are APPENDED and evaluated in order:
  "overrides": [
    {
      "files": "experimental/**/*.css",
      "rules": { "structure-unknown-selector": "warn" },
    },
    // Later matches override earlier ones
  ],
}

Tags ​

tagDefinitions ​

Each definition requires tagName and syntaxKind.

PropertyTypePurpose
tagNamestringTag name, with or without the leading @; it must start with a letter and may contain letters, digits, or hyphens.
syntaxKind"record" | "block" | "modifier" | "inline"How the parser reads the tag.
allowMultiplebooleanAllow the tag to appear more than once in a comment.
recordKind"component" | "utility" | "declaration" | "layout"Record category for a custom record tag.
aliasForstringIdentify the tag this custom tag aliases.
Show examples
jsonc
{
  "tagDefinitions": [
    {
      "tagName": "@author",
      "syntaxKind": "block", // Standalone block at the end of a doc comment
    },
  ],
}
jsonc
{
  "tagDefinitions": [
    {
      "tagName": "@widget",
      "syntaxKind": "record", // Marks a new record (like @component)
      "recordKind": "component", // Treat as a component type
      "allowMultiple": false,
    },
  ],
}
jsonc
{
  "tagDefinitions": [
    {
      "tagName": "@audience",
      "syntaxKind": "inline", // Can appear inline in prose
      "allowMultiple": true, // Can be used multiple times
    },
  ],
}
jsonc
{
  "tagDefinitions": [
    {
      "tagName": "@deprecated-reason",
      "syntaxKind": "block",
      "aliasFor": "@deprecated", // This tag is an alias for @deprecated
    },
  ],
}

supportForTags ​

Use tag names as keys and booleans as values. Set a standard tag to false to disable it or true to enable it. This is useful when keeping the standard vocabulary but changing support for selected tags.

Show examples
jsonc
{
  "supportForTags": {
    "example": false, // Don't process @example tags
    "see": false, // Don't process @see tags
  },
}
jsonc
{
  "noStandardTags": true, // Disable all standard tags by default
  "supportForTags": {
    "summary": true, // But enable @summary
    "modifier": true, // And @modifier
    "csspart": true, // And @csspart
  },
}

CSS interpretation ​

modifierConvention ​

Choose a preset or supply a custom convention:

jsonc
{
  "modifierConvention": "bem",
  // Or describe a custom convention:
  // "modifierConvention": {
  //   "structure": "chained",
  //   "separator": "-",
  //   "elementSeparator": "__",
  //   "statePrefixes": ["is-", "has-"]
  // }
}

The built-in presets are bem, rscss, and bare. A custom convention accepts:

PropertyTypePurpose
structure"chained" | "suffix" | "attribute"Selector form used for modifiers.
separatorstring or string[]Modifier separator or separators.
elementSeparatorstring or string[]BEM-style element delimiter; matching classes become parts.
statePrefixesstring[]Class prefixes that identify states, such as is- and has-.
statePseudoClassesstring[]Native pseudo-classes to treat as states. Supplying this replaces the built-in set.
pseudoElementsstring[]Native pseudo-elements to document, without the leading ::. Supplying this replaces the built-in set.
propValuebooleanSplit modifier names into property and value segments.
propValueSeparatorstringSeparator between those segments when propValue is enabled.

structure and separator are required for a custom object. The preset defaults to BEM when omitted.

Presets ​

Use a built-in preset for conventions matching popular CSS naming systems:

Show examples
jsonc
{
  // Block Element Modifier: component__part--modifier
  "modifierConvention": "bem",
}
jsonc
{
  // Reasonable System for CSS Structure: component -child -modifier
  "modifierConvention": "rscss",
}
jsonc
{
  // Minimal convention: component -modifier
  "modifierConvention": "bare",
}

Custom conventions ​

Define custom naming conventions by specifying structure, separators, and prefixes:

Show examples
jsonc
{
  "modifierConvention": {
    "structure": "chained", // Modifiers appear as .component-modifier
    "separator": "-", // Chained modifier separator
    "elementSeparator": "__", // Elements as component__part
    "statePrefixes": ["is-", "has-"], // State prefixes
  },
}
jsonc
{
  "modifierConvention": {
    "structure": "suffix", // Modifiers appear as .component--modifier
    "separator": "--", // Suffix separator
    "statePrefixes": ["state-"], // Treat state- prefix as a state
  },
}
jsonc
{
  "modifierConvention": {
    "structure": "chained",
    "separator": "-",
    "propValue": true, // Split .component-color-blue into color=blue
    "propValueSeparator": ":", // Property and value separated by colon
  },
}

inlineComments ​

Choose how an ordinary CSS comment on a member rule combines with prose from its doc tag:

  • append adds the comment after the tag prose (default).
  • prepend adds it before the tag prose.
  • replace uses the comment instead of the tag prose.
  • ignore discards the member comment for documentation.
Show examples

Given this CSS with both a tag and a member comment:

css
/**
 * @modifier hover
 * Shows on hover.
 */
.button--hover {
  /* Sets the highlight color. */
  color: highlight;
}
jsonc
{
  // Result: "Shows on hover. Sets the highlight color."
  "inlineComments": "append",
}
jsonc
{
  // Result: "Sets the highlight color. Shows on hover."
  "inlineComments": "prepend",
}
jsonc
{
  // Result: "Sets the highlight color."
  "inlineComments": "replace",
}
jsonc
{
  // Result: "Shows on hover."
  "inlineComments": "ignore",
}

globalPrecedence ​

Choose how to resolve a modifier defined both explicitly and with @global:

  • base lets the explicit modifier take precedence (default).
  • global lets the global modifier take precedence.
Show examples

Given this CSS with both a global and explicit modifier:

css
/**
 * @component button
 * @global hover Rendered when hovering anywhere on the button.
 */
.button {
}

/**
 * @modifier hover
 * Shows when hovering over the primary variant.
 */
.button--primary:hover {
}
jsonc
{
  // Explicit .button--primary:hover takes precedence over global hover
  "globalPrecedence": "base",
}
jsonc
{
  // Global hover takes precedence; explicit definition flagged as conflict
  "globalPrecedence": "global",
}

Providers ​

Each providers entry requires path. It may point to a source stylesheet or a published model.json. Relative paths beginning with . resolve from the config file; package specifiers use Node resolution.

PropertyTypePurpose
pathstringSource stylesheet or published model.
baseHrefstringURL prefix for links to the provider's rendered pages.
prefixobjectRewrite the provider's base-class prefix before records are merged.

prefix requires from and accepts to and isRegExp. from is a literal prefix unless isRegExp is true, in which case it is a regular-expression source anchored at the start of the class name. to is used verbatim; no separator is inserted. Omit it or use an empty string to strip the prefix.

Consuming sources ​

Load documentation from stylesheets or precompiled models in your project or from npm packages:

Show examples
jsonc
{
  "providers": [
    {
      "path": "./styles/base.css", // Relative path from config file
    },
  ],
}
jsonc
{
  "providers": [
    {
      "path": "@company/ui-kit/styles.css", // npm package path
      "baseHref": "https://docs.company.com/ui-kit/", // URL prefix for links
    },
  ],
}
jsonc
{
  "providers": [
    {
      "path": "@cssdoc/defaults/model.json", // Precompiled model from package
    },
  ],
}

Prefix rewriting ​

Transform class name prefixes before merging documentation from providers:

Show examples
jsonc
{
  "providers": [
    {
      "path": "./vendor/external.css",
      "prefix": {
        "from": "vendor-", // Find this prefix
        "to": "my-", // Replace with this
      },
    },
  ],
}
jsonc
{
  "providers": [
    {
      "path": "./vendor/theme.css",
      "prefix": {
        "from": "theme_", // Find this prefix
        // Omit "to" to remove the prefix entirely
      },
    },
  ],
}
jsonc
{
  "providers": [
    {
      "path": "./vendor/icons.css",
      "prefix": {
        "from": "^icon[A-Z]", // Match: iconArrow, iconSearch, etc.
        "to": "icon-", // Replace with: icon-arrow, icon-search
        "isRegExp": true, // Treat "from" as a regex pattern
      },
    },
  ],
}

Lint rules ​

rules ​

Set any supported rule to off, warn, or error. Unspecified rules use their defaults: missing-summary and unknown-custom-property default to off; most other rules default to warn, while duplicate IDs default to error. See linting for each rule's behavior.

RuleDefaultPurpose
alias-requires-canonicalwarnAliased modifiers must have a canonical replacement via {@link} or alias target
component-name-casewarnComponent class names must match the configured naming convention
conflicting-global-modifierwarnComponent modifiers conflicting with global modifier definitions must be resolved
cssdoc-directivewarnUnknown or malformed doc-comment directives
deprecated-modifierwarnDeprecated modifiers applied in CSS or usage must include deprecation rationale
deprecated-requires-canonicalwarnDeprecated modifiers/parts must have a canonical replacement via {@link} or note
disallowed-elementwarnComponent is applied to HTML elements outside its documented allow-list
duplicate-record-iderrorRecord identifier is duplicated within the same kind in this scope
duplicate-record-id-cross-kinderrorRecord identifier is shared across different kinds; use typed structure refs
invalid-default-valuewarnCustom property default value doesn't match declared syntax
invalid-fallback-valuewarnCustom property fallback value doesn't match declared syntax
invalid-property-valuewarnCustom property value doesn't match declared syntax
missing-summaryoffRecord lacks a @summary description
name-not-in-csswarnDocumented modifier or part name is not found in any CSS selector
part-name-casewarnPart name must match the configured naming convention
readonly-redefinitionwarnRead-only record redefines a property with multiple incompatible values
sealed-reset-valuewarnSealed or frozen record uses disallowed reset-like value keywords
structure-ambiguous-recordwarn@structure reference is ambiguous across record kinds; use a typed ref like @component
structure-unknown-recordwarn@structure references a record that doesn't exist or isn't the documented kind
structure-unknown-selectorwarn@structure references a selector that isn't the component class or documented member
unknown-annotation-refwarn@ref doesn't match any annotation legend entry in the record
unknown-custom-propertyoffUsage references a custom property that isn't documented
unknown-modifierwarnApplied or referenced modifier isn't documented for the component
unknown-partwarnApplied or referenced part isn't documented for the component
unknown-statewarnApplied or referenced pseudo-class state isn't documented for the component
undocumented-css-partwarnCSS ::part() selector lacks a corresponding @csspart description
undocumented-modifierwarnModifier selector lacks a corresponding @modifier description
undocumented-partwarnPart selector lacks a corresponding @part description
Show examples
jsonc
{
  "rules": {
    "missing-summary": "off", // Allow components without a summary
    "unknown-custom-property": "warn", // Warn about undefined custom properties
    "duplicate-record-id": "error", // Error on duplicate IDs
  },
}
jsonc
{
  "rules": {
    "unknown-modifier": "error", // All modifiers must be documented
    "unknown-part": "error", // All parts must be documented
    "structure-unknown-selector": "error", // All structure references must exist
    "undocumented-modifier": "error", // All modifiers must have prose
  },
}

overrides ​

Each override requires files and rules. files is one glob or an array of globs, all relative to the config file where the override is declared. Matching overrides apply in order, and later matches win. The rules object accepts the same rule names and severities as the top-level rules field.

Show examples
jsonc
{
  "rules": {
    "missing-summary": "error", // Strict by default
  },
  "overrides": [
    {
      "files": "vendor/**/*.css", // But relax for vendor code
      "rules": {
        "missing-summary": "off", // Allow vendor code without summaries
      },
    },
  ],
}
jsonc
{
  "rules": {
    "undocumented-modifier": "warn", // Default to warning
  },
  "overrides": [
    {
      "files": "src/components/**/*.css", // But require docs for internal code
      "rules": {
        "undocumented-modifier": "error", // All modifiers must have prose
        "missing-summary": "error", // All components must have a summary
      },
    },
  ],
}
jsonc
{
  "overrides": [
    {
      "files": ["experimental/**/*.css", "deprecated/**/*.css"], // Less strict for experimental
      "rules": {
        "structure-unknown-selector": "warn", // Allow some loose references
      },
    },
    {
      "files": "src/stable/**/*.css", // Strict for stable code
      "rules": {
        "structure-unknown-selector": "error", // All references must resolve
      },
    },
  ],
}

ruleOptions ​

PropertyTypePurpose
values.allowInheritbooleanAllow inherit in sealed/frozen value checks (default false).
sealed.mode"strict" | "compat"strict checks the full reset-keyword set; compat checks only unset and initial.
Show examples
jsonc
{
  "ruleOptions": {
    "values": {
      "allowInherit": false, // Reject inherit as a reset value
    },
  },
}
jsonc
{
  "ruleOptions": {
    "values": {
      "allowInherit": true, // Allow inherit as a reset value
    },
  },
}
jsonc
{
  "ruleOptions": {
    "sealed": {
      "mode": "strict", // Check full CSS reset keyword set
    },
  },
}
jsonc
{
  "ruleOptions": {
    "sealed": {
      "mode": "compat", // Check only unset and initial
    },
  },
}

Naming and structure ​

naming ​

Set component and/or part to a naming preset (pascalCase, camelCase, or lowercase) or a custom regular-expression source. The corresponding name-case rule checks each configured class kind.

Naming presets ​

Use built-in conventions to enforce consistent component and part naming across your stylesheets:

Show examples
jsonc
{
  "naming": {
    "component": "pascalCase", // e.g., MyButton, AlertDialog
    "part": "camelCase", // e.g., buttonText, dialogTitle
  },
}
jsonc
{
  "naming": {
    "component": "lowercase", // e.g., mybutton, alertdialog
    "part": "lowercase", // e.g., buttontext, dialogtitle
  },
}
jsonc
{
  "naming": {
    "component": "camelCase", // e.g., myButton, alertDialog
    "part": "camelCase", // e.g., buttonText, dialogTitle
  },
}

Custom naming patterns ​

Define regular-expression patterns to enforce domain-specific or legacy naming conventions:

Show examples
jsonc
{
  "naming": {
    // Custom pattern: start with uppercase, followed by alphanumerics
    "component": "^[A-Z][a-zA-Z0-9]*$",
  },
}
jsonc
{
  "naming": {
    // Custom pattern: lowercase words separated by underscores
    "component": "^[a-z]+(_[a-z]+)*$",
  },
}

structureIgnore ​

List external class names that are valid in @structure but aren't documented in the current scope. Entries can be literal names or simple globs, where * matches any run of characters.

Show examples
jsonc
{
  "structureIgnore": [
    "external-layout", // Known external component
    "third-party-wrapper", // Known external wrapper
  ],
}
jsonc
{
  "structureIgnore": [
    "bootstrap-*", // All Bootstrap utility classes
    "tailwind-*", // All Tailwind utility classes
    "material-*", // All Material Design classes
  ],
}
jsonc
{
  "structureIgnore": [
    "legacy-component", // Specific legacy class
    "vendor-*", // All vendor-prefixed classes
    "*-utility", // All utility classes, any prefix
  ],
}

Render options ​

The render object supplies defaults to consumers. Explicit emitter options override them.

PropertyTypePurpose
includeInternalbooleanInclude records marked @visibility internal; defaults to false.
sectionOrderstring[]Order and include record-page sections. Omitted section keys are dropped.
headingPrefixstringPrefix each record-page title.
baseHrefstringBase URL for @related links and index/sidebar links.
structureView"text" | "diagram" | "both"Choose the structure tree, flowchart, or both; defaults to both.
structureVariantView"diagram" | "sections"Render structure variants as one combined diagram or separate variant subsections; defaults to diagram.
groupsstring[]Put named sidebar/index groups first in the listed order; unlisted groups follow the default order.
exampleFiltersobjectFilter examples independently for Markdown, HTML, and hover.

Sections and structure views ​

Control which sections appear in record documentation and how component structures are rendered:

Show examples
jsonc
{
  "render": {
    "sectionOrder": [
      "demo", // Show live demos first
      "examples", // Then code examples
      "usage", // Then usage patterns
      "modifiers", // Then modifier reference
      "states", // Then states
      "cssProperties", // Then CSS properties
      "accessibility", // Then accessibility info
    ],
  },
}
jsonc
{
  "render": {
    "structureView": "diagram", // Show component structure as diagram
    "structureVariantView": "sections", // Show variants as separate subsections
  },
}

Available sectionOrder values: demo, examples, usage, annotations, modifiers, parts, shadowParts, pseudoElements, states, slots, structure, subcomponents, cssProperties, functions, animations, layers, conditions, tokensConsumed, compat, accessibility, related, and see.

Example filtering ​

Filter examples independently for different output formats (Markdown, HTML, and hover tooltips):

Show examples
jsonc
{
  "render": {
    "exampleFilters": {
      "markdown": {
        "labels": ["web-component", "react"], // Show these example types
        "includeUnlabeled": false, // Don't show examples without labels
      },
    },
  },
}
jsonc
{
  "render": {
    "exampleFilters": {
      "markdown": {
        "labels": ["web-component", "react"], // Show web-component and React examples in Markdown
      },
      "html": {
        "labels": ["web-component"], // Show only web-component examples in HTML output
      },
      "hover": null, // No filter for hover; show all examples
    },
  },
}

Example filter structure: exampleFilters may set markdown, html, and hover. Each surface accepts either null or an object with a required labels array and optional includeUnlabeled boolean. Labels are unique lowercase kebab-case strings. An example is included when any label matches; unlabeled examples are included by default. Set a surface to null to clear an inherited filter for that surface. An omitted surface doesn't add a filter.

General render configuration ​

Configure display options like internal visibility, base URL, heading prefixes, and sidebar group ordering:

Show examples
jsonc
{
  "render": {
    "includeInternal": false, // Hide internal-only records
    "baseHref": "https://docs.example.com/", // Base URL for links
  },
}
jsonc
{
  "render": {
    "groups": [
      "Layouts", // Show first
      "Components", // Show second
      "Utilities", // Show third
      // Other groups follow in default order
    ],
  },
}
jsonc
{
  "render": {
    "includeInternal": false, // Hide internal records
    "baseHref": "https://docs.example.com/", // Base URL for links
    "structureView": "diagram", // Show structures as diagrams
    "sectionOrder": ["demo", "examples", "modifiers", "states", "cssProperties", "accessibility"],
    "exampleFilters": {
      "markdown": {
        "labels": ["web-component", "react"], // These frameworks only
        "includeUnlabeled": true, // Also include examples without labels
      },
      "hover": null, // No filter for hover tooltips
    },
  },
}

Complete JSON Schema ​

The block below is included from the published schema source, so it stays aligned with editor validation:

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

Released under the MIT License