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.
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
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
Use this pattern when Alex asks for divination tied to an astrological time boundary rather than a random coin cast: Moon degree ingress → next Moon degree ingress, Sun degree ingress → next Sun degree ingress, an Ascendant return window, or any caller-supplied {startUtc,endUtc}.
Core model:
- Treat the boundary interval as the ritual container.
- Divide startUtc → endUtc into exactly 64 equal time segments.
- Map each segment to the Human Design/Rave Mandala gate order, not King Wen order: 41,19,13,49,30,55,37,63,22,36,25,17,21,51,42,3,27,24,2,23,8,20,16,35,45,12,15,52,39,53,62,56,31,33,7,4,29,59,40,64,47,6,46,18,48,57,32,50,28,44,1,43,14,34,9,5,26,11,10,58,38,54,61,60.
- Return the active segment as the primary hexagram/gate, the next segment as context/next field, and optionally the previous segment as the just-completed field.
- Keep this as a stateless utility/API; do not precompute or store high-volume Moon-degree tables unless there is a clear caching need.
Implementation notes:
- The I Ching app can host the pure helper because it already owns the 64-hexagram dataset.
- Transit-list-demo can provide degree-boundary timestamps; the I Ching app should remain generic and accept arbitrary start/end timestamps.
- Add targeted tests for segment index math, wraparound from segment 64 to gate 41, and clamping atUtc into the interval.
- Session reference: references/hd-time-boundary-divination.md.
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
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