Research foundations

The measurement gap

Measuring emotional experience is harder than it looks. The dominant approaches each carry structural limitations that leave a significant gap in what researchers and practitioners can actually deploy.

Simple self-report scales

Single-item ratings ("How do you feel? 1–10"), emoji sliders, and visual analogue scales are easy to administer and widely used. But they are not grounded in any validated model of emotion. They collapse a complex, multidimensional experience into a single number — losing almost all signal in the process. A "7" before an experience and a "7" after could reflect entirely different emotional states. There is no principled way to compare ratings across people, sessions, or contexts because the scale itself has no anchored meaning.

Clinical instruments

Validated instruments like the PHQ-9 (depression), GAD-7 (anxiety), PANAS (positive/negative affect schedule), and POMS (profile of mood states) are rigorously developed and clinically meaningful. But they carry significant structural limitations for general-purpose before/after emotional capture:

• Clinically specific. The PHQ-9 measures depression. The GAD-7 measures anxiety. Neither spans the full range of human affective experience — positive states, mixed states, and states that don't map onto a clinical diagnosis are outside their scope.
• Burdensome to administer. PHQ-9 takes 2–3 minutes; PANAS and POMS take 10–20. For before/after capture or repeated daily administration this is prohibitive. Completion rates fall sharply with length.
• Opaque to users. "Over the last two weeks, how often have you had little interest or pleasure in doing things? — Not at all / Several days / More than half the days / Nearly every day." This question requires clinical framing to interpret. The person answering rarely understands what their score measures or how it relates to how they actually feel right now. This is a trust and engagement failure on top of the scope limitation.
• Not composable. No single instrument spans the full affective space. Using multiple instruments compounds the administration burden and produces disconnected data streams.

The gap affect-kit addresses

There is no widely-adopted, evidence-grounded instrument that is simultaneously:

• Fast enough for before/after capture and repeated administration
• Broad enough to cover any emotional state, not just clinical ones
• Grounded in validated affective science, not arbitrary scales
• Legible to the people taking it — producing results they recognize and understand

affect-kit addresses this gap using Russell's circumplex model of affect as the scientific foundation [2] and the NRC VAD Lexicon as the vocabulary backbone [3]. The design goal: an instrument a researcher can defend and a user can connect with — simultaneously. The rater takes under 60 seconds, produces a structured Rating object grounded in validated V/A/D coordinates, and uses language users recognize because it comes from how people actually describe how they feel.

1. The dimensional model of affect

Why dimensions, not categories

Discrete-emotion theories — Ekman's "basic emotions" of anger, disgust, fear, happiness, sadness, and surprise — have been challenged since the 1980s by evidence that emotion is better modeled as a continuous space than as a set of named categories. Russell's circumplex model [2] and Mehrabian & Russell's PAD/VAD model [1] propose that any emotional state can be located in a space defined by three orthogonal dimensions:

• Valence (V) — pleasantness. How positive or negative the experience is. Ranges from −1 (maximally negative) to +1 (maximally positive).
• Arousal (A) — activation. How energized or calm. Ranges from −1 (maximally calm/lethargic) to +1 (maximally energized/excited).
• Dominance (D) — control. The degree of agency, from −1 (completely helpless) to +1 (completely in control). See §1.2 for why this dimension is preserved even though it isn't visualized.

The dimensional approach has accumulated substantial evidence:

• Posner et al. (2005) found that PET and fMRI studies map emotional experience onto valence and arousal axes more cleanly than onto discrete categories.
• Lindquist et al. (2012) [7] found that "basic emotion" categories lack consistent neural signatures, while valence and arousal dimensions do.
• Barrett (2017) [6], in How Emotions Are Made, argues that emotions are constructed from core affect (valence × arousal) plus conceptual knowledge — strong support for treating dimensions as primary and labels as secondary refinements.

1.1 Why include dominance even though it's not visualized

Two emotions can share nearly identical V and A coordinates but differ meaningfully in D:

These distinctions have genuine clinical relevance: high-D negative states call for assertion and boundary skills; low-D negative states call for containment and grounding. The difference also surfaces in longitudinal patterns — chronic low-D states correlate with depression and learned helplessness; chronic high-D negative states with anger dysregulation.

In affect-kit, the face glyph and color visualization use only V and A — those are the dimensions a face can naturally communicate. D is preserved in every Rating object as analytical metadata, available for downstream research export and aggregation, but not visualized in the UI.

2. The interaction model: orient, refine, commit

2.1 The three-step flow

A capture has three steps. They are deliberately distinct so each one does a single thing well:

1. Orient. Drag the face to indicate roughly where you feel you are in V/A space. The face mirrors your placement and the color tints in real time; the 55 emotion words sort themselves so the most relevant rise to the top. This step is a gesture, not a measurement — your body knows it's here before you have a word for it.
2. Refine. Tap the words that fit, up to five, at three intensity levels. Each word carries lexicon-validated VAD coordinates, and the intensity-weighted composite of your selections is the measurement.
3. Commit. Tap Done to finalize. The rating preserves both the pre-verbal placement (face) and the composite VAD from your words (composite), separately.

This sequence is grounded in affective science:

• Feeling precedes naming (Damasio 1999 [16]; Barrett 2017 [6]). Pre-verbal somatic awareness is real and distinct from verbal categorization.
• Labeling emotions reduces their intensity — "affect labeling" (Lieberman et al. 2007 [9]) — so naming after the gesture avoids contaminating the somatic signal.
• The face provides immediate non-judgmental feedback: it is a mirror of the user's state, not an evaluation of it.

2.2 Why the gesture is not the measurement

The orientation step might feel like a rating, but mechanically it isn't. The gesture does three things, and exactly three:

1. Drives the face glyph expression in real time
2. Drives the color tint interpolation
3. Sorts the NRC VAD Lexicon by Euclidean distance from the gesture position so the most relevant words rise to the top

The gesture is an affordance for navigation through a 55-word vocabulary — an intuitive, pre-verbal entry point into the lexicon. A user who drags toward the upper-left (negative V, positive A) sees anger, panic, and frustration rise to the top; a user who drags toward the lower-right sees calm, peaceful, and serene. The gesture replaces what would otherwise be a flat, overwhelming list.

2.3 Words compose the V/A/D measurement

The validated measurement comes from the selected words and their intensity levels, weighted using each word's NRC VAD Lexicon coordinates:

weight = level / 3                       // 0.33, 0.67, or 1.0

composite.v = Σ(word.v × weight) / Σ(weight)
composite.a = Σ(word.a × weight) / Σ(weight)
composite.d = Σ(word.d × weight) / Σ(weight)

This design is why affect-kit can produce genuine dominance values despite showing only a 2D gesture surface: dominance enters the rating through the lexicon. A user who taps frustrated (NRC d=−0.49, low-control) versus anger (d=+0.31, agentic) generates structurally different ratings. The gesture alone cannot make this distinction; the words can.

2.4 The face-vs-composite gap as a signal

Even though the gesture isn't the formal measurement, it carries real signal — and the rating object preserves it separately. The Rating object holds both the pre-verbal placement (rating.face) and the label-aggregated composite coordinates (rating.composite). The gap between them is itself research data.

Work on emotional granularity (Barrett 2001; Kashdan, Barrett & McKnight 2015 [8]) links the ability to make fine-grained distinctions between similar emotions to mental health outcomes. Large, persistent gaps between where a user gestures and what they eventually label are operationally close to measures of alexithymia — difficulty identifying or describing one's own feelings. Longitudinal tracking of this gap is a future research use case for the package.

3. The face glyph

3.1 FACS action units

The face glyph encodes V and A using Facial Action Coding System (FACS, Ekman & Friesen 1978 [5]) action units selected for their cross-cultural consistency — validated in 17 cultures by Cordaro et al. (2018) [10]:

Calm vs joy distinction. The calm face uses a soft upward eye arch (positive V, negative A) without crows feet. Joy adds the Duchenne crows feet — orbicularis oculi contracts only with high-intensity positive affect. This anatomical distinction matters for cross-cultural recognition.

3.2 Why a reductive glyph

The face is intentionally minimal: black ink linework, no skin tone, no eye whites, no hair, no body. This is by design:

1. Cultural neutrality. Skin color, hair texture, and facial structure encode race, ethnicity, and gender. Removing them removes that load from a tool designed to reflect universal affective dimensions.
2. Universality. The features are a graph of relationships — brows above eyes, mouth below nose — not a portrait of a specific person.
3. Self-projection. A non-photorealistic face is easier to project onto. Users see "their" feeling, not a depicted person's feeling.
4. Research-aligned. Schematic faces are recognized at the V/A level as well as photographs (Aviezer et al. 2008 [15]).

3.3 Animation principles

The face on the rater is alive but not theatrical:

• Breath. Subtle vertical translation at ~0.55 Hz, amplitude ~0.5 viewBox units. Conveys a living presence without being distracting.
• V-driven cohesion. At high arousal with negative valence (anger zone), facial features tremor and are displaced from each other. At high arousal with positive valence, features are stable but bouncy. Calm states are still. The rule: "out of control but still a face."
• Shock on chip selection. Selecting a high-arousal label triggers a brief burst of additional motion, reinforcing the connection between the word and the face's expression.
• Reduced motion. prefers-reduced-motion: reduce disables tremor and breath. Functional transitions (drag morphing, chip level changes) are preserved but shortened.

4. Vocabulary: the NRC VAD Lexicon

4.1 Primary source

affect-kit's 55-word emotion vocabulary draws V/A/D coordinates from the NRC Valence-Arousal-Dominance Lexicon v2.1 (Mohammad 2025 [3]):

• 20,000+ English words with V/A/D ratings, crowd-sourced from native speakers
• Published values normalized to 0..1 (rescaled to −1..1 in affect-kit)
• Free for research and commercial use
• Multilingual extensions available for ~100 languages

Secondary cross-references: Warriner et al. (2013) [4] (13,915 words, V/A only, high precision) and Bradley & Lang (1999) ANEW norms (1,034 words, comprehensive V/A/D).

4.2 Vocabulary curation principles

The 55 emotions were selected from the NRC lexicon following these principles:

1. Quadrant coverage. Span all four V/A quadrants reasonably evenly. Avoid the common clinical bias toward negative-emotion vocabularies.
2. Intensity gradation. Include emotions of varying intensity within each quadrant. Content and ecstatic are both positive-valence / positive-arousal but at very different intensities.
3. Single-word. Prefer single words over phrases. "Overwhelmed" not "feeling overwhelmed." Compactness matters for chip rendering.
4. Common language. Everyday words over clinical terms. "Sad" not "dysphoric."
5. No moral loading. Skip words that imply judgment. "Resentful" is an emotion; "guilty" carries moral weight but is included because it's affectively specific. "Sinful" is not.

4.3 Emotional granularity as a trackable outcome

Research by Barrett and colleagues (Kashdan, Barrett & McKnight 2015 [8]) established that emotional granularity — the ability to make fine-grained distinctions between similar emotions — predicts mental health outcomes: higher granularity correlates with lower psychopathology; lower granularity with depression, anxiety, and alexithymia.

The intensity levels (1/2/3) on chips are themselves a granularity affordance. A user who selects only level-3 chips treats each emotion as binary; a user who uses all three levels makes finer distinctions. The number of distinct emotion words a user employs across sessions, and how they distribute across V/A space, are trackable granularity signals.

4.4 Why the vocabulary is not customizable

Consumers cannot pass custom emotion words via props. The reasons:

• Trust. The entire rating computation depends on V/A/D values being empirically validated. Arbitrary words break that guarantee silently.
• Calibration. V/A/D values are empirical norms, not opinions. Allowing overrides is a category mistake.
• Internationalization is principled. Future language support will use validated multilingual lexicons (NRC has them for ~100 languages), selected via a strict language prop, not free-form data.

5. Color design

5.1 The four-quadrant palette

Color mode maps the V/A position to a continuous blend across four corner colors, each associated with a quadrant of emotional space:

Color choices follow cross-cultural color-emotion associations (Adams & Osgood 1973 [18]; Hupka et al. 1997): red/pink for anger, gold for joy, green for calm, blue for sadness. Cyan is deliberately avoided at the lower-left (sadness) corner because in HRV/biofeedback contexts cyan conventionally signals "high coherence" — a semantic conflict with sadness.

5.2 OKLab interpolation

Colors blend in OKLab color space (Ottosson 2020 [14]) via bilinear interpolation across the four corners. OKLab is perceptually uniform, so V/A positions blend smoothly without the hue-flip and luminance-jump artifacts that HSL interpolation produces at quadrant interiors (particularly around gold, which has a narrow luminance band in HSL).

5.3 When color is appropriate

Color mode defaults to off in clinical and wellness contexts where affect-kit is a supporting instrument. Reasons:

• Don't compete with the primary signal. If the host product owns a color identity (e.g., HRV biofeedback with a green/red palette), affect-kit introducing a second color system creates visual noise.
• Don't moralize the state. A bright pink surface for negative emotions reads as "bad." Monochrome lets the user have a state without being told it's good or bad.
• Reduces visual stimulation for activated states. A user in a high-arousal anxious state does not benefit from a vibrant red surface.

Color mode is appropriate for standalone use — journaling, publication, social sharing — where visual expressiveness is the point.

6. Longitudinal foundations

affect-kit is a logbook substrate — it captures single ratings and renders them faithfully. Longitudinal interpretation is future territory, but the design decisions made now are constrained by what the literature can actually defend.

6.1 What progress means for emotional self-rating

The fundamental error in longitudinal emotion tracking is treating affect as having a monotonic "improvement" direction. Research shows otherwise:

• Feeling more negative emotion is not worse if it's contextually appropriate (Davis, Gross & Ochsner 2011 [12]).
• Emotional flexibility — the ability to access a range of emotions including negative ones — predicts wellbeing better than emotional positivity (Kashdan & Rottenberg 2010 [13]).
• Pattern interruption carries more clinical information than long-term averages: sudden shifts in emotion patterns over weeks matter more than whether average valence is slightly positive (Bolger, Davis & Rafaeli 2003 [17]).

6.2 Three operationally-defined longitudinal patterns

The affect-dynamics literature converges on three patterns that can be meaningfully tracked longitudinally, anchored on valence as the primary axis (the dimension with the most settled operational definitions and the most intuitive user interpretation):

6.3 Why valence is the anchor for future recipes

Of the three VAD dimensions, valence is the strongest anchor for longitudinal recipes. Arousal carries less interpretive consensus over time — the same elevated arousal reading can mean excitement, anxiety, or flow depending on context. Dominance has very little experience-sampling research behind it as an outcome variable. Affect-kit captures all three dimensions in every Rating, but the first longitudinal recipe implementations will anchor on valence first.

Each future recipe must be parameterised (thresholds, windows, definitions set by the consumer), cite the minimum it would defend, and avoid composite "wellness scores." The construct opposite of emotional granularity is alexithymia — not contentment. Both matter for different reasons.

6.4 HRV + affect: parallel tracks

In contexts pairing affect-kit with HRV biofeedback, the two signals must be tracked in parallel and never combined into a single score. HRV is physiological (autonomic state, objective normal ranges); affect is phenomenological (felt experience, no normal ranges). A user with low HRV who reports calm is not an error — it is interesting data. Show both as parallel timelines that share an x-axis, and let users see the divergences themselves.

7. Design position: logbook substrate, not diagnostic

affect-kit's published components capture, render, and aggregate emotion ratings. They do not interpret trajectories or make clinical claims.

Longitudinal interpretation of dimensional affect is genuinely unsettled science. Applying clinical-flavored names like "stuck," "anxious loop," or "resilience score" to regions of V/A space prescribes meaning the data alone doesn't carry. The rater UI uses face, color, and quadrant position as affordances for label selection — navigation aids — not as semantic claims about quadrants themselves. Treating those quadrants as semantically meaningful in longitudinal views would import meaning that the capture flow never asserted.