API description quality review

Purpose

Review the descriptions of component props, events and slots for whether a developer or an agent can use the component correctly from the description and the metadata beside it. The review uses four diagnostic lens assessments per component package and one rating derived from them. It produces no criterion scores, percentages or issue-rate calculations.

Rubric version

The current version is 1.0.

This file owns the lenses, the rating rule, the cluster and package-unique treatment, and the suggested-rewrite standard. API estate index owns the reviewer input. API review reports owns the report contracts. api-quality-rubric.config.json owns the machine-readable values. The content-quality rubric is separate and unchanged.

Scope

• Unit: one component package, @maersk-global/mds-components-core-<slug>. accordion and accordion-item are separate packages with separate ratings.
• Source: the api key of the package’s metadata.json, which holds props, events, slots and types. Nothing else: no component source, demos, page content or other metadata keys.
• Reviewed text: the description of every prop, event and slot. The other fields (type, defaultValue, options, required, category, typescriptType, types) are evidence the descriptions are checked against. They are not reviewed for wording.

Review sequence

1. Read the reviewer input in full. Do not consult earlier reviews, scores or ledgers.
2. Examine each reviewed description through all four lenses.
3. Record each supported problem once as a finding, noting every lens it affects.
4. Assess each lens as Strong, Mixed or Weak from the supported evidence.
5. Return the lens assessments verbatim. Reviewers do not rate quality: the merge step derives it from the lens assessments (Quality rating).

Do not count defects, calculate rates or force a finding under every lens. A lens with no supported problem needs no finding.

Review lenses

Every Mixed or Weak assessment must be supported by at least one substantive finding. Every substantive finding must name at least one Mixed or Weak lens. Explain a problem once even when it affects several lenses.

A substantive finding changes what a developer or agent can understand, decide or do with the API. Optional polish improves wording without a demonstrated effect on those outcomes.

Shared clusters and package-unique descriptions

The estate index groups items by key (kind, name and type):

• A shared cluster is a key used by two or more packages. The estate reviewer reviews each cluster once, across all its wordings, under all four lenses. A finding fans out to every affected package it names, so the same problem is never reported package by package. Consistency can only be judged here.
• A package-unique description belongs to a key used by exactly one package. The package reviewer reviews these under clarity, completeness and accuracy. Consistency does not apply to unique descriptions: they have nothing to be consistent with, so the package report has no consistency assessment. The merge takes a package’s consistency from its clusters alone, and a package in no cluster is Strong for consistency.

A package’s own copy of a shared item is judged in its cluster, not again by the package reviewer.

Quality rating

Per lens, a package’s assessment is the worst of:

1. the package reviewer’s assessment of its unique descriptions (clarity, completeness and accuracy only; consistency comes from clusters); and
2. the worst estate-reviewer assessment (the combined assessment: the estate review is run twice by independent reviewers, and per cluster and lens the merge takes the worse of the two reports) of the flagged clusters the package belongs to, under that lens, capped at Mixed (a Weak cluster counts as Mixed for each package in it), but only when the package meets the threshold gate below.

Threshold gate. The gate is about the package as a whole. A package’s flagged items are its items (props, events and slots) that sit in a cluster the estate reviewer assessed Mixed or Weak under any lens, each item counted once whichever lenses flagged it. If the flagged items are at least 25% of the package’s total items and at least 2 items, the gate is met and the package’s flagged clusters count: each lens takes the worst assessment across the package’s flagged clusters under that lens (capped at Mixed). Below the gate the clusters’ findings are still listed in the estate summary and the estate report, but they lower no lens for that package. The thresholds are clusterRating.minShare (0.25) and clusterRating.minItems (2) in review/config/api-quality-rubric.config.json; the merge script reads them from there. Each package’s gate (distinct flagged items, total, share, met, and the flagged count per lens) is recorded in the estate summary (clusterGate).

Worst means Weak, then Mixed, then Strong. The package reviewer’s assessment always applies in full. Only a package’s own unique descriptions can make a lens Weak for that package. A shared description that is poor estate-wide (for example disabled) lowers each package using it to at most Medium, and only when it is a meaningful part of that package’s API, so one poor shared prop does not rate an otherwise good component down. The estate report still records the cluster as Weak. A package with no unique descriptions takes its assessment from counted clusters alone; a package in no cluster takes it from the package reviewer alone. Estate findings are also kept in the estate report.

The overall rating is then derived from the lens assessments. Apply the first matching condition:

This keeps the consistency rule of the content-quality rubric: High needs every lens Strong, and Medium or Low need at least one Mixed or Weak lens. It differs from the content-quality rubric in one respect: there the rating is a holistic judgement about a core task and is explicitly not derived from the lens assessments. API packages have no core task, and no single reviewer sees the whole package, so the rating is a deterministic function of the merged lens assessments. The merge script, not a reviewer, applies it. qualityReason is generated from the decisive lens and finding IDs.

The rating covers only the reviewed descriptions. It does not prove the component behaves as described.

Finding standard

Every substantive finding must include:

• a quote of the description, or the precise missing statement;
• the affected key and, for a cluster, the wordings and packages involved;
• the likely consequence for a developer or agent;
• the lens or lenses involved;
• a suggested rewrite, or one concrete author question when the intended behaviour is not established by the metadata.

Use neutral report IDs (F1, F2 and so on) with no severity labels. Separate substantive findings from optional polish.

Suggested rewrite standard

A rewrite is for the component source, where the description is fixed upstream. It must:

• apply the content-voice-and-tone skill: British spelling, active voice, lead with the point, one meaning per sentence, no hype;
• describe the item, not the component’s page: state what it does, then the value it accepts or the payload it carries, then the condition that matters;
• agree with the item’s type, options and defaultValue. Name options exactly as the metadata does, and state the default only when the metadata records one;
• for a cluster, give one wording that every affected package can use unchanged, or state which packages need a variant and why. Say which wordings (W1, W2) it replaces;
• never invent behaviour. When the metadata does not establish it, ask one author question instead of writing a rewrite;
• stay short. A description that restates the name adds nothing.

See also