Check Comprehension
check-comprehensionRun three text-only tests on interface copy or markup after building a screen to catch unclear wording, insider jargon, and complexity before presenting it to users.
Instructions
Run the comprehension check on an interface you just built. Call this after get-review-rules, before you present the screen to the user.
Review rules catch what is broken. This catches what is unclear: copy that makes sense to the people who built the product and to nobody else.
It reads text only: the copy you pass, or the text it extracts from your markup. It does not see what renders: not screenshots, text inside images, or visual hierarchy. A pass is a text result, not visual approval.
Three tests, run on the screen's own words:
Mom test. Would a person outside the team understand this? Flags insider vocabulary, unexplained acronyms and sentences too long to follow.
15 second test. If the screen takes longer than 15 seconds to explain, it is too complex. Flags word count, stacked concepts and competing actions.
Screenshot test. With zero context, can someone say what the screen does? Flags a missing title, actions that hide the outcome ("Continue", "Got it") and icon-only controls.
Pass either the copy or the markup:
check-comprehension({ screen: "Lesson end card", headline: "Lesson complete", body: ["Claim the June badge by collecting more quest points from your daily, friend and weekend quests."], actions: ["Continue"] })
check-comprehension({ screen: "Billing page", code: "…the JSX you wrote…" })
Check every panel, not only the page's own copy. When a sales page, deck or social image shows a mock product screen, dashboard, table or chat panel, call this once per panel with that panel's text. Text inside a mock-up is still copy the reader reads, and long or insider text hides there most often.
For a slide, pass surface: "slide" (a screen named slide, deck or presentation gets it by default) and call once per slide. A slide adds a density test, and it never passes on text: approve it only after you review its rendered screenshot.
Use knownTerms for words your audience genuinely knows, so the check stops flagging them. When the team saved rules, their approved words count as known and their banned words fail a brand test. Fix every critical and serious finding, then call this again on the rewritten copy.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | Supporting copy, one string per visible line or paragraph. | |
| code | No | JSX, TSX or HTML for the screen. Copy is extracted from it when headline/body/actions are omitted. | |
| screen | Yes | What this screen is, e.g. 'lesson end card', 'billing page'. | |
| actions | No | Visible button and link labels, e.g. ['Claim badge', 'Not now']. Search fields, filters and selects are not actions. | |
| context | No | Optional. One sentence on WHY you are calling this and what the user asked for (e.g. 'adding nav icons for the fintech dashboard'). Used only for usage analytics; does not change the result. | |
| surface | No | "slide" adds the slide density test and withholds a pass until a screenshot review. Defaults to "slide" when the screen name says slide, deck or presentation. | |
| headline | No | The screen's title, if you are passing copy rather than markup. | |
| knownTerms | No | Words this audience already knows, so they are not flagged as insider language. |