mindit-clarity

name

mindit-clarity

description

Analyze a design or screen for clarity — whether a stranger can read the intent in five seconds. Use this whenever the user asks about hierarchy, what stands out, what gets noticed first, whether a CTA is obvious, whether labels make sense, why users miss something on a screen, or why a layout feels cluttered or confusing. Also trigger when the user pastes a screenshot or URL and asks "what's wrong with this" or "is this clear" without specifying which force. Produces a structured decision artifact with score, criteria, and anti-pattern matches.

mindit-clarity

The first of the eight forces. Run this when the question is "can a stranger read the intent."

The force

Clarity asks one question: drop a stranger in front of this design for five seconds, what do they understand? Not what the team meant to say. What the design actually communicates in the absence of context, training, or patience.

Clarity is not minimalism. A dense Bloomberg terminal can be perfectly clear to its trader audience. A pretty marketing page can be totally opaque about what the product does. Clarity is the match between what the design wants to convey and what the design actually conveys to the person seeing it for the first time.

When to run this

Run this skill when the user:

• Pastes a screenshot, mockup, or URL and asks for a review without specifying which force.
• Says the words "hierarchy," "stands out," "noticed," "obvious," "cluttered," "confusing," "what's the most important thing," or "what does this say."
• Is reviewing a CTA, a landing page hero, a dashboard, an error state, or any surface where the user has under ten seconds to form an impression.
• Asks "why are users not clicking the primary action."

How to analyze

Walk through these steps in order. Do not skip ahead.

1. Capture the subject. Note what is being analyzed: screen, flow, feature, component. If the user provided a URL or file path, record it. If they only described the design, ask once for a screenshot or detailed description before scoring.

2. The five-second test, in writing. Without looking at the rubric, write three sentences answering: "If a stranger looked at this for five seconds and then it disappeared, what would they think this is, what would they think is the most important thing on the screen, and what would they think they should do next?" Be honest. If the answer is "I am not sure," that is data.

3. Score each criterion below. For each of the six criteria, give a score 0–100 and a one-sentence reason. Do not round to multiples of 10 unless you genuinely cannot distinguish.

4. Check the anti-patterns. Open anti-patterns.yaml (sibling to this SKILL.md). For each pattern, decide if it applies. If it does, add a finding with the anti-pattern slug and a fix.

5. Compute the score. Weighted sum of criteria, rounded to nearest integer. Report it as one number out of 100.

6. Write the artifact. Two files. See "Output format" below.

Rubric

Criterion	Weight	What you are scoring
Hierarchy	0.25	Is the single most important element on the screen the most visually dominant? Or does the eye get pulled to something secondary?
Labeling	0.20	Do labels say what they mean? Is "Submit" the right verb? Is "Settings" hiding three different concepts under one label?
Affordance	0.20	Does interactive content look interactive? Does static content look static? No mystery-meat buttons, no clickable-looking text that does nothing.
Density	0.15	Is there enough room for the eye to rest, given the audience? An overpacked dashboard for casual users fails. The same density for power users may be correct.
Distinguishability	0.10	Can adjacent items be told apart at a glance? Two buttons of the same weight, three identical card variants, similar but not-identical icons all fail this.
First-glance test	0.10	What you wrote in step 2. If a stranger gets it, score high. If they would mistake the purpose entirely, score low.

Anti-patterns

See anti-patterns.yaml for the full registry. Match by symptom, not by name.

Brief list: mystery-meat-navigation, low-contrast-cta, buried-primary-action, competing-hierarchies, icon-only-actions, inflated-density, label-that-lies, two-cta-tie.

Output format

Produce two files. Both go in .mindit/decisions/ of the project the user is working on. If that directory does not exist, create it.

File 1: Markdown

Path: .mindit/decisions/clarity-<yyyymmdd>-<slug>.md

Template:

# Clarity review: <subject name>

**Score:** <0–100>
**Date:** <ISO date>
**Subject:** <what was analyzed>

## Five-second test
<three sentences from step 2>

## Criteria
- Hierarchy <score>/100 — <one sentence>
- Labeling <score>/100 — <one sentence>
- Affordance <score>/100 — <one sentence>
- Density <score>/100 — <one sentence>
- Distinguishability <score>/100 — <one sentence>
- First-glance test <score>/100 — <one sentence>

## Findings
- **[severity]** <anti-pattern if matched>: <summary>. Fix: <concrete next step>.

## Open questions
- <unmade decision the design assumes>

File 2: JSON

Path: .mindit/decisions/clarity-<yyyymmdd>-<slug>.json

Conform to schemas/decision.schema.json at the package root. Required fields: id, skill ("mindit-clarity"), subject, force ("clarity"), score, criteria (array of six), findings, open_questions, created_at, version ("1.0.0").

Example

Input from user: "Review the hero on https://example.com/pricing for clarity."

Five-second test: "It looks like a marketing page for a SaaS. The most visually dominant thing is a stock photo of a smiling person, not the pricing. A stranger would not know what tier to pick or even that pricing is the topic of the page."

Sample scores: Hierarchy 32, Labeling 71, Affordance 60, Density 80, Distinguishability 55, First-glance 25. Weighted score: 51.

Sample finding: { severity: "high", anti_pattern: "buried-primary-action", summary: "Pricing tiers sit below the fold; hero is a stock photo. Eye lands on the photo, not the offer.", fix: "Move the three-tier comparison above the fold; demote the stock photo to background or remove it." }

What this skill does NOT do

• It does not evaluate whether the design should be clear (sometimes intentional opacity is the point, e.g. a puzzle game).
• It does not run the other seven forces. If the user wants a full review, run mindit-audit instead.
• It does not propose a redesign. It produces findings and fixes, one decision at a time.
• It does not work without a subject. If the user has not shown you the design, ask for it once before scoring.