# chirp-ui API Reference

URL: /chirp-ui/api/
Section: api
Description: Browse Python API documentation by package.

---

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

# chirp-ui API Reference

Browse Python API documentation by package.

0 filters selected

## Modules

17 modules

autodoc-python

library

Framework-neutral package metadata for Chirp UI consumers.

Frameworks and static-site generators can consume this module to discover the
public Chirp UI template root, static assets, and manifest path without reading
package internals or hardcoding filenames in theme templates.

(/chirp-ui/api/library/)

autodoc-python

inspect

Design system introspection — dump the chirp-ui API surface.

Usage::

python -m chirp_ui.inspect # JSON report
python -m chirp_ui.inspect --summary # compact table
python -m chirp_ui.inspect --tokens # token catalog only
python -m chirp_ui.inspect --components # component descriptors only
python -m chirp_ui.inspect --provides # {% provide %} statements + annotations
python -m chirp_ui.inspect --consumes # consume() calls + annotations
python -m chirp_ui.inspect --audit-context # dead provides, unprovided consumes, annotation drift

(/chirp-ui/api/inspect/)

autodoc-python

layout_affinity

Layout-affinity vocabulary for recipe-level workspace contracts.

The current layout-affinity contract is intentionally narrow: rendered
templates may emit documented ``data-chirpui-*`` attributes, and parent
primitives may resolve those attributes inside their own scoped CSS. This
module centralizes the allowed vocabulary without projecting it into the public
manifest schema yet.

(/chirp-ui/api/layout_affinity/)

autodoc-python

alpine

Alpine runtime detection for chirp-ui.

chirp-ui has a small, enumerable set of macros that require
``chirpui-alpine.js`` to work at runtime (theme toggle, dialogs,
dropdowns, collapsible sidebar, etc). When an app ships a layout that
imports those macros but forgets the script tag, every interactive
component breaks silently.

This module exposes the manifest of Alpine-requiring factories and a
pure `check_alpine_runtime`() helper. Chirp's ``use_chirp_ui(app)``
calls the helper against the first rendered response at freeze time so
the mistake surfaces as a warning (or a raised error, in dev) at startup
rather than as broken UI in production.

Example::

from chirp_ui.alpine import check_alpine_runtime

result = check_alpine_runtime(rendered_html)
if not result.ok:
missing = ", ".join(sorted(result.missing))
raise RuntimeError(
f"layout uses Alpine factories {{{missing}}} but "
"chirpui-alpine.js is not in the rendered HTML"
)

(/chirp-ui/api/alpine/)

autodoc-python

manifest

Agent-groundable manifest of the chirp-ui component surface.

This module publishes the component registry (``chirp_ui.components.COMPONENTS``
plus ``chirp_ui.tokens.TOKEN_CATALOG``) as a stable JSON snapshot. AI agents
and docs tooling can read the manifest to cite real classes, tokens, slots,
and templates instead of plausible-sounding ones.

Schema
------
``{"schema": "chirpui-manifest@5", "version": "<pkg>", "components": {...},
"tokens": {...}, "theme_packs": [...], "stats": {...}}``

* ``components`` keys sorted; each entry contains ``block``, ``variants``,
``sizes``, ``modifiers``, ``elements``, ``slots``, ``tokens``,
``extra_emits``, ``trim_emits``, ``emits``, ``template``, ``category``,
``maturity``, ``role``, ``authoring``, ``requires``, plus the ``@2``
additions ``macro``, ``params``, and ``lineno``, the ``@3`` composition
additions ``composes``, ``slot_forwards``, and ``slots_yielded``, and the
``@4`` appearance/tone additions ``appearances`` and ``tones``.
* ``params`` is a list of ``{"name": str, "has_default": bool,
"is_required": bool}`` derived from the template AST via
`chirp_ui._macro_introspect`. Empty when the descriptor has no
template, the macro cannot be resolved, or the template has no
``{% def %}`` matching the resolved name.
* ``macro`` is the resolved macro identifier (``descriptor.macro`` if set,
else ``block.replace("-", "_")``). ``null`` when the descriptor has no
template or no matching macro is found.
* ``lineno`` is the source line of the ``{% def %}`` tag (``0`` when
unavailable).
* ``slots`` is the sorted union of ``descriptor.slots``, direct slots
extracted from the macro body, and yielded slots accepted by composite
wrappers. The unnamed default slot is represented as ``""``. Hand-authored
descriptor entries can over-declare (e.g. for documentation), but the
manifest never under-reports a real slot.
* ``slots_extracted`` is the AST-derived slot list (sorted, default = ``""``)
exposed separately so parity tests can spot descriptor↔template drift
without losing the merged ``slots`` contract.
* ``slots_yielded`` is the source-derived list of ``{% yield %}`` /
``{% yield name %}`` caller slots. Composite forwarding metadata is explicit
in ``composes`` and ``slot_forwards``.
* ``provides`` / ``consumes`` are sorted lists of context keys (e.g.
``"_card_variant"``) sourced from `chirp_ui.inspect`. A key is
attributed to the macro whose ``{% def %}`` lineno is the largest one
preceding the ``{% provide %}`` / ``consume()`` site.
* ``description`` is the stripped text inside the leading
``{#- chirp-ui: ... -#}`` doc-block of the template file. One block per
file, covering every macro; empty string when the descriptor has no
template. New chirp-ui templates must carry a doc-block
(``tests/test_description_coverage.py``).
* ``tokens`` keys sorted; each entry is ``{"category": …, "scope": …}``.
* ``theme_packs`` lists packaged token-only theme CSS resources in stable
catalog order.
* ``stats`` aggregates counts, including ``components_with_params``, a
``registry_debt`` scorecard for descriptor/CSS reconciliation burn-down,
and a ``manifest_quality`` scorecard for agent-facing metadata coverage.

Deterministic: two calls to `build_manifest`() yield byte-identical JSON.

CLI
---
``python -m chirp_ui.manifest --json`` writes JSON to stdout.

See ``docs/plans/done/PLAN-agent-grounding-depth.md`` and
``docs/DESIGN-manifest-signature-extraction.md``.

(/chirp-ui/api/manifest/)

autodoc-python

validation

chirp-ui variant validation — strict mode, warning infrastructure, and registries.

When strict mode is enabled (via `set_strict`()), validation warnings
escalate to ``ValueError``. In non-strict mode, `_warn`() emits a
filterable `ChirpUIValidationWarning` so developers see feedback
without crashes.

``VARIANT_REGISTRY``, ``APPEARANCE_REGISTRY``, ``TONE_REGISTRY``, and
``SIZE_REGISTRY`` are derived from the canonical component descriptors in
`chirp_ui.components`.

Everything not in __all__ is internal and may change without notice.

(/chirp-ui/api/validation/)

autodoc-python

icons

Icon registry: semantic names → Unicode glyphs for chirp-ui components.

Use the `icon` filter to resolve names in templates: `{{ "status" | icon }}` → ◎.
Unknown names pass through unchanged for backward compatibility.

(/chirp-ui/api/icons/)

autodoc-python

find

Fuzzy component discovery over the shipped manifest — ``python -m chirp_ui find``.

Sprint 6 of the agent-grounding-depth epic. The manifest is the registry
projection; this module turns it into a one-liner for humans and agents who
know *what* they want but not the exact BEM block name.

Search model
------------

A component matches a query when the query is a case-insensitive substring of
any of:

* ``name`` — the manifest key, e.g. ``metric-card``
* ``block`` — the BEM block, e.g. ``metric-card`` (usually same as name)
* ``category`` — e.g. ``data-display``, ``feedback``
* ``description`` — the ``{#- chirp-ui: ... -#}`` doc-block text

Query filters (``--category`` etc.) are applied AFTER substring match, so
``find --category=feedback`` lists every component in that category even when
no term is given.

Use ``--authoring=preferred`` to list the registry-blessed primitives agents
should reach for first, or ``--authoring=compatibility`` to audit legacy
helpers retained for existing templates.

Output
------

One line per hit, stable/sorted::

{name:<30} {category:<16} {first-line-of-description}

Exit code ``0`` always (including zero hits) — this is discovery, not
validation.

See ``docs/plans/PLAN-agent-grounding-depth.md § Sprint 6``.

(/chirp-ui/api/find/)

autodoc-python

chirp_ui

chirp-ui — Reusable Kida component library for Chirp.

Headless, htmx-native, zero JavaScript. Install and import::

pip install chirp-ui

{%% from "chirpui/card.html" import card %%}
{%% from "chirpui/modal.html" import modal, modal_trigger %%}

When used with Chirp, components are auto-detected via ``PackageLoader``.
For standalone Kida usage, call `get_loader`().
Call `register_filters`() to ensure bem/field_errors/html_attrs filters are available.
Call `register_colors`() once per app if you use semantic color names with
``resolve_color`` / ``badge(..., color=...)`` / ``filter_chips`` (see ``docs/COMPONENT-OPTIONS.md``).

(/chirp-ui/api/chirp_ui/)

autodoc-python

_macro_introspect

AST introspection for ``{% def %}`` macros — internal.

Wraps `kida.lexer` + `kida.parser` to extract per-macro parameter
metadata without compiling the template (so no chirp-ui filter stubs are
required at manifest-build time).

Used by `chirp_ui.manifest` to project macro Python signatures into the
agent-groundable manifest. See ``docs/plans/done/PLAN-agent-grounding-depth.md`` and
``docs/DESIGN-manifest-signature-extraction.md``.

(/chirp-ui/api/_macro_introspect/)

autodoc-python

filters

Template filters required by chirp-ui components.

These match Chirp's filter API so chirp-ui works with any Chirp version.
Register via `register_filters`() when using Chirp.

Everything not in __all__ is internal and may change without notice.

(/chirp-ui/api/filters/)

autodoc-python

__main__

``python -m chirp_ui`` dispatch — subcommand front door.

Currently a single subcommand (``find``) plus a pointer to the existing
``python -m chirp_ui.manifest`` entry point. New subcommands go here.

See ``docs/plans/PLAN-agent-grounding-depth.md § Sprint 6``.

(/chirp-ui/api/__main__/)

autodoc-python

tokens

CSS custom property catalog — machine-readable index of --chirpui-* tokens.

Each `TokenDef` records a single CSS custom property: its name,
semantic category, and scope (global or a component block name).

The catalog is bootstrapped by ``scripts/extract_tokens.py`` and curated here
as the source of truth. Tests validate it against ``chirpui.css`` to catch
drift.

Categories
----------
* **color** — semantic colors, state colors, gradients
* **spacing** — fluid spacing scale and role aliases
* **typography** — font sizes, weights, families, line-heights
* **radius** — border-radius scale
* **elevation** — box-shadow tokens
* **motion** — easing curves and durations
* **layout** — structural tokens (container max, grid min, sidebar dims)
* **component** — per-component override knobs (scoped)

(/chirp-ui/api/tokens/)

autodoc-python

route_tabs

Route-family tab helpers for chirp-ui route_tabs component.

Tab item: dict or object with ``href``, optional ``match`` (default ``"exact"``).
Full dict shape (from Chirp ``TabItem`` via ``_tab_item_to_shell_dict``):
``{ label, href, icon?, badge?, match? }``.

(/chirp-ui/api/route_tabs/)

autodoc-python

theme_packs

Immutable catalog of token-only Chirp UI theme packs.

(/chirp-ui/api/theme_packs/)

autodoc-python

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.

(/chirp-ui/api/components/)

autodoc-python

chirp-ui API Reference

Browse Python API documentation by package.

(/chirp-ui/api/)