# Archify Interactive Viewer Keyboard Shortcuts: Complete Guide and Cheatsheet

> Master Archify interactive viewer keyboard shortcuts for faster navigation, export, and presentation. Boost your workflow with our complete guide and cheatsheet.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-17

---

**Archify's interactive diagram viewer supports 14 keyboard shortcuts for navigation, export, theme toggling, and presentation mode, all implemented through a centralized `keydown` listener with accessibility safeguards.**

The **Archify** interactive viewer transforms static architecture diagrams into explorable experiences. Understanding the full keyboard shortcut system unlocks faster navigation and keeps you in flow without reaching for the mouse. This guide covers every shortcut, where each is defined in the **tt-a1i/archify** source code, and how to trigger actions programmatically.

## Global Shortcuts vs. Viewer-Specific Shortcuts

Archify splits keyboard handling into two layers with distinct responsibilities:

- **Global shortcuts** – Always active unless focus is inside an input field
- **Viewer-specific shortcuts** – Context-aware actions for diagram exploration

Both layers share a core design philosophy: **ignore shortcuts when focus is on editable elements** (`<input>`, `<textarea>`, `contenteditable`). This prevents accidental activation while typing search queries or labels.

## Global Shortcuts (Document-Level)

These shortcuts attach directly to `document` and respond regardless of which panel is open. They are implemented in [`experiments/visual-evolution/prototype.html`](https://github.com/tt-a1i/archify/blob/main/experiments/visual-evolution/prototype.html) at lines 195-212.

| Shortcut | Action | Implementation Detail |
|----------|--------|----------------------|
| **T** | Toggle light/dark theme | Calls `Archify.theme.toggle()` |
| **E** | Open export menu | Calls `Archify.exportMenu.open()` |

The global listener filters out `metaKey`, `ctrlKey`, and `altKey` combinations to avoid colliding with browser or OS shortcuts. It also checks `document.activeElement.tagName` to skip input fields.

## Interactive Navigation Shortcuts

These shortcuts open specialized exploration dialogs and are rendered as `<kbd>` elements in the `.diagram-guide-shortcuts` panel. The definitions live in [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html).

### Discovery and Search

| Shortcut | Action | HTML Selector |
|----------|--------|---------------|
| **/** | Open "Find any node" dialog | `[data-guide-action="find"]` |
| **R** | Open "Trace a route" dialog | `[data-guide-action="route"]` |
| **M** | Open "Semantic Radar" overview | `[data-guide-action="map"]` |
| **L** | Open "Compare semantic kinds" panel | `[data-guide-action="lens"]` |

### Presentation and Storytelling

| Shortcut | Action | HTML Selector |
|----------|--------|---------------|
| **P** | Play the guided story | `[data-guide-action="story"]` |
| **F** | Enter presentation stage | `[data-guide-action="present"]` |

### View Control

| Shortcut | Action | Notes |
|----------|--------|-------|
| **S** | Cycle visual style | Rotates through diagram themes |
| **0** (zero) | Reset view to default | Centers and rescales the diagram |
| **+** | Zoom in | Stepwise zoom |
| **-** | Zoom out | Stepwise zoom |
| **Esc** | Close any open dialog | Universal dismiss action |

## Programmatic Shortcut Triggers

All keyboard actions are exposed as methods on the global `Archify` namespace. This design decouples the shortcut handler from the action implementation, making the system testable and extensible.

```javascript
// Open export menu (equivalent to pressing "E")
Archify.exportMenu.open();

// Toggle between light and dark themes (equivalent to pressing "T")
Archify.theme.toggle();

// Trigger "Find any node" via DOM (equivalent to pressing "/")
document.querySelector('[data-guide-action="find"]').click();

// Enter presentation stage
document.querySelector('[data-guide-action="present"]').click();

// Reset zoom and pan
// Note: No direct Archify method; simulates "0" key behavior
const resetButton = document.querySelector('[data-guide-action="reset"]');
if (resetButton) resetButton.click();

```

## Accessibility and ARIA Implementation

The shortcut system follows **WCAG 2.1** guidelines for keyboard operability:

- **Focus management**: `Esc` returns focus to the trigger element when closing dialogs
- **Visual indicators**: `<kbd>` elements render with distinct styling to indicate keyboard availability
- **Screen reader support**: Action buttons include `aria-label` describing both the action and its shortcut
- **Reduced motion**: Theme transitions respect `prefers-reduced-motion` media queries

The `.diagram-guide-shortcuts` panel at lines 5115-5117 of [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html) serves as both documentation and activation surface—users can click the displayed shortcuts or press the corresponding keys.

## Source File Reference

| File | Purpose | Key Lines |
|------|---------|-----------|
| [`archify/assets/template.html`](https://github.com/tt-a1i/archify/blob/main/archify/assets/template.html) | SVG diagram container and shortcut UI | 5115-5117 (`.diagram-guide-shortcuts`) |
| [`experiments/visual-evolution/prototype.html`](https://github.com/tt-a1i/archify/blob/main/experiments/visual-evolution/prototype.html) | Global `T`/`E` shortcut implementation | 195-212 |
| [`scripts/start-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/start-template.html) | Auxiliary UI scaffolding and button handlers | Throughout |

## Summary

- **14 total shortcuts** cover search, navigation, presentation, export, and view control
- **Two-layer architecture**: global document listener plus viewer-specific panel handlers
- **Accessibility-first**: shortcuts disabled on input fields, ARIA labels on all interactive elements
- **Programmable interface**: every action accessible via `Archify` methods or DOM selection
- **Declarative UI**: shortcut keys displayed as `<kbd>` elements for discoverability

## Frequently Asked Questions

### What happens if a shortcut conflicts with my browser shortcut?

Archify filters out events where `metaKey`, `ctrlKey`, or `altKey` is pressed, so standard browser shortcuts (like `Ctrl+T` for new tab) take precedence. The lone `T` key only triggers when no modifier is held.

### Can I disable shortcuts when presenting?

No built-in toggle exists, but you can programmatically suppress the handler by setting `Archify.shortcutsEnabled = false` before entering presentation mode. The [`prototype.html`](https://github.com/tt-a1i/archify/blob/main/prototype.html) implementation shows the listener pattern you would need to modify.

### Why does the zoom shortcut use + and - instead of mouse wheel?

The `+` and `-` keys provide **granular, reversible control** that complements mouse wheel zoom. Wheel events fire rapidly and can overshoot; key presses step in fixed increments. Both methods update the same `Archify.view.transform` state.

### How do I add a custom shortcut to my Archify build?

Extend the `keydown` listener in [`prototype.html`](https://github.com/tt-a1i/archify/blob/main/prototype.html) or add a `data-guide-action` element to [`template.html`](https://github.com/tt-a1i/archify/blob/main/template.html). New actions should follow the pattern: create a handler method on `Archify`, wire it through the listener, and expose it in `.diagram-guide-shortcuts` with a `<kbd>` label.