# AQWUM Requirements · v2 (from Hala screenshots, May 27 2026)

> Source: two annotated mockups — **Home / Life Structure** and **Today's Practices** — capturing the system perspective and depth of requirements for AQWUM across every surface (web landing, methodology, LifeMap, onboarding, future mobile). The screenshots are **not** mobile-only; they show the canonical model the rest of the site must align with.
> Authority: this document, then `AQWUM-METHODOLOGY.md`, then the screenshots themselves.

---

## 1 · Vocabulary shifts and new primitives

The mobile mockups introduce vocabulary and a structural depth that the current web demo does not yet model. Sync everything to this list before continuing implementation.

### 1.1 Scalar state indicators (top of Home)

| Indicator | Range | Sub-label | Meaning |
|---|---|---|---|
| **Focus Score** | 0.00–1.00 | "Slightly Scattered" / "Focused" / etc. | Composite score: how concentrated the user is across objectives this week. Driven by variance in objective load + completion ratio. |
| **Nafs State** (نفس) | 0–100 | "Overall Health" | Soul/self state. A single scalar that summarizes the five-sphere capacity. Habits/practices either lift or drain it (see §3.4). |

These replace the abstract methodology vocabulary on the mobile surface. **Both must be visible at all times on the Home page.**

### 1.2 The three-tier hierarchy (mandatory)

The mobile model has **three** levels, not two:

```
Objective
  └── Habit
        └── Practice
```

| Level | Examples (from screenshots) | Owns |
|---|---|---|
| **Objective** | Be Healthy · Grow as Engineer · Be Mindful · Build Connections | Description · weekly hour budget · % completion · 1+ habits · color · active/paused state · archive flag |
| **Habit** | Cardio Training · Strength Building · React Mastery · Meditation Practice | Frequency (Daily, 3×/week, etc.) · target completion (e.g. "1/3 this week") · % completion · 1+ practices |
| **Practice** | Morning Run · Evening Walk · React Tutorial · Build Side Project | Duration · energy type · Nafs impact · checked/unchecked state · individual timer |

**This is a contract.** Every UI surface that currently uses two levels (Theme → Habit) must be re-mapped to three levels. The current "habit" in the LifeMap corresponds to **Habit** here, and we must add a Practice layer below it.

### 1.3 Energy types (4, not 5)

The mobile UI uses **four** energy types as chips on each practice:

| Energy | Glyph | Color in mocks | Maps to current methodology |
|---|---|---|---|
| **⚡ Physical** | ⚡ | green | Body sphere |
| **🧠 Mental** | 🧠 | cyan | Mind + Brain spheres (collapsed) |
| **❤️ Emotional** | ❤️ | pink | Heart sphere |
| **🔮 Spiritual** | 🔮 | purple | Soul sphere |

**Decision required:** keep the 5-sphere model in methodology + map to 4 on mobile, OR drop "Brain" as a separate sphere and unify to 4 everywhere. Recommendation: **keep 5 in methodology** (for the anatomical accuracy in §4.2 of `AQWUM-METHODOLOGY.md`), **render 4 on mobile** (Mind + Brain collapse into "Mental"). The Nafs scalar still aggregates all five.

### 1.4 Nafs impact per practice

Every practice carries a Nafs-state delta:

- `+N` (positive) — the practice **lifts** Nafs when completed. Spiritual + Emotional practices tend to be positive.
- `−N` (negative) — the practice **drains** Nafs when scheduled but not balanced. Mental/Physical can be neutral or net-negative if over-allocated.

The number shown next to the chip is the **per-completion impact**. Examples from screenshots:
- Morning Meditation · Spiritual · `+7`
- Evening Reflection · Emotional · `+4`
- Coffee with Friends · Emotional · `+4`
- Strength Training · Physical · `−5`
- React Tutorial · Mental · `−5`
- Build Side Project · Mental · `−5`
- Read System Design · Mental · `−5`
- Deep Work Session · Mental · `−7`
- Morning Run · Physical · `−0`
- Calorie Tracking · Mental · `−0`

**Implication:** mental practices tend toward `−` (cognitive load); spiritual/emotional toward `+`. This produces the **need for spiritual practice** the methodology talks about — without it, Nafs depletes.

---

## 2 · Home / Life Structure screen requirements

### 2.1 Header

- Brand (AQWUM logo + name) on left
- Notification bell with red dot (unread)
- Profile icon

### 2.2 Greeting

- `Welcome back, {firstName}` — bold weight on the name.

### 2.3 Scalar cards (2 columns)

- **Focus Score** card: sparkle icon, value (0.65), sub-label ("Slightly Scattered"). Yellow tint when scattered, green when focused.
- **Nafs State** card: pulse icon, value (75), sub-label ("Overall Health"). Color tracks value — cyan/green at high, yellow at mid, pink/red at low.

### 2.4 Navigation tiles (3 cards)

| Tile | Subtitle | Destination |
|---|---|---|
| **Schedule View** | Week & day planning | Timeline view (existing `#roadmap`) |
| **Progress** | "A reflection of how your actions shape your path" | Stats/history view (new) |
| **Your identity** | "The path you were meant for" | Identity card / North Star view (new) |

**Your identity** is visually larger and brighter — it's the **North Star tile** (T5 from earlier plan).

### 2.5 Life Structure section

Header: `Life Structure` with `↓ Archive` action top-right (jumps to archived objectives).

Then a vertical list of **Objective cards**, each with:

| Element | Notes |
|---|---|
| Icon | Auto-chosen per objective (heart, code brackets, brain, people) |
| Title | e.g. "Be Healthy" — bold |
| Habit count pill | "3 habits" — colored chip |
| Description | Subtitle text — purpose statement |
| Weekly budget | `12h / 18h per week` — actual / planned |
| Completion ring | Big circular % indicator on the right |
| Expand chevron | Collapses/expands the habit list below |
| Power icon | Active / Paused toggle (orange when active) |
| Archive icon | Quick-archive (cyan) |

When expanded, the **Habit rows** appear:

| Element | Notes |
|---|---|
| Bullet/target icon | Color matches objective |
| Habit name | e.g. "Cardio Training" |
| Frequency | e.g. "5x/week" |
| Completion fraction pill | e.g. "1/3" — completed this week / target this week |
| Progress bar | Same color as objective; shows weekly % |
| Expand chevron | Reveals practices |

When the habit is expanded, **Practice rows** appear:

| Element | Notes |
|---|---|
| Checkbox circle | Filled green if today's instance is complete |
| Practice name | e.g. "Morning Run" |
| Duration | e.g. "30 min" |

Paused objectives ("Build Connections" in mock) appear at the bottom under a `Paused` separator with reduced opacity and a `Manage` button instead of expand.

### 2.6 Bottom navigation

Five tabs, the first three currently mapped:

| Tab | Icon | Purpose |
|---|---|---|
| **Home** | house | This screen |
| **Timeline** | layers | LifeMap year/week/day views |
| **State** | pulse | Stamina spheres + Nafs detail + Compass |
| **Practices** | target | Today's practices list (next screen) |
| **Budget** | clock | Time-budget tracker (BETA engine surface) |

---

## 3 · Today's Practices screen requirements

### 3.1 Header

- `Today's Practices`
- `{n} of {total} completed` (e.g. "4 of 10 completed")

### 3.2 Daily Progress bar

- Full-width gradient progress bar
- % label on the right (e.g. 40%)

### 3.3 Practice cards (vertical list)

Order: **roughly chronological by scheduled time, BUT completed ones float to top** (greyed/strikethrough).

Each card contains:

| Row | Elements |
|---|---|
| Top | Checkbox circle · Practice name · arrow link (→) |
| Meta chips row | Habit-name chip (purple) · frequency · clock+duration |
| Energy + Nafs row | Energy-type chip with icon · Nafs-impact pill (`+N` green up-arrow, `−N` pink down-arrow) |
| Action row | "Start Timer" button (cyan) with duration on the right |

**Completed cards** are visually distinct:
- Strikethrough on the practice name
- Lighter background tint
- Filled green checkbox
- No Start Timer button (already done)

### 3.4 Daily Insight footer card

- "🌱 Every small step counts. Start with one practice!"
- A motivational/Identity-anchor line. May surface a Qurʾānic anchor if one is configured.

---

## 4 · Computation rules

### 4.1 Focus Score formula

```
focus = 1 − normalised_variance(load_per_objective)
        × completion_ratio_this_week
        × identity_alignment_factor
```

Where:
- `normalised_variance` rises when load is spread thin across many objectives
- `completion_ratio` is `practices_completed / practices_scheduled` this week
- `identity_alignment_factor` is `1.0` if all habits map to active objectives, lower if there's drift practice

Sub-labels by range:
- `≥ 0.85` → **Sharply focused**
- `0.65–0.85` → **Focused**
- `0.45–0.65` → **Slightly Scattered**
- `< 0.45` → **Scattered**

### 4.2 Nafs State formula

```
nafs = base 50
     + Σ (completed_practice.nafs_impact, in last 7 days)
     − Σ (overdue_practice.penalty)
     × seasonal_modifier (from §5.2 Four-Humors)
     clamp 0..100
```

A practice with `+7` adds 7 to Nafs when completed. A practice with `−5` removes 5 when scheduled but not balanced. Spiritual practices always contribute positive; mental can go negative when over-clustered.

Sub-labels by range:
- `≥ 85` → **Lifted**
- `70–85` → **Overall Health**
- `50–70` → **Steady**
- `30–50` → **Drained**
- `< 30` → **Depleted**

### 4.3 Objective completion %

```
% = (Σ habit_completion %) / habit_count
```

### 4.4 Habit completion %

```
% = practices_completed_this_week / target_this_week
```

Where `target_this_week` is computed from the habit's frequency (Daily = 7, 3×/week = 3, etc.).

---

## 5 · Data model changes

### 5.1 Schema

```ts
type Objective = {
  id: string;
  name: string;
  description: string;          // "Maintain physical wellness and build strength"
  icon: string;                 // heart, code, brain, people
  color: string;                // hex
  weeklyBudgetHours: number;    // planned (e.g. 18)
  paused: boolean;
  archived: boolean;
  priority: number;             // ordering for archive/auto-drop
};

type Habit = {
  id: string;
  objectiveId: string;
  name: string;                 // "Cardio Training"
  frequency: 'daily' | { perWeek: number };
  priority: number;             // ordering for drop-one-for-me
  practices: Practice[];        // 1+ practices
};

type Practice = {
  id: string;
  habitId: string;
  name: string;                 // "Morning Run"
  durationMin: number;          // 30
  energy: 'physical' | 'mental' | 'emotional' | 'spiritual';
  nafsImpact: number;           // +7, -5, etc.
  scheduledAt?: string;         // ISO time
  sequenceCapacity?: number;    // for chained practices (T6 in plan)
  sequenceNext?: string;        // id of next practice when capacity consumed
};

type Day = {
  date: string;
  practiceInstances: { practiceId: string; completed: boolean; completedAt?: string }[];
};
```

### 5.2 Migration from current LifeMap model

| Current field | New field | Notes |
|---|---|---|
| `theme.id, name, hex` | `objective.id, name, color` | Direct map |
| `theme.start, end, partial, archived, version` | `objective.archived, paused` | Drop start/end (we're trait-level now) |
| `habit.id, themeId, name, dur, freqWk, energies, hArchived, priority` | Split into `habit` + `practice` | Each old "habit" becomes a Habit with one or more Practices. `dur` moves to Practice. Energy weights collapse to 4 types per Practice. |
| `nowWeek` | `currentDate` | |
| `outState` | unchanged | |

---

## 6 · Pages & routes (planned for this work stream)

| Path | Status | Notes |
|---|---|---|
| `mobile.html` | **new** | Preview of the two mockup screens — useful as a reference frame, not a mobile-only product. The real model applies everywhere. |
| `index.html#roadmap` | refactor | LifeMap rewired to three-tier hierarchy. Energy stack now uses 4 types. Add Nafs scalar overlay. |
| `index.html` | hero update | Show Focus Score + Nafs State sample on the landing. |
| `onboarding.html` | extend | Practice configuration step (after Habit config). |
| `methodology.html` | extend | Add a component showing the three-tier hierarchy + Focus/Nafs scoring formulas as interactive widgets. |

---

## 7 · Implementation sequence

**Phase A — preview page** (this turn): `mobile.html` showing both screens side-by-side as a mobile-frame mock, using the new data model. Validates the model end-to-end without breaking existing pages.

**Phase B — refactor LifeMap** (next): rewire `index.html#roadmap` to three-tier hierarchy. Energy stack now uses 4 types. Add Nafs scalar overlay.

**Phase C — onboarding extension**: after Habit configuration (existing step 03), add **Practice configuration** step that picks practices inside each habit with duration + energy + Nafs impact.

**Phase D — North Star tile**: "Your identity" tile becomes a full screen showing the 5-10y Identity goal + Cyclone snapshot.

**Phase E — bottom tabs**: build State (sphere details + Nafs history) and Budget (time-budget tracker) screens.

---

## 8 · Open questions

1. **Focus Score weighting** — is variance the right primary signal, or should completion ratio dominate?
2. **Nafs impact source** — do we ask the user during onboarding ("how does this practice make you feel?") or pre-fill from a catalogue?
3. **Practice scheduling** — is `scheduledAt` an explicit time (e.g. 06:30), a window (morning/evening), or unbound (just "today")?
4. **Sequence capacity** — when a Practice has e.g. 22h of Chapter 1, do we model "Chapter" as a sub-Practice or as a Practice with `sequenceCapacity` countdown?

Mark these in the next iteration after seeing the preview.

---

## 9 · Changelog

| Date | Change |
|---|---|
| 2026-05-27 | v1.0 — derived from Hala mobile mockups (Home + Today's Practices). Three-tier hierarchy locked. Phase A authored. |