planet/docs/deprecated/admin-next-soft-glass-goal-driven-plan.md

Admin Next Soft Glass Goal-Driven Plan

Goal

Rebuild /admin-next/* into a modern soft-glass / light-neumorphic console while keeping the legacy Ant Design admin routes available for comparison. The new console must use visual references only as design anchors, not as imported templates, and must be implemented as Planet-owned reusable components and page patterns.

The redesign must cover desktop and mobile. Data display, icon semantics, table readability, and scroll behavior are first-class acceptance criteria.

Criteria For Success

• This archived plan exists at docs/deprecated/admin-next-soft-glass-goal-driven-plan.md.
• /admin-next/* has real pages for every route; route usage of ShadowPage is removed.
• Admin Next supports system, light, and dark theme modes using the same persistence and system-theme idea as Docs.
• The visual language reads as soft-glass / light-neumorphic instead of an AntD reskin: translucent panels, fine borders, subtle glow, cool backgrounds, restrained accent colors, crisp icons, and tactile controls.
• Mobile is explicitly designed: mobile navigation, filter sheets/chips, card-list data views, full-screen detail sheets, and bottom action bars instead of squeezed desktop tables.
• Tables do not show double scrollbars. Long fields are inspectable, copyable, or expandable; important columns stay readable.
• Existing custom scrollbar components remain the default scroll experience.
• cd frontend && bun run build passes.
• Static checks can prove no route-level placeholder remains.

Reference Strategy

Use references to calibrate feel, not to take over code:

• User-provided soft-glass / light-neumorphic dashboard images define the desired mood.
• Shadcn / Tailwind / glassmorphism admin templates may be inspected for shadow, spacing, panel, dark-mode, and app-shell ideas.
• Do not import a complete template, router, auth layer, state layer, or business page.
• Planet-specific interactions such as datasource tasks, BGP briefs, AI settings, log streams, Earth resources, and custom scrollbars are implemented in this repo.

Source-Of-Truth Mining

Design content and page boundaries from existing repo history and docs:

• docs/CHANGELOG.md
• docs/plans/*
• docs/technical/*frontend*
• TODO.md

Important current boundaries:

• DataSources is a datasource directory and runtime-control page, not a configuration editor.
• Collection Management owns collector endpoint, credential, custom source, mapping, and runtime configuration.
• Earth Content owns TV livestreams, brand assets, boundary precision, basemap, and Earth display resources.
• AI owns provider settings, tools, prompts, and Playground.
• BGP is an observability and evidence workspace, not just tables.
• Alerts is a duty/analysis workspace for system, BGP, and situational risk.
• Logs should become a usable log workbench with filtering and structured detail.
• Settings should keep platform settings only.

Reusable Architecture

Recommended structure:

• admin-next/design: theme tokens, theme mode, status colors, icon semantics, chart themes, scrollbar themes.
• admin-next/components: primitive UI such as button, input, select, tabs, dialog, drawer, badge, status pill, icon badge.
• admin-next/patterns: page patterns such as PageFrame, GlassPanel, MetricCard, CommandBar, FilterRail, InspectorDrawer, DataWorkspace, SettingsWorkspace, ScrollableRegion, TableRegion, and MobileSheet.
• admin-next/features: business modules such as datasources, data-list, bgp, alerts, ai, logs, settings, earth-content, collection-management, users.
• admin-next/services: feature API gateways and hooks. Pages should not scatter URL construction.
• admin-next/routes: route manifest used by navigation, command search, breadcrumbs, and legacy links.

Interaction Rules

• Row click opens an inspector; frequent row actions live in the inspector header.
• Bulk selection opens a floating command bar.
• Common filters stay visible; advanced filters open a sheet/drawer.
• Detail, JSON, log context, and AI brief use inspector or reading panels instead of stacked modal dialogs.
• Settings are split into FormSection blocks with local save, dirty state, connection test, and reset.
• Dangerous actions use a confirm sheet.
• Loading, empty, error, and retry states are shared through reusable patterns.

Mobile Rules

• Do not squeeze desktop layout into mobile.
• Use mobile navigation and sheets instead of a permanent desktop sidebar.
• Filters collapse into a filter sheet; active filters remain visible as chips.
• Data workspaces default to card-list mode on mobile and allow explicit table mode for dense comparison.
• Details open in full-screen mobile sheets.
• Batch actions use a sticky bottom command bar.
• Long logs and JSON use full-screen reading/editing surfaces with custom scrollbars.

Table And Data Display Rules

• Tables must prioritize complete data display:
  • key columns get stable widths and priority;
  • long fields have peek/expand or inspector detail;
  • IDs, URLs, metadata, and errors are copyable;
  • complex fields are rendered fully in inspector.
• Desktop tables use one TableRegion scroll container.
• Mobile defaults to card-list display and supports dense table mode.
• Native scrollbar visuals are hidden where custom scrollbars apply.

Icon Rules

• Use lucide-react.
• Define icon semantics by category:
  • navigation icon;
  • entity icon;
  • status icon;
  • action icon;
  • severity icon.
• Icons must not be the only semantic carrier unless the icon is universally obvious; use labels or tooltips.
• Status icons pair with StatusPill.
• Colors come from tokens, not ad hoc hard-coded values.

Page Design

Dashboard

• System health, realtime connection, datasource activity, task trend, alert summary, recent events, and quick commands.
• Restart flow uses a confirm sheet and log console.
• Mobile uses horizontal metric cards and collapsible event/command panels.

DataSources

• Datasource directory and runtime control.
• Desktop: overview rail, datasource table/list, inspector.
• Mobile: datasource cards with status, latest task, trigger/toggle actions.
• Batch trigger uses command bar.
• Endpoint/config/task details are shown fully in inspector.

DataList

• Collection result browsing, search, source/type filters, paging, distribution chart, and detail inspector.
• Fix double scrollbars.
• Mobile defaults to cards and allows table mode.

BGP

• Views: collectors, incidents, anomalies, events, AI brief.
• Emphasize severity, region, ASN/prefix, collector coverage, and evidence.
• AI brief shows facts, judgment, and evidence gaps.

Alerts

• Real pages for system, BGP, and situational alerts.
• Shared alert workspace with stats, severity/status filters, list, and inspector.
• AI brief appears in inspector/mobile sheet.

AI

• Provider, tools, prompts, and Playground.
• Provider and tool settings use local save and connection tests.
• Prompt registry is grouped by task.
• Mobile Playground uses step tabs rather than cramped columns.

Logs

• Log workbench with source, level, date, search, refresh, copy, and structured detail.
• Desktop uses a terminal-like log stream.
• Mobile rows expand or open a full-screen reading sheet.

Users

• Search, role filter, create/edit/delete, Gatekeeper groups.
• Edit/create in drawer/sheet.
• Gatekeeper groups use checkbox chips.

Settings

• Platform settings only: system, notification, security, SMTP.
• Each section saves independently.

Earth Content

• TV livestreams, brand assets, boundary precision, basemap, and layer resources.
• Resource previews, upload state, and boundary build status are emphasized.

Collection Management

• Collector config, custom sources, mapping, runtime control.
• Custom source creation uses a step sheet.
• Advanced JSON is isolated in a collapsible editor.

Milestones

1. Save this plan and establish goal-driven criteria.
2. Build design/theme/pattern foundations.
3. Remove route-level placeholders and create real pages for all /admin-next/* routes.
4. Redesign layout, theme, mobile shell, scroll behavior, and table behavior.
5. Fill core workspaces with real API calls and reusable patterns.
6. Verify build, no ShadowPage route usage, and core route availability.

Verification

Run:

cd frontend && bun run build
rg "ShadowPage" frontend/src/admin-next
rg "axios\\." frontend/src/admin-next/pages
rg "overflow: auto|overflow-y: auto" frontend/src/admin-next

Manual route checks:

• /admin-next
• /admin-next/datasources
• /admin-next/data
• /admin-next/bgp
• /admin-next/alerts/system
• /admin-next/alerts/bgp
• /admin-next/alerts/situational
• /admin-next/ai
• /admin-next/logs
• /admin-next/users
• /admin-next/settings
• /admin-next/earth-content
• /admin-next/collection-management

Manual viewport checks:

• desktop;
• mobile width;
• low height;
• 125% / 150% browser zoom;
• light / dark / system theme modes.