-
Notifications
You must be signed in to change notification settings - Fork 0
Visual Construction
"When 22 panels look like they were built by the same engineer on the same afternoon, the design system is working."
You build your first editor panel. You pick a font size — 10 points, seems right. You pick a background color — dark gray, matches the editor. You add some padding — 8 pixels here, 12 there. It looks fine.
You build your second panel. You pick font sizes again, slightly different this time because you forgot what you used before. The background is a different shade of gray. The padding is inconsistent. It still looks fine in isolation.
By the tenth panel, you have ten different visual vocabularies. Every panel "looks fine" on its own, but switching between them feels like switching between applications built by different teams. The Mental model overhead is real: the user has to re-learn visual cues every time they change panels.
This is not a hypothetical scenario. It is exactly what happened in PGX before the Visual Construction System was built. A formal audit by four independent reviewers scored the framework's 22 panels at an average of 11.9 out of 20 on visual consistency. The bottom panels scored 7 out of 20.
The solution is not "try harder" or "follow guidelines." The solution is a system that makes inconsistency harder than consistency.
A single header file defines every visual value used across all 25 PGX editor panels. There are no hardcoded colors, no magic numbers, no per-file font definitions. Every visual decision traces back to a named token.
Surfaces — The background hierarchy:
- Base: The darkest background, used for panel roots
- Raised: One step lighter, for cards and elevated containers
- Elevated: Two steps lighter, for tooltips and overlays
- Overlay: Semi-transparent, for modal backdrops
Text — Four levels of emphasis:
- Primary: Full-contrast text for main content
- Secondary: Reduced contrast for supporting text
- Muted: Low contrast for captions and labels
- OnColor: High-contrast text for use on colored backgrounds
Semantic — Status communication:
- Good (green): Success, healthy, passing
- Warning (amber): Degraded, attention needed
- Error (red): Failed, critical, broken
- Info (blue): Neutral information, highlights
- Neutral (gray): Inactive, disabled, placeholder
System — One color per subsystem:
- Save: green. GameFlow: orange. PSO: cyan. LevelFlow: indigo. Loading: magenta. Profile: yellow. MGOS: purple. Audio: orange. Construction: teal. Data Registry: cyan. And so on.
System colors are the framework's visual identity. When a developer sees a cyan accent bar, they know they are looking at a PSO or Data Registry panel. When they see magenta, they know it is Loading.
10 font tokens, each with a defined style and size:
| Token | Style | Size | Purpose |
|---|---|---|---|
| PanelTitle | Bold | 13pt | Panel headers only |
| SectionHeader | Bold | 11pt | Section dividers |
| SubHeader | Bold | 10pt | Graph labels, subsection titles |
| Body | Regular | 10pt | Primary content |
| BodySmall | Regular | 9pt | Compact mode content |
| Badge | Bold | 9pt | Status badges, filter buttons |
| Caption | Regular | 8pt | Legends, footer text |
| Mono | Monospace | 9pt | IDs, timestamps, versions |
| KPIValue | Bold | 18pt | KPI card values |
| KPILabel | Regular | 8pt | KPI card labels |
No panel defines its own font. Every text element references one of these 10 tokens.
A base-4px rhythm:
| Token | Value | Use |
|---|---|---|
| XS | 2px | Micro-gaps (icon to text tight) |
| SM | 4px | Tight gaps (label to graph, between badges) |
| MD | 8px | Standard gaps (icon to text, card padding) |
| LG | 12px | Content gaps (graph label margins) |
| XL | 16px | Section internal spacing |
| XXL | 24px | Section separation |
All spacing values multiply by a density factor (1.0x default, 0.75x compact), giving every panel a built-in density toggle without per-panel implementation.
- Border: Default (subtle dividers), Subtle (barely visible), Accent (system-colored)
- Radius: SM (2px for badges), MD (4px for cards), LG (8px for panels)
- Width: AccentBar (2px), AccentStripe (4px for section dividers)
- Height: Row heights for default and compact density
- Motion: Timing values for animations (not yet widely adopted)
Tokens define the vocabulary. Atomic widgets define the grammar.
A 2px horizontal stripe in a specified color. Every PGX panel starts with an accent bar in its system color. It is the visual signature that says "this is a PGX panel" and "this panel belongs to system X."
22+ instances across all panels.
Title text (PanelTitle token), optional subtitle (Body token), optional density toggle, optional action buttons. Standardized layout ensures that every panel's top section has the same visual weight and interaction pattern.
21 instances — one per panel that has content (the Hub uses a custom header).
A background band with optional accent stripe, title text, and a right-content slot.
The section divider is the most-deployed atomic widget: 75 instances. It replaces the ad-hoc section headers that previously existed in various forms — some bold text, some with lines, some with backgrounds, some with nothing.
The right-content slot is important: filter buttons and range selectors live inside the section header, not in a separate row below it. This follows Dogma D10 (filter integration) and saves vertical space.
A compact metric card: 2px accent bar at the top, optional icon, label in small text, value in large bold text. Supports lambda-driven value updates for live data.
29 instances, typically arranged in horizontal rows of 2-4 at the top of panel sections.
A colored pill with text. Used for state indicators, category labels, and filter buttons. 6 instances.
A sticky bar at the bottom of the panel with status text and optional action buttons. 19 instances.
A centered composition of icon, title, and description for panels or sections that have no data to show. Shows a clear message about why data is missing and what the user can do about it.
Column headers with fixed widths, matching the token system's typography and color conventions.
A tiny colored circle (green/yellow/red) for inline health indicators in lists and tables.
A progress bar with configurable thresholds for visualizing platform budget consumption. Changes color as the value approaches or exceeds the budget.
A standardized row widget with optional system-color accent, consistent padding, and fixed-width columns.
The atomic widgets provide consistent building blocks. The UX Dogmas ensure those blocks are assembled consistently.
These are not guidelines. They are non-negotiable rules that emerged from a formal audit process and are enforced as permanent design law.
D1 — Vertical Oxygen: Content blocks never touch. Section dividers carry 24px top padding. Graph sections follow a specific spacing pattern: 12px label-top, 4px label-to-graph, 4px graph-to-legend, 24px between groups.
D2 — Horizontal Proximity (Gestalt): Related data is visually grouped. Action buttons live next to their content. Table columns use fixed widths, not fill-width. If the eye must travel more than 400px horizontally to connect information, the layout is broken.
D3 — Section Headers: All section headers use the section divider widget. Background band, accent stripe in system color, bold title, right-content slot for filters. No exceptions.
D4 — KPI Cards: Top accent bar (2px). Optional icon. Label in 8pt regular. Value in 18pt bold. Standard padding. No bottom decorations.
D5 — Accent Identity: Every panel starts with a 2px accent bar in its system color. Section dividers carry the same color. KPI chips use semantic colors.
D6 — Typography Hierarchy: 10 font tokens, strictly assigned by purpose. No ad-hoc font sizes.
D7 — Spacing Scale: Base-4px rhythm. Six named sizes from XS (2px) to XXL (24px).
D8 — Density Awareness: Default 1.0x, Compact 0.75x. Row heights adjust. Font sizes adjust. Toggle in panel header.
D9 — Theme Mechanism: Lambda-driven values for theme-sensitive colors. Minimum two themes: dark (default) and bright (validation). Themes affect only surface and text base colors.
D10 — Filter Integration: Filters live in section header right-content slots. No separate filter rows.
The Visual Construction System was not designed in isolation and then adopted. It was built through a five-phase migration that touched every existing panel:
Created the token header and the Slate input method bridge. Established the color, font, and spacing vocabularies. Built the first 11 atomic widgets.
Built the Visual Showcase panel — an interactive catalog of every token and widget. This served as both a reference and a validation tool: if a widget looked wrong in the Showcase, it would look wrong in every panel.
Migrated all 27 panels to use the token system. Over 450 individual replacements: hardcoded color values became named tokens, inline font definitions became font tokens, magic-number padding became spacing tokens.
Three panels were migrated manually (they required careful attention to system-specific visual logic). The remaining 24 were migrated systematically, each following the same token replacement process.
Replaced ad-hoc UI patterns with atomic widgets. 151 widget instances across 21 panels in the first pass. One panel (the Registry Validation tab) was excluded due to a circular dependency between editor modules — it uses the tokens directly but constructs its own headers.
Three sub-phases:
- E1: Dead code cleanup. Removed 4 obsolete utility functions, deleted the v1 empty state widget (replaced by v2), reduced shared utilities from 7 to 5.
- E2: Remaining token replacements. 169 color and font replacements across 19 files, reaching 0 remaining hardcoded font references.
- E2.1: Final widget adoption. 16 additional widget instances in 2 panels, bringing the total from 151 to 167.
| Metric | Before | After |
|---|---|---|
| Hardcoded colors | 500+ | 72 (all domain-specific or intentional) |
| Hardcoded fonts | 100+ | 0 |
| Hardcoded spacing | Uncounted | Tokens everywhere |
| Atomic widget instances | 0 | 167 |
| Panels using token system | 0 | 27 |
| Average UX score (audit) | 11.9 / 20 | 16.5+ / 20 (estimated post-remediation) |
The 72 remaining hardcoded colors are intentional: domain-specific colors (like per-category tints in the Data Registry) and system-specific visualization colors that do not generalize to tokens.
- Development Preview
- Getting Started
- Release branch catalog
- Public Plugin Matrix
- Early Preview Plugins
- Known Issues
- Architecture Overview
- Plugin Topology
- Module Reference
- Configuration and Registry
- Data-Driven Design
- Profiles and Budgets
- Gameplay Tag Architecture
- Initialization Pipeline
- Cross-Plugin Communication
- Message System
- Event Handlers
- Logging and Trace
- Runtime Flows
- Blueprint API Design
- Editor Integration
- Editor Visual System