# ki-ai-label

> A compact provenance mark for AI-generated content, with optional details and a user-initiated request to restore their original text.

## When to use

Mark text or a value generated by AI. Include the source in
`explanation` when people can inspect how it was generated. In a `ki-input`,
place the label in the `end` slot to describe the field's provenance.

## When not to use

Use a status component for active generation or processing,
and an application action for changes that do not restore the person's text.

## Examples

# AI label examples

Mark generated content beside the text it describes.

```html
<header>Weekly summary <ki-ai-label></ki-ai-label></header>
```

Give people a short provenance explanation when they need to assess a result.
The model and generation time are optional.

```html
<ki-ai-label
  explanation="Written from the incident reports of the last 30 days."
  model="Standard"
  generated-at="2026-11-19T10:32"
></ki-ai-label>
```

Use the input's `end` slot to announce the provenance with the field
description. Keep the original in application state and restore it on
`ki-revert`.

```html
<ki-input id="subject" label="Subject" value="Incident summary">
  <ki-ai-label
    slot="end"
    explanation="Suggested from the incident reports."
    revertible
  ></ki-ai-label>
</ki-input>

<script type="module">
  const field = document.querySelector('#subject');
  const label = field.querySelector('ki-ai-label');
  const original = 'Weekly summary';

  label.addEventListener('ki-revert', () => {
    field.value = original;
    label.remove();
    field.focus();
  });
</script>
```

## Attributes

- `explanation` (string | undefined): Plain-text explanation of how the content was generated. Supply a nonblank explanation to offer disclosure. Omit it for a static mark.
- `generated-at` (string | undefined): Optional generation date or time, displayed as supplied.
- `generated-at-label` (string, default 'Generated'): Visible prefix for the generation date or time.
- `label` (string, default 'AI'): Short visible provenance text. Localize it with the trigger name.
- `model` (string | undefined): Optional plain-text model name shown in the explanation.
- `model-label` (string, default 'Model:'): Visible prefix for the model name.
- `popover-label` (string, default 'About this content'): Accessible name of the non-modal explanation panel.
- `revert-label` (string, default 'Revert to my text'): Visible text and accessible name of the revert action.
- `revertible` (boolean, default false): Offer the revert action inside the explanation. Enable it when the application has the original text and handles `ki-revert`.
- `size` ("md" | "sm", default 'sm'): Size of the painted mark. Unknown values use the small metrics.
- `trigger-label` (string, default 'AI-generated: about this content'): Accessible name of the disclosure button. Include the visible label.

## Slots

None.

## Parts

- `explanation`: Source explanation paragraph.
- `icon`: Decorative sparkles glyph.
- `label`: Tinted mark containing the icon and visible text.
- `metadata`: Optional model and generation time.
- `popover`: Non-modal explanation panel.
- `revert`: Button that requests reversion.
- `trigger`: Disclosure button, available with an explanation.

## Events

- `ki-revert` (CustomEvent<void>): Bubbles when a person requests their original text. Use this request to restore the original from application state.

## Methods

None.

## CSS custom properties

- `--ki-ai-label-backdrop-filter`: Complete filter behind the AI provenance mark. Defaults to none.
- `--ki-ai-label-bg`: Fill of the AI provenance mark.
- `--ki-ai-label-bg-image`: Optional image over the AI provenance fill. Defaults to none.
- `--ki-ai-label-border-width`: Border width of the panel and the forced-colors mark.
- `--ki-ai-label-fg`: Text and icon ink of the AI provenance mark.
- `--ki-ai-label-gap`: Gap between the mark and its icon or between provenance metadata items.
- `--ki-ai-label-md-height`: Minimum painted block size of the medium AI mark.
- `--ki-ai-label-md-icon-size`: Sparkles icon size in the medium AI mark.
- `--ki-ai-label-md-padding-inline`: Inline inset of the medium AI mark.
- `--ki-ai-label-popover-backdrop-filter`: Complete filter behind the provenance explanation. Defaults to none.
- `--ki-ai-label-popover-bg`: Raised fill of the provenance explanation.
- `--ki-ai-label-popover-bg-image`: Optional image over the provenance explanation fill. Defaults to none.
- `--ki-ai-label-popover-border`: Hairline color of the explanation panel.
- `--ki-ai-label-popover-fg`: Ink of the provenance explanation and metadata.
- `--ki-ai-label-popover-gap`: Gap between the panel sections and between the panel and trigger.
- `--ki-ai-label-popover-padding`: Inset of the explanation panel.
- `--ki-ai-label-popover-radius`: Corner radius of the explanation panel.
- `--ki-ai-label-popover-shadow`: Elevation of the explanation panel.
- `--ki-ai-label-popover-width`: Preferred inline size of the explanation panel.
- `--ki-ai-label-radius`: Corner radius of the AI provenance mark.
- `--ki-ai-label-sm-height`: Minimum painted block size of the small AI mark.
- `--ki-ai-label-sm-icon-size`: Sparkles icon size in the small AI mark.
- `--ki-ai-label-sm-padding-inline`: Inline inset of the small AI mark.
- `--ki-density-target-min`: The smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1).
- `--ki-focus-ring-color`: Colour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme.
- `--ki-focus-ring-offset`: Gap between a focusable component and its keyboard focus ring.
- `--ki-focus-ring-width`: Thickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once.
- `--ki-typography-family-body`: semantic font family for typography family body.
- `--ki-typography-line-height-caption-2`: semantic dimension for typography line height caption 2.
- `--ki-typography-line-height-para`: semantic dimension for typography line height para.
- `--ki-typography-size-body-1`: semantic dimension for typography size body 1.
- `--ki-typography-size-body-2`: semantic dimension for typography size body 2.
- `--ki-typography-size-caption-2`: semantic dimension for typography size caption 2.
- `--ki-typography-weight-body-semibold`: semantic font weight for typography weight body semibold.
