Update documentation to reflect current implementation (6 trials, Iqra University context, Firebase storage)

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 [Your Name/Organization]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,225 @@
+# UI Conformity Experiment
+
+> **Beta UI Diagnostic Dashboard**: A behavioral research tool investigating AI authority bias in user interface design preferences
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Overview
+
+This repository contains a web-based behavioral experiment designed to investigate whether "AI Recommended" labels influence users' UI design preferences. The study employs a randomized between-subjects design to measure conformity effects in human-computer interaction.
+
+### Research Question
+
+**Does an "AI Recommended" label influence users' UI design preferences?**
+
+## Quick Start
+
+```bash
+# Clone the repository
+git clone https://github.com/hashexplaindata/Conformity-experiment.git
+cd Conformity-experiment
+
+# Start a local server
+python -m http.server 8000
+
+# Access the experiment
+# Control condition: http://localhost:8000/code/index.html?condition=control
+# AI label condition: http://localhost:8000/code/index.html?condition=ai
+```
+
+## Project Structure
+
+```
+Conformity-experiment/
+├── code/                          # Application files
+│   ├── index.html                 # Main experiment page (147 lines)
+│   ├── experiment.js              # Core behavioral engine (489 lines)
+│   └── style.css                  # Styling & animations (281 lines)
+├── docs/                          # Documentation & ethics
+│   ├── README.md                  # Quick reference guide
+│   ├── METHODS.md                 # Formal research methodology
+│   ├── RUNBOOK.md                 # Step-by-step operational guide
+│   ├── IRB_CHECKLIST.md           # Ethics compliance checklist
+│   ├── CONSENT.txt                # Participant consent form
+│   └── DEBRIEF.txt                # Post-study disclosure
+├── .github/workflows/             # CI/CD pipelines
+│   └── codeql.yml                 # Security scanning
+├── firebase.json                  # Firebase hosting configuration
+└── .firebaserc                    # Firebase project reference
+```
+
+## Experimental Design
+
+### Conditions
+
+- **Control Group**: Views 6 pairs of UI mockups with neutral labels ("Option A" / "Option B")
+- **Treatment Group**: Views identical pairs with "✨ AI Recommended" badges on designated options
+
+### Trial Domains (Iqra University Context)
+
+1. **Information Density** - Course Schedule (List vs. Grid)
+2. **Data Visualization** - HEC Attendance Warning (Circular gauge vs. Progress bar)
+3. **Financial Overview** - Fee Voucher (Card vs. Centered layout)
+4. **Campus Event** - Event Display (Visual-dominant vs. Compact)
+5. **Interaction** - QEC Faculty Evaluation (Radio buttons vs. Slider)
+6. **Navigation** - Digital Library (Floating search vs. Header-integrated)
+
+### Data Collection
+
+Each participant record captures:
+- **Primary DV**: Whether the AI-labeled option was selected
+- **Reaction time**: Millisecond-accurate (`performance.now()`)
+- **AI familiarity**: 5-point Likert scale covariate
+- **Semantic justification**: Free-text explanation (optional)
+- **Metadata**: UUID, condition, trial sequence, timestamps
+
+## Features
+
+### Technical Highlights
+
+- 🎯 **Client-side randomization** - 50/50 condition assignment
+- ⚡ **Millisecond-accurate telemetry** - `performance.now()` reaction time tracking
+- 🔥 **Firebase integration** - Automatic Firestore sync (`conformity_telemetry` collection)
+- 🎨 **Modern UI** - Dark theme with Bento grid design and radial glow effects
+- 🔒 **Privacy-first** - Anonymous UUIDs, no PII collection
+- 📱 **Responsive** - Mobile and desktop compatible
+- 🚫 **Anti-manipulation** - Browser back-navigation prevention
+
+### Research Features
+
+- Counterbalanced AI badge assignment
+- Randomized trial order
+- Left/Right position randomization (prevents motor habituation)
+- Covariate collection (AI familiarity)
+- Qualitative data capture (semantic justification)
+
+## Deployment Options
+
+### 1. Local Development
+```bash
+python -m http.server 8000
+```
+
+### 2. Firebase Hosting
+```bash
+npm install -g firebase-tools
+firebase login
+firebase deploy --only hosting
+```
+
+### 3. GitHub Pages
+1. Enable in repository Settings > Pages
+2. Access at: `https://[username].github.io/Conformity-experiment/code/index.html?condition=control`
+
+### 4. Netlify
+1. Drag `code/` folder to [app.netlify.com/drop](https://app.netlify.com/drop)
+2. Share generated URL with condition parameters
+
+## Documentation
+
+| Document | Purpose |
+|----------|---------|
+| [`docs/README.md`](docs/README.md) | Quick reference and file overview |
+| [`docs/METHODS.md`](docs/METHODS.md) | Formal research methodology (copy-paste ready) |
+| [`docs/RUNBOOK.md`](docs/RUNBOOK.md) | Step-by-step operational guide for running sessions |
+| [`docs/IRB_CHECKLIST.md`](docs/IRB_CHECKLIST.md) | 15-point ethical review checklist |
+| [`docs/CONSENT.txt`](docs/CONSENT.txt) | Participant informed consent template |
+| [`docs/DEBRIEF.txt`](docs/DEBRIEF.txt) | Post-study disclosure statement |
+
+## Ethical Considerations
+
+✅ **IRB-Ready**: Includes informed consent, debrief, and ethics checklist
+✅ **Minimal Risk**: Viewing UI mockups only
+✅ **Voluntary**: Participants can withdraw at any time
+✅ **Anonymous**: UUID-based identification, no PII
+✅ **Transparent**: Full disclosure of manipulation in debrief
+✅ **Withdrawal Rights**: 7-day data withdrawal window with Participant ID
+
+## Requirements
+
+- **Browser**: Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
+- **Server** (optional): Python 3.x, Node.js, or any HTTP server
+- **Firebase** (optional): For data persistence and hosting
+
+## Data Format
+
+Data is stored in **tidy data long format** with the following schema:
+
+```javascript
+{
+  participant_id: "abc123xyz...",           // Anonymous UUID
+  experimental_condition: "ai_labeled",      // "control" or "ai_labeled"
+  ai_familiarity_covariate: 3,              // 1-5 Likert scale
+  trial_sequence: 1,                         // 1-6
+  ui_domain: "Information Density...",       // Trial category
+  ai_badge_position: "B",                    // "A", "B", or "none"
+  user_selection: "B",                       // "A" or "B"
+  chose_target_layout: true,                 // Boolean
+  reaction_time_ms: 2341,                    // Milliseconds
+  semantic_justification: "I prefer...",     // Free text
+  timestamp: 1710278400000                   // Unix ms
+}
+```
+
+## Usage
+
+### For Researchers
+
+1. Review [`docs/METHODS.md`](docs/METHODS.md) for study design
+2. Follow [`docs/RUNBOOK.md`](docs/RUNBOOK.md) for session operations
+3. Complete [`docs/IRB_CHECKLIST.md`](docs/IRB_CHECKLIST.md) for ethics approval
+4. Configure Firebase credentials (or use localStorage fallback)
+5. Deploy and share condition-specific URLs with participants
+
+### For Developers
+
+```javascript
+// Configuration
+const CFG = {
+    NUM_TRIALS: 6,
+    CONDITION: 'ai_labeled' | 'control',
+    COLLECTION: 'conformity_telemetry'
+};
+
+// Trial definition structure
+const TRIAL = {
+    domain: 'Trial Category Name',
+    renderA: () => `<div>...</div>`,  // Option A HTML
+    renderB: () => `<div>...</div>`,  // Option B HTML
+    target: 'A' | 'B'                  // Hypothesized preference
+};
+```
+
+## Contributing
+
+This is an academic research project. For questions or collaboration inquiries, please open an issue.
+
+## License
+
+MIT License - See [LICENSE](LICENSE) for details
+
+## Citation
+
+If you use this experiment framework in your research, please cite:
+
+```bibtex
+@software{conformity_experiment_2026,
+  title = {UI Conformity Experiment: AI Authority Bias in Interface Design},
+  author = {[Your Name]},
+  year = {2026},
+  url = {https://github.com/hashexplaindata/Conformity-experiment}
+}
+```
+
+## Acknowledgments
+
+- Built with vanilla JavaScript for maximum portability
+- Firebase for data persistence
+- Iqra University and Pakistan HEC for contextual realism
+
+---
+
+**Version**: 2.0 | **Last Updated**: 2026-03-12 | **Status**: Production Ready
+
+For operational guidance, see [`docs/RUNBOOK.md`](docs/RUNBOOK.md)
+For methodology details, see [`docs/METHODS.md`](docs/METHODS.md)

docs/IRB_CHECKLIST.md

@@ -11,12 +11,12 @@
 | 5 | Minimal risk | YES | Task involves viewing UI mockups and clicking |
 | 6 | Deception disclosed | YES | Debrief explains AI label manipulation |
 | 7 | Debrief provided | YES | Available at study completion and as DEBRIEF.txt |
-| 8 | Data security | YES | Data stored locally on participant devices |
+| 8 | Data security | YES | Data synced to Firebase Firestore with secure access rules |
 | 9 | No vulnerable populations targeted | YES | 18+ adults only |
 | 10 | Aggregate reporting only | YES | No individual results published |
 | 11 | Contact information provided | YES | Researcher contact in consent and debrief |
 | 12 | No physical or psychological harm | YES | Viewing interface designs only |
-| 13 | Data retention policy | N/A | Local CSV files; no server storage |
+| 13 | Data retention policy | YES | Firebase cloud storage with configurable retention |
 | 14 | Compensation disclosed | N/A | No compensation offered |
 | 15 | Conflicts of interest | NONE | Academic research only |
 
@@ -33,4 +33,4 @@
 - [ ] Approval #: _______________
 
 ---
-_Template version: 1.0 | 2026-02-27_
+_Template version: 2.0 | 2026-03-12_

docs/METHODS.md

@@ -18,58 +18,51 @@ Participants were recruited from [classroom / online panel]. Inclusion criteria:
 
 A between-subjects experimental design with two conditions:
 
-- **Control condition:** Participants viewed 8 pairs of UI mockups with neutral labels ("Option A" / "Option B") and selected their preferred design.
-- **AI Label condition:** Participants viewed the same 8 pairs, but one option in each pair displayed a "★ AI Recommended" badge.
+- **Control condition:** Participants viewed 6 pairs of UI mockups with neutral labels ("Option A" / "Option B") and selected their preferred design.
+- **AI Label condition:** Participants viewed the same 6 pairs, but one option in each pair displayed a "✨ AI Recommended" badge.
 
 Assignment to conditions was randomized (50/50) using client-side JavaScript random number generation at the point of entry.
 
 ## Stimuli
 
-Eight pairs of high-fidelity UI mockups were created covering common interface patterns:
+Six pairs of high-fidelity UI mockups were created covering common interface patterns in the context of Iqra University and Pakistan Higher Education Commission (HEC):
 
-1. E-commerce product card (button color: blue vs. green)
-2. Settings page (toggle alignment: left vs. right)
-3. Analytics dashboard widget (chart type: bar vs. line)
-4. Signup form (CTA copy: "Sign Up" vs. "Get Started")
-5. Pricing table (highlighted tier: Basic vs. Pro)
-6. Navigation sidebar (icon style: outlined vs. filled)
-7. Notification banner (position: top vs. inline)
-8. Search results (layout: list vs. grid)
+1. **Information Density (Course Schedule)** - List view vs. Bento grid layout
+2. **Data Visualization (HEC Attendance Warning)** - Circular gauge with 78% attendance vs. Linear progress bar
+3. **Financial Overview (Fee Voucher)** - Card-based layout vs. Centered layout for semester fees
+4. **Campus Event (Visual Dominance)** - Visual-dominant poster vs. Compact text-heavy layout
+5. **Interaction (QEC Faculty Evaluation)** - Radio button scale vs. Interactive slider for rating
+6. **Navigation Hierarchy (Digital Library)** - Floating search button vs. Header-integrated search
 
-Each pair shared identical layout and functionality, differing only in a single design attribute. Pairs were rendered as CSS/HTML mockups within the experiment page. In the AI condition, one option per pair received a visually prominent "★ AI Recommended" badge. The assignment of which option received the badge was counterbalanced across pairs.
+Each pair shared identical content and functionality, differing only in a single design attribute (layout pattern, visualization type, or interaction method). Pairs were rendered as inline CSS/HTML mockups within the experiment page. In the AI condition, one option per pair received a visually prominent "✨ AI Recommended" badge. The assignment of which option (A or B) received the badge was predetermined based on hypothesized modern design preferences (e.g., Bento grid over list, circular gauge over bar chart).
 
 ## Procedure
 
-1. Participants accessed the experiment via a URL that randomly redirected them to one of two conditions.
+1. Participants accessed the experiment via a URL with condition parameter (`?condition=control` or `?condition=ai`).
 2. A welcome screen explained the task and obtained informed consent.
-3. Participants completed 8 trials presented in randomized order.
-4. On each trial, two UI mockups appeared side-by-side (left/right placement randomized).
-5. Participants clicked to select their preferred design.
-6. After selection, they rated their confidence on a 5-point scale (1 = not at all confident, 5 = very confident).
-7. Upon completion, participants saw a summary and could download their responses.
+3. Participants rated their AI familiarity on a 5-point Likert scale (covariate: 1=Never used → 5=Daily user).
+4. Participants completed 6 trials presented in randomized order.
+5. On each trial, two UI mockups appeared side-by-side (left/right placement randomized).
+6. Participants clicked to select their preferred design.
+7. Reaction time was automatically captured using `performance.now()` for millisecond accuracy.
+8. After all trials, participants provided an optional free-text justification explaining their selection strategy.
+9. Upon completion, participants saw a confirmation screen with their anonymous Participant ID and data sync status.
 
 ## Measures
 
-- **Primary DV:** Choice (A or B) — coded as whether the AI-preferred option was selected
+- **Primary DV:** Choice (A or B) — coded as whether the AI-labeled option was selected (`chose_target_layout` boolean)
 - **Secondary DVs:**
-  - Confidence rating (1–5 Likert scale)
-  - Reaction time (ms) — time from trial display to choice click
-- **Between-subjects IV:** Condition (control vs. AI label)
-- **Metadata:** Participant UUID, trial order, pair ID, timestamp
-
-## Metadata
-
-- Participant UUID
-- Condition (control vs. AI label)
-- AI familiarity covariate
-- Trial sequence
-- UI domain
-- AI badge position
-- User selection
-- Choice (target layout)
-- Reaction time (ms)
-- Semantic justification
-- Timestamp
+  - Reaction time (ms) — Time from trial display to choice click, measured via `performance.now()`
+  - Semantic justification — Free-text explanation of decision-making strategy (optional)
+- **Between-subjects IV:** Condition (`control` vs. `ai_labeled`)
+- **Covariate:** AI familiarity (1–5 Likert scale: Never used, Rarely, Occasionally, Frequently, Daily)
+- **Metadata:**
+  - Participant UUID (anonymous identifier)
+  - Trial sequence (1-6, randomized order)
+  - UI domain (trial category name)
+  - AI badge position (which option had the badge: "A", "B", or "none" for control)
+  - User selection ("A" or "B")
+  - Timestamp (Unix milliseconds)
 
 ## Ethics
 
@@ -79,7 +72,8 @@ Each pair shared identical layout and functionality, differing only in a single
 - A debrief statement was provided upon completion explaining the true purpose of the study and the manipulation.
 - Participants could withdraw at any time by closing their browser.
 - The study involved minimal risk (viewing interface mockups and clicking preferences).
-- Data was stored locally on participant devices (CSV download) and not transmitted to external servers.
+- Data was synced to Firebase Firestore (`conformity_telemetry` collection) with fallback to localStorage for offline participants.
+- Participants were informed they could request data withdrawal within 7 days using their Participant ID.
 
 ---
-_Copy-paste this text into your Methods section. Update bracketed placeholders as needed._
+_Last updated: 2026-03-12 | Copy-paste this text into your Methods section. Update bracketed placeholders as needed._