# neuralmarketing.org — Visual & interaction framework

Version 3.0

## Direction

An experimental observatory for hidden systems that shape attention, perception, and choice. Preserve the approved editorial identity while making demonstrations and research records the primary units. The project studies mechanisms of influence and asks whether revealing them helps people act on their own priorities. It spans physical environments, digital interfaces, media, technology, and social systems.

### Principles

1. Give each view one dominant signal.
2. Use space to separate ideas and proximity to relate them.
3. Let the interface acknowledge actions and explain outcomes.
4. Use the serif as a change of perspective, not as general body text.
5. Preserve meaningful choice and reversible exploration.

## Information architecture

The observatory (`/`) opens with a voluntary one-minute demonstration, followed by the study collection, six lenses, physical-world research, and the operating principle. `/studies/` provides search and intersecting filters by lens and kind, plus a personal visit record. Each study has an independent route at `/studies/<id>/` with a focused task and a nine-part research record. `/the-rule-that-was-never-written/` is a standalone campaign encounter that leads into the Adaptation lens without presenting itself as a collected experiment. `/method/` explains the programme, domains, evidence boundaries, participation, and data handling. `/framework/` remains the living design system.

The illustrative attention field lives on the method page. It remains a visual metaphor, not a measurement.

## Foundations

| Token | Value | Role |
| --- | --- | --- |
| `--paper` | `#FAFBF9` | Page surface |
| `--surface` | `#F0F2ED` | Grouped content |
| `--ink` | `#1D211F` | Primary text |
| `--muted` | `#626862` | Supporting text |
| `--line` | `#D9DDD7` | Structural dividers |
| `--blue` | `#254DFF` | Actions, focus, emphasis |
| `--blue-dark` | `#1733B8` | Hovered primary action |
| `--blue-wash` | `#EDF0FF` | Subtle information surface |
| `--dark` | `#172621` | Reflective section |
| `--white` | `#FFFFFF` | Text on primary actions |

Structural dividers are not input boundaries. Inputs use the stronger `#7F897E` edge. Error feedback uses `#AC2B25`, success feedback `#28603B`. Errors and success states also use clear text. Color never carries the state alone.

## Typography

- DM Sans: headings, body copy, links, controls. Fallback: Arial, sans-serif.
- Instrument Serif italic: editorial emphasis. Fallback: Georgia, serif.
- DM Mono: labels and metadata. Fallback: monospace.
- Body: at least 1 rem, generally line-height 1.6–1.85.
- Regular control labels: at least 0.875 rem.
- Secondary metadata: at least 0.75 rem.
- Display: fluid, typically 3.4–6.1 rem; serif emphasis can be 1.1–1.13 times the surrounding display.
- Use negative tracking on large display text only. Preserve readable letter spacing at small sizes.
- Keep long reading text near 60–75 characters per line where space allows.

## Layout

- Maximum page width: 1440 px including gutters.
- Gutters: 64 px desktop, 40 px at 1100, 28 px at 800, 24 px at 600 and below.
- Editorial two-column layouts become one column at 600 px.
- Framework index becomes horizontal at 900 px.
- Spacing scale: 4, 8, 16, 24, 32, 48, 64, 96 px. Optical adjustments are permitted when they serve the composition.
- Main section spacing is approximately 96–100 px desktop and 60 px mobile.
- Corners: 4 px for imagery and controls; 8 px for dialogs; circles for icon-only actions.
- Avoid wrapping cards in redundant surfaces. Favor rules, whitespace, and typography for structure.

## Component contracts

### Buttons and links

Use `.button.button-primary` for the dominant action, `.button.button-secondary` for a quieter action, and `.text-link` for editorial navigation. Use an anchor for navigation or download and a button for a change within the page. Icon-only buttons require accessible labels. Main interactive hit areas are at least 44 px. Primary buttons use white text on Cobalt; hover darkens the surface and raises the element by 2 px. Native disabled controls cannot be activated.

### Navigation

Use semantic navigation landmarks with distinct labels. At small widths, the menu button controls the visibility of the main navigation through `aria-expanded` and `aria-controls`. Escape and outside click dismiss it. Closing via Escape restores focus. Selecting a link dismisses the menu.

### Tabs

Use `tablist`, `tab`, and `tabpanel` roles with linked IDs. Keep only the selected tab in the tab sequence. Arrow keys move between tabs; Home and End select the first and last. Update `aria-selected`, `tabindex`, and the panel's `hidden` attribute together. The main lens list is vertical; the component example is horizontal.

### Dialogs

Use the native `dialog` element and `showModal()`. Give the dialog an accessible title. Provide a labeled close action. Escape, the close action, and an outside-backdrop click dismiss it. Preserve scroll position on the underlying page and restore focus to the original trigger. 

### Fields and validation

Use visible labels, helpful descriptions, and programmatically associated inline error messages. Preserve entered text. Set `aria-invalid` on failure, announce the error, and focus the invalid control. Announce success only after the operation represented has occurred. The framework form is explicitly a local validation example; it sends and stores nothing.

### Clipboard and transient feedback

Await the Clipboard API before confirming success. If copying is blocked, show the exact value in selectable text. Feedback is a polite status announcement, not an interruption. Do not claim an action happened when it did not.

### Disclosure

Use native `details` and `summary` for supporting explanations. Disclosure should not conceal the primary action or essential conditions of a choice.

## Motion and the attention field

- Standard interface transitions: 200–240 ms, `cubic-bezier(.2,.7,.25,1)`.
- Large image hover: 700 ms with a small scale change.
- Avoid page-entry animation that hides useful content while waiting.
- Honor `prefers-reduced-motion`. Disable smooth scrolling and transition effects. Start the field paused.
- The field supports three visual mappings: emphasis, rhythm, and direction. Intensity adjusts the effect. Labels explain the mapping in words.
- This is an illustrative study. It does not measure attention, record cursor positions, infer emotion, or model individual behavior.
- Pause is always available. The application may remember that preference locally under `nm-motion-paused`; a preference storage error must not break the interface.
- Stop the animation offscreen and when the document is hidden. Cap device pixel ratio to avoid unnecessarily large render buffers.

## Accessibility and resilience

- Provide a skip link, landmarks, one page-level h1, and a logical heading hierarchy.
- Keep a strong visible focus indicator and do not remove it for visual simplicity.
- Interactive states must be understandable without color or hover.
- Keep touch targets distinct and comfortably sized.
- Describe meaningful imagery. The generated cobalt glass lens is illustrative, not documentary.
- Provide descriptive text for the canvas and standard controls that do not depend on pointer gestures.
- Reserve image dimensions to reduce layout movement.
- Fonts use immediate local fallback. Static content and navigation remain available if web fonts fail.
- Demonstrations, the enhanced field, and dialog readers require JavaScript. The no-JavaScript notice identifies the limitation; full study records, method, overview, and lens explanations remain available.
- Actual WCAG conformance requires browser, assistive-technology, zoom, and real-device review. Code-level implementation is not a certification.

## Editorial content and imagery

Write in an observant, plain, curious voice. Prefer specific questions over abstract claims. Keep uncertainty visible. Do not invent performance metrics, affiliations, case studies, testimonials, or scientific validation.

Field-note model:

1. Stable lens key (`attention`, `affect`, or `intent`).
2. Category and observation number.
3. Clear title and a short premise.
4. Original body content with a practical question or observation exercise.
5. Appropriate visual and descriptive alt text.

The earlier essays are supplementary original drafts. Studies are the primary unit in version 2. The nine playable demonstrations illustrate a question; the three remaining records are clearly marked protocols, not completed investigations.

Use optical materials, refraction, and typographic studies for the art direction. The cobalt glass asset was generated specifically for the site, then exported as WebP. Functional diagrams should remain exact HTML/CSS/SVG or canvas rather than generated pictures of diagrams.

## File map

| File | Responsibility |
| --- | --- |
| `dist/index.html` | Observatory structure and summaries |
| `dist/framework/index.html` | Living design framework |
| `dist/assets/style.css` | Shared tokens, layout, editorial components, responsive styles |
| `dist/assets/site.js` | Navigation, lenses, canvas, original essays, reading dialogs |
| `dist/assets/framework.css` | Framework-specific specimens and documentation layout |
| `dist/assets/framework.js` | Copy actions, specimen dialog, validation, tabs, motion example |
| `dist/assets/design-tokens.json` | Portable token values |
| `dist/assets/attention-glass.webp` | Local editorial artwork |

## Extension rules

Update tokens before creating one-off style overrides. Reuse semantic components. Add a separate route when a distinct task or content model needs one. Do not add forms that imply delivery without a real configured service. If analytics, accounts, persistent submissions, or a content service are introduced, document their behavior and dependencies separately.

## Release checks

Validate both route entrypoints, local assets, anchors, ARIA references, syntax, and intended text/background contrast. Review narrow screens, text enlargement, keyboard navigation, screen-reader output, focus restoration, reduced motion, empty input, success feedback, and browser Back behavior. Check the deployed version's terminal success status. A private review deployment does not connect or modify the live neuralmarketing.org domain.


## Research framework — version 2

### Primary proposition

An experimental observatory for the hidden systems that shape attention, perception, and choice. Understand the mechanism; make the mechanism visible. Study both how influence works and whether disclosure can restore agency.

### Six lenses

- Attention: salience, interruption, novelty, motion, contrast, gaze, cognitive load.
- Perception: framing, sensory context, expectation, anchoring, cross-modal effects.
- Desire: scarcity, status, imitation, association, anticipation, identity.
- Choice: defaults, friction, ordering, decoys, complexity, commitment.
- Memory: repetition, familiarity, narrative, peak-end effects, reconstruction.
- Adaptation: personalisation, ranking, behavioural prediction, affect inference, AI.

A lens is a conceptual filter. It is not an assertion that a particular mechanism was measured or found in a study.

### Four content kinds

Demonstrations are educational local experiences. Experiments require a defined research plan and actual observations. Field studies inspect real physical or digital settings. Interventions test a redesign against a participant-relevant goal. Kind and status are separate fields. A proposed experiment is not recruiting merely because it appears in the collection.

### Current collection

Nine runnable demonstrations: default selection; price context; visual salience and recall; six versus twenty-six choices; simulated popularity; repeated exposure; human/machine attribution; choice blindness; and related-word recognition. Three protocols: physical sensory context, disclosure and agency, and useful friction. None collect pooled research data.

### Experience contract

1. Invitation: disclose voluntary participation, temporary concealment of exact details, simulated claims, and local storage before starting.
2. Experience: randomise the selected cue where relevant. Keep unrelated content fixed. Confine interventions to the task; do not change ordinary navigation covertly.
3. Response: require an actual answer for numerical ratings. Preserve deferral. Separate familiarity from preference and confidence from satisfaction.
4. Immediate reveal: report the actual variant and response, never a fabricated estimate. Include mechanism, alternative explanations, real-world use, ethical dimension, and countermeasure.
5. Informed replay: remove the intervention while preserving order and other relevant presentation. Keep a parent reference and label replay as informed rather than a control sample.
6. Personal record: allow inspection, export, and clearing. Mark early reveals separately from completed tasks.

The standalone reversal encounter follows a narrower contract and an intentionally independent campaign identity rather than duplicating the observatory page system. Four taps reward a bright surface cue; three later taps reward a contextual frame, with the old cue still present. The one-second indicator is presentational and never removes a choice or changes an outcome. Offer untimed mode before play. Describe the visible cues in accessible names, move focus at controlled step changes, reveal the rewarded cue after every choice, and allow an early reveal. The final trace reports observed clicks, never a brain, dopamine, personality, intelligence, or susceptibility score. An informed replay labels the contingency; any difference is explicitly confounded by practice and memory. Sharing exports only a challenge line and route URL, not the visitor's trace.

Participant-facing popularity, reference prices, stock levels, and source attributions inside demonstrations are fictional stimuli. Their construction is disclosed before participation in general terms and identified exactly at reveal. They are never used as real site popularity, evidence, endorsements, or commercial claims.

### Standard study record

Observation → Hypothesis → Mechanism → Experiment → Result → Alternative explanations → Real-world use → Ethical dimension → Countermeasure. Add primary source links and explicit limitations. The source catalogue and all complete records are available as `research-protocols.json`.

### Data and inference

Records use session storage (`nm-observations-v2`) with an in-memory fallback, retaining up to the most recent 100 records. Store the study ID, assignment, option order, responses, exposures, timestamps, completion state, mode, and parent replay reference. Export only the visitor's local records. Clearing removes them from the active tab store.

The standalone rule game uses a separate tab-scoped key (`nm-rule-game-v1`) and retains up to 20 traces so campaign interactions cannot enter the study collection record. Its export is local JSON. No trace is sent through the share action.

The application makes no research submissions, captures no eye movements, infers no emotion, assigns no psychological score, and computes no pooled result. Static hosting can have operational request logs; do not describe application privacy as a claim about the provider's full infrastructure.

A single response does not prove an effect or lack of one. Free recall is not gaze. Immediate replay mixes disclosure with practice and memory. The proposed agency study uses a new transfer task and a comparison group precisely because replay is not proof of protection.

### Formal study launch

Before recruiting for a real experiment, complete the protocol: population, recruitment, hypotheses, manipulation checks, allocation, sample-size rationale, outcomes, exclusions, stopping rules, comparison conditions, consent and disclosure, withdrawal handling, retention, collection infrastructure, and analysis plan. Physical studies also need stable environmental conditions and individual sensory access considerations. These are requirements of the proposed research programme; they are not features claimed to be operating in this version.

### Implementation map

- `dist/assets/research-data.mjs`: twelve complete study records, six lenses, eleven primary-source references, standard field names.
- `dist/assets/trial-model.mjs`: pure variant assignment, response validation, immutable updates, audit reconstruction, record creation.
- `dist/assets/observatory.js`: task rendering, reveal/replay interactions, intersecting collection filters, tab-local records and export.
- `dist/assets/observatory.css`: research-specific composition, task controls, reveal, record, protocol and method surfaces.
- `scripts/generate-pages.mjs`: static page generation from the study catalogue.
- `scripts/rule-game-page.mjs`: standalone campaign markup and research debrief.
- `dist/assets/rule-game-model.mjs`: pure seven-round contingency and summary model.
- `dist/assets/rule-game.js` and `rule-game.css`: game state, local trace, share/download controls, and presentation.
- `scripts/legacy-sections.json`: preserved original field-note and canvas components.
- `tests/trial-model.test.mjs`: meaningful data-integrity and replay tests.
- `tests/rule-game.test.mjs`: reversal, counterbalancing, observed-summary, and share-copy tests.

After changing study data or generated-page structure, run `node scripts/generate-pages.mjs`. Generated HTML and JSON remain tracked. Run `node --test tests/trial-model.test.mjs` for the model checks. No dependency installation is required. Browser and assistive-technology QA remain separate release checks.

## The human weight / version 3

The guided route `/the-human-weight/` connects the social situation, introspection, recollection, agency, and compassion. It uses the established cobalt, forest, paper, and editorial typography. Chapter links are direct hashes; browser Back restores chapter position. All chapters and research notes remain readable without JavaScript.

- Give the visitor an experience, a verifiable reveal, a primary research link, a human question, and a practical possibility. Do not force a philosophical conclusion.
- Use official Mind Field links as viewing companions, credit Michael Stevens and Vsauce, and keep independent research attribution clear. Do not imply affiliation or a faithful replication of an episode.
- Preserve an actual choice even when the simulated display is substituted. A mismatch report and lack of a report are distinct from an inference about awareness.
- In the memory task, distinguish absence, recognition, uncertainty, and missing answers. Show the exact list. Do not generalise to a personal memory or testimony.
- The memory replay keeps the list available as an external record. It is an informed demonstration of support, not a test of awareness alone.
- Opening and closing reflections stay only in page memory. Offer local text download and clearing, state the loss on navigation or reload, and assign no empathy or belief score.
- `human-studies.mjs` supplies the two records and four new references; `human-path.mjs` generates the guided narrative; `human-path.js` and `human-path.css` provide navigation and presentation.

### Price demonstration sequence

Study 002 starts with the crossed-out €79 reference beside €29, then shows popularity, scarcity, and the plain €29 offer last. Each requires separate value, urgency, and confidence ratings. The normal flow reveals only after offer four, while stop/reveal remains available. The reveal includes an accessible comparison table, and early exits distinguish completed ratings, the current unrated offer, and unseen offers. The four-offer replay removes all claims. Records retain each offer number and its actual cue; sequence effects and repeated exposure remain explicit limitations.

### Progress and return paths

Use `navigation.mjs` for whitelisted entry context, return URLs, and next-study selection. Home-origin demonstrations return to the homepage collection; collection-origin and direct entries return to the dedicated collection. Preserve valid search/lens/kind filters and skip protocols when suggesting the next runnable demonstration. Never use an arbitrary return URL. Place return and next actions immediately after the result heading and again after the explanation, including early reveals. Guided inline experiences additionally continue to their next chapter.

Use explicit round progress and advance after a submitted response. Salience selection buttons advance immediately; ratings and preselected defaults still require confirmation. Defaults and salience compare two presentations; social counts and source attribution compare three. Record each presentation with its response. These within-visit comparisons cannot separate intervention effects from order, repetition, or prior responses. Leave disclosure-sensitive memory and choice-blindness flows intact.

### Everyday consequences

Follow each demonstration’s ethical explanation with “Outside this demonstration”: a short, specific account of what may be at stake in ordinary life, the possibility of no disclosure or replay, and a practical check. Keep it alongside the ethics section in both the reveal and the full research record. Avoid implying that this visit proves a particular real-world intervention or personal susceptibility.

### Promoted presentations first

Price offers begin with the reference-price anchor and finish with the plain price. Popularity runs from 18,400 to 23 likes, then no count. Human and machine recommendation labels appear in shuffled order before the unattributed version; no ranking of those two sources is assumed. Defaults and salience already show their cue before the neutral presentation. This ordering is an editorial choice, not evidence that participants will recognise the pattern later. Fixed order and carryover remain limitations.

### Review of incidental patterns

Task-based `entryTitle`, `entryDeck`, and `entryContext` fields provide the invitations and next-study labels. Preserve original research titles for the optional full record and the immediate reveal. Search covers both. Do not hide the voluntary invitation, temporary concealment notice, or mechanism-first route.

| Demonstration | Handling |
| --- | --- |
| Defaults | Assign cadence order once and preserve it across rounds and replay. |
| Prices | Keep the requested promoted-first, plain-last order; disclose fixed-order limits. |
| Salience | Preserve description and card order across highlighted and neutral rounds. |
| Choice sets | Randomly select six from 26 and preserve their relative order; keep size order random. |
| Popularity | Keep the requested high-count-first order and same passage. |
| Repetition | Commit preference before showing the familiarity question; preserve label order. |
| Attribution | Randomly assign the recommended notebook once; keep it fixed across sources and replay. |
| Choice blindness | Preserve the true selection; immediate mismatch reporting remains available. |
| Memory | Vary recognition-question order by visit, preserving it for replay; retain the actual word list. |

These changes address visible procedural differences. They do not establish that recognition of a mechanism was delayed, or make a within-visit comparison an unbiased causal estimate. Record interpretation explicitly retains uncontrolled sequence, prior exposure, and knowledge of the hypothesis.

The human-weight path is a closing reflection: homepage chapter 06 follows the five explanatory chapters, the collection ends with a reflection invitation after the visit record, and the last demonstration in each collection offers the reflection alongside its collection return. The reflection remains directly accessible, accepts first-time arrivals, and ends with a return to the study collection. No completion gate or inferred change of belief is used.

Each task step opens with a prominent round/offer/step banner, segmented progress, and an acknowledgement of the preceding response. Focus moves to the new step label; acknowledgements do not repeat choices or reveal stimuli. The memory transition acknowledges reading rather than claiming an answer was recorded. Transitions remain immediate, with no forced delay or animation.


The physical-environment field protocol includes four AI-generated scenes based on the homepage glass object: jeweller, gallery, market, and gravel, in that order. `scripts/environment-gallery.mjs` supplies the responsive gallery, optional cue explainer, and attributed De Beers historical context. The scenes are illustrative and change several features together, including potentially the rendered object; no ratings, added trial engine, causal result, or monetary valuation is implied. The field protocol remains a proposal. Image prompts and provenance are recorded in `scripts/environment-image-prompts.md`.


## Automatic system theme

Every route follows `prefers-color-scheme` automatically. If the system preference is absent or unavailable, the site uses light. The palette is applied in the document head before stylesheet paint and updates when the system preference changes. There is no manual selector and no theme cookie is read or written. Previously saved theme choices are ignored.

| Role | Light | Dark |
| --- | --- | --- |
| Page | #FAFBF9 | #141A17 |
| Grouped surface | #F0F2ED | #1F2822 |
| Main text | #1D211F | #EDF1E9 |
| Supporting text | #626862 | #ACB7AD |
| Link / focus | #254DFF | #9AADFF |
| Filled action | #254DFF | #3458D6 |
| Text on action | #FFFFFF | #FFFFFF |
| Input border | #7F897E | #7F9180 |

Semantic tokens also cover status badges, progress, inputs, errors, success, and information panels. Figures, photos, explicit palette swatches, and notebook colour stimuli retain their source colours. Theme styles do not invert imagery. See `theme.js`, `theme.css`, and `scripts/theme-markup.mjs`. The header uses its original compact menu layout without a theme control.