Vector UI

Reusable thin-line control-room UI primitives for Scarecrow and future projects.

This package is the shared implementation of the vector diagnostic language used across the Scarecrow editor. It is intentionally domain-agnostic: it should provide the system language, not ROM-specific concepts.

The art-direction source of truth now lives in NERV_ART_DIRECTION.md. The typography source of truth now lives in NERV_TYPOGRAPHY_SPEC.md. The media and monitoring source of truth now lives in NERV_MEDIA_MONITORING_SPEC.md.

Install

When published:

npm install @kytra/nerv-ui

Current consumer setup:

import '@kytra/nerv-ui/styles/theme.css'
import '@kytra/nerv-ui/styles/base.css'
import { SystemFrame, SystemField, SystemButton } from '@kytra/nerv-ui'

For the Swift NervUI to React port strategy, see NERVUI_REACT_PORT.md.

What It Provides

Tokens and Base Styles

• styles/theme.css
• styles/base.css

These define:

• signal colors
• background surfaces
• typography families
• spacing
• motion
• global dark-mode baseline behavior for the system

Build and Catalog

• npm run build now produces a real dist/ package with:

  • index.js
  • index.d.ts
  • compiled component CSS
  • copied styles/theme.css
  • copied styles/base.css

• npm run dev:vector-ui in the Scarecrow web app opens the live component lab at /?catalog=vector-ui.

• npm run test:run runs the package-local Vitest suite.

• npm run check runs:

  • typecheck
  • component tests
  • package build

• npm run pack:dry-run validates the package artifact shape.

• npm run release:verify runs the full package release gate.

• npm run publish:public publishes the package using the configured public access mode.

• npm run test:visual in the Scarecrow web app runs screenshot regression tests against the live catalog route.

• npm run test:visual:update in the Scarecrow web app refreshes those screenshot baselines intentionally.

• This catalog is the current stand-in for Storybook.

  • It is intentionally lighter and closer to the real Scarecrow runtime.
  • If we later need addon-style controls, visual regression workflows, or public-facing docs polish, Storybook becomes a stronger next step.

Current Quality Gates

The package now has a package-local test harness using:

• Vitest
• jsdom
• Testing Library

Current representative tests cover:

• dialog semantics and escape-close behavior
• combobox filtering and selection flow
• table empty and populated states
• tab selection callbacks
• field labeling and native input interaction

This is not full coverage yet, but it is the start of a real library-quality workflow rather than demo-only confidence.

Visual Regression

Visual stability is currently guarded through the live catalog instead of Storybook.

Current screenshot coverage includes:

• overview shell and coverage surface
• controls surface
• diagnostics surface
• desktop and large-phone viewports

The current baseline images live under:

• apps/web/tests/visual/vector-ui-catalog.spec.ts-snapshots

For the release flow and semver guidance, see RELEASING.md.

Mobile Support Matrix

Current support intent:

• mobile-ready

  • SystemButton
  • SystemField
  • SystemCheckbox
  • SystemChip
  • SystemChipButton
  • SystemTabs
  • CompactTaskFlow
  • AlertBanner
  • SystemDialog
  • SystemDrawer
  • SystemMenu
  • SystemTooltip
  • SystemTable with horizontal overflow behavior
  • SystemToolbar
  • WorkspaceSplit

• mobile-adaptive

  • CommandStrip
  • FrameTitle
  • SystemAccordion
  • SystemDefinitionList
  • SystemPagination
  • SystemStepper
  • SubsystemRail
  • InspectorSection
  • InspectorRail
  • SignalPlot
  • ContourPlot
  • HexCluster
  • TopologyGrid
  • SelectionBracket
  • IndicatorRail

The adaptive diagnostics now switch automatically on narrow screens:

• SignalPlot
  • adds guide rails and compact value labels
• ContourPlot
  • simplifies traces and adds a low-noise frame
• HexCluster
  • swaps full in-hex labels for compact tags plus a legend
• TopologyGrid
  • swaps side labels for node tags plus a legend
• SelectionBracket
  • adds a framed compact focus state instead of only corner marks
• IndicatorRail

CompactTaskFlow is the library-owned pattern for turning a dense workstation into a compact lane flow. It owns:

• the mobile lane tab frame
• active-lane visibility
• the desktop-to-compact transition

Apps should supply the lane items, active lane state, and any desktop grid classes, but they should not rebuild the lane selector and hide/show behavior themselves.

• swaps wrapped long labels for compact segment legends

Current Components

Exported from src/index.ts:

• AlertBanner
• AudioMonitor
• ChamferPanel
• CollapsibleSection
• CommandStrip
• ContourPlot
• DividerRail
• FrameTitle
• GridOverlay
• HazardBar
• HexGridBackground
• HexCluster
• IndicatorRail
• InspectorRail
• InspectorSection
• MAGIVotingPanel
• ScanLineOverlay
• ScreenBorderFrame
• SegmentedBarMeter
• SevenSegmentDisplay
• StatusPanel
• StatusTag
• SubsystemRail
• SystemAccordion
• SystemAppBar
• SystemBadge
• SystemBreadcrumbs
• SystemButton
• SystemButtonGroup
• SystemChip
• SystemChipButton
• SystemCheckbox
• SystemCodeBlock
• SystemCombobox
• SystemDefinitionList
• SystemDialog
• SystemDrawer
• SystemEmptyState
• SystemField
• SystemFilterBar
• SystemFrame
• SystemIconButton
• SystemInputAdornment
• SystemInlineAlert
• SystemLabel
• SystemListButton
• SystemMetric
• SystemMenu
• SystemModal
• SystemPagination
• SystemPopover
• SystemProgressBar
• SystemRadioGroup
• SignalLabel
• SystemSegmentedControl
• SystemStepper
• SystemSplitButton
• SystemSwitch
• SystemTable
• SystemSummaryCard
• SystemTabs
• SystemToolbar
• SystemTooltip
• SelectionBracket
• SignalPlot
• SignalScrubber
• ToastNotification
• TopologyGrid
• TransportControls
• VideoMonitor
• WarningStripe
• WaveformDisplay
• WorkspaceSplit
• WorkspaceHeader

Design Intent

The package exists to solve two different problems:

1. outer shell structure
2. inner editor control consistency

It should also solve a third problem now:

3. strong visual authorship

@kytra/nerv-ui should not drift toward a neutral web dashboard aesthetic. The library is expected to be aggressively art-directed, with the studio app acting as the proving ground for that visual language.

The first version of the migration proved that shell primitives alone are not enough. Dense editor screens still feel inconsistent if they keep:

• generic select menus
• old rounded list cards
• ad hoc metric tiles
• legacy buttons
• light-theme form controls

So this package should continue to grow in both directions:

• layout and framing primitives
• interior control primitives

What Belongs Here

Good candidates for vector-ui:

• frames
• rails
• tabs
• buttons
• status tags
• chips
• form fields
• metrics
• list rows
• reusable warning and diagnostic surfaces

Bad candidates for vector-ui:

• sprite-specific mold editors
• ROM-specific field groupings
• monster or formation semantics
• emulator control logic
• any component that only makes sense in one screen and has no second consumer

Usage Rules

Prefer Real HTML Controls

Use native:

• button
• input
• select
• textarea

and style them through shared wrappers instead of replacing them with custom fake controls.

Theme Native Menus Explicitly

One practical lesson from Scarecrow:

select styling must include option and optgroup handling where browsers allow it. Styling only the closed field is not enough.

Use Local CSS Modules for Domain Surfaces

The package should provide the system language. App-local CSS Modules should handle:

• domain-specific layout
• canvas staging
• unusual tool geometry
• temporary migration bridges away from legacy CSS

Avoid Decorative Drift

If a new component is added, it should answer at least one of these questions:

• Does it repeat across screens?
• Does it solve a real UX consistency problem?
• Does it encode a reusable part of the system language?

If not, keep it local to the app.

Suggested Consumption Pattern

Use the package like this:

• SystemFrame for section boundaries
• FrameTitle and WorkspaceHeader for structured page titles
• CommandStrip for telemetry summaries
• SystemButton for actions
• SystemField and SystemCheckbox for form controls
• SystemListButton for selectable editor rows
• SystemMetric and SystemSummaryCard for readout tiles
• SystemChip and SystemChipButton for compact state and mode selection

Then wrap truly custom tools, such as sprite canvases or editor overlays, with local CSS Modules.

Near-Term Expansion

The most likely next additions are:

• explicit SVG icon sets
• stronger popover/menu positioning helpers
• broader component test coverage
• accessibility-focused assertions for more primitives
• broader visual regression coverage
• package publishing/release workflow beyond local dist builds

Reference

The fuller system write-up and roadmap currently live in the Scarecrow repo docs.