Imported from amberhoward78-creator/visual-literacy (SKILL.md). Install upstream with npx skills add amberhoward78-creator/visual-literacy. Copyright stays with the author (MIT).

Visual Literacy: Teaching AI to See Like a Designer

AI doesn't just need instructions. It needs teachable models of human expertise.

What This Is

Visual Literacy is a reasoning framework — not a prompt template, not a formatting guide, not a CSS utility. It teaches AI to make visual design decisions by modelling how humans perceive information.

The problem it solves: AI can generate a layout. It cannot tell you if the layout works. It does not notice flat hierarchy, broken rhythm, competing emphasis, or cognitive overload. This framework gives it those perceptions as explicit reasoning principles.

This Augments Human Judgement. It Does Not Replace It.

Visual Literacy teaches AI to reason about design so that humans can make better decisions faster — not so that AI makes decisions alone.

The goal is a collaboration:

• AI provides structured analysis, perceptual reasoning, and diagnostic frameworks
• Humans provide intent, taste, context, audience knowledge, and final judgment

An AI that can score a design 0-5 across eight dimensions is useful. An AI that overrides a designer's informed choice because it scored lower on a rubric is not.

Use this framework to sharpen your thinking, not to outsource it.

The Premise

AI does not possess visual intuition. It cannot instantly recognize when a page feels balanced, crowded, unfinished, confusing, or elegant. This intuition must be translated into explicit reasoning principles.

Teaching AI visual literacy means teaching it not simply how to format information, but how humans perceive information.

The shift is from formatting to perception.

The Core Principle

Every visual decision should be explainable in terms of how a human will perceive and process the information.

If you cannot explain why a visual choice helps a human understand, it is decoration. If you can explain it in terms of cognition, it is design.

Quick Start

1. Copy the skill to your project

# Clone the repository
git clone https://github.com/amberhoward78-creator/visual-literacy.git

# Copy to your project's skill directory
cp -r visual-literacy/.opencode/skills/visual-literacy ./your-project/.opencode/skills/

2. Tell your AI to use it

In your prompt or system message:

Use the visual-literacy skill to evaluate and reason about the design of this document.

3. See the difference

Before (formatting instruction):

"Make the headings bigger and add more white space."

After (perceptual reasoning):

"The visual hierarchy is insufficient — the reader cannot scan and identify the information structure. The spacing between unrelated sections does not differentiate them from spacing within sections. Increase heading-body contrast. Use inter-section spacing at 2-3x intra-section spacing to signal conceptual distance."

When to Use This Skill

Use this skill when:

• Creating any document, report, or presentation
• Designing interfaces or layouts
• Evaluating or critiquing existing designs
• Making decisions about spacing, hierarchy, grouping, or emphasis
• Translating a formatting instruction into a perceptual decision
• Debugging why something "feels wrong" but you cannot name why
• Running a design review or UX audit

The Four Modes

Three modes reason about design. A fourth verifies it. Design, Critique, and Translate are all reasoning activities — they produce a hypothesis about what should be true. Only rendering and looking produces evidence of what is true.

Mode 1: Design (Proactive)

When creating something new, reason through visual decisions using the heuristics before producing output. Do not wait to be asked why you chose a particular layout.

How to use: Ask the AI to walk through its visual reasoning before generating the design:

Before designing this page, walk through your perceptual reasoning:
1. What is the information structure?
2. How will a human perceive this?
3. What cognitive load am I placing on the reader?
4. Does the visual structure communicate intention?
Then generate the design based on that reasoning.

Mode 2: Critique (Evaluative)

When reviewing existing work, diagnose problems using the perceptual framework. Name what is wrong, why it is wrong, and what cognitive principle is being violated.

How to use: Provide a screenshot, code, or description and ask for a structured critique:

Using the visual-literacy evaluation rubric, critique this design.
Score each dimension 0-5, identify severity levels, and provide
specific fix recommendations with perceptual rationale.

Mode 4: Verify (Mandatory — Never Optional)

Before any artifact is called done, its rendered result must be inspected.

No design reasoning is complete until the rendered artifact has been inspected. Producing a layout is a hypothesis. Rendering and looking at it is the test.

You may not report an artifact as finished based on the source you wrote. Render it. View it. Check it against the invariants. Then report.

If the artifact cannot be rendered in this environment, say so explicitly and mark the work unverified. Do not describe unverified work as complete.

This mode runs after Design, Critique, or Translate. It is not a fourth way to think about design — it is the check that the thinking produced something real.

How to use:

Before calling this design done:
1. Render the artifact to an image (or open it in the target application).
2. Look at it. Compare against intent.
3. Run the mechanical invariants (see references/verification-protocol.md).
4. Check absence against the source manifest.
5. If you fixed anything, re-render and re-inspect the whole artifact.

Follow the full protocol in references/verification-protocol.md.

When given a formatting instruction, translate it into the perceptual intent behind it. Then execute the perceptual goal, not the literal instruction.

How to use: Give a formatting instruction and ask for the translation:

I want to "add more white space to this page." Using the
formatting-to-perception translation guide, explain the perceptual
intent behind this instruction and then execute it correctly.

Perceptual Reasoning Process

Before making any visual decision, run through this sequence:

1. What is the information structure?

• What is the primary content?
• What is the hierarchy of importance?
• What groups together logically?
• What must be read in sequence vs. what can be scanned?

2. How will a human perceive this?

• Where will the eye go first? Is that the right place?
• Can the reader scan and find what they need in under 5 seconds?
• Are related concepts visually connected?
• Is there a clear path through the content?

3. What cognitive load am I placing on the reader?

• How many decisions must the reader make at each point?
• Am I asking them to hold information in working memory?
• Can they recover their place easily if interrupted?
• Is the density appropriate for the content type?

4. Does the visual structure communicate intention?

• Does every element earn its space?
• Does spacing communicate relationship or accident?
• Do patterns repeat with purpose or inconsistency?
• Does the page feel complete, not abandoned?

5. What does it actually look like?

• Render it. Look at it. Compare against intent.
• What surprised you? What is different from what you imagined?
• Run the invariants. Check what is missing, not just what is present.
• A fix is a change: re-render and re-look after every fix. (See references/verification-protocol.md.)

The Heuristic Framework

Nine categories, 27 heuristics, one priority system.

Consult references/design-heuristics.md for the full catalog with perceptual rationale, violations, and diagnosis methods.

Priority order when heuristics conflict:

1. Hierarchy — the reader must know what is most important
2. Grouping — the reader must know what belongs together
3. Flow — the reader must know where to go next
4. Emphasis — the reader must know what matters most
5. Rhythm — the reader must be able to form expectations
6. Balance — the layout must feel stable
7. Integrity — a document that lies is worse than one that is merely cluttered
8. Completion — the page must feel resolved
9. Restraint — every element must earn its place

Perceptual Principles

The cognitive science foundation. Not design rules — facts about how human brains process visual information.

Consult references/perceptual-principles.md for the full foundation.

Evaluation Rubric

Score any design 0-5 across 9 dimensions. Total: /45.

The rubric is scored from the rendered artifact, never from a description, source file, or intent. If you have not viewed it, you cannot score it. A mechanical invariant failure caps the total at 25/45 regardless of perceptual quality — a beautiful document with clipped text is not a 34.

Consult references/evaluation-rubric.md for scoring guidance, severity classification (P0-P3), and fix recommendations.

Resolving Conflicts

When heuristics pull in opposite directions:

Consult references/heuristic-conflicts.md for the full resolution framework.

Translating Formatting to Perception

Consult references/formatting-to-perception.md for the full translation dictionary.

The Architecture

This skill follows a six-layer reasoning architecture:

Mental Model          → How experts perceive this domain
    ↓
Perceptual Principles → The cognitive science that explains why
    ↓
Heuristics            → Practical rules of thumb
    ↓
Conflict Resolution   → What to do when rules contradict
    ↓
Evaluation Rubric     → Structured scoring for quality
    ↓
Translation Layer     → Convert naive instructions to expert reasoning

This architecture is domain-agnostic. Visual literacy is the first application. The same six layers could teach AI expert cognition in architecture, medicine, education, leadership, or any field where tacit expertise resists articulation.

Output Requirements

When using this skill, always:

1. Name the perceptual principle behind every visual decision
2. Explain the cognitive effect of layout choices
3. Diagnose problems in terms of violated principles, not aesthetic preferences
4. Score designs using the evaluation rubric when critiquing
5. Translate instructions from formatting to perception when asked to implement feedback
6. Verify the rendered artifact before reporting completion — render it, look at it, and never describe unverified work as complete

Anti-Patterns

Never:

• Choose a layout because it "looks professional" without explaining why
• Add decorative elements that do not serve comprehension
• Treat spacing, typography, or color as arbitrary aesthetic choices
• Skip the reasoning step because "it just feels right"
• Apply heuristics mechanically without considering the specific content
• Declare a document, diagram, or layout correct without viewing the rendered output
• Trust a source-level scan (colours, fonts, structure) as evidence of visual correctness
• Apply a fix without re-verifying the whole artifact, including the class of defect the fix could introduce
• Review an artifact in a single state when it has several
• Report "no issues found" from a rubric pass without a final open-ended look

The Litmus Test

After producing any visual design, ask:

"Can I explain every spacing decision, every type choice, every grouping, and every emphasis in terms of how a human will perceive and process this information?"

If yes, the design is reasoned. If no, it is decoration.