DESIGN.md

metadata

name: พระไตรปิฎก มจร. — Tipitaka Reader
description: >-
  Digital reader for the MCU Pali Tipitaka canon with full-text search and AI
  assistance
colors:
  primary: '#c8860a'
  primary-deep: '#9a6307'
  primary-light: '#e8b84a'
  indigo-bg: '#1a1a2e'
  indigo-deep: '#0f0f1e'
  indigo-surface: '#222242'
  neutral-cream: '#fdfaf5'
  neutral-cream-dark: '#f5edd8'
  neutral-paper: '#faf7f2'
  neutral-warm-white: '#f8f6f0'
  text-dark: '#1a1a1a'
  text-soft: '#555555'
  text-muted: '#888888'
  text-light: '#e0e0e0'
  border-light: '#e0d0b0'
  border-dark: '#3a3a5e'
  highlight-bg: '#fff3cd'
  success-bg: '#e8f5e9'
  info-bg: '#e3f2fd'
typography:
  display:
    fontFamily: Sarabun, 'Noto Serif Thai', 'Noto Sans Thai Looped', sans-serif
    fontSize: clamp(1.2rem, 2vw, 1.6rem)
    fontWeight: 700
    lineHeight: 1.3
    letterSpacing: 0.02em
  body:
    fontFamily: Sarabun, 'Noto Serif Thai', 'Noto Sans Thai Looped', sans-serif
    fontSize: 17px
    fontWeight: 400
    lineHeight: 2.1
    letterSpacing: normal
  label:
    fontFamily: Sarabun, 'Noto Sans Thai Looped', sans-serif
    fontSize: 0.82em
    fontWeight: 600
    lineHeight: 1.4
    letterSpacing: 0.04em
rounded:
  sm: 4px
  md: 6px
  lg: 8px
  xl: 12px
spacing:
  xs: 4px
  sm: 8px
  md: 16px
  lg: 24px
  xl: 32px
components:
  button-primary:
    backgroundColor: '{colors.primary}'
    textColor: '{colors.neutral-warm-white}'
    rounded: '{rounded.md}'
    padding: 10px 20px
  button-secondary:
    backgroundColor: transparent
    textColor: '{colors.text-light}'
    rounded: '{rounded.md}'
    padding: 10px 20px
  button-secondary-hover:
    backgroundColor: '{colors.indigo-surface}'
    textColor: '{colors.primary}'
    rounded: '{rounded.md}'
  card:
    backgroundColor: '{colors.neutral-cream}'
    textColor: '{colors.text-dark}'
    rounded: '{rounded.md}'
    padding: 8px 12px
  reader-panel:
    backgroundColor: '{colors.neutral-cream}'
    textColor: '{colors.text-dark}'
    rounded: '{rounded.lg}'
    padding: 24px 32px
    maxWidth: 70ch
    lineHeight: 2.1
  page-marker:
    textAlign: center
    textColor: '{colors.text-muted}'
    fontSize: 0.82em
    margin: 32px 0
    letterSpacing: 0.04em
  nav-drawer:
    width: 320px
    widthMobile: 100%
    backgroundColor: '{colors.indigo-bg}'
    tabs:
      - toc
      - search
      - overview
    animation: slide-in from left
  ai-fab:
    size: 56px
    shape: circle
    position: fixed bottom-24px right-24px
    backgroundColor: '{colors.primary}'
    iconColor: '{colors.neutral-warm-white}'
    hoverScale: 1.05
    activeScale: 0.95
  ai-popup:
    width: 420px
    maxHeight: 70vh
    position: fixed above ai-fab
    bottomOffset: 96px
    rightOffset: 24px
    draggable: true
    minimizable: true
    backgroundColor: '{colors.neutral-paper}'
    rounded: '{rounded.lg}'
  ai-message-user:
    backgroundColor: '{colors.info-bg}'
    textColor: '{colors.text-dark}'
    rounded: '{rounded.xl}'
    padding: 8px 12px
  ai-message-assistant:
    backgroundColor: '{colors.success-bg}'
    textColor: '{colors.text-dark}'
    rounded: '{rounded.xl}'
    padding: 8px 12px
  right-toolbar:
    width: 44px
    position: fixed right-0
    backgroundColor: '{colors.indigo-surface}'
    buttonSize: 44px
    iconColorRest: '{colors.text-muted}'
    iconColorActive: '{colors.primary}'
    dividerColor: '{colors.border-dark}'
    opacityScrolling: 0.2
    opacityRest: 1
    scrollStopDelay: 1.5s
    hoverZone: 60px
themes:
  dark:
    description: Default — Indigo Midnight shell, Parchment reader
    shell: '{colors.indigo-bg}'
    nav: '{colors.indigo-bg}'
    reader: '{colors.neutral-cream}'
    ai-panel: '{colors.indigo-deep}'
  light:
    description: Warm white shell, paper reader
    shell: '{colors.neutral-warm-white}'
    nav: '{colors.neutral-cream-dark}'
    reader: '{colors.neutral-paper}'
    ai-panel: '{colors.neutral-cream-dark}'
  classic:
    description: Parchment throughout — closest to printed scripture
    shell: '{colors.neutral-cream-dark}'
    nav: '{colors.neutral-cream}'
    reader: '{colors.neutral-cream}'
    ai-panel: '{colors.neutral-paper}'

Design System: พระไตรปิฎก มจร. — Tipitaka Reader

1. Overview

Creative North Star: "The Dhamma Light" (แสงแห่งธรรม)

A digital scripture reader that feels like light illuminating ancient wisdom. The interface is a quiet chamber — indigo walls, warm golden accents, and cream-paper reading surfaces. Every design decision bends toward one purpose: making the sacred text the most prominent thing on screen.

This system explicitly rejects:

• SaaS dashboard aesthetics (cards with badges, data-heavy chrome, progress bars)
• AI-first UIs where the chatbot dominates the experience
• Dark mode as a gamer-aesthetic choice (dark surfaces exist but are subdued, not dramatic)
• Anything that competes with readability — animated backgrounds, neon accents, decorative floating elements

The app has two modes of being: reading (the user is deep in text — controls fade, AI is closed) and exploring (the user is searching or browsing — panels open, navigation is present). The design prioritizes the reading state.

Key Characteristics

• Tonal layering, not shadows. Depth is conveyed through shifts in background lightness, not drop shadows. The reader surface is the lightest layer; navigation panels are progressively darker.
• Typography-led hierarchy. Scale and weight contrast carry the information architecture. Color is supplementary, not structural.
• Generous rhythm. Line height, padding, and margins are spacious — this is text meant for slow, contemplative reading, not rapid scanning.
• The accent is earned. Gold appears on interactive elements, highlights, and active states — never as decoration. Its rarity signals "this is actionable."

2. Colors: The Indigo & Gold Palette

The palette pairs a deep indigo architecture (nav, sidebar, backgrounds) with warm cream for reading surfaces and gold for interaction. The contrast between cool indigo and warm cream+gold creates a serene, focused atmosphere.

Primary

• Dhamma Gold (#c8860a / oklch(0.62 0.12 68)): The sole accent color. Used for active states, hover borders, icons, highlight markers, and page pills. Never applied to more than 10% of any surface. Its golden warmth echoes the ink of illuminated manuscripts.

Neutral

• Indigo Midnight (#1a1a2e / oklch(0.18 0.04 280)): App shell and navigation background. A very dark blue-black that reads as black but has subtle cool character.
• Indigo Void (#0f0f1e / oklch(0.12 0.03 280)): The deepest layer — AI panel, footer areas. Conveys depth below the navigation layer.
• Indigo Surface (#222242 / oklch(0.22 0.05 280)): Hover state for navigation items, secondary card backgrounds.
• Parchment Cream (#fdfaf5 / oklch(0.96 0.01 75)): The reading surface. Warm off-white reminiscent of aged paper. Used for reader panel and cards in classic/light mode.
• Cream Dark (#f5edd8 / oklch(0.93 0.02 75)): Hover state for reading-surface items. Also used for active result cards.
• Warm Paper (#faf7f2 / oklch(0.95 0.01 75)): Alternative reading background, slightly cooler than Parchment Cream. Used for AI panel and secondary surfaces.

Semantic

• Text Dark (#1a1a1a): Primary body text on light surfaces.
• Text Soft (#555555): Secondary text, section headers.
• Text Muted (#888888): Metadata, timestamps, page numbers.
• Text Light (#e0e0e0): Text on dark surfaces.
• Border Cream (#e0d0b0): Borders on light/classic surfaces.
• Border Indigo (#3a3a5e): Borders on dark surfaces.
• Highlight Yellow (#fff3cd): Search result highlighting in text.
• Message User Blue (#e3f2fd): User chat bubble background.
• Message Assistant Green (#e8f5e9): AI chat bubble background.

Named Rules

The Gold Rarity Rule. Gold appears on ≤5% of any given screen. Its role is signal, not ornament. If an element is not interactive or active, it should not be gold.

The Parchment Priority Rule. The reader surface is always the lightest element on screen, regardless of theme. Even in dark mode, the reader background lifts by one tonal step.

3. Typography

Display & Body Font: Sarabun (with 'Noto Serif Thai', 'Noto Sans Thai Looped' fallback)

Sarabun is a modern Thai sans-serif with excellent readability at body sizes. Its open counters and generous ascenders accommodate Thai tone marks and Pali diacritics without crowding. The font is native to the Thai web ecosystem (Google Fonts) and renders reliably across platforms.

Character: Warm, legible, undistracting. Sarabun at 17px with 2.1 line-height creates a rhythm that matches the cadence of Pali chanting — spacious enough for the eye to rest between lines.

Hierarchy

• Display (700, clamp(1.2rem, 2vw, 1.6rem), 1.3): Volume titles, section headings in the TOC. Large enough to anchor a panel, never dramatic.
• Headline (600, 1.2rem, 1.4): Panel headers ("ผลการค้นหา", "เลือกเล่มที่ต้องการอ่าน").
• Title (600, 1rem, 1.4): Card titles, result headers.
• Body (400, 17px / 1rem, 2.1): The primary reading size. Capped at 70ch max-width on the reader panel. Line height of 2.1 is deliberate — Thai script needs vertical breathing room for tone marks above and below characters.
• Label (600, 0.82em, 1.4, 0.04em letter-spacing): Metadata, page numbers, section references. Uppercase in Thai context via CSS text-transform.

Named Rules

The Sarabun Solitude Rule. No secondary font. Sarabun serves every role from display to label. Mixing fonts would add visual chatter to a system whose job is to disappear.

4. Elevation

The system uses tonal layering exclusively — depth is conveyed by varying background lightness, never by box shadows. This is deliberate: shadows create the illusion of floating cards, which contradicts the manuscript-like reading experience. Instead, surfaces feel like stacked paper.

The z-order from deepest to lightest:

1. AI panel / background chrome — darkest indigo (#0f0f1e)
2. Sidebar / navigation — dark indigo (#1a1a2e)
3. Card / hover surfaces — indigo surface (#222242) on dark; cream dark (#f5edd8) on light
4. Reader panel — lightest cream (#fdfaf5) — always the brightest surface

Named Rules

The Flat-By-Default Rule. Every surface is flat at rest. Tonal shifts appear only in response to state — hover, active, focus. No card shadows, no floating elements, no elevated buttons.

5. Components

Buttons

• Shape: Rounded rectangle with 6px radius. Consistent across all variants.
• Primary: Gold fill (#c8860a), white text. Used for the primary action on any panel — "ค้นหา", "ส่งคำถาม". Hover: deeper gold (#9a6307). Height: 44px minimum.
• Secondary: Transparent fill, border matching current theme's border color. Used for navigation, toggle, and utility actions. Hover: gold border + indigo surface background. Active: translateY(-1px) micro-motion.
• Icon-only: Transparent, same geometry. Used in sidebar icon mode. Active variant uses gold border.
• Ghost (TOC/List items): Full-width, text-align left, transparent. Hover: gold text + tinted background.

Cards (Search Results / TOC)

• Shape: 6px radius, 1px border matching theme border color. Left border is not used as accent (avoiding side-stripe anti-pattern per design law).
• Resting: Transparent or panel-matching background. Text at body weight.
• Active: Gold border + lighter background tint. No shadow.
• Internal spacing: 8px top/bottom, 12px left/right.

Reader Panel

• Shape: 8px radius, no border (breathes within its column). Background is always the lightest surface on screen.
• Header: Section title + volume/page pill in gold. Separated from text by a thin border.
• Typography: 17px body, 2.1 line-height, 70ch max-width. Content is left-aligned (Thai/Pali reads left-to-right).
• Search highlighting: mark element with highlight yellow background + gold underline.

AI Chat Panel (inside AIPopup)

• Container: 8px radius popup, floating above the FAB — never a permanent column.
• User message bubble: Light blue (#e3f2fd) background, 12px radius (bottom-right corner flattened to 4px).
• Assistant message bubble: Light green (#e8f5e9) background, 12px radius (bottom-left corner flattened to 4px).
• Thinking indicator: Italic, muted text above assistant messages when in reasoner mode.
• Input: Full-width text input with 44px height, gold focus ring.

Right Reading Toolbar

Vertical strip fixed to the right edge of the viewport. The sole home for all reading-flow controls. Never in the NavDrawer — these need to be reachable without opening a panel.

Layout (top to bottom):

┌────────┐
│ หน้า N │  ← page pill (current page, tappable to jump)
│  / 532 │  ← total pages, muted
├────────┤
│   ^    │  ← previous page
│   v    │  ← next page
├────────┤
│   ↑    │  ← scroll to top
│  A+    │  ← increase font size
│  A−    │  ← decrease font size
│  ☀/🌙 │  ← cycle theme (dark → light → classic)
└────────┘

• Width: 44px. Each button is 44 × 44px (touch minimum).
• Background: Indigo Surface (#222242) in dark theme — one step lighter than the shell, reads as a contained strip.
• Dividers: 1px border-dark (#3a3a5e) between groups. No divider between A+ and A−.
• Icon color: Text Muted (#888888) at rest; Dhamma Gold (#c8860a) on hover/active.
• Page pill: Gold text on dark surface. Tapping opens an inline number input for direct page jump (no modal).
• Auto-hide: Fades to 20% opacity when the user is actively scrolling. Returns to full opacity on scroll-stop (1.5s) or when cursor enters the 60px right edge zone.
• No shadow. Sits flush against the right viewport edge — tonal contrast with the reader panel is sufficient separation.
• Theme toggle icon: Changes to reflect current theme — ☀ (dark), 🌙 (light), 📜 (classic).

Page Marker (Continuous Scroll Divider)

Appears between pages in the continuous scroll reading experience. It is purely informational — never a control.

• Layout: Centered, full reader-column width.
• Text: "— หน้า N —" in Text Muted (#888888), label scale (0.82em), 0.04em letter-spacing.
• Margin: 32px top and bottom — generous breathing room signals a boundary without breaking rhythm.
• No border, no rule. The text alone is sufficient. A horizontal rule would add visual weight where only a pause is needed.

NavDrawer (Navigation Sidebar)

Three tabs: TOC (table of contents), Search, Overview. Slides in from the left.

• Width: 320px on desktop; 100% viewport width on mobile with an overlay backdrop.
• Background: Indigo Midnight (#1a1a2e) in dark/default theme — one tonal step lighter than the app shell.
• Tabs: Full-width tab strip at top, gold underline on active tab. No icon-only tab bar — labels are always visible.
• Behavior: On desktop, the drawer can push the reader or overlay it (user preference). On mobile, always overlays with a semi-transparent backdrop.
• Close target: The backdrop itself is tappable to close on mobile; a ✕ button is present at top-right for keyboard users.

AI Floating Action Button (FAB)

The sole entry point to the AI assistant. Presence at bottom-right is persistent when AI is closed; it disappears when the popup is open (replaced by the popup's close control).

• Size: 56 × 56px circle. Minimum touch target met without padding hacks.
• Background: Dhamma Gold (#c8860a). This is the only gold surface in the UI — it earns its prominence.
• Icon: Lotus or spark glyph in warm white. No text label (position and color are sufficient affordance).
• Hover: scale(1.05), color deepens to #9a6307. Ease-out-quart, 150ms.
• Active: scale(0.95), 80ms. Communicates physical press.
• Unread indicator: 8px dot in amber at top-right of button. Only when the AI has a response the user hasn't seen.
• No shadow. Tonal layering rule applies — the gold surface against the indigo background creates sufficient contrast without elevation.

AI Popup

Opens above the FAB. Draggable by its title bar. Never full-screen on desktop.

• Default position: bottom: 96px; right: 24px (24px gap above FAB).
• Size: 420px wide, max-height 70vh. On mobile: 100vw − 16px margin each side, anchored to bottom.
• Draggable: Title bar drag handle (cursor: grab). Constrained to viewport bounds.
• States: Open (full), Minimized (title bar only, ~48px tall), Closed (FAB only).
• Background: Warm Paper (#faf7f2) — lighter than indigo shell, slightly darker than reader panel. Reads as a floating layer without a shadow.
• Title bar: "✨ ผู้ช่วยธรรมะ" left-aligned, minimize (—) and close (✕) right-aligned.
• Quick Actions: Shown on first open, before any message. Four preset buttons in a 2×2 grid: อธิบายให้เข้าใจง่าย, สรุปใจความสำคัญ, วิเคราะห์หลักธรรม, ประยุกต์ใช้ในชีวิต. Plus a free-text input below.
• Mode toggle: fast / reasoner — compact toggle in title bar area. Not prominent; scholars who need it will find it.

Highlight / Mark

• Shape: 3px radius, no padding for inline highlights.
• Color: Highlight yellow (#fff3cd) background in light mode, amber-gold (#4a3c10) in dark mode.
• Weight: Bolded to distinguish from surrounding text.
• Animation: Subtle pulse-in on appearance (400ms ease-out-quart).

6. Themes

Three named themes. Dark is the default — the physical scene is a scholar at a desk in a dim monastery library, warm lamp to the right, the screen the primary light source.

Token	Dark (default)	Light	Classic
Shell	Indigo Midnight #1a1a2e	Warm White #f8f6f0	Cream Dark #f5edd8
NavDrawer	Indigo Midnight #1a1a2e	Cream Dark #f5edd8	Parchment Cream #fdfaf5
Reader	Parchment Cream #fdfaf5	Warm Paper #faf7f2	Parchment Cream #fdfaf5
AI Panel	Indigo Void #0f0f1e	Cream Dark #f5edd8	Warm Paper #faf7f2
Body text	Text Dark #1a1a1a	Text Dark #1a1a1a	Text Dark #1a1a1a
Nav text	Text Light #e0e0e0	Text Dark #1a1a1a	Text Soft #555555

Switching: Via the theme toggle button (☀/🌙/📜) in the Right Reading Toolbar — bottom of the toolbar strip, always visible.

7. Do's and Don'ts

Do	Don't
Use gold sparingly — only for interactive/active elements	Add gold borders to every card "for consistency"
Keep the reader panel as the lightest surface	Use shadows to elevate the reader above the background
Let typography carry the hierarchy	Rely on color alone to distinguish headings from body
Use generous line height (2.1) for Thai/Pali text	Squeeze text to fit more content on screen
Close AI panel when not in active use	Let the AI panel dominate the layout
Use tonal layering to indicate depth	Add drop shadows anywhere
Keep navigation compact and predictable	Add animations that delay reading
Show the page number prominently in gold	Hide navigation controls in hamburger menus
Test every color combination at WCAG AA	Assume dark theme text on dark backgrounds is readable
Prefer inline/panel alternatives to modals	Use modals for search results or text selection

8. Animation & Motion

All animations serve function — they orient the user or confirm an action. No animation exists for decoration.

Global: Respect prefers-reduced-motion: reduce — all animations collapse to instant state changes.

Easing & Duration Tokens

Token	Value	Usage
ease-standard	cubic-bezier(0.4, 0, 0.2, 1)	Most transitions (panels, opacity)
ease-out-quart	cubic-bezier(0.25, 1, 0.5, 1)	Elements entering view (drawer, popup)
ease-in-quart	cubic-bezier(0.5, 0, 0.75, 0)	Elements exiting view
duration-fast	150ms	Micro-interactions (hover, active)
duration-normal	250ms	Panel transitions, state changes
duration-slow	400ms	Large-area transitions (drawer, popup)

Component Animations

Component	Trigger	Animation	Duration	Easing
NavDrawer	Open	translateX(-100%) → translateX(0)	duration-slow	ease-out-quart
NavDrawer	Close	translateX(0) → translateX(-100%)	duration-normal	ease-in-quart
NavDrawer backdrop	Open	opacity: 0 → 0.5	duration-slow	ease-standard
AI FAB	Hover	scale(1) → scale(1.05), color deepens	duration-fast	ease-out-quart
AI FAB	Active	scale(1) → scale(0.95)	80ms	ease-standard
AI FAB	Unread pulse	Subtle ring pulse (opacity 0.4→0→0.4)	2000ms loop	ease-standard
AI Popup	Open	opacity: 0, translateY(16px) → opacity: 1, translateY(0)	duration-slow	ease-out-quart
AI Popup	Close	opacity: 1 → 0, translateY(0) → translateY(8px)	duration-normal	ease-in-quart
Search results	Appear	Stagger children: opacity: 0 → 1, delay 50ms × index (max 8 items)	duration-normal	ease-out-quart
Highlight mark	Appear	Background pulse-in (0→100% opacity)	duration-slow	ease-out-quart
Page marker	Enter viewport	No animation — static text, appears naturally via scroll	—	—
Right Toolbar	Scroll start	opacity: 1 → 0.2	duration-normal	ease-standard
Right Toolbar	Scroll stop (1.5s)	opacity: 0.2 → 1	duration-normal	ease-standard
Theme switch	Toggle	Cross-fade backgrounds: opacity swap	duration-slow	ease-standard
Loading skeleton	Pulse	Background shimmer left→right	1500ms loop	ease-standard

Named Rules

The No-Bounce Rule. No spring or bounce physics anywhere. The aesthetic is calm, not playful — overshooting motion contradicts the contemplative reading environment.

The Stagger Cap Rule. List animations stagger at most 8 items (8 × 50ms = 400ms max). Beyond 8, remaining items appear instantly. Long stagger chains feel sluggish.