Malevich

AI-Things / Prompts / Prompt/

Document component

Produce a `<name>.docs.md` for a Malevich component — the authoritative file the website renders, the MCP server returns, and the agents.md generator reads — matching the frontmatter and section order of the existing component docs.

documentation · code → docs-page · updated 2026-05-21

Use case: When a new component's CSS (and optional init function) exists and needs its authoritative docs.md written.

When to use

A component's .css (and .ts, if it has runtime) exists, and you need its <name>.docs.md — the single source of truth that the docs portal renders, the MCP server returns, and the <name>.agents.md generator reads. Use this to generate that file in the house style, matching button.docs.md exactly.

This produces documentation for an existing component. To author the component itself, use the malevich-new-component skill first. Never hand-write <name>.agents.md — it is generated from this docs.md plus the applicability matrix.

The prompt

Fill in the placeholders and send the text below.

You are working in the Malevich design system. Before answering, read:

  • llm-wiki/architecture.md (the docs.md format section)
  • An existing reference: packages/components/src/elements/interactive/button/button.docs.md
  • The component's row in packages/components/modifiers/applicability.json

I need a docs.md for the following component.

Component name (kebab-case): {{name}} Layer: {{layer}} (foundations / elements / blocks / sections / overlays)

Component CSS:

{{css}}

Component runtime (if any):

{{ts}}

Write {{name}}.docs.md matching the existing component docs:

Frontmatter (exactly these keys):

---
component: {{name}}
layer: {{layer}}
status: stable
tier-3-tokens: <count of component-specific tokens the CSS consumes>
last-updated: "2026-05-21"
---

Body sections, in this order:

  1. # {{name}} title + a one-paragraph description of the intent (what it's for, not what it looks like).
  2. ## When to use — one paragraph; include when NOT to use it.
  3. ## Variants — a table, one row per .-variant, with the class and the use.
  4. ## States — a table; or N/A — reason if static.
  5. ## Sizes / rhythm — the supported data-rhythm values or -s/-l variants; or N/A — single size.
  6. ## Modifiers — the data-{category} categories and values this component accepts, read straight from its applicability row.
  7. ## Anatomy — annotated HTML showing the element classes.
  8. ## Tokens used — the semantic tokens first, then the tier-3 (component-specific) tokens, read straight from the CSS.
  9. ## Accessibility — what the component guarantees and what the application must provide.
  10. ## Edge cases — short FAQ-style entries.
  11. ## Do — concrete recommendations.
  12. ## Don't — concrete anti-patterns.
  13. ## Related — links to nearby components.

Rules:

  • Derive every "Tokens used" entry from the actual CSS — don't guess.
  • Derive the "Modifiers" section from the applicability row — don't invent categories the component doesn't accept.
  • Examples use standard HTML + classes; no <m-*> tags (ADR-0004). Icons use the <i class="icon" data-icon="name"> pack contract.
  • Follow the existing files' habit of a one-line N/A — reason for inapplicable sections rather than dropping the heading.
  • Match the editorial voice of button.docs.md: precise, declarative, no marketing words.

Variables

Placeholder What to fill in
{{name}} The component's kebab-case name (empty-state).
{{layer}} foundations, elements, blocks, sections, or overlays.
{{css}} The component's .css file contents.
{{ts}} The component's .ts file, or "none — pure CSS."

Example input

Name: badge. Layer: elements. CSS defines .badge, .badge.-info, .badge.-success, .badge.-danger, consuming --color-info, --color-success, --color-danger, --color-ink-inverse, --font-overline-*, --radius-tag, --space-inset-element-s. Runtime: none. Applicability row: surface: ["flat"], everything else empty.

Example output (abridged)

---
component: badge
layer: elements
status: stable
tier-3-tokens: 0
last-updated: "2026-05-21"
---

# Badge

A small inline label that marks status or category on an adjacent
element. Static, single size — when you need an interactive control,
reach for a Button or a Tag instead.

## When to use

Use a badge to annotate something else: a "new" marker on a nav link, a
status pill on a row, a count on a tab. Don't use it for standalone
messages — that's an Alert.

## Variants

| Variant | Class            | Use for                        |
|---------|------------------|--------------------------------|
| Info    | `.badge.-info`   | Neutral status, "beta", counts |
| Success | `.badge.-success`| Positive status, "active"      |
| Danger  | `.badge.-danger` | Negative status, "failed"      |

## States

N/A — Badge is static.

## Sizes / rhythm

N/A — single size; Badge does not accept the rhythm modifier.

## Modifiers

| Category | Values | Notes |
|----------|--------|-------|
| surface  | flat   | The only modifier Badge accepts. |

All other categories are empty in Badge's applicability row.

## Anatomy

​```html
<span class="badge -info">Beta</span>
​```

## Tokens used

- `--color-info`, `--color-success`, `--color-danger`,
  `--color-ink-inverse`
- `--font-overline-*` (five properties), `--radius-tag`,
  `--space-inset-element-s`

Tier 3: none.

## Accessibility

- The badge is decorative annotation; the status meaning must also be in
  text or an `aria-label` on its host. Never rely on color alone.

## Edge cases

- Long text wraps; we don't truncate.

## Do

- Pair the badge with the thing it labels.

## Don't

- Don't use a badge as a button. It isn't interactive.

## Related

- `Tag` — for removable, interactive labels
- `Alert` — for standalone status messages

Pairs with