@echelon-foundry/visual-engineering 1.0.0 → 1.0.1

package/payload/context/UI-ANTI-PATTERNS.md

@@ -26,3 +26,19 @@ audiences:
 - Accessibility treated as a final audit
 - Visual novelty prioritized over recognition and verification
 - Research guidance applied without inspecting the product context
+
+- Semantic state collapsed into a generic success, failure, loading, empty, or complete state when the product distinguishes consequential alternatives
+- Presentation code independently recreates domain action legality instead of consuming the authoritative capability or legal-action model when one exists
+- Scoped uncertainty or coverage flattened into a global completion percentage, pass/fail verdict, or status without a valid product aggregation rule
+- Unknown external effect presented as definite failure with an unsafe blind retry path
+- Previous render, screenshot, or cached presentation state treated as authority for a newer semantic state
+
+- Arbitrary component-local animation durations or easing curves with no named interaction model
+- Spring or bounce applied to every state change regardless of the phenomenon
+- Decorative lag layered onto drag, resize, scrub, scroll, slider, or other direct manipulation
+- Determinate progress that overshoots, bounces past, or visually outruns the authoritative value
+- Infinite shimmer, spin, pulse, or other repeated motion with no reduced-motion substitution
+- Animation speed, mass, bounce, or travel used to imply severity, priority, permission, confidence, or correctness
+- View-transition morphs between elements that do not represent continuous identity
+- Concurrent animations that overwrite the same transform/property and silently cancel one another
+- Motion used as the only cue that state, activity, success, failure, selection, or validation changed

package/payload/context/UI-DECISION-CHECKLIST.md

@@ -19,6 +19,13 @@ audiences:
 - Which relationships must remain visible?
 - What are the consequences of misunderstanding or error?
 - Which existing product and design-system constraints apply?
+- What is authoritative for the state, uncertainty, completion, unresolved work, and legal actions this view presents?
+- Which state distinctions change what the user may safely conclude or do?
+- Which semantic scopes must remain distinct rather than being combined into one status?
+- Which visual channels carry consequential meaning, and what happens if hue, iconography, border, position, motion, or another channel is unavailable?
+- What is the Perceptual Failure Boundary for each important or critical semantic state?
+- Is a proposed accessibility preset based on measured need, explicit user choice, or an unsupported assumption about a diagnosis?
+- Does this task contain strong linguistic context, or is it low-context content such as an identifier, code, unfamiliar name, or critical value?
 
 ## During implementation
 
@@ -32,6 +39,14 @@ audiences:
 - Is native HTML being replaced without a demonstrated benefit?
 - Does responsive behavior preserve meaning and task priority?
 - Are loading, empty, error, success, and recovery states designed?
+- Has an unknown, partial, stale, or unverifiable state been strengthened into a definite success, failure, empty, or complete state?
+- Where authoritative capabilities or legal actions exist, do controls derive from them rather than recreate legality locally?
+- Do summaries preserve the scope and uncertainty of the facts they aggregate?
+- Is decision-relevant unresolved work visible enough that users do not have to infer it from missing controls or generic errors?
+- Does consequential state remain identifiable without hue alone?
+- If CVD simulation is used, is it treated as screening rather than proof?
+- If presentation adapts to a user profile, are semantic meaning, legal actions, reading order, and programmatic state unchanged?
+- Are user preference and measured performance being kept distinct when either is used to justify a design decision?
 
 ## Required verification
 
@@ -42,10 +57,68 @@ audiences:
 - Reduced motion
 - Forced colors or high contrast
 - Color-independent state recognition
+- Grayscale plus protan, deutan, and tritan simulation as screening conditions where color carries categorization
+- Text-spacing overrides where reading content is material
+- Semantic channel dropout for consequential states: remove each declared visible channel independently and verify important and critical meaning survives
+- Run the Visual Engineering robustness manifest when the repository defines important or critical semantic states
+- Review the minimal failure sets and improve low-boundary states when practical
 - Long, missing, and extreme content
 - Screen-reader semantics for critical workflows
 - First-glance hierarchy inspection
 - Deliberate verification of consequential information
+- Exercise at least one consequential non-happy semantic state and compare the rendered actions/status with the authoritative product state
+- Where stale state can change meaning or legal action, verify that old presentation evidence is not treated as proof of the current state
+
+
+## Motion model selection
+
+Before adding or reviewing motion:
+
+- What does the motion communicate?
+- What state or input is authoritative?
+- Is the phenomenon inertial/spring, gravity-derived, constant-velocity/cadence, direct-manipulation/value tracking, or perceptual interpolation?
+- Is overshoot physically and semantically safe?
+- Can the user interrupt or rapidly repeat the interaction without stale queued motion?
+- Does direct manipulation track the pointer, scroll position, or authoritative value without decorative lag?
+- Can determinate progress ever visually exceed the authoritative value?
+- Does repeated activity stop when the activity stops?
+- Is a new duration/easing inherited from the shared model, or is there a documented reason for a new one?
+- What is the model-specific reduced-motion substitution?
+- Is the interface still correct when progressive animation support is unavailable?
+
+During verification:
+
+- Exercise rapid repeated activation and interruption.
+- Verify final visual state equals actual semantic state.
+- Verify focus movement/restoration does not wait on decoration.
+- Verify pointer drag/resize/scrub does not lag.
+- Verify determinate progress remains bounded.
+- Verify indeterminate cadence does not imply false progress.
+- Verify reduced motion removes spatial/repeated effects without losing state or feedback.
+- Verify simultaneous effects do not clobber one another.
+- Verify animation is not the only carrier of consequential meaning.
+
+## Application polish gate
+
+- Have applicable polish dimensions been identified?
+- Have reachable non-happy states been exercised rather than inferred?
+- Have high-risk state and environment seams been tested?
+- Have pathological content and boundary fixtures been used?
+- Does persistence presentation tell the truth about local, pending, persisted, failed and conflicting state?
+- Are untested environments and states recorded as unknown rather than passed?
+- Is there evidence behind a zero-finding review?
+- Have recurring defect classes been pushed upstream into shared components, rules or fixtures where appropriate?
+
+## Application polish gate
+
+- Have applicable polish dimensions been identified?
+- Have reachable non-happy states been exercised rather than inferred?
+- Have high-risk state and environment seams been tested?
+- Have pathological content and boundary fixtures been used?
+- Does persistence presentation tell the truth about local, pending, persisted, failed and conflicting state?
+- Are untested environments and states recorded as unknown rather than passed?
+- Is there evidence behind a zero-finding review?
+- Have recurring defect classes been pushed upstream into shared components, rules or fixtures where appropriate?
 
 ## Agent handoff
 
@@ -56,3 +129,5 @@ Report:
 - Verification performed
 - Material deviations and rationale
 - Unresolved evidence or product questions
+- Material semantic-projection assumptions, including the authoritative state source when it is not obvious
+- Perceptual robustness manifest result, failure boundaries, and any accepted low-boundary states

package/payload/context/UI-FOUNDATIONS.md

@@ -52,8 +52,12 @@ Visual quality is not decoration applied after structure. Architecture, content
 ## Typography and reading
 
 - Typography must expose hierarchy, grouping, sequence, and status.
-- Optimize measure, line height, weight, and spacing for the actual content and reading task.
-- Preserve user control over text size and reflow.
+- Optimize measure, line height, weight, width, spacing, and size for the actual content and reading task.
+- Distinguish high-context prose from low-context identifiers, codes, names, labels, and safety-critical values. Low-context content has less linguistic error correction and may require stronger glyph distinction.
+- Preserve user control over text size, spacing, reflow, and browser or OS text preferences.
+- Do not assume that a font marketed for dyslexia is generally superior. Current evidence does not support a universal dyslexia-font benefit.
+- When a population is heterogeneous, prefer measuring the relevant bottleneck or offering direct controls over assigning a visual preset from a diagnosis.
+- Treat user preference and measured reading performance as separate evidence.
 - Do not depend on font size alone to establish hierarchy.
 - Avoid low-contrast secondary text that becomes functionally invisible.
 - Use labels and language that reflect the user's domain, not implementation terminology.
@@ -61,10 +65,13 @@ Visual quality is not decoration applied after structure. Architecture, content
 ## Color
 
 - Treat color as relational and context-dependent; evaluate colors in their actual surroundings.
-- Use perceptually meaningful color spaces and measurable contrast where implementation permits.
+- Use task-appropriate color spaces and measurable contrast, but do not treat color-distance metrics as proof of accessibility.
+- Treat WCAG contrast requirements as mandatory conformance floors, not universal human-performance thresholds.
 - Never use color as the only carrier of state, urgency, selection, or error.
+- Design consequential states for semantic channel survivability: meaning should survive loss of hue or another nonessential visual channel.
+- Use CVD simulation and grayscale as fault-injection screens, not as substitutes for affected-user validation.
 - Reserve high chromatic or luminance contrast for information that earns attention.
-- Validate light, dark, forced-color, and color-vision conditions.
+- Validate light, dark, forced-color, color-vision, low-brightness, and relevant glare conditions.
 - Distinguish semantic color roles from raw palette values.
 
 ## Wayfinding and interaction
@@ -76,14 +83,51 @@ Visual quality is not decoration applied after structure. Architecture, content
 - Do not hide critical actions behind unfamiliar gestures or unexplained icons.
 - Ensure keyboard order, reading order, focus order, and visual order tell the same story.
 
+
+## Motion and temporal behavior
+
+- Choose the animation model from the phenomenon before choosing duration or easing.
+- Use inertial/spring response for perceived objects settling after activation or release.
+- Use gravity-derived timing only for an intentionally modeled directional cue; mass does not change gravity-derived timing.
+- Use constant-velocity/cadence motion for repeated activity such as spinners or skeleton shimmer.
+- Use direct-manipulation/value tracking when pointer, scroll, native control value, or application value is authoritative. Do not add decorative lag or overshoot.
+- Use perceptual interpolation for opacity, color, backdrop, and other non-spatial state changes rather than inventing fake mechanical behavior.
+- Semantic state changes immediately. Motion represents state and never authorizes it.
+- Determinate progress never overshoots the authoritative value.
+- Press and selection motion must not move the hit target or queue stale responses.
+- Repeated motion stops when the represented activity stops.
+- Equivalent phenomena should use equivalent motion unless a documented context difference justifies otherwise.
+- New component-local durations and easing curves require an explicit reason. Arbitrary `200ms ease` is not a design rationale.
+- Reduced motion is model-aware: remove spatial travel, bounce, repeated motion, and decorative compression while preserving direct mappings, final state, focus, feedback, and activity semantics.
+- Progressive animation features must fail back to a correct static interface.
+
+## Semantic projection
+
+A UI is often a purpose-specific projection of richer product state. Treat that projection as a semantic boundary, not only a visual transformation.
+
+- Identify what is authoritative for the state, uncertainty, completion, unresolved work, and legal actions shown on the screen.
+- Do not communicate stronger certainty, success, completeness, or authority than the source state supports. Loading is not empty; unknown is not failed; partial is not complete; unverifiable is not pass.
+- Preserve domain alternatives when they differ in legal next action, authority, uncertainty, reconciliation, recovery, completion meaning, or another material user conclusion.
+- Preserve scope. A fact that is complete for one dimension does not imply completeness for another.
+- Where the product exposes legal actions or capabilities, derive available UI actions from that authority rather than re-implementing legality in presentation code.
+- Keep decision-relevant unresolved work perceptible. Do not make users infer reconciliation, pending review, stale state, or partial coverage from generic errors or missing controls.
+- Do not invent aggregate percentages, pass/fail verdicts, or global completion states unless the product defines a valid aggregation rule.
+- Preserve the purpose of the projection. A task-focused view need not expose every domain fact, but it must not imply that omitted state does not exist.
+
+These constraints preserve meaning, not visual form. Visual Engineering still determines hierarchy, grouping, density, wording, interaction pattern, responsive composition, and aesthetic expression.
+
 ## Accessibility and human factors
 
 - Begin with semantic HTML and native behavior.
 - Components own intrinsic behavior; products still own meaningful labels, page hierarchy, instructions, and contextual correctness.
-- Support keyboard navigation, visible focus, zoom, text scaling, reduced motion, forced colors, and assistive technology.
+- Support keyboard navigation, visible focus, zoom, text scaling, text-spacing overrides, reduced motion, forced colors, and assistive technology.
+- Use strong accessible defaults before introducing personalization.
+- Apply **mechanism before mode**: a disability label may guide research or recruitment, but do not assume it identifies the active visual bottleneck or the correct presentation.
+- Preserve user choice. Adaptive presentation must be inspectable, reversible, and unable to change semantic meaning or legal actions.
 - Treat error prevention and recovery as part of the information architecture.
 - In high-consequence contexts, prioritize unambiguous identification and verification over visual novelty.
 - Test with realistic stress, interruption, density, and degraded-display conditions when those conditions are plausible.
+- Separate standards conformance, preference, comfort, and task performance. Passing one does not prove the others.
 
 ## Responsive behavior
 
@@ -102,6 +146,31 @@ Visual quality is not decoration applied after structure. Architecture, content
 - Separate source tokens, semantic tokens, theme mappings, and component consumption.
 - Validate components in real consumer contexts rather than assuming framework interoperability.
 
+## Perceptual robustness operating assumptions
+
+Visual Engineering currently treats Perceptual Envelope, Semantic Channel
+Survivability, and Perceptual Failure Boundary as **provisional engineering
+defaults**. They are sufficiently supported to guide architecture and
+implementation even where complete human validation is unavailable.
+
+- Do not block implementation waiting for perfect experimental certainty.
+- Keep the assumptions explicit, versioned, reversible, and testable.
+- Important and critical semantic states should survive loss of any single
+  declared visible channel.
+- Critical states should retain an explicit text or icon cue and programmatic
+  semantics.
+- Treat the smallest channel-loss combination that breaks meaning as the
+  Perceptual Failure Boundary.
+- Prefer designs with a larger failure boundary when other task requirements are
+  equivalent.
+- Use repository-specific evidence to override these defaults when that evidence
+  is stronger, and record the reason.
+- Never describe the channel model as a simulation of a disability or as proof
+  of individual human performance.
+
+Repositories may encode these assumptions in a Visual Engineering robustness
+manifest and evaluate them with the `robustness` CLI command.
+
 ## Evidence-sensitive decision making
 
 - Distinguish established guidance, supported hypotheses, working theory, and unresolved research.

package/payload/context/context.json

@@ -1,37 +1,41 @@
 {
   "schemaVersion": "1.0",
-  "contextVersion": "1.0.0",
+  "contextVersion": "1.0.1",
   "sourceRepository": "https://github.com/kemiller2002/Visual-Engineering",
-  "sourceCommit": "0be73c83d8c257794d53cb9ddc9a6db69f843fbf",
-  "generatedAt": "2026-09-17T20:09:11.210Z",
+  "sourceCommit": "b648cdef291d39c443ccb10215529ad69afe8b32",
+  "generatedAt": "2026-10-06T15:52:16.005Z",
   "researchCatalogVersion": "1.1",
-  "researchDocuments": 97,
+  "researchDocuments": 112,
   "profile": "ui-foundations",
   "classification": "public",
   "artifacts": [
     {
       "file": "AGENT-INSTRUCTIONS.md",
-      "sha256": "6122eeb1a6fcc17b86043c0bd34c2a1474796c1953956428e4d3118b46aa9e28"
+      "sha256": "3736636964f88644de0a5c9c255dfd88d4275f254ee179166203579e823d4d2e"
     },
     {
       "file": "UI-FOUNDATIONS.md",
-      "sha256": "0f5d4e0259038b6b8d76e3acdb937ec7b1cc099d374f45ca1ba2fdb1350252c0"
+      "sha256": "7dee7189eedd9448f9fc7816bdc22fa41e32bd1ac465c880df0754faa30a8b73"
     },
     {
       "file": "UI-DECISION-CHECKLIST.md",
-      "sha256": "a4c66988885e89363af756a84dae6aa2731efea0024be6bfdaa2247085ad1e99"
+      "sha256": "47bcb1191362e43ebbd8064bde87015186dbe47c1a72bfbadfd2e0a3a611b629"
     },
     {
       "file": "UI-ANTI-PATTERNS.md",
-      "sha256": "4698844792e274a40d9086c998b8b9b77a01ac9006fd0590a2688d6de9fdda49"
+      "sha256": "6066b2faca907eb0afde78b9840020186901d782880fbad23bb41599e88bafc1"
+    },
+    {
+      "file": "APPLICATION-POLISH.md",
+      "sha256": "94da532ba5f54617e269525a2b7188b9bf2ba531f96fa9e8c88023a08a38cf51"
     },
     {
       "file": "RESEARCH-INDEX.md",
-      "sha256": "b09cd82ad563c28188ebf731fda2b362de8c1144b6c31e1a509fab25ded52db6"
+      "sha256": "1e1f7f9ebdf7ae99de1b81b18837a6d5ce2497617dc2a7a21e61d5be9badfb22"
     },
     {
       "file": "sources.json",
-      "sha256": "cfb3c9544ab0c9ce5f8dc225002b94eccd6de0fd8875069d4daa7def1be54be5"
+      "sha256": "07b5fef9d83664e5c8aa6d00e7d20db146798e8db3b2175f97eb4c863526897c"
     }
   ]
 }