Typography Lab

A typography testing tool for comparing 13px → 14px and 15px → 16px in context. Includes side-by-side pages, changed-text highlights, synchronized scrolling and clicks, and layout measurements.

This is an experimental testing tool. The current version is not recommended for production sites. Use a local installation or an isolated staging copy with test data.

• Activating the plugin immediately changes typography in wp-admin for all logged-in users, regardless of role, and on wp-login (including logged-out login and password-reset screens). It is not limited to the lab or the person testing it. Public-facing site pages receive no typography overrides or scanning scripts.
• The scanner measures layout as content changes on admin and login screens. Its performance has not been assessed on large or busy sites.
• The comparison panes are real WordPress sessions. Editing, saving, publishing, and other actions affect the actual installation. Even opening some editor screens can create drafts.
• Click synchronization uses heuristics to avoid duplicating content-changing actions. These checks are not a guarantee across third-party plugins, custom controls, or translated labels. Turn synchronization off before performing actions that change content or settings.
• Validation has covered this local WordPress Studio installation, not a broad theme/plugin compatibility matrix, performance assessment, or security audit.

Font-size changes happen in the browser; the plugin does not rewrite theme or core source files. Deactivating it and reloading open pages removes the treatment, but does not undo content edits made through the panes.

Before a production release, the experiment should be opt-in per tester, scanning should be confined to the lab, and synchronized interactions need stricter safeguards and broader testing.

• WordPress 6.6 or later and PHP 7.4 or later are the declared minimums. Live validation so far has been on WordPress 7.1 in Studio with Chrome; older versions and multisite have not been verified.
• A current desktop browser and a WordPress account with the manage_options capability (normally an administrator) to open the lab.
• Python 3 to build an installable ZIP from source. No Composer, npm, or JavaScript build step is needed to run the plugin.
• Access to the company GitHub Enterprise repository to clone the source.

1. Download typography-lab-0.1.23.zip from the 0.1.23 release, or build it from source below. Use the named plugin ZIP in the release assets.
2. On your local or staging WordPress site, open Plugins → Add Plugin → Upload Plugin, select the ZIP, and choose Install Now.
3. Activate Typography Lab. The typography treatment starts immediately in wp-admin and wp-login.
4. Open Tools → Typography Lab → Open comparison lab. The lab starts on Dashboard.

Use the Tools link so WordPress supplies the correct site address and asset paths. Do not open assets/lab.html directly or switch between localhost and 127.0.0.1 for the same installation.

Clone the repository into your site's plugins directory:

cd /path/to/wordpress/wp-content/plugins
git clone https://github.com/mattmiklic/typography-lab.git typography-lab

Activate Typography Lab from WordPress Plugins. Alternatively, clone anywhere, build a ZIP, and upload it using the steps above.

If upgrading from the original MU-plugin experiment, remove wp-content/mu-plugins/wpds-type-lab.php and its wpds-type-lab asset folder before activating this plugin. Legacy browser captures remain untouched in storage, but are no longer loaded. Internal message/storage identifiers and WordPress token names retain their original prefixes for compatibility.

Keep the Git checkout separate from the installed plugin if desired. Studio restricts PHP access to its site directory, so a plugin symlink pointing outside that directory is not supported by this setup.

After editing the checkout, copy its source into the installed plugin folder, excluding Git metadata and release archives:

rsync -av --exclude='.git/' --exclude='dist/' --exclude='__pycache__/' --exclude='.DS_Store' /path/to/typography-lab/ /path/to/studio-site/wp-content/plugins/typography-lab/

Reload the lab to pick up changes. Editing the checkout alone does not update a separate installed copy.

The default development branch is trunk. The initial plugin import is committed directly there.

From this repository root, run:

python3 scripts/package.py

The script creates dist/typography-lab-0.1.23.zip, with one top-level typography-lab/ directory. Publish that ZIP as a GitHub release asset. Commit the contents of this folder as the repository root; dist/ is ignored. Repository metadata, installation files, credentials, and browser captures are not included in the package.

Open Tools → Typography Lab, or /wp-admin/index.php?typography-lab=1, while signed in as an administrator.

When activated, the plugin applies these root custom-property overrides on wp-admin and wp-login, including accessible editor frames:

--wpds-typography-font-size-md: 14px;
--wpds-typography-font-size-lg: 16px;

Core files and line-height tokens are unchanged. Rendered non-token text at computed 13px or 15px also receives a 14px or 16px element override in wp-admin for logged-in users regardless of role, and on wp-login regardless of login status. Eligible sizes can come from raw px, calc(), other variables, or inheritance. Public-facing site requests do not enqueue any of the plugin’s runtime scripts. The two changes share the same scope and update when content changes. Closed menu text receives the treatment before opening, but captures still include only rendered text.

The lab uses this same full treatment in After and preserves original sizes in Before. Outside the lab, ?wpds-type=before selects the complete baseline for that document and its accessible nested frames. The runtime overrides do not migrate source declarations to tokens.

Deactivate Typography Lab in Plugins to disable the experiment, then reload open pages. Core and theme files are not edited. The Tools menu and lab endpoint retain normal administrator access checks; typography changes do not depend on those checks.

1. The lab starts on Dashboard. Focus the Page field for suggested admin pages; type to filter them or enter a local path. Selecting a suggestion loads both panes immediately. Use Load for a manually entered path. The panes split the available width equally by default, accounting for their borders, spacing, and page padding. Enter a viewport width to override both panes; clear the field to return to Auto. Width changes apply immediately without reloading the pages. Manually sized panes scroll horizontally if they exceed the available space.
2. Highlight changed text is on by default. Yellow marks identify changed text in each pane and refresh as content changes; form controls use a dashed outline. Toggle it off to inspect original colors and focus styles. This runs independently of the current capture.
3. Sync scrolling and clicks is on by default. Scrolling, navigation clicks, menus, native select controls, search typing, and Escape are mirrored in either direction. Scroll containers (including accessible nested frames) synchronize by relative scroll position so both can reach the bottom despite text reflow. The outer horizontal viewport containers synchronize too. Switch sync off for independent interaction. These are live WordPress pages sharing this installation: saves and other mutations are real. The synchronizer excludes form submission, password/file inputs, editable content, nonce-bearing links, and recognized content-changing actions such as Save, Publish, Delete, and Upload. It is intended for reviewing the local UI; it is not a transaction sandbox. Unrecognized/plugin-specific actions may require disabling sync.
4. Results update automatically as the baseline page changes.
5. Use Locate in panes to reveal text in both frames, including admin flyouts.

Controls are matched by element path plus tag, role, label, and text, with a unique semantic match as fallback. If the panes diverge, an unmatched action is skipped and a message appears above the panes. Load restores the same page in both frames. Dragging, rich-text editing, arbitrary keyboard shortcuts, browser back/forward, cross-origin frames, and full interaction-state replay are not supported.

Expand Changed text below the panes to see the comparison list, sorted by layout priority. Locate in panes reveals the selected text in both panes. Its red outline stays until you locate another item, press Escape, or leave the pane’s page.

Clipping and new horizontal overflow have high priority; extra wrapping has medium priority; height increases over 1px alone have low priority. Results are sorted by this priority. These are automated observations, not confirmed defects.

• It inventories elements with their own text, plus input values/placeholders, whose baseline computed font size is exactly 13px or 15px. Password and hidden inputs are excluded.
• The scanner first measures the token-only response, then applies additional element font-size overrides. Token identifies a response to the root tokens; Additional override identifies text changed by the additional element override. Computed-size detection does not establish whether the original CSS used px, calc(), another variable, or a scoped token. The current capture records its scope. The table shows changed candidates only.
• New text lines, increased element height, new horizontal overflow, and clipping against ancestor boxes are review signals. Existing overflow is identified separately. These are heuristics: they do not prove a usability defect or establish that text without a signal passes.
• Text is measured in its own document. Accessible same-origin nested frames are included; inaccessible frames cannot be scanned.
• Closed menus, hidden states, virtualized unmounted rows, generated CSS text, canvas, shadow DOM, custom placeholder pseudo-element styling, and precise glyph overlap need separate coverage. This is not an exhaustive automatic crawl of WordPress.
• Scoped custom-property redefinitions can prevent a root override from reaching descendants; these may receive an additional element override if their baseline is 13px or 15px. Token expressions whose baseline computes to a different size are outside this inventory.
• CSS transitions are temporarily suppressed during synchronous measurement, then restored after final sizes are committed. Scan settled states after fonts and content load.

• The lab shows a login screen or broken panes: open it through Tools using the site's configured address. Sign in at that same address; localhost and 127.0.0.1 have separate browser sessions.
• Text still appears small: Before deliberately preserves original sizes. In After, inspect the element containing the actual text; a parent container may still report 13px while its text child is 14px. Existing 11px, 12px, and 14px text is outside the current experiment. If visible text itself remains at 13px or 15px, record the page, element, and state for investigation.
• A finding disappears from the live page: Return to the same URL and state to locate the element again. The comparison covers the currently rendered state.

Start with Site Editor navigation, Pages/DataViews in each layout, filters and view options, Templates, Patterns, Styles panels, block-editor sidebars/toolbars/inserters, command palette, and media dialogs. Include empty results, long titles, narrow layouts, disabled states, and RTL/translated strings if relevant. The installation's available content and plugin set define the test surface.

fixture.html is a deterministic local scanner fixture. Load /wp-content/plugins/typography-lab/assets/fixture.html in the lab. Expected: all 8 baseline candidates change, reporting 5 token-driven changes and 3 additional overrides; hidden text, screen-reader announcements, clipped hidden ancestors, and transparent ancestors excluded; visible live regions retained; wrapping for MMMMM MMMMM; new overflow and clipping for MMMMMMMM; input value included. Before and after must remain 15px and 16px after scanning the large clipping example.

PHP lint and Node syntax checks:

php -l typography-lab.php
node --check assets/assessment.js
node --check assets/tokens.js
node --check assets/scanner.js
node --check assets/lab.js
node --check assets/sync.js

Synchronization validation: load /wp-content/plugins/typography-lab/assets/sync-fixture.html. Check View options in either pane, type into Search, scroll the bordered container and nested frame, and disable Sync scrolling and clicks to check independent operation. The fixture Save button only increments its own local counter; it must never increment the other pane. Live Site Editor Pages navigation and View options were also verified in both directions.

Press Alt+T on Windows or Option+T on Mac on an ordinary wp-admin page to switch both token and non-token changes on or off without reloading. The shortcut is ignored while typing in text fields or editable content. A brief status message confirms the sizes. This works inside accessible editor frames and remembers the choice across admin navigation in the same tab using session storage. Public-facing site pages remain unchanged whether logged in or out. The comparison panes and explicit ?wpds-type=before URLs keep their assigned variants.

Comparisons are held in memory for the current page. The keyboard preference uses tab session storage. Legacy local-storage captures are left untouched but are no longer read. The plugin sends no comparison data to an external service and creates no WordPress database tables or options. Licensed under GPL-2.0-or-later; see LICENSE.

Horizontal locate validation: load assets/locate-fixture.html through its plugin URL in the lab at 1000px, wait for the automatic comparison, and locate each row. Both outer viewports should scroll horizontally to reveal the outlined text, including the nested-frame example. Repeat with synchronization off.