Text-based visual components are a semantic language, not decoration.
The primary goal is to make meaning visible inside prose without breaking the reading flow or reducing complex distinctions to generic colored boxes.
The canonical model is:
BLOCK TYPE
→ editorial / structural role
COLOR
→ semantic / epistemic status
EMOJI
→ concept identity
EMPHASIS
→ force / importance / state
GROUPING
→ context / perspective / section
A component must remain understandable even when color, border styling, or emoji is ignored.
This skill applies to text-oriented visual components such as:
It does not replace mermaid-visual-standard.
Use mermaid-visual-standard when meaning depends primarily on:
Use this skill when meaning can remain primarily textual but benefits from visual semantic emphasis.
Every visual text component must represent the actual role of the content.
Do not choose a component because it is visually attractive.
Examples:
Evidence
≠ interesting fact
Warning
≠ important paragraph
Insight
≠ summary
Claim
≠ evidence
Question
≠ uncertainty
Takeaway
≠ understanding
A component label must preserve the conceptual distinction present in the source.
The block type answers:
What kind of communicative act is this?
Recommended structural families:
| Structural role | Preferred component | Typical content |
|---|---|---|
| framing | Context / Background | environment, source framing, provenance |
| orientation | Intent / Goal | objective, direction, purpose |
| observation | Observation | reported or measured state |
| assertion | Claim | statement requiring support |
| support | Evidence | measurement, corroboration, source-backed support |
| provisional explanation | Hypothesis | possible mechanism or explanation |
| unresolved state | Unknown / Open Question | missing information, unresolved inquiry |
| conflict | Contradiction / Tension | incompatible evidence or interpretations |
| synthesis | Understanding / Insight | integrated meaning or accepted synthesis |
| explicit output | Projection / Takeaway | consequence, artifact, explicit conclusion |
| operation | Action / Try This | next step, exercise, practical action |
| caution | Warning | risk, caveat, misuse, failure mode |
| illustration | Example | concrete instance |
| terminology | Definition | term and meaning |
| source orientation | Reference | external or internal source |
| conceptual bridge | Connection | relation to another concept |
| completion | Checkpoint / Result | accepted state, completion criterion |
Do not create one unique component for every concept.
Reuse the same component type whenever the communicative role is the same.
This skill shares the semantic vocabulary of mermaid-visual-standard.
Canonical semantic palette:
context fill #D9EAF7 stroke #7AA6C2
observation fill #DDF3E8 stroke #78AA91
claim fill #FFF1BF stroke #C8A84E
evidence fill #E8DDF5 stroke #A68BC4
hypothesis fill #F8DFC4 stroke #C9986D
uncertainty fill #F6D6DD stroke #BF7C89
contradiction fill #F4CFC8 stroke #B96B5D
understanding fill #DCEFD6 stroke #86A878
projection fill #ECEBE8 stroke #9C9992
orchestration fill #DDE3F4 stroke #8998C8
Recommended meanings:
context — source, framing, provenance, environment;observation — observed or reported state;claim — assertion requiring support;evidence — support, measurement, corroboration;hypothesis — provisional explanation or mechanism;uncertainty — unresolved, incomplete, unknown;contradiction — conflict or incompatible support;understanding — synthesized accepted understanding;projection — explicit representation or action derived from understanding;orchestration — coordination, capability, system-level control.Color communicates role, not decoration.
Do not recolor a block merely to create visual variety.
Recommended vocabulary:
Use at most one functional emoji in a component heading unless there is a strong semantic reason otherwise.
The same concept should keep the same emoji across one document or product family.
Emoji is functional, not decorative.
Do not add emoji to:
Use visual emphasis conservatively.
Recommended levels:
neutral
→ ordinary explanatory component
accented
→ relevant semantic distinction
strong
→ warning, contradiction, accepted result, explicit decision
critical
→ only for genuine risk, invalid state, or severe warning
Do not use maximum emphasis simply because a paragraph is important.
Importance and epistemic status are different dimensions.
Group multiple blocks only when they share a real:
Do not use container-within-container layouts purely for decoration.
Use for framing, provenance, environment, assumptions, or surrounding conditions.
Preferred identity:
📚 CONTEXT
Do not use Context as a generic introduction box.
Use when stating purpose, direction, desired outcome, or explicit orientation.
Preferred identity:
🧭 INTENT
Intent is not the same as a task description.
Use for what was seen, measured, reported, or externally observed.
Preferred identity:
👁 OBSERVATION
Observation is not automatically Evidence.
Use for an assertion that may require support or validation.
Preferred identity:
⚠️ CLAIM
A claim should not visually imply that it is already accepted.
Use for data, corroboration, source-backed support, measurements, or observations that actually bear on a claim.
Preferred identity:
🔎 EVIDENCE
A source is not evidence merely because it contains a relevant sentence.
Use for provisional explanations or mechanisms under inquiry.
Preferred identity:
🧩 HYPOTHESIS
Do not render a hypothesis as accepted understanding.
Use for genuine unresolved information.
Preferred identity:
❓ UNKNOWN
An unknown is not an error state.
Use when inquiry remains active and can be expressed as a question.
Preferred identity:
❓ OPEN QUESTION
An open question may arise from an unknown but is not identical to it.
Use when support, observations, sources, or interpretations conflict.
Preferred identity:
⚠️ CONTRADICTION
A contradiction is not automatically falsification.
Use for an experiment, check, verification, or acceptance step.
Preferred identity:
🧪 VALIDATION
Operational success is not epistemic acceptance.
Use for synthesized meaning that integrates relevant context, evidence, constraints, and inquiry.
Preferred identity:
🧠 UNDERSTANDING
Do not use Understanding as a visually upgraded Summary.
Use when understanding is transformed into an explicit artifact, representation, decision, specification, or communicated form.
Preferred identity:
📄 PROJECTION
Use for an actual next step or operation.
Preferred identity:
▶️ ACTION
Use when a state has actually met defined acceptance conditions.
Preferred identity:
✅ CHECKPOINT
Do not use success styling merely because a section is complete.
Editorial components are useful, but they must not be confused with epistemic roles.
Use for a concept the reader should retain.
Preferred identity:
💡 KEY IDEA
A Key Idea may contain a claim, but does not itself mean the claim is validated.
Use for a compact conceptual synthesis that helps the reader see a pattern, connection, implication, or deeper interpretation.
Preferred identity:
🧠 INSIGHT
When the content represents accepted epistemic synthesis, prefer Understanding.
Use for real risk, caveat, misuse, security concern, data-loss risk, misleading interpretation, or important constraint.
Preferred identity:
⚠️ WARNING
Do not use Warning for ordinary advice.
Use for secondary information that helps but is not central.
Preferred identity:
📝 NOTE
Avoid excessive notes.
Use for a concrete illustration of a concept.
Preferred identity:
📝 EXAMPLE
Examples do not prove a general claim by themselves.
Use for explicit terminology.
Preferred identity:
📖 DEFINITION
Keep definitions concise.
Use to orient the reader toward a source, document, standard, post, section, book, paper, or repository.
Preferred identity:
📚 REFERENCE
A reference is not evidence by default.
Use to expose a meaningful relation to another concept, post, system, pattern, or part of the publication.
Preferred identity:
🔗 CONNECTION
Use for an exercise, experiment, prompt, implementation suggestion, or practical reader action.
Preferred identity:
▶️ TRY THIS
Use for the concise explicit point the reader should carry forward.
Preferred identity:
📄 TAKEAWAY
A Takeaway summarizes projected meaning. It is not necessarily Understanding.
Use only for actual quotations.
Preferred identity:
“ … ”
— Source
Do not reformat paraphrases as quotes.
Use for internal conceptual navigation.
Preferred identity:
🔗 RELATED CONCEPT
Prefer direct links when the publication format supports them.
Whenever text visual components represent knowledge, preserve these distinctions:
Citation ≠ Source
Source ≠ Evidence
Evidence ≠ Claim
Claim ≠ Understanding
Operational success ≠ Epistemic acceptance
Retrieval ≠ Semantic extraction
Generated citation span ≠ Source passage
Additional rules:
Create a component only when it materially improves at least one of:
Do not create a component when ordinary prose is clearer.
Prefer:
If a page becomes a sequence of boxes, the visual hierarchy has failed.
Prefer:
Avoid:
The semantic component is independent of the rendering technology.
Canonical pipeline:
Semantic role
→ component declaration
→ publication adapter
→ visual rendering
Example:
Understanding
→ semantic component
→ Jekyll / HTML / EPUB / Markdown adapter
→ rendered block
Do not encode publication-specific visual hacks into semantic source unless the target platform requires it.
Markdown must have a readable fallback.
Generic fallback:
> **🧠 Insight**
>
> Understanding emerges from the relation between evidence, context, and inquiry.
Evidence:
> **🔎 Evidence**
>
> The benchmark shows a measurable change under the observed conditions.
Open question:
> **❓ Open Question**
>
> What remains unknown after this evidence?
Warning:
> **⚠️ Warning**
>
> Do not treat successful tool execution as epistemic validation.
GitHub-compatible Markdown may use this form when appropriate:
> [!NOTE]
> Supporting information.
> [!TIP]
> Practical suggestion.
> [!IMPORTANT]
> Important constraint.
> [!WARNING]
> Significant risk.
> [!CAUTION]
> High-risk consequence.
Do not force all semantic components into GitHub’s limited native taxonomy. Use a plain blockquote with explicit semantic heading when the native alert type would change the meaning.
When a FACTORY controls preprocessing, prefer a semantic source form such as:
:::context
Source framing or environment.
:::
:::intent
What this section is trying to achieve.
:::
:::evidence
Support for a specific claim.
:::
:::unknown
What remains unresolved.
:::
:::understanding
Synthesized accepted meaning.
:::
Alternative compact syntax:
[context]
...
[/context]
[evidence]
...
[/evidence]
[understanding]
...
[/understanding]
The exact source syntax is implementation-specific.
The semantic names are canonical.
Prefer semantic HTML.
Example:
<aside class="semantic-block semantic-block--understanding"
data-semantic-role="understanding">
<header class="semantic-block__title">
<span aria-hidden="true">🧠</span>
<span>Understanding</span>
</header>
<div class="semantic-block__body">
<p>Meaning emerges through synthesis, not repetition.</p>
</div>
</aside>
Recommended principles:
aside for supplementary semantic blocks;section when the block is a true document section;data-* attributes;aria-hidden when the adjacent text names the role;Publication adapters may map the canonical palette to CSS variables.
Example:
:root {
--semantic-context-bg: #D9EAF7;
--semantic-context-border: #7AA6C2;
--semantic-observation-bg: #DDF3E8;
--semantic-observation-border: #78AA91;
--semantic-claim-bg: #FFF1BF;
--semantic-claim-border: #C8A84E;
--semantic-evidence-bg: #E8DDF5;
--semantic-evidence-border: #A68BC4;
--semantic-hypothesis-bg: #F8DFC4;
--semantic-hypothesis-border: #C9986D;
--semantic-uncertainty-bg: #F6D6DD;
--semantic-uncertainty-border: #BF7C89;
--semantic-contradiction-bg: #F4CFC8;
--semantic-contradiction-border: #B96B5D;
--semantic-understanding-bg: #DCEFD6;
--semantic-understanding-border: #86A878;
--semantic-projection-bg: #ECEBE8;
--semantic-projection-border: #9C9992;
--semantic-orchestration-bg: #DDE3F4;
--semantic-orchestration-border: #8998C8;
}
Example base component:
.semantic-block {
margin: 1.4rem 0;
padding: 1rem 1.1rem;
border: 1px solid;
border-left-width: 4px;
border-radius: 0.65rem;
}
.semantic-block__title {
display: flex;
align-items: center;
gap: 0.45rem;
margin-bottom: 0.55rem;
font-weight: 700;
}
.semantic-block__body > :first-child {
margin-top: 0;
}
.semantic-block__body > :last-child {
margin-bottom: 0;
}
Use CSS as presentation.
Do not let CSS invent semantic meaning that is absent from the source.
For Jekyll-based FACTORIES, prefer a semantic include or plugin abstraction.
Example source:
{% include semantic-block.html
type="understanding"
title="Understanding"
content="Meaning emerges through synthesis, not repetition."
%}
Or a Markdown extension transformed during build:
:::understanding
Meaning emerges through synthesis, not repetition.
:::
The build layer should map semantic role to:
Do not copy inline styles into every post.
README files often have limited styling.
Priority order:
Do not sacrifice semantic precision merely to obtain a colored GitHub alert.
In EPUB/PDF/book layouts:
A semantic block must remain understandable:
Required practices:
When applying this skill to existing content:
Rebuild only when semantic clarity or reading flow requires it.
Before:
The important point is that intent changes the unit of organization.
After:
> **🧠 Insight**
>
> Intent changes the unit of organization.
Use only if this is genuinely a conceptual synthesis.
Before:
The benchmark recorded lower latency in all three measured scenarios.
After:
> **🔎 Evidence**
>
> The benchmark recorded lower latency in all three measured scenarios.
Use only when the measurement actually supports a relevant claim.
Before:
Do not assume a successful API call means the returned information is correct.
After:
> **⚠️ Warning**
>
> Do not assume a successful API call means the returned information is correct.
> **❓ Unknown**
>
> The available evidence does not yet establish whether the behavior generalizes
> beyond the observed environment.
> **🧠 Understanding**
>
> Retrieval and understanding are separate stages: obtaining a passage does not
> establish that its meaning was extracted correctly.
Ask these questions in order:
Is this ordinary explanation?
→ keep prose
Is it framing?
→ Context
Is it a purpose or orientation?
→ Intent
Is it something observed?
→ Observation
Is it an assertion needing support?
→ Claim
Does it actually support/challenge a claim?
→ Evidence
Is it a provisional mechanism?
→ Hypothesis
Is something genuinely unresolved?
→ Unknown / Open Question
Is there a conflict?
→ Contradiction
Is this a verification step?
→ Validation
Is this synthesized meaning?
→ Understanding / Insight
Is this an explicit consequence or concise output?
→ Projection / Takeaway
Is it a practical next step?
→ Action / Try This
Is there a real risk?
→ Warning
Is it only illustrating?
→ Example
Is it defining terminology?
→ Definition
Is it pointing elsewhere?
→ Reference / Connection
The two standards share semantics but use different visual channels.
MERMAID
shape
color
emoji
edge
subgraph
TEXT VISUALS
block type
color
emoji
emphasis
grouping
Canonical correspondence:
| Shared semantic dimension | Mermaid | Text visual |
|---|---|---|
| structural role | node shape / native construct | component type |
| semantic status | node/element color | block color |
| concept identity | emoji in label | emoji in heading |
| relation force | edge style / label | wording, reference, emphasis |
| context | subgraph / grouping | section / grouped components |
| reading order | graph topology | document flow |
Do not force text into Mermaid when prose is clearer.
Do not force relations into prose when a diagram is clearer.
Across one document or product family:
Consistency means semantic consistency, not identical box sizes.
Before accepting a text visual component, verify:
Preserve semantic meaning, not visual novelty.
Block type expresses what kind of communicative act it is.
Color expresses semantic or epistemic status.
Emoji identifies the concept.
Emphasis expresses force, not truth.
Grouping expresses context or perspective.
Ordinary prose remains the default.
A source is not evidence merely because it is cited.
A visually stronger block is not epistemically stronger.
Use the smallest visual vocabulary that makes meaning clearer.