Skip to main contentSkip to footer
Browse principles
Principle 6visibility

Expose meaningful operational state, not internal complexity

Present the state of the system in language and structures that are relevant to the user, rather than exposing low-level internals that do not support action or understanding.

Key Facts

Cluster
visibility
Primary risk
The system either obscures important status or overwhelms the user with irrelevant mechanics.
Related examples
6 library examples
Doctrine library
Internal doctrine reference
Why does this principle matter?

Users need to understand operational truth, but not necessarily implementation detail. Good design translates machine activity into meaningful human-facing status.

Use states such as active, queued, blocked, awaiting approval, complete, or failed.
Communicate dependencies when they affect progress or outcome.
Describe activity in user-relevant terms.
Reserve deeper technical detail for specialist or diagnostic views where appropriate.
What failure does this principle prevent?

The system either obscures important status or overwhelms the user with irrelevant mechanics.

AI as interface embellishment: A conventional product is given a text input and labelled intelligent, without any meaningful change in operational model.
Simulated autonomy: The system appears autonomous in language or presentation but cannot act with meaningful independence.
Opaque execution: Work occurs in the background without adequate status, accountability, or recoverability.
How do I apply this in practice?

The implementation library contains inspectable, runnable examples that show this principle applied in real agentic product code. Study the source paths, library choices, and runtime assumptions — not just the pattern name.

Implementation example

Get Single Page

Runnable example (intermediate) for script using docling, openai. (script · intermediate)

Inspect implementation

Implementation example

Web Search

Runnable example (intermediate) for script using docling, openai. (script · intermediate)

Inspect implementation

Implementation example

Search Handbook

Runnable example (intermediate) for script using docling, openai. (script · intermediate)

Inspect implementation

Related examples