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:
{
"$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
| Field | Type | Purpose |
|---|---|---|
$schema | string | Schema URL used by editors. |
extends | string[] | Config files or package exports to inherit. Relative paths resolve from the config that declares them. |
noStandardTags | boolean | Disable all standard tags; only custom tagDefinitions remain enabled. |
tagDefinitions | object[] | Add custom doc-comment tags. |
supportForTags | object | Enable or disable individual tags by name. |
modifierConvention | preset or object | Describe 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. |
providers | object[] | Consume records from another CSS source or published model. |
rules | object | Set lint rule severities. |
overrides | object[] | Set rule severities for matching file globs. |
ruleOptions | object | Tune behavior shared by related lint rules. |
naming | object | Enforce naming conventions for component and part classes. |
structureIgnore | string[] | Exempt external class names from structure-unknown-selector. |
globalPrecedence | "base" | "global" | Choose which modifier wins when a global and explicit definition conflict. |
render | object | Set 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
{
"$schema": "https://cssdoc.dev/cssdoc.schema.json",
// Inherit from a preset configuration package
"extends": ["@cssdoc/config/web-components"],
}{
"$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
},
}{
"$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",
},
}{
"$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
{
// Inherit from another config file in the project
"extends": ["./cssdoc.base.json"],
// Override specific fields
}{
// Inherit from a published config preset
"extends": ["@cssdoc/config/web-components"],
// Add or override settings
"rules": {
"missing-summary": "off", // This overrides the inherited value
},
}{
// 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
{
// 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
{
// 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-*"]
}{
// 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.
| Property | Type | Purpose |
|---|---|---|
tagName | string | Tag 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. |
allowMultiple | boolean | Allow the tag to appear more than once in a comment. |
recordKind | "component" | "utility" | "declaration" | "layout" | Record category for a custom record tag. |
aliasFor | string | Identify the tag this custom tag aliases. |
Show examples
{
"tagDefinitions": [
{
"tagName": "@author",
"syntaxKind": "block", // Standalone block at the end of a doc comment
},
],
}{
"tagDefinitions": [
{
"tagName": "@widget",
"syntaxKind": "record", // Marks a new record (like @component)
"recordKind": "component", // Treat as a component type
"allowMultiple": false,
},
],
}{
"tagDefinitions": [
{
"tagName": "@audience",
"syntaxKind": "inline", // Can appear inline in prose
"allowMultiple": true, // Can be used multiple times
},
],
}{
"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
{
"supportForTags": {
"example": false, // Don't process @example tags
"see": false, // Don't process @see tags
},
}{
"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:
{
"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:
| Property | Type | Purpose |
|---|---|---|
structure | "chained" | "suffix" | "attribute" | Selector form used for modifiers. |
separator | string or string[] | Modifier separator or separators. |
elementSeparator | string or string[] | BEM-style element delimiter; matching classes become parts. |
statePrefixes | string[] | Class prefixes that identify states, such as is- and has-. |
statePseudoClasses | string[] | Native pseudo-classes to treat as states. Supplying this replaces the built-in set. |
pseudoElements | string[] | Native pseudo-elements to document, without the leading ::. Supplying this replaces the built-in set. |
propValue | boolean | Split modifier names into property and value segments. |
propValueSeparator | string | Separator 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
{
// Block Element Modifier: component__part--modifier
"modifierConvention": "bem",
}{
// Reasonable System for CSS Structure: component -child -modifier
"modifierConvention": "rscss",
}{
// Minimal convention: component -modifier
"modifierConvention": "bare",
}Custom conventions
Define custom naming conventions by specifying structure, separators, and prefixes:
Show examples
{
"modifierConvention": {
"structure": "chained", // Modifiers appear as .component-modifier
"separator": "-", // Chained modifier separator
"elementSeparator": "__", // Elements as component__part
"statePrefixes": ["is-", "has-"], // State prefixes
},
}{
"modifierConvention": {
"structure": "suffix", // Modifiers appear as .component--modifier
"separator": "--", // Suffix separator
"statePrefixes": ["state-"], // Treat state- prefix as a state
},
}{
"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:
appendadds the comment after the tag prose (default).prependadds it before the tag prose.replaceuses the comment instead of the tag prose.ignorediscards the member comment for documentation.
Show examples
Given this CSS with both a tag and a member comment:
/**
* @modifier hover
* Shows on hover.
*/
.button--hover {
/* Sets the highlight color. */
color: highlight;
}{
// Result: "Shows on hover. Sets the highlight color."
"inlineComments": "append",
}{
// Result: "Sets the highlight color. Shows on hover."
"inlineComments": "prepend",
}{
// Result: "Sets the highlight color."
"inlineComments": "replace",
}{
// Result: "Shows on hover."
"inlineComments": "ignore",
}globalPrecedence
Choose how to resolve a modifier defined both explicitly and with @global:
baselets the explicit modifier take precedence (default).globallets the global modifier take precedence.
Show examples
Given this CSS with both a global and explicit modifier:
/**
* @component button
* @global hover Rendered when hovering anywhere on the button.
*/
.button {
}
/**
* @modifier hover
* Shows when hovering over the primary variant.
*/
.button--primary:hover {
}{
// Explicit .button--primary:hover takes precedence over global hover
"globalPrecedence": "base",
}{
// 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.
| Property | Type | Purpose |
|---|---|---|
path | string | Source stylesheet or published model. |
baseHref | string | URL prefix for links to the provider's rendered pages. |
prefix | object | Rewrite 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
{
"providers": [
{
"path": "./styles/base.css", // Relative path from config file
},
],
}{
"providers": [
{
"path": "@company/ui-kit/styles.css", // npm package path
"baseHref": "https://docs.company.com/ui-kit/", // URL prefix for links
},
],
}{
"providers": [
{
"path": "@cssdoc/defaults/model.json", // Precompiled model from package
},
],
}Prefix rewriting
Transform class name prefixes before merging documentation from providers:
Show examples
{
"providers": [
{
"path": "./vendor/external.css",
"prefix": {
"from": "vendor-", // Find this prefix
"to": "my-", // Replace with this
},
},
],
}{
"providers": [
{
"path": "./vendor/theme.css",
"prefix": {
"from": "theme_", // Find this prefix
// Omit "to" to remove the prefix entirely
},
},
],
}{
"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.
| Rule | Default | Purpose |
|---|---|---|
alias-requires-canonical | warn | Aliased modifiers must have a canonical replacement via {@link} or alias target |
component-name-case | warn | Component class names must match the configured naming convention |
conflicting-global-modifier | warn | Component modifiers conflicting with global modifier definitions must be resolved |
cssdoc-directive | warn | Unknown or malformed doc-comment directives |
deprecated-modifier | warn | Deprecated modifiers applied in CSS or usage must include deprecation rationale |
deprecated-requires-canonical | warn | Deprecated modifiers/parts must have a canonical replacement via {@link} or note |
disallowed-element | warn | Component is applied to HTML elements outside its documented allow-list |
duplicate-record-id | error | Record identifier is duplicated within the same kind in this scope |
duplicate-record-id-cross-kind | error | Record identifier is shared across different kinds; use typed structure refs |
invalid-default-value | warn | Custom property default value doesn't match declared syntax |
invalid-fallback-value | warn | Custom property fallback value doesn't match declared syntax |
invalid-property-value | warn | Custom property value doesn't match declared syntax |
missing-summary | off | Record lacks a @summary description |
name-not-in-css | warn | Documented modifier or part name is not found in any CSS selector |
part-name-case | warn | Part name must match the configured naming convention |
readonly-redefinition | warn | Read-only record redefines a property with multiple incompatible values |
sealed-reset-value | warn | Sealed or frozen record uses disallowed reset-like value keywords |
structure-ambiguous-record | warn | @structure reference is ambiguous across record kinds; use a typed ref like @component |
structure-unknown-record | warn | @structure references a record that doesn't exist or isn't the documented kind |
structure-unknown-selector | warn | @structure references a selector that isn't the component class or documented member |
unknown-annotation-ref | warn | @ref doesn't match any annotation legend entry in the record |
unknown-custom-property | off | Usage references a custom property that isn't documented |
unknown-modifier | warn | Applied or referenced modifier isn't documented for the component |
unknown-part | warn | Applied or referenced part isn't documented for the component |
unknown-state | warn | Applied or referenced pseudo-class state isn't documented for the component |
undocumented-css-part | warn | CSS ::part() selector lacks a corresponding @csspart description |
undocumented-modifier | warn | Modifier selector lacks a corresponding @modifier description |
undocumented-part | warn | Part selector lacks a corresponding @part description |
Show examples
{
"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
},
}{
"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
{
"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
},
},
],
}{
"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
},
},
],
}{
"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
| Property | Type | Purpose |
|---|---|---|
values.allowInherit | boolean | Allow 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
{
"ruleOptions": {
"values": {
"allowInherit": false, // Reject inherit as a reset value
},
},
}{
"ruleOptions": {
"values": {
"allowInherit": true, // Allow inherit as a reset value
},
},
}{
"ruleOptions": {
"sealed": {
"mode": "strict", // Check full CSS reset keyword set
},
},
}{
"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
{
"naming": {
"component": "pascalCase", // e.g., MyButton, AlertDialog
"part": "camelCase", // e.g., buttonText, dialogTitle
},
}{
"naming": {
"component": "lowercase", // e.g., mybutton, alertdialog
"part": "lowercase", // e.g., buttontext, dialogtitle
},
}{
"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
{
"naming": {
// Custom pattern: start with uppercase, followed by alphanumerics
"component": "^[A-Z][a-zA-Z0-9]*$",
},
}{
"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
{
"structureIgnore": [
"external-layout", // Known external component
"third-party-wrapper", // Known external wrapper
],
}{
"structureIgnore": [
"bootstrap-*", // All Bootstrap utility classes
"tailwind-*", // All Tailwind utility classes
"material-*", // All Material Design classes
],
}{
"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.
| Property | Type | Purpose |
|---|---|---|
includeInternal | boolean | Include records marked @visibility internal; defaults to false. |
sectionOrder | string[] | Order and include record-page sections. Omitted section keys are dropped. |
headingPrefix | string | Prefix each record-page title. |
baseHref | string | Base 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. |
groups | string[] | Put named sidebar/index groups first in the listed order; unlisted groups follow the default order. |
exampleFilters | object | Filter 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
{
"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
],
},
}{
"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
{
"render": {
"exampleFilters": {
"markdown": {
"labels": ["web-component", "react"], // Show these example types
"includeUnlabeled": false, // Don't show examples without labels
},
},
},
}{
"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
{
"render": {
"includeInternal": false, // Hide internal-only records
"baseHref": "https://docs.example.com/", // Base URL for links
},
}{
"render": {
"groups": [
"Layouts", // Show first
"Components", // Show second
"Utilities", // Show third
// Other groups follow in default order
],
},
}{
"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:
{
"$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"
}
}
}
}
}
}