---
name: iching-app-development
description: "Class-level patterns for building I Ching apps and features: study-card PWAs, divination coin flows, mandala/wheel visualizations, and faithful text ingestion workflows."
version: 1.0.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [iching, divination, svg, pwa, study-app, flashcards, pdf-extraction]
    related_skills: [mobile-flashcard-pwa, vision-first-book-pdf-extraction, hd-prism-app]
---

# I Ching App Development

## Overview
Use this umbrella for I Ching-class product work: study apps, divination flows, symbolic SVG diagrams, and ingestion of source texts/translations. The maintainable unit is the whole app/domain, not one skill per ritual UI tweak or one mandala task.

## When to Use
- Building or evolving an I Ching study app
- Adding a coin-based divination flow
- Rendering trigrams/hexagrams or mandala-style SVG visualizations
- Importing classical source text from difficult PDFs into structured app data

## 1. Study-app architecture
A good stack for this class of app:
- React + Vite + TypeScript frontend
- Express backend when needed
- PWA deployment via PM2 + nginx
- data-driven hexagram dataset with shared helpers for rendering and lookup

Useful UX principles:
- card/study surface is the product, so keep chrome small
- glyph visuals must be obvious, not merely technically present
- constrain hexagram proportions so they read as traditional tall/narrow stacks
- visual QA matters more than assuming the data binding is wrong

## 2. Coin divination flow
Core rules that worked:
- exactly 3 coins per cast
- Heads/Yang = 3
- Tails/Yin = 2
- odd sum => Yang line, even sum => Yin line
- build 6 lines bottom-up and resolve directly against the dataset

Implementation pattern:
- keep math and lookup in pure helpers (`divination.ts`-style module)
- keep animation and view state in the app shell/component layer
- after six throws, route directly to the matching hexagram detail

UX lessons:
- premium coin visuals matter; generic gold circles feel cheap
- use redundant readability cues (Yin/Yang text, line-shape cues, values) without cluttering the ritual screen
- reserve fixed layout space so status/breakdown text does not cause the CTA to jump during casting
- if CSS animation starts feeling staged, split toss trajectory and coin-body flipping, or move to GSAP

## 3. Mandala / wheel visualization
For concentric I Ching diagrams:
- make line orientation explicit as a product rule, especially whether bottoms face inward
- keep ring-generation logic deterministic and inspectable
- use SVG transforms carefully so each figure stays tangent to the ring while preserving the desired orientation
- if integrating with Human Design or another wheel system, keep one source of truth for gate/hexagram order

## 4. Source-text ingestion
For book-like PDFs with broken text layers but readable page images:
- prefer TOC/bookmark-guided segmentation
- render pages to PNG
- use a vision-first transcription pipeline for fidelity
- preserve page images as source-of-truth references
- merge structured output back into the app dataset, not as loose notes

## Common Pitfalls
1. Treating subtle rendering as a data bug when the real problem is weak visual affordance
2. Mixing divination math with UI state instead of isolating pure helpers
3. Cluttering the casting screen with too much always-visible explanation
4. Using the broken PDF text layer when page-image transcription is clearly better
5. Splitting closely related I Ching work into separate micro-skills instead of one umbrella

## Verification Checklist
- [ ] Hexagram/trigram visuals are easy to perceive in screenshots, not just present in DOM
- [ ] Divination helpers correctly map coin values, parity, and bottom-up line order
- [ ] Six throws resolve to the intended hexagram entry
- [ ] Mandala/wheel orientation rules are consistent and documented
- [ ] Imported source text preserves wording and is linked to source page images