1. Overview

This style guide defines the design system for the Tanach project. All user-facing pages MUST follow these guidelines to ensure a consistent user experience.

Key Principles:

Consistency: All pages use the same components, colors, spacing, and typography
Centralization: Design tokens are defined in tanach-common.css
Reusability: Web Components provide standardized UI elements
Maintainability: Changes to design tokens automatically apply to all pages

2. Design Tokens MANDATORY

Design tokens are defined in src/css/tanach-common.css. All pages MUST use these tokens instead of hardcoded values.

Color Tokens

--base-bg

Background color

--base-text

Primary text color

--accent-color

Primary accent color

--border-color

Border color

Spacing Tokens

--spacing-xs

4px

--spacing-sm

8px

--spacing-md

12px

--spacing-lg

20px

3. Theme Toggle Component MANDATORY

All user-facing pages MUST include the theme toggle component using the Web Component.

Live Example

The theme toggle appears in the lower left corner (see bottom of page).

Implementation - Method 1: Web Component (Recommended)

<!-- In the <body> tag -->
<script type="module" src="src/js/components/ThemeToggle.js"></script>
<theme-toggle></theme-toggle>

<!-- For subdirectories, add path-prefix attribute -->
<theme-toggle path-prefix="../"></theme-toggle>

Implementation - Method 2: Standard HTML

<!-- Theme Toggle -->
<div id="theme-toggle" class="btn-group position-fixed"
     style="bottom: 20px; left: 20px; z-index: 1000; box-shadow: 0 2px 10px rgba(0,0,0,0.2);">
    <button class="btn btn-outline-secondary" data-theme="light" title="Light Theme">
        <i class="bi bi-sun-fill"></i>
    </button>
    <button class="btn btn-outline-secondary" data-theme="dark" title="Dark Theme">
        <i class="bi bi-moon-fill"></i>
    </button>
    <button class="btn btn-outline-secondary" data-theme="system" title="System Theme">
        <i class="bi bi-display"></i>
    </button>
</div>

<!-- Theme Manager Script -->
<script src="src/js/ThemeManager.js"></script>
<script>
  document.addEventListener('DOMContentLoaded', () => {
    ThemeManager.initialize();
  });
</script>

Rules:

✅ MUST be positioned at bottom: 20px, left: 20px
✅ MUST use btn-outline-secondary class (NOT btn-secondary)
✅ MUST use standard Bootstrap icons:
- bi-sun-fill for light theme
- bi-moon-fill for dark theme
- bi-display for system theme
✅ MUST have z-index: 1000
✅ MUST have box shadow: 0 2px 10px rgba(0,0,0,0.2)
❌ DO NOT override positioning in individual page styles
❌ DO NOT use different icons (e.g., bi-moon-stars-fill, bi-circle-half)
❌ DO NOT use inline CSS for theme toggle styling (use tanach-common.css)

4. Language Switcher Component RECOMMENDED

The language switcher allows users to change the interface language. All user-facing pages MUST include the language switcher with flag menu to allow users to switch between English, Hebrew, and French interfaces. The switcher uses the Lang system lang.js for dynamic translation loading.

Implementation

<!-- Include Language CSS -->
<link rel="stylesheet" href="src/css/lang.css" type="text/css">

<!-- Language Switcher (in <body> tag) -->
<div class="language-flag-container" style="position: fixed; left: 20px; top: 20px; z-index: 1001;">
    <button class="current-flag-btn" id="current-flag-btn" title="Change Language">
        <img id="current-flag-icon" src="src/images/flags/gb.svg" alt="English" class="flag-icon">
    </button>
    <div class="flag-menu" id="flag-menu">
        <button class="flag-menu-item" onclick="Lang.load('en')" data-lang="en">
            <img src="src/images/flags/gb.svg" alt="English" class="flag-icon">
            <span>English</span>
        </button>
        <button class="flag-menu-item" onclick="Lang.load('he')" data-lang="he">
            <img src="src/images/flags/il.svg" alt="עברית" class="flag-icon">
            <span>עברית</span>
        </button>
        <button class="flag-menu-item" onclick="Lang.load('fr')" data-lang="fr">
            <img src="src/images/flags/fr.svg" alt="Français" class="flag-icon">
            <span>Français</span>
        </button>
    </div>
</div>

<!-- Language Manager Script -->
<script src="src/js/lang.js"></script>

Translation Attributes

Add data-i18n attributes to elements that need translation:

<h1 data-i18n="page_title">Default English Text</h1>
<button data-i18n="submit_button">Submit</button>
<label for="input" data-i18n="field_label">Field Label</label>

Translation Files

Translation files are located in build/nodejs/public/locales/:

en.json - English translations
he.json - Hebrew translations
fr.json - French translations

Rules:

✅ MUST be positioned at top: 20px, left: 20px
✅ MUST have z-index: 1001 (above theme toggle)
✅ MUST include lang.css stylesheet
✅ MUST include lang.js script
✅ MUST support at least English, Hebrew, and French
✅ Add data-i18n attributes to all translatable text
✅ Add new translation keys to all three language files
❌ DO NOT override positioning in individual page styles
❌ DO NOT forget to initialize lang system in page initialization

Initialization in JavaScript

async function initializePage() {
    // Initialize Lang system FIRST
    if (window.Lang && window.Lang.init) {
        await window.Lang.init();
        if (window.Lang.initializeFlagMenu) {
            window.Lang.initializeFlagMenu();
        }
    }

    // ... rest of initialization
}

5. Page Header Component OPTIONAL

The page header component provides consistent headers across pages.

Live Example

Implementation

<script type="module" src="src/js/components/PageHeader.js"></script>
<page-header title="התנ&quot;ך - Hebrew Bible" subtitle="Optional subtitle"></page-header>

6. Web Components

Web Components provide reusable, consistent UI elements.

Available Components

Component	File	Usage	Status
`<theme-toggle>`	`src/js/components/ThemeToggle.js`	Theme switching buttons	MANDATORY
Language Switcher	`src/js/lang.js`	Language selection menu	RECOMMENDED
`<page-header>`	`src/js/components/PageHeader.js`	Page title and subtitle	OPTIONAL

6. Typography

Typography tokens ensure consistent font sizing and hierarchy.

Headings

H1 Heading - התנ"ך

H2 Heading - תורה

H3 Heading - בראשית

H4 Heading - פרק א

H5 Heading - פסוק א

H6 Heading - Small Heading

Font Size Tokens

--font-size-xs: 0.75rem (12px)
--font-size-sm: 0.875rem (14px)
--font-size-base: 1rem (16px)
--font-size-lg: 1.125rem (18px)
--font-size-xl: 1.25rem (20px)
--font-size-2xl: 1.5rem (24px)
--font-size-3xl: 1.75rem (28px)
--font-size-4xl: 2rem (32px)
--font-size-5xl: 2.5rem (40px)

7. Colors

Color tokens automatically adapt to light and dark themes.

Semantic Colors

--success-color

--danger-color

--warning-color

--info-color

8. Spacing

Use spacing tokens for consistent margins and padding.

/* Use spacing tokens instead of hardcoded values */
.my-element {
  margin: var(--spacing-lg);           /* Good ✅ */
  margin: 20px;                        /* Bad ❌ */

  padding: var(--spacing-md);          /* Good ✅ */
  padding: 12px;                       /* Bad ❌ */
}

9. Development Rules

MANDATORY Rules

✅ ALL user-facing pages MUST include tanach-common.css
✅ ALL user-facing pages MUST use the theme toggle component
✅ Theme toggle MUST be positioned at left: 20px; bottom: 20px;
✅ Use design tokens from tanach-common.css for colors, spacing, typography
✅ Use Web Components when available for consistent UI
❌ DO NOT override design token values in individual page styles
❌ DO NOT hardcode colors - use CSS variables
❌ DO NOT hardcode spacing - use spacing tokens
❌ DO NOT create inline styles for theme toggle

Best Practices

Test all changes in both light and dark themes
Ensure RTL support for all text and layouts
Use semantic HTML elements
Keep accessibility in mind (ARIA labels, keyboard navigation)
Use Bootstrap classes where appropriate for consistency
Document any new components added to the design system

UI Positioning Convention

Standard Layout Pattern:

Top Left: Settings/Options buttons (gear icon, display options)
- Position: top: 20px; left: 20px;
- Z-index: 1001 (above theme toggle)
- Examples: Display options in pasuk.html, Book selector in BasicTropsMulti.html
Bottom Left: Theme toggle buttons (light/dark/system)
- Position: bottom: 20px; left: 20px;
- Z-index: 1000
- MANDATORY on all user-facing pages

Rationale: Separating settings (top) from theme controls (bottom) creates clear visual hierarchy and prevents button overlap.

התנ"ך - Design System Style Guide

Table of Contents

1. Overview

2. Design Tokens MANDATORY

Color Tokens

Spacing Tokens

3. Theme Toggle Component MANDATORY

Live Example

Implementation - Method 1: Web Component (Recommended)

Implementation - Method 2: Standard HTML

Rules:

4. Language Switcher Component RECOMMENDED

Implementation

Translation Attributes

Translation Files

Rules:

Initialization in JavaScript

5. Page Header Component OPTIONAL

Live Example

Implementation

6. Web Components

Available Components

6. Typography

Headings

H1 Heading - התנ"ך

H2 Heading - תורה

H3 Heading - בראשית

H4 Heading - פרק א

H5 Heading - פסוק א

H6 Heading - Small Heading

Font Size Tokens

7. Colors

Semantic Colors

8. Spacing

9. Development Rules

MANDATORY Rules

Best Practices

UI Positioning Convention