Customizing the Story Template

Relevant source files

The following files were used as context for generating this wiki page:

• story_template.html
• build_story_artifact.py
• README.md
• diagram_inventory.json
• requirements-build.txt

The story template defines the visual presentation and interactive logic for the GestaltView Visual Story. It exists as a single, self-contained HTML file that requires no external dependencies or frontend build steps. The system injects story data into this template during the build process to produce a functional static site.

Architecture and Data Flow

The customization process involves modifying the story_template.html file or the build_story_artifact.py script to change how data appears to the user. The builder script acts as the orchestrator, merging structured data from the diagram_inventory.json (or a direct PDF source) into the HTML template.

The diagram shows the build-time flow where the Python script merges the JSON inventory and the HTML template into a final self-contained artifact.
Sources: build_story_artifact.py:17-21, README.md:9-12

Data Injection Mechanism

The builder script reads the content of story_template.html and identifies the __APP_DATA__ placeholder. It converts the Python representation of chapters and items into a JSON string and performs a string replacement. This makes all story content available to the client-side JavaScript as a single global object.

Sources: build_story_artifact.py:355-358, story_template.html:306

Visual Customization via CSS

The template uses CSS Custom Properties (variables) defined in the :root selector to manage the design system. You can modify these variables to change the theme, colors, and typography of the story layer.

Core Theme Variables

The following table summarizes the primary variables used for visual styling:

Variable	Usage	Source Reference
--void	Deep background color	story_template.html:10
--navy	Secondary background / panel base	story_template.html:10
--panel	Card and component background	story_template.html:10
--cyan	Primary accent color for UI elements	story_template.html:10
--amber	Warning/Highlight accent color	story_template.html:10
--ink	Primary text color	story_template.html:10
--radius	Border radius for cards and buttons	story_template.html:10
--sans	Primary sans-serif font stack	story_template.html:10

Layout Sections

The HTML structure is divided into distinct semantic sections that you can customize:

• Masthead: Contains the brand name and system notes.
• Landing: The entry screen providing depth selection (Orientation, System, Architecture).
• Experience: The main interactive workspace containing the Sidebar (Atlas) and the Story article.
• Modal: A dedicated container for high-resolution image viewing.

Sources: story_template.html:125-188

Interactive Logic Customization

The JavaScript logic within the template manages state transitions, search functionality, and content rendering based on the user's selected "depth" or "lens."

Application State Management

The application tracks state using several key variables and functions:

• activeLevel: Stores the current depth lens (e.g., 'orientation', 'system', 'architecture').
• activeId: Stores the ID of the currently displayed diagram or figure.
• renderItem(id): Clears the main story container and populates it with new content based on the provided ID.
• renderNav(query): Filters the sidebar atlas based on user input.

The sequence diagram illustrates how user interactions trigger state updates that subsequently refresh the DOM content.
Sources: story_template.html:315-325, story_template.html:350-385

Depth Lens Mapping

The template provides three distinct lenses for every visual. These lenses correspond to the explanations object within the diagram_inventory.json items.

Lens Key	UI Label	Description
orientation	Get Oriented	Plain language, high-level context.
system	Understand the System	Product surfaces and data movement.
architecture	Explore the Architecture	Technical wiring and code references.

Sources: story_template.html:318-322, diagram_inventory.json:65-69

Summary of Customization Entry Points

To effectively customize the story layer, target the following areas:

1. Metadata Expansion: Add new keys to CURATED_COPY or CURATED_PARTS in build_story_artifact.py to provide more data to the template.
2. Styling: Modify the :root CSS variables in story_template.html for rapid re-theming.
3. Component Design: Alter the template literals within the renderItem function in the <script> block to change how cards, tags, or buttons are structured.
4. Chapter Structure: Modify the CHAPTERS list in the Python builder to regroup visuals or change the narrative flow.

Sources: build_story_artifact.py:64-150, story_template.html:10-25, story_template.html:350-375