iching-study-app

I Ching Study App

Project-specific guide for working on Alex's I Ching Study app.

App Overview

• Path: /home/avalon/apps/iching-study
• URL: https://iching-study.apps.poofc.com
• Stack: React 19 + Vite + TypeScript + Express
• PM2 process: iching-study
• Repo: firemountain/iching-study

Build + Deploy

Always use the app's build command, then restart PM2, then verify the built asset timestamps.

cd /home/avalon/apps/iching-study
npm run build
pm2 restart iching-study
pm2 save
stat dist/assets/index-*.css dist/assets/index-*.js

Then visually verify the live site at https://iching-study.apps.poofc.com.

Core UI Files

• Main app UI: src/App.tsx
• Styling: src/index.css
• Hexagram data: src/data/hexagrams.ts
• Divination helpers: src/lib/divination.ts
• Human Design center quiz geometry: src/lib/humanDesignCenters.ts
• Divination + quiz tests: src/App.test.tsx, src/lib/divination.test.ts

Human Design Center Quiz

The app now includes a quiz section for memorizing which Human Design gates/hexagrams belong to which centers, plus the gate's exact visual slot within each center.

Product expectations

• Sidebar includes a Quiz section entry separate from study/divination/admin.
• Quiz home should act as a landing screen so more quizzes can be added later.
• First quiz should be Human Design centers.
• Prompt should show:
• gate number
• hexagram name
• hexagram character
• hexagram line figure
• User must answer by tapping the exact numbered slot on the correct center card, not by picking only the center name.
• This trains both center recall and positional recall so channel study can be layered on later.

Reusable implementation pattern

• Keep quiz routing lightweight inside src/App.tsx by extending ViewMode with quiz and using a small activeQuizId for sub-quiz selection.
• Keep reusable Human Design center geometry in a dedicated module: src/lib/humanDesignCenters.ts.
• Store per-center SVG path data, viewBox, label, fill color, and gate point coordinates in that module.
• Derive GATE_TO_CENTER, ALL_HUMAN_DESIGN_GATES, and helper lookups from the shared center data so tests/UI stay in sync.
• For prompts, reuse the existing hexagrams.ts dataset so gate = hexagram and the quiz can display the standard line glyph.

Where the geometry came from

The correct source of truth was the HD Prism app on the same server, not a hand-made recreation.

Use these HD Prism sources: - center shapes / bodygraph SVG: /home/avalon/apps/hd-prism/apps/hdprism/public/svg/empty-bodygraph.svg - gate-to-center mapping: /home/avalon/apps/hd-prism/apps/hdprism/lib/constants.ts - placement logic reference: /home/avalon/apps/hd-prism/apps/hdprism/components/BodygraphScreen.tsx

Practical extraction lesson

The fastest reusable workflow was: 1. Read constants.ts for gate-to-center truth. 2. Read BodygraphScreen.tsx to understand how gate labels were placed on the SVG. 3. Extract center SVG paths and channel endpoints from empty-bodygraph.svg. 4. Build a compact local data file in the I Ching app (src/lib/humanDesignCenters.ts) rather than coupling directly to HD Prism runtime code.

This is better than trying to import HD Prism components directly because the I Ching app only needs stable geometry + mappings, not the whole bodygraph renderer.

UX lessons learned

• The quiz works better when every center card shows both the silhouette and a tappable numbered answer grid below it.
• When revealing the answer, highlight both the correct slot and the selected wrong slot so the user learns the positional correction instantly.
• The quiz home page matters: it avoids painting the app into a corner when more quiz types (channels, harmonics, etc.) are added later.

Test coverage

When editing quizzes, cover at least: - sidebar opens and shows Quiz section - quiz home opens from the sidebar - human design center quiz launches - prompt exposes a gate number - selecting the correct numbered slot produces a success state and next-gate CTA

Coin Divination Flow

The app now includes a dedicated mobile-only divination mode launched from the sidebar.

Entry point and screen behavior

• Sidebar includes Start divination
• Divination uses its own view mode in src/App.tsx
• Keep the screen visually sparse: top-left menu button, coin stage, cast status, CTA, and bottom-stacked lines
• After 6 casts, resolve the hexagram from bottom-up line order and open the existing hexagram details card automatically

Coin semantics

• Heads = Yang = value 3
• Tails = Yin = value 2
• Sum 3 coins per cast
• Odd total => Yang line (1)
• Even total => Yin line (0)
• Lines stack bottom-up and match directly against hexagram.lines

Implementation pattern

Use pure helpers in src/lib/divination.ts for: - coin value mapping - line generation from 3 faces - completion detection - hexagram lookup from 6 lines

Keep UI-specific animation/state in src/App.tsx.

Animation and visual lessons learned

Simple generic gold circles looked cheap and failed user expectations. The better pattern was: - ancient Chinese cash-coin styling with a square center hole - visible bronze/brass rim, inner ring, patina, and depth cues - explicit Yin/Yang labeling on the coins (陰 Yin, 陽 Yang) - explicit role markers requested by user (Woman, Man, with ♀ / ♂) - randomized per-cast motion values so coins do NOT land in the same pile every time - higher toss arc, faster drop, and bounce/settle phases feel better than a soft float-up/float-down animation

Practical motion pattern

For each cast, generate per-coin values for: - horizontal drift - vertical drift - spin - tilt - animation delay - rise height - bounce amount - settle rotation - faux depth

Then feed them into CSS custom properties and a single keyframe animation. This keeps animation expressive without adding a physics library.

Visual QA heuristic

If a visual review says the coins feel like a repeated tidy preset rather than tossed physical objects, increase: - toss height - drop speed contrast - per-coin randomization - spread/rotation variance

If Yin/Yang is not obvious in a screenshot, do not rely on subtle engraved details alone — add explicit readable text labels. - Divination logic: src/lib/divination.ts

Coin Divination Flow

The app now includes a mobile-first coin divination mode launched from the sidebar.

Entry point

• Sidebar includes a Start divination action under its own Divination section.
• This should switch the app into a dedicated view === 'divination' mode rather than layering over study/admin views.

Intended mobile layout

The divination screen should feel nearly blank and immersive: - Keep only the discreet top-left floating menu button visible outside the main interaction area. - Do NOT reuse the normal study top bar on this screen. - Center the coin throw interaction and keep the accumulated lines anchored near the bottom. - Initial state should be minimal: no big explanatory copy blocks, just the throw state and button.

Throw behavior

• Each throw uses exactly 3 coins.
• Heads = yang = value 3
• Tails = yin = value 2
• Sum the three coin values.
• Odd totals create a yang line (1)
• Even totals create a yin line (0)
• Build 6 lines from bottom to top.
• After the 6th line, resolve the matching hexagram from hexagrams.ts and open that hexagram's existing detail card.

Implementation pattern

Use pure helper functions in src/lib/divination.ts for reusable logic: - getCoinValue() - getLineFromCoins() - isDivinationComplete() - getHexagramFromThrownLines() - throwCoins()

Keep the UI state in App.tsx, but keep coin math and hexagram resolution out of the component.

UX findings

• Showing placeholder/default coins before the first throw makes the screen feel less blank than requested; start with no visible coins until the first throw.
• A visually "discreet" menu button can still be too subtle; slightly increasing tap-target size improved mobile usability without breaking the minimal look.
• Bottom-stacked lines looked too disconnected when the lower region was too tall; reduce the reserved bottom area so the built hexagram feels tied to the current throw.

Test coverage

When editing this flow, cover both pure logic and UI behavior: - src/lib/divination.test.ts for heads/tails values, odd/even line conversion, completion, and hexagram lookup. - src/App.test.tsx for sidebar entry, divination screen launch, first throw result, and six-throw completion opening the resolved hexagram.

Hexagram Rendering Conventions

Main card hexagram proportions

The front-of-card hexagram should look like a normal I Ching hexagram — relatively narrow/tall, not stretched wide.

The glyph is rendered by LineGlyph in src/App.tsx and styled in src/index.css.

Important styling constraints: - Keep .line-glyph width constrained (~11rem max) so the six-line stack does not look flattened. - Keep vertical line spacing balanced with width. - Avoid giving the glyph full-card width. - Rounded modern line styling is okay, but the width-to-height ratio must still read as a traditional hexagram.

Compact trigram glyphs

For compact trigram cards on the back/details side: - Use a smaller fixed width (~4.2rem) - Keep the compact line gap tighter than the full hexagram - Slightly thicker compact lines are okay if the overall trigram remains legible

Trigram Detail Rendering

A text-only trigram section can look broken or "missing" even if the data is present.

For each trigram card, show ALL of the following together: 1. Compact line glyph (LineGlyph ... compact) 2. Trigram symbol character (☰, etc.) 3. Human-readable image label (heaven, earth, etc.) 4. Name and attribute text

Proven working pattern

Wrap the trigram visuals in a dedicated visual block: - .trigram-visual - .trigram-symbol-block - .trigram-symbol - .trigram-image-label

This makes the trigram instantly readable and prevents the symbol area from looking empty in browser screenshots or on mobile.

UX Lesson Learned

If a user says a visual element is "not showing," don't assume the data binding is broken. In this app, the trigram data existed and LineGlyph rendered, but the presentation was too subtle. The correct fix was to improve the visual affordance, not to debug API/data flow.

Coin Divination Flow

The app now includes a dedicated mobile-only divination mode launched from the sidebar.

Product expectations

• Sidebar must include Start divination
• Divination is a fullscreen-feeling mode with only:
• discreet top-left menu button
• central coin-casting hero area
• bottom-stacked line results
• User performs 6 casts total
• Each cast throws 3 coins
• Heads / Yang = 3
• Tails / Yin = 2
• Sum the 3 coins:
• odd total => yang line (1)
• even total => yin line (0)
• Stack lines bottom-up
• After 6 lines, resolve the matching hexagram and open that hexagram directly in study view with the back/details side visible

Implementation pattern

• Keep coin math in a pure helper module: src/lib/divination.ts
• Keep UI state in src/App.tsx
• Use deterministic helper functions for:
• coin face value mapping
• line creation from 3 coins
• completion detection
• lookup from 6 thrown lines to hexagrams
• Add dedicated tests in src/lib/divination.test.ts
• Add UI coverage in src/App.test.tsx

Premium coin visual direction

If Alex asks for the coins to feel "cool," "ancient Chinese," or more premium, the correct direction is: - Ancient Chinese cash coin look with square hole in the center - Coins should feel like aged bronze/brass artifacts, not flat yellow UI circles - Use: - rim + inner ring - patina / oxidation variation - darker recesses around square hole - engraved character treatment - stronger contact shadows - visible thickness / perspective - Larger coins read better on mobile; do not keep them too small - Remove tiny visual labels around the coins if they clutter the hero composition; use screen-reader-only text instead

Motion / physics direction

Cheap coin motion feels fake immediately. Better results come from: - per-coin drift and staggered timing - larger toss arc - stronger tumbling / rotation variation per coin - settle state with convincing shadow placement - a more ceremonial, sparse composition rather than crowding the screen

UX lesson learned

For this app, minimalist is good, but "empty + generic" is not. The divination screen only feels premium when the coins themselves become the hero object. If the coins are too small, too flat, or too labeled, the whole experience reads like placeholder UI instead of ritual interaction.

Wilhelm Translation Import Workflow

The app now supports a full Wilhelm translation panel on the hexagram details side.

Preferred extraction strategy

Do NOT rely on the PDF text layer for Wilhelm extraction. In this PDF, direct text extraction is garbage due to font encoding.

Use this pipeline instead: 1. Use PDF bookmarks / TOC to map each hexagram to page ranges. 2. Render those pages to PNGs. 3. Use a vision-capable model to transcribe the PNGs into structured JSON. 4. Preserve source page images in the repo for fidelity and future spot-checks. 5. Merge the generated Wilhelm data into src/data/hexagrams.ts.

Files involved

• Vision extractor: scripts/extract-wilhelm-vision.ts
• Section map: data/wilhelm-section-map.json
• Generated full dataset: src/data/wilhelm-extracted.generated.json
• Source page images: public/wilhelm/<hexagram-number>/page-XXX.png
• Hexagram data merge: src/data/hexagrams.ts
• UI rendering: src/App.tsx
• Styling: src/index.css
• UI test: src/App.test.tsx

Extraction lessons learned

• Vision-first was materially better than OCR-first for this document.
• TOC/bookmarks are reliable for segmentation.
• Vision handled headings, The Judgement, The Image, and The Lines far better than Tesseract cleanup.
• Prompt wording matters a lot. The better prompt explicitly says:
• do not paraphrase or modernize
• preserve old-fashioned wording
• preserve visible line breaks when they are part of the poetic/book layout
• format Above/Below as Romanized / English name, Element
• Page 133 is afterword material and should NOT be included in hexagram 64. The TOC-derived page range fixes this.

Integration pattern

Extend Hexagram with: - wilhelm?: { heading, pageStart, pageEnd, sourceImages, above, below, judgement, image, lines, notes, fullText }

Render a dedicated WilhelmPanel on the details/back side with: - heading - page range - above / below cards - Judgement block - Image block - line cards for The Lines

Use white-space: pre-wrap for Wilhelm text so line breaks survive.

Practical repo workflow

• Run sample first:
• npx tsx scripts/extract-wilhelm-vision.ts --sample
• Run full extraction:
• npx tsx scripts/extract-wilhelm-vision.ts
• Copy the full report JSON into app data if needed:
• cp docs/reports/wilhelm-vision-full.json src/data/wilhelm-extracted.generated.json

Testing lesson

Once Wilhelm is in the UI, existing tests may start failing from ambiguous matches because the same phrases appear in both the modern summary copy and the Wilhelm panel. Fix tests by scoping assertions with within(panel) and using heading levels when needed.

Verification Checklist

After changing card/trigram visuals, divination visuals, or Wilhelm content: 1. Build succeeds 2. PM2 process restarts cleanly 3. dist/ asset timestamps are fresh 4. Front card hexagram looks narrower and closer to traditional proportions 5. Back/details shows clearly visible upper + lower trigram visuals 6. Divination sidebar entry exists and opens correctly 7. Divination screen shows 3 visible premium coins before the first cast 8. Casting animation completes and line progress updates correctly 9. Six casts resolve to a matching hexagram and open its details view 10. Wilhelm panel appears on the hexagram details side with heading, sections, and lines 11. Live browser check shows no JS errors 12. Commit and push changes to GitHub

Git Workflow

Always commit and push after changes:

git add src/App.tsx src/index.css
git commit -m "Fix hexagram proportions and trigram visuals"
git push origin main

Pitfalls

• A glyph can be technically present but visually read as missing if the symbol area is too subtle.
• Full-width flex rendering makes hexagrams look too wide; constrain width explicitly.
• Always verify with a visual browser check after deploy, not just local code inspection.