התנ"ך - Design System Style Guide

Living documentation for maintaining UI consistency across all pages

Table of Contents

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:

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. 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>

5. 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
<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

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.

Back to Main Index Studying Tools