# RULES — Basiri v2 (App 33)

These are hard rules for any agent that builds or edits this app. They are adapted from the `appllama-app-design-skill` in `/.claude/skills/`, from Apple's HIG, and from the Basiri brief, and they are applied to the reference apps studied in `research/`. **A broken rule is a bug, not a matter of taste.**

## 0. Method
1. **Study before drawing.** Every screen names the reference pattern it adopts (see `RESEARCH.md`). Build nothing "from imagination".
2. **Adopt the skeleton, not the pixels.** Take the layout, the hierarchy and the control choices. Never copy logos, brand colours or copy text.
3. **A screen is not done until it has been seen running.** Check it at 320, 390 and 430 px, with long Persian copy, an empty state and a mid-flow state.

## 1. Anti-slop (default bans)
| # | Rule | Check |
|---|---|---|
| A1 | **No gradients** on any surface, button or text | count = 0 |
| A2 | **No glass on content.** Glass is only the system chrome: tab bar, scroll-edge blur and sheet grabber area | glass surfaces ≤ 2 per screen |
| A3 | **One accent, locked:** `#007AFF` (Apple systemBlue) for the primary action, the selected state and progress only | distinct accent hues = 1 |
| A4 | **One semantic extra:** `#FF9500` (gold) marks a *comeback day* dot and nothing else | used only in `.dot.back` |
| A5 | **One grey family:** Apple system cool greys (`#F2F2F7`, `#E5E5EA`, `#C7C7CC`, label alphas of `#3C3C43`) | no warm greys |
| A6 | **No emoji** in the UI. No sparkles, orbs or AI auras | 0 |
| A7 | **No decorative imagery.** A photo appears only when the user created it (evidence) or when it is a person (avatar) | 0 stock heroes |
| A8 | **One label per intent:** start = «شروع», save = «ثبت», dismiss = «لغو», done = «انجام شد» | no synonyms |
| A9 | **No confetti, pulses or looping animations** | 0 infinite animations |
| A10 | **No card spam.** Content lives in the timeline or in inset-grouped lists. Cards only for a live, active item | ≤ 1 card per screen |
| A11 | **No stats for decoration.** Every number must answer a question the user has | justified per number |

## 2. Shape lock
- **Controls:** capsule (buttons, segmented control, text fields, chips, tab bar).
- **Inset-grouped lists and the one live card:** radius **26**, continuous corners. The iOS 26 value is 26.
- **Avatars, timeline nodes and checkmarks:** circles.
- **Nothing else** is allowed. No 8, 12, 16 or 20 radii anywhere.

## 3. Type (Vazirmatn; Estedad only for the Large Title)
| Style | Size / line-height / weight |
|---|---|
| Large Title | 34 / 1.3 / 800 (Estedad), exactly one per screen |
| Title 2 | 22 / 1.45 / 700 (article titles only) |
| Headline | 17 / 1.55 / 600 |
| Body | 17 / 1.75 / 400 |
| Callout | 16 / 1.6 / 400 |
| Subhead | 15 / 1.55 / 400 |
| Footnote | 13 / 1.5 / 400 |
| Caption | 12 / 1.4 / 500 |

- **Numbers:** anything that counts, times or costs uses Persian digits with `tabular-nums`.
- **Emphasis:** use weight only, from the same family. Never switch typeface mid-sentence.

## 4. Colour roles
| Token | Value |
|---|---|
| `--bg` | #FFFFFF |
| `--grouped` | #F2F2F7 (list sections on white) |
| `--label` | #000 |
| `--label-2` | rgba(60,60,67,.6) |
| `--label-3` | rgba(60,60,67,.3) |
| `--sep` | rgba(60,60,67,.18) at 0.5px |
| `--fill` | rgba(120,120,128,.12) |
| `--accent` | #007AFF |
| `--accent-bg` | rgba(0,122,255,.1) (selected rows, current timeline node) |
| `--back` | #FF9500 (comeback dot only) |
| `--destructive` | #FF3B30 (delete only) |

## 5. Navigation grammar (fixed)
- **Tab bar:** physical order left→right **من | هم‌مسیر | راهنما | مسیر من | امروز**.
  - 5 equal items; no centre FAB; labels always shown.
  - The active tab uses the filled icon and the accent colour.
  - Tabs **never animate content**. The switch is instant, and each tab keeps its own stack.
  - Re-tapping the active tab pops to its root.
- **Push** (slides from the left in RTL, 350 ms native curve) is for reading and drilling in: lesson, guide answer, member, chapter. The back chevron points right and carries the previous title.
- **Modal** (page sheet, «لغو» on the leading side and «ثبت» on the trailing side) is for self-contained tasks: commitment and reflection.
- **Form sheet** (medium detent, grabber) is for short interruptions: evidence type, comeback plan.
- **One-way doors:** after «ثبت» on a commitment or reflection, back never reopens the old state; the timeline moves forward.
- **Large Title** collapses into an inline title with a scroll-edge blur after 40 px. Never hand-roll a coloured header.

## 6. Motion (frequency gate)
| Frequency | Motion |
|---|---|
| Tab switch, scroll, back | Platform default only |
| Press | Buttons scale 0.97 in 100 ms (`cubic-bezier(.23,1,.32,1)`). Rows get a background highlight, never a scale |
| Push / modal / sheet | 350–420 ms, strong ease-out. Exits are faster than entrances |
| Completion | Checkmark fades and scales 0.6 → 1 in 180 ms, with one haptic |
| **Forbidden** | Entrance animations on lists, looping motion, bounce without a gesture |

**Reduce Motion:** every transition becomes a 150 ms cross-fade.

## 7. Product rules (Basiri brief)
- **Today** answers "what matters now" in one glance. It is a **timeline of the loop**: Learn → Commit → Act → Evidence → Reflect.
  - The current node carries **the only primary button on screen**.
  - It is not a dashboard, not a checklist of unrelated tasks, and not a pile of cards.
- **Recovery** never shames and never resets a streak.
  - After a pause, the timeline opens with a grey interval note and one comeback node (10 minutes, the same work).
  - There are no streak counters anywhere.
- **Guide** always shows what it knows (path, step, last reflection) before any input. It is never a blank chat.
- **Circle (هم‌مسیر)** is a small circle of people with states and one shared pact. It has no feed, no followers and no likes count.
- **Me** is memory: patterns, then a timeline, then settings last.
- **My Path** is a sequence with a clear "you are here". It is not a catalogue.

## 8. States every screen ships
The default, pressed, disabled, loading, empty, completed, interrupted and recovery states must all be designed. A disabled primary button has 30% opacity and is **explained** by a footnote.

## 9. Accessibility
- Tap targets are at least 44 pt.
- Contrast is at least 4.5:1 for text; accent on white is 6.2:1.
- Every control has an `aria-label` in Persian.
- Reduce Motion and Reduce Transparency are honoured.

## 10. Pre-flight (run before every hand-off)
- [ ] Accent hues: 1 (+ the gold comeback dot)
- [ ] Radii: only capsule / 26 / circle
- [ ] Gradients: 0 · Emoji: 0 · Infinite animations: 0
- [ ] Primary buttons visible at once: ≤ 1
- [ ] Tab x-order checked in the DOM: من is leftmost and امروز is rightmost
- [ ] No text overflow at 320 px