# components

URL: /chirp-ui/api/components/
Section: api
Description: Component descriptors — single source of truth for chirp-ui's BEM API surface.

Each `ComponentDescriptor` declares the full public contract of a component:
block name, allowed variants (legacy/mutually exclusive), appearances, tones,
sizes, boolean modifiers (additive), BEM elements, Kida slot names, and
overridable CSS custom properties.

Downstream consumers:

* ``VARIANT_REGISTRY`` / ``SIZE_REGISTRY`` in `chirp_ui.validation` derive
  from ``COMPONENTS``.
* The ``bem()`` filter validates against descriptors when strict mode is on.
* Contract tests auto-generate expected CSS class names from descriptors.
* `design_system_report`() exposes the full surface for introspection.

---

> For a complete page index, fetch /chirp-ui/llms.txt.

# components

Component descriptors — single source of truth for chirp-ui's BEM API surface.

Each `ComponentDescriptor` declares the full public contract of a component:
block name, allowed variants (legacy/mutually exclusive), appearances, tones,
sizes, boolean modifiers (additive), BEM elements, Kida slot names, and
overridable CSS custom properties.

Downstream consumers:

* ``VARIANT_REGISTRY`` / ``SIZE_REGISTRY`` in `chirp_ui.validation` derive
from ``COMPONENTS``.
* The ``bem()`` filter validates against descriptors when strict mode is on.
* Contract tests auto-generate expected CSS class names from descriptors.
* `design_system_report`() exposes the full surface for introspection.

module

Component descriptors — single source of truth for chirp-ui's BEM API surface.

Each `ComponentDescriptor` declares the full public contract of a component:
block name, allowed variants (legacy/mutually exclusive), appearances, tones,
sizes, boolean modifiers (additive), BEM elements, Kida slot names, and
overridable CSS custom properties.

Downstream consumers:

* ``VARIANT_REGISTRY`` / ``SIZE_REGISTRY`` in `chirp_ui.validation` derive
from ``COMPONENTS``.
* The ``bem()`` filter validates against descriptors when strict mode is on.
* Contract tests auto-generate expected CSS class names from descriptors.
* `design_system_report`() exposes the full surface for introspection.

SlotForward

class

Explicit mapping from a composite's public slot to a composed child slot.

``slot`` and ``target_slot`` use ``""`` for the default slot, matching
`slots` and the manifest convention.
``target`` is a key in `COMPONENTS`, not a CSS block or macro name.

ComponentDescriptor

class

Frozen description of a single chirp-ui component's public CSS API.

Fields
------
block : str
BEM block name (e.g. ``"btn"``). CSS class becomes ``chirpui-{block}``.
variants : tuple[str, ...]
Mutually-exclusive modifiers (``chirpui-{block}--{variant}``).
Empty string ``""`` means "no variant class emitted".
appearances : tuple[str, ...]
Cross-component visual treatment values the component opts into
(``chirpui-{block}--{appearance}``). These are descriptor-backed macro
params, not global utility classes.
tones : tuple[str, ...]
Semantic intent values the component opts into
(``chirpui-{block}--{tone}``). ``danger`` is the shared destructive
tone; legacy ``error`` values remain component-local variants.
sizes : tuple[str, ...]
Size modifiers (``chirpui-{block}--{size}``).
modifiers : tuple[str, ...]
Additive boolean modifiers that can combine with variant/size
(e.g. ``"loading"`` → ``chirpui-btn--loading``).
elements : tuple[str, ...]
BEM elements (``chirpui-{block}__{element}``).
slots : tuple[str, ...]
Public caller slots the macro accepts (``""`` = default slot). This
includes direct Kida ``{% slot %}`` placeholders and caller content
forwarded into composed children.
composes : tuple[str, ...]
Component registry keys this component semantically composes.
slot_forwards : tuple[SlotForward, ...]
Explicit public-slot forwarding contracts into composed children.
tokens : tuple[str, ...]
Component-scoped CSS custom properties (override knobs for theming).
extra_emits : tuple[str, ...]
Escape hatch for classes the BEM grammar cannot derive
(compound-state classes, internal structural elements not surfaced
as BEM elements, etc.). Joined into `emits`.
trim_emits : tuple[str, ...]
Explicitly removes grammar-derived classes that are accepted by a
descriptor's public vocabulary but intentionally have no standalone
CSS rule (for example implicit/default variants).
template : str
Filename in ``templates/chirpui/`` (e.g. ``"button.html"``).
category : str
Grouping label for documentation/introspection.
maturity : str
Stability tier for agents and docs. Public descriptors set this
explicitly so the manifest does not infer product readiness.
role : str
Semantic role for discovery/agent planning. Empty means "derive from
category" (effects → ``effect``, composites → ``pattern``, etc.).
authoring : str
Agent-facing authoring hint. ``"preferred"`` marks vocabulary to reach
for first, ``"compatibility"`` marks retained legacy surface, and empty
derives from maturity (legacy → compatibility, internal → internal,
everything else → available).
requires : tuple[str, ...]
Runtime features the component needs when rendered. Keep explicit
entries for non-obvious requirements; the manifest may add derived
requirements (for example Alpine factories) during projection.
macro : str | None
Macro identifier inside `template` (e.g. ``"shimmer_button"``).
When ``None``, defaults to ``block.replace("-", "_")`` at lookup
time. Set explicitly only when the macro name diverges from the BEM
block (e.g. ``block="shimmer-btn"`` → ``macro="shimmer_button"``).
Used by `chirp_ui.manifest` to resolve param signatures from
the template AST.

DesignSystemStats

class

Aggregate counts for the design system surface.

DesignSystemReport

class

Machine-readable summary of the chirp-ui design system surface.

design_system_report

function

Machine-readable summary of the full chirp-ui design system surface.

Returns the same live projection as `build_manifest`(),
including derived macro signatures, runtime requirements, provide/consume
keys, descriptions, theme packs, and aggregate quality stats. The historical
top-level keys (``"components"``, ``"tokens"``, and ``"stats"``) remain
present for existing callers.