# KEY visual grammar
Visual language specification for the renderer
This defines how computational state is represented visually without introducing interpretation, bias, or narrative.
Parent: KEY presentation intent, KEY renderer spec
Downstream: KEY stage text
-----
## Purpose
The visual grammar defines how different computational states look, how different outcomes are distinguished, how transitions are shown, and how meaning is conveyed without explanation.
It does not suggest outcomes, rank candidates visually beyond what the data supports, or introduce visual bias toward success or failure.
The visual system must remain epistemically neutral.
-----
## Governing Constraint (Inherited)
The renderer must reveal the computation, not replace it with a story.
-----
## 1. Core Visual Principles
Neutrality: No visual element may imply correctness, incorrectness, importance, or inevitability unless that status is explicitly supported by the computation.
Consistency: The same visual rules apply across lens search and composition search. If the underlying kernel is the same, the visual grammar must be the same.
Legibility over style: Clarity of state distinction is prioritized over aesthetics.
Discrete state transitions: Visual transitions must reflect actual computational transitions. No blending between states. No morphing that implies continuity where none exists.
-----
## 2. Color System
Color encodes state type, not quality or desirability. The color of a candidate says what it is, not how good it is.
### Base Palette
Active candidate (unscored): Light gray / near-white
Hard veto (inadmissible): Sharp red / high contrast
Admissible non-surviving: Desaturated mid-gray, slight decay
Surviving candidate: Steady mid-tone, slightly brighter neutral
Promoted structure: Soft blue
World geometry: Fixed metallic or stone tone
Accidental / contrast candidate: Same as GIE path
### Critical Color Rules
- No color gradient may imply “getting closer to correct”
- No gold, glow, pulse, or reward-like signaling at any point
- Success is not visually celebrated — it is shown
- The promoted structure color (soft blue) must not be applied to candidates during search — it is earned at promotion, not before
-----
## 3. Failure Encoding (Critical Section)
Two failure types must be visually distinct and instantly readable. This is the most important visual distinction in the demo.
### Type 1 — Hard Veto (Inadmissible)
Meaning: candidate violates world constraints before invariance scoring. Structurally incompatible.
Visual treatment:
- Sharp, immediate removal
- Brief high-contrast mark at elimination
- No score shown
- Contributes only to hard-veto counter
Behavior: appears briefly, is eliminated with no persistence
### Type 2 — Admissible but Non-Surviving
Meaning: candidate passed world pre-screen but failed invariance test.
Visual treatment:
- Visible in population distribution
- Score shown below threshold
- Gradual de-emphasis or decay
- Remains part of distribution shape
Behavior: persists temporarily, then fades
### Architectural Meaning
Hard veto = excluded before evaluation
Non-survivor = evaluated and failed
-----
## 4. Population Representation
During search, the population is shown as a distribution, not individuals.
Allowed:
- Density cloud
- Scatter field
- Histogram of scores
- Contour projection
Requirements:
- Show spread
- Show clustering
- Show convergence
- Reflect hard-veto as count reduction
Forbidden:
- Highlighting individuals
- Labeling “best” candidates
- Showing candidate geometry
-----
## 5. Candidate to Structure Transition (Promotion)
Meaning: a candidate earns independent standing.
Visual behavior:
1. Population clears
2. Single structure appears
3. Color shifts to promoted
4. Structure persists
Requirements:
- Discrete transition
- No morphing
- Structure appears as new object
No labels. Only structure.
-----
## 6. Geometry Representation
Raw signal:
- Noisy point clouds
- No connections
- Ambiguous
Candidate transformations:
- Show transformed distributions
- No templates
Promoted structures:
- Clean minimal geometry
- Stable
Critical constraint:
No recognition cues. No semantic labeling.
-----
## 7. Composition Stage (High-Risk Section)
Core requirement: must feel like the same system on a new substrate.
Visual rules:
- Same distribution representation
- Same failure encoding
- Same promotion behavior
- Same secondary panel
Only differences:
- Inputs are structures
- Geometry type differs
Forbidden:
- Redesigning layout
- New metaphors
- Elevated importance
-----
## 8. World Geometry
Appearance:
- Rigid
- Fixed
- Mechanical
Behavior:
- Not visible before evaluation
- No idle animation
- Responds discretely
Critical constraint:
The world is indifferent.
-----
## 9. World Interaction
Before:
World is not visible.
Failure:
- Constraint A: insertion fails
- Constraint B: jam
- Constraint C: no activation
No partial success indicators.
Success:
- Clean insertion
- Rotation
- Trigger fires
- State transition
No celebration.
-----
## 10. Contrast Branch (Critical Constraint)
Visual equality is mandatory.
The accidental candidate must be:
- equally clean
- equally plausible
Forbidden:
- roughness
- dimming
- distortion
- predictive cues
Failure must come from the world, not the renderer.
-----
## 11. Perturbation Test
Layout:
Side-by-side, identical framing.
Behavior:
- Same world
- Same perturbation
- Same visual treatment
Outcome:
Only difference is world response.
-----
## 12. Motion Rules
Allowed:
- Population evolution
- Promotion appearance
- World interaction
Forbidden:
- Decorative animation
- Easing or smoothing
- Anticipation
- Idle loops
Motion reflects computation only.
-----
## 13. Visual Density
Only show what is necessary.
Avoid:
- clutter
- redundancy
- overlapping signals
-----
## 14. Hierarchy of Attention
1. Active computation
2. Structural evidence
3. Stage text
-----
## 15. Visual Integrity Tests
All must pass:
- Reveals computation
- No bias
- No extra information
- Preserves survival vs appearance
- Same rules across stages
- No seams
-----
## 16. One-Line Summary
The visual system must show what happened, not what it means.
-----
End of KEY visual grammar