sam/dev_arc_aws
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: fix conflicting Kiro steering/spec files (#25)

Browse source 
* Add editable display-name field to generic integrations

Lets users set a custom name for Proxmox, Docker, AWS, Remote Desktop,
Netbird, Cloudflare, Uptime Kuma, and Weather integrations, separate
from the host/IP field, mirroring the SSH host rename pattern.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016kF4hZWEkRCPPvCZTeXxn4

* Surface the new-integration name field as a labeled input

The name field for new generic integrations was a faint header input
with only placeholder text, easy to miss. Move it into the form grid
as a proper labeled "Name" field next to the other connection fields.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016kF4hZWEkRCPPvCZTeXxn4

* Add file upload for SSH private key and certificate fields

Lets users pick a key file from disk (e.g. ~/.ssh) instead of pasting
its contents into the Private Key / OPKSSH Certificate fields.

* Fix SSH private key paste corrupting multi-line PEM format

Private Key and Certificate fields were single-line <input> elements,
which strip newlines on paste and corrupt PEM-formatted keys (causing
'Unsupported key format' errors). Render them as multi-line textareas
instead so pasted keys keep their line breaks.

* Add JSON-converted bookmark import file for Archnest data import

Converts homarr-bookmarks.md into the format expected by /api/data/import.

* Auto-populate bookmark icons via favicon service in import JSON

Each bookmark now points to Google's favicon endpoint for its domain
instead of having no icon at all.

* docs: fix conflicting Kiro steering/spec files missed in prior cleanup

The earlier doc-cleanup pass only checked root-level markdown files and
missed .kiro/, a dotdir holding Kiro IDE spec-driven-dev artifacts. Two
files there directly contradicted the real app and design-decisions.md:

- .kiro/steering/design-rules.md is auto-injected into every Kiro
  session, but stated an 80px/50px sidebar and Zustand state management
  — both wrong (real app: 200px/64px sidebar, plain React state +
  localStorage, no Zustand). Rewrote it to match design-decisions.md so
  Kiro doesn't steer future sessions on stale info.
- .kiro/specs/archnest-dashboard/requirements.md was an abandoned
  requirements-only spec (no design.md/tasks.md ever followed) for the
  original 6-page/Network-page/CDN-asset vision, same vintage as the
  already-deleted archnest-blueprint.md. Removed the whole spec
  directory since nothing references it and it never matured past
  requirements.

Documented both files (and why they were removed/rewritten) in the
README's documentation map.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016kF4hZWEkRCPPvCZTeXxn4

---------

Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
Samuel James 2026-06-20 10:51:11 -04:00 • committed by GitHub
parent d8286ac42b
commit b2600e2577
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 81 additions and 274 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
.kiro/specs/archnest-dashboard/.config.kiro
View file

@ -1 +0,0 @@
{"specId": "7d81eaca-5010-4445-bc59-f3a49742d6c3", "workflowType": "requirements-first", "specType": "feature"}

194
.kiro/specs/archnest-dashboard/requirements.md
View file

@ -1,194 +0,0 @@
# Requirements Document
## Introduction
ArchNest Dashboard is a 6-page custom dashboard designed as a portfolio showcase piece. It provides system health monitoring, infrastructure management, network analytics, bookmark management, an embedded SSH terminal, and user settings — all unified under a dark/gold aesthetic. The application targets deployment on AWS infrastructure as a free, open-source tool with a potential paid tier for advanced features.
## Glossary
- **Dashboard**: The ArchNest single-page application providing all 6 pages of functionality
- **Sidebar**: The fixed left navigation component (80px wide) containing the logo, nav items, and system status indicator
- **Top_Bar**: The shared header component (56px height) displaying page title, search bar, notifications, and user info
- **Hero_Banner**: A full-width banner image component shown on certain pages (Glance, Infrastructure, Network, BookNest)
- **Card**: A styled container element with 12px border radius, dark background (#141518), and 1px border (#1E2025)
- **Glance_Page**: The main operations dashboard showing system health overview at route `/`
- **Infrastructure_Page**: The cloud infrastructure monitoring page at route `/infrastructure`
- **Network_Page**: The network performance and security monitoring page at route `/network`
- **BookNest_Page**: The digital library and bookmark management page at route `/booknest`
- **Terminal_Page**: The embedded SSH terminal page at route `/terminal`
- **Settings_Page**: The user preferences and system configuration page at route `/settings`
- **Sparkline**: A small inline chart showing data trends without axes or labels
- **Progress_Ring**: A circular progress indicator displaying percentage values
- **Status_Indicator**: A colored dot (green/yellow/red) representing operational state
- **Gold_Accent**: The primary accent color (#C8A434) used for active states, links, and highlights
- **CDN**: The GitHub-hosted asset repository at `https://raw.githubusercontent.com/SamuelSJames/assets-public/master/`
- **Terminal_Bridge**: The Node.js WebSocket-to-SSH bridge service enabling browser-based terminal connections
- **Bookmark**: A stored link entry with name, URL, icon, category, and favorite status
## Requirements
### Requirement 1: Application Shell and Navigation
**User Story:** As a user, I want a consistent navigation sidebar and top bar across all pages, so that I can move between dashboard sections efficiently.
#### Acceptance Criteria
1. THE Dashboard SHALL render a fixed left Sidebar of 80px width containing the ArchNest logo, 6 navigation items (Glance, Infrastructure, Network, BookNest, Terminal, Settings) each displaying an icon at 18px and a label at 14px, a collapse/expand toggle button, and a system status indicator at the bottom showing a colored dot (green for operational, orange for degraded, red for critical) with accompanying status text.
2. WHEN a user clicks a navigation item in the Sidebar, THE Dashboard SHALL navigate to the corresponding route, highlight the active item with Gold_Accent color and a 3px left border, and remove the highlight from the previously active item.
3. WHEN a user clicks the Sidebar collapse toggle, THE Sidebar SHALL collapse to icon-only mode at 50px width (hiding labels and showing only icons), and clicking the toggle again SHALL expand the Sidebar back to 80px with labels visible.
4. THE Top_Bar SHALL display at a fixed height of 56px the current page title (bold, uppercase, 18px), a search bar (300px width, rounded), a notification bell icon, and a user avatar (36px with gold ring) with the user name and role label.
5. IF the notification count is greater than zero, THEN THE Top_Bar SHALL display a badge on the notification bell icon showing the numeric count up to 99, and "99+" for counts exceeding 99.
6. WHILE the viewport width is between 768px and 1200px, THE Sidebar SHALL auto-collapse to icon-only mode at 50px width and display a tooltip with the navigation item label when the user hovers over a navigation icon.
7. WHILE the viewport width is below 768px, THE Sidebar SHALL transform into a bottom navigation bar displaying all 6 navigation items as icons with labels below each icon, and the system status indicator SHALL be hidden.
8. IF a user navigates to an undefined route, THEN THE Dashboard SHALL redirect the user to the Glance page at the root route.
### Requirement 2: Global Design System
**User Story:** As a user, I want a cohesive dark theme with gold accents throughout the application, so that the interface is visually consistent and professional.
#### Acceptance Criteria
1. THE Dashboard SHALL use background color #0D0E10 for pages, #141518 for Cards, and #0A0B0D for the Sidebar.
2. THE Dashboard SHALL use #C8A434 as the primary Gold_Accent color for links, active states, progress bars, and interactive highlights.
3. THE Dashboard SHALL use #2ECC71 for success/operational states, #E67E22 for warnings, and #E74C3C for critical/error states.
4. THE Dashboard SHALL render text in #E8E6E0 (primary, 14px body), #7A7D85 (secondary/labels, 12-13px), and #C8A434 (accent/active elements).
5. THE Dashboard SHALL render Card titles at 12-13px, uppercase, with 1px letter-spacing in secondary color (#7A7D85), and large numbers at 28-36px bold in primary color (#E8E6E0).
6. WHEN a user hovers over a Card, THE Dashboard SHALL transition the Card border color to Gold_Accent (#C8A434) over 0.2 seconds using ease timing.
7. THE Dashboard SHALL apply 12px border radius, 1px solid #1E2025 border, 20-24px padding, and no box-shadow (flat design) to all Cards.
8. WHEN a Card or interactive element receives keyboard focus, THE Dashboard SHALL display a visible Gold_Accent (#C8A434) outline of at least 2px to meet accessibility focus indicator requirements.
### Requirement 3: Hero Banner Display
**User Story:** As a user, I want a branded hero banner on main pages, so that the dashboard has visual identity and branding.
#### Acceptance Criteria
1. THE Hero_Banner SHALL display the archnest-brand.png image from the CDN at full width (100%) of the main content area with 12px border radius, overflow hidden, and the image scaled to cover the entire banner area while maintaining its aspect ratio.
2. WHILE the Glance_Page is active, THE Hero_Banner SHALL render at 200px height.
3. WHILE the Infrastructure_Page, Network_Page, or BookNest_Page is active, THE Hero_Banner SHALL render at 120px height.
4. WHILE the Terminal_Page or Settings_Page is active, THE Dashboard SHALL hide the Hero_Banner.
5. IF the hero banner image fails to load, THEN THE Hero_Banner SHALL display the banner container at the specified height with the card background color (#141518) and no broken-image icon visible.
### Requirement 4: Glance Page — System Overview
**User Story:** As a user, I want a high-level overview of system health, resources, alerts, and network traffic on the main page, so that I can assess operational status at a glance.
#### Acceptance Criteria
1. THE Glance_Page SHALL display a top row of 4 status Cards showing: System Status (percentage 0–100% with Progress_Ring, "Last checked: Xm ago" timestamp, and a gold Sparkline at the bottom showing recent health check trend), Infrastructure (server icon + resource count + "Total Resources" subtitle + colored dot breakdown: Running/Warning/Critical), Security (shield icon + alert count + "Active Alerts" subtitle + severity breakdown: Low/Medium/High), and Network (network icon + uptime percentage + "Network Uptime" subtitle + gold area Sparkline showing 24h uptime trend).
2. THE Glance_Page SHALL display a middle row with 3 columns (30%/40%/30%): Resource Overview (card title + X close button, 5 progress bars each with an icon, label, gold fill bar, and "current / max" value), Recent Activity (card title + X close button, 5 timestamped events each showing an icon, event title, source/service subtitle, and relative timestamp), and Top Alerts (card title + "View all" link, up to 4 alerts each with severity-colored dot, alert name, source subtitle, and relative timestamp).
3. THE Glance_Page SHALL display a bottom row with 2 columns (65%/35%): Network Traffic (card title, dark area chart with gold/amber gradient fill, stats showing Incoming Gbps with percentage change and Outgoing Gbps with percentage change) and Shortcuts (card title, 4 icon buttons in a 2x2 or 1x4 grid, each with an outlined icon in a bordered container and label below: Add Server, Create Backup, Deploy App, View Logs).
4. THE Glance_Page footer SHALL display contextual stats: System Status percentage, Resource count, Alert count, and Uptime percentage, along with a "Last updated" timestamp on the right indicating time since last data refresh.
5. IF data for any status Card or section fails to load, THEN THE Glance_Page SHALL display a loading skeleton placeholder within that Card or section and not block rendering of other sections.
6. WHEN the Glance_Page loads, THE Progress_Ring and Sparkline SHALL animate their fill from 0 to the current value within 1 second.
7. WHEN a user clicks the X close button on a Card (Resource Overview or Recent Activity), THE Glance_Page SHALL hide that Card from view for the current session.
### Requirement 5: Infrastructure Page — Resource Management
**User Story:** As a user, I want to monitor cloud infrastructure resources, costs, and health across regions, so that I can manage my cloud environment effectively.
#### Acceptance Criteria
1. THE Infrastructure_Page SHALL display sub-tabs with a maximum of 4 tabs visible at once (Overview, Compute, Storage, Database) and remaining tabs (Network, Containers, Load Balancers, DNS, Backups, Tags) accessible via a scrollable overflow menu, defaulting to the Overview tab as active.
2. THE Infrastructure_Page SHALL display a top row of 5 status Cards: Total Resources (integer count with percentage trend and up/down arrow), Total Cost MTD (dollar amount formatted as $XX,XXX.XX with percentage trend), Resource Health (percentage 0–100% with trend), Active Alerts (integer count with percentage trend), and Uptime (percentage 0–100% with trend).
3. THE Infrastructure_Page SHALL display a middle row with 3 columns (30%/40%/30%): Resource Distribution (donut chart showing category name and percentage share), Infrastructure Map (dark world map with gold glowing dots at region locations and connection lines, footer showing region count, AZ count, and resource count with a "Live" indicator), and Top Resources by Utilization (ranked list of up to 5 items showing instance name, type, and percentage utilization).
4. THE Infrastructure_Page SHALL display a bottom row with 3 columns (35%/35%/30%): Resource Trend (multi-line area chart showing Compute, Storage, Database, and Network lines over a 7-day X-axis), Cost Breakdown MTD (donut chart showing service name, dollar amount, and percentage share), and Recent Activity (timestamped list of up to 5 events ordered newest-first).
5. THE Infrastructure_Page SHALL provide an "+ Add Resource" action button positioned adjacent to the sub-tabs.
6. THE Infrastructure_Page footer SHALL display contextual stats: provider name, region count, AZ count, resource count, health percentage, MTD cost, and alert count.
### Requirement 6: Network Page — Performance Monitoring
**User Story:** As a user, I want to monitor network performance, traffic patterns, and security threats, so that I can ensure network reliability and safety.
#### Acceptance Criteria
1. THE Network_Page SHALL display sub-tabs with a maximum of 4 tabs visible at once (Overview, Traffic, Topology, Devices) and remaining tabs (Interfaces, VPN, DNS, Firewalls, Load Balancers, Alerts, Reports) accessible via a scrollable overflow menu, defaulting to the Overview tab as active.
2. THE Network_Page SHALL display a top row of 6 status Cards: Network Health (percentage, 0–100%), Total Traffic (throughput in Gbps or Tbps), Packet Loss (percentage, 0–100%), Active Connections (integer count), Threats Blocked (integer count with an orange warning icon displayed when count exceeds 0), and Average Latency (value in milliseconds).
3. THE Network_Page SHALL display a middle row with 3 columns (25%/50%/25%): Top Talkers (ranked list of up to 5 items showing host name and throughput in Gbps), Network Topology (interactive map supporting click-and-drag pan, zoom in/out buttons, and a fullscreen toggle, with gold nodes and connection lines, and a legend indicating Live in green, Warning in orange, and Critical in red), and Interface Utilization (up to 5 interfaces with percentage bars) stacked with Alert Summary (counts grouped by Critical, Warning, and Info severity).
4. THE Network_Page SHALL display a bottom row with 3 columns (35%/35%/30%): Traffic Over Time (area chart with inbound, outbound, and total lines over a 24-hour X-axis from 00:00 to 24:00, Y-axis ranging from 250 Gbps to 1.5 Tbps), Protocol Distribution (donut chart showing protocol name and percentage share), and Recent Events (timestamped list of up to 5 entries, ordered newest first).
5. THE Network_Page SHALL provide a "Last 24 Hours" time-range dropdown and an "Export Report" action button positioned in the page action area adjacent to the sub-tabs.
6. THE Network_Page footer SHALL display contextual stats: region count, site count, device count, interface count, connection count, and network health percentage.
### Requirement 7: BookNest Page — Bookmark Management
**User Story:** As a user, I want to organize, access, and monitor my bookmarks by category with health status tracking, so that I can efficiently manage my digital resources.
#### Acceptance Criteria
1. THE BookNest_Page SHALL display page stats below the title showing total link count, category count, and favorites count in the format: "🔗 {count} Links | 📁 {count} Categories | ⭐ {count} Favorites".
2. THE BookNest_Page SHALL display a Quick Access row with 5 category Cards (Infrastructure, Development, AI Tools, AWS, Networking), each showing up to 5 service icons from the CDN and the total link count for that category.
3. THE BookNest_Page SHALL display bookmark groups in 2 rows of 4 columns each: Row 1 (Infrastructure & Self Hosted, Development & Code, Lab & Networking, AWS) and Row 2 (AI Tools, Learning, Finance, Life), each group displaying up to 20 Bookmark items.
4. THE BookNest_Page SHALL display a right sidebar (25% width) with 4 widgets: Favorites list (maximum 10 items), Recently Used list showing the 5 most recently accessed Bookmarks with relative timestamps (e.g., "5m", "1h", "2h"), Link Health donut chart (Online/Warning/Offline), and Category Breakdown donut chart.
5. WHEN a user clicks the star toggle on a Bookmark item, THE BookNest_Page SHALL add or remove the Bookmark from the Favorites list and render the star icon in Gold_Accent color when favorited or in secondary text color (#7A7D85) when not favorited.
6. THE BookNest_Page SHALL render each Bookmark item with a colored icon (16-20px), name (14px), and star toggle aligned to the right.
7. THE BookNest_Page SHALL classify each Bookmark's link health as "Online" when the link responds successfully, "Warning" when the link responds with degraded performance or non-success status, or "Offline" when the link is unreachable, and display the counts in the Link Health donut chart.
8. IF a Bookmark's service icon fails to load from the CDN, THEN THE BookNest_Page SHALL display a generic fallback icon at the same dimensions (16-20px) without breaking the layout of the Bookmark item.
### Requirement 8: Terminal Page — Embedded SSH
**User Story:** As a user, I want an embedded SSH terminal in the browser with multiple session tabs, so that I can manage remote servers without leaving the dashboard.
#### Acceptance Criteria
1. THE Terminal_Page SHALL render a full-height terminal viewport using xterm.js with JetBrains Mono or Fira Code font at 14px, 5000-line scrollback, and gold block cursor with 500ms blink interval.
2. THE Terminal_Page SHALL display a tab bar (40px height) at the top showing open sessions (maximum 10 simultaneous tabs) with host name and connection Status_Indicator (green for connected, yellow for connecting, gray for disconnected), with the active tab having a gold bottom border.
3. WHEN a user clicks the "+" button in the tab bar, THE Terminal_Page SHALL display a quick-connect dropdown listing saved hosts (Pre, Proxmox, Linode, RackNerd 1, RackNerd 3, Studio).
4. WHEN a user selects a saved host from the dropdown, THE Terminal_Page SHALL initiate an SSH connection through the Terminal_Bridge with a 10-second connection timeout and open a new terminal tab displaying the host name.
5. THE Terminal_Page SHALL display a status bar (28px height) at the bottom showing connection state (Connecting, Connected, or Disconnected), host name, session duration in HH:MM:SS format, and shell type, with split-pane, fullscreen, and disconnect controls on the right.
6. THE Terminal_Page SHALL apply syntax coloring: Gold_Accent for prompts, #E8E6E0 for commands, #7A7D85 for output, #E74C3C for errors, and #1ABC9C for directories.
7. IF an SSH connection attempt fails or times out, THEN THE Terminal_Page SHALL display an error message indicating the failure reason in the terminal viewport and set the tab Status_Indicator to disconnected (gray).
8. WHEN a user clicks the close button on a terminal tab, THE Terminal_Page SHALL terminate the SSH session for that tab and remove the tab from the tab bar, switching focus to the nearest remaining tab.
9. IF the Terminal_Bridge service is unreachable, THEN THE Terminal_Page SHALL display an error message indicating the bridge is unavailable and disable the quick-connect dropdown until connectivity is restored.
### Requirement 9: Settings Page — Configuration
**User Story:** As a user, I want to configure my profile, appearance, integrations, and notification preferences, so that I can personalize the dashboard experience.
#### Acceptance Criteria
1. THE Settings_Page SHALL display a left navigation panel (200px) with sections: Profile, Appearance, Integrations, Notifications, Data & Backup, and About, with the active section highlighted using Gold_Accent color.
2. THE Settings_Page Profile section SHALL display editable fields for avatar (64px with gold ring), display name (maximum 50 characters), role (maximum 30 characters), email (validated for standard email format), and timezone (selectable from standard timezone list), with a "Save Changes" button.
3. THE Settings_Page Appearance section SHALL provide: a Dark/Light theme toggle, accent color swatches (Gold, Teal, Purple, Blue, Green, Red), a font size slider (12-16px in 1px increments), a sidebar expanded/collapsed toggle, an animations on/off toggle, and a card border radius slider (4-16px in 1px increments).
4. THE Settings_Page Integrations section SHALL display configuration Cards for Proxmox, Docker, NetBird, Cloudflare, AWS, Uptime Kuma, and Weather API, each with a Status_Indicator (green for connected, red for disconnected), configuration fields, masked secrets with eye toggle for visibility, and a "Test Connection" button.
5. WHEN a user clicks "Test Connection" on an integration Card, THE Settings_Page SHALL display a loading state during the connection attempt and then show a success indicator if the connection succeeds within 10 seconds.
6. IF a "Test Connection" attempt fails or times out after 10 seconds, THEN THE Settings_Page SHALL display an error indicator with a message describing the failure reason.
7. THE Settings_Page Notifications section SHALL provide toggles for enable/disable, threshold selection (All/Critical/Warning+), email notifications, browser push notifications, and sound with volume slider (0-100%).
8. THE Settings_Page Data & Backup section SHALL provide actions for Export Bookmarks (JSON), Import Bookmarks (accepting JSON files up to 5MB), Export Settings, Reset to Defaults, and Clear Cache.
9. WHEN a user clicks "Reset to Defaults", THE Settings_Page SHALL display a confirmation dialog requiring explicit user confirmation before executing the reset, and SHALL not proceed if the user dismisses or cancels the dialog.
10. THE Settings_Page About section SHALL display application version, author name, repository link, technology stack, and license information.
### Requirement 10: Responsive Layout
**User Story:** As a user, I want the dashboard to adapt to different screen sizes, so that I can use the application on desktop, tablet, and mobile devices.
#### Acceptance Criteria
1. WHILE the viewport width exceeds 1200px, THE Dashboard SHALL render the full layout with expanded Sidebar (80px), multi-column Card grids (up to 6 columns per row as defined per page), and all widgets visible.
2. WHILE the viewport width is between 768px and 1200px, THE Dashboard SHALL collapse the Sidebar to icon-only mode (50px), arrange status Card rows in 2-column grids, and stack middle/bottom row columns vertically where they exceed 2 columns.
3. WHILE the viewport width is below 768px, THE Dashboard SHALL replace the Sidebar with a bottom navigation bar (56px height), arrange all Cards in single-column layout, and hide the BookNest right sidebar widgets in favor of a toggleable overlay.
4. THE Dashboard SHALL support a minimum viewport width of 320px without horizontal scrolling or content overflow.
### Requirement 11: Asset Loading from CDN
**User Story:** As a user, I want dashboard assets (logos, banners, service icons) to load reliably from the CDN, so that the interface renders correctly with all visual elements.
#### Acceptance Criteria
1. THE Dashboard SHALL load the ArchNest logo from `logos/brands/archnest-logo.png` on the CDN for the Sidebar.
2. THE Dashboard SHALL load the hero banner image from `backgrounds/archnest-brand.png` on the CDN.
3. THE BookNest_Page SHALL load service icons from the CDN repository for the following services: Proxmox, GitHub, GitLab, Gitea, AWS, Docker, Cloudflare, NetBird, CasaOS, Portainer, Cockpit, ChatGPT, Claude, GNS3, EVE-NG, and Wireshark.
4. IF a CDN asset does not produce a successful image load event within 10 seconds, THEN THE Dashboard SHALL treat the asset as failed and render a fallback placeholder element that occupies the same dimensions as the intended asset, preserving the surrounding layout without visible reflow.
5. IF a CDN asset fails to load, THEN THE Dashboard SHALL display a generic icon placeholder for service icons (matching the 16-20px icon size) or a solid background fill matching the Card background color for banner and logo assets.
### Requirement 12: State Management
**User Story:** As a user, I want my preferences, session data, and UI state to persist across navigation, so that the dashboard remembers my context.
#### Acceptance Criteria
1. THE Dashboard SHALL use Zustand for global state management of user preferences, active sessions, navigation state, and bookmark data.
2. WHEN a user changes a setting in the Settings_Page, THE Dashboard SHALL persist the change to local storage and apply the setting to the UI within 100 milliseconds without triggering a full page reload.
3. WHEN a user navigates between pages, THE Dashboard SHALL preserve and restore terminal session scrollback buffers, scroll positions (to the nearest pixel), and active sub-tab selections so that returning to a previously visited page displays the same state the user left.
4. WHEN the Dashboard loads and local storage contains previously persisted state, THE Dashboard SHALL restore user preferences, theme settings, sidebar expansion state, bookmark favorites, notification preferences, and active sub-tab selections from the stored data within 200 milliseconds of app initialization.
5. IF local storage is unavailable or the storage quota is exceeded, THEN THE Dashboard SHALL continue operating with in-memory state for the current session and display an indicator in the Settings_Page that persistence is degraded.
6. IF stored state fails validation or is corrupt, THEN THE Dashboard SHALL discard the invalid data, apply default values for all preferences, and operate normally without displaying an error to the user.

137
.kiro/steering/design-rules.md
View file

@ -1,97 +1,90 @@
# ArchNest Design Rules — Must Follow on Every Page # ArchNest Design Rules — Must Follow on Every Page
These are hard-learned rules from the Glance page build. Apply to ALL pages. > Kept in sync with `/design-decisions.md` at the repo root, which is the
> canonical source — if the two ever disagree, trust `design-decisions.md`
> and fix this file to match. This file exists so Kiro steering injects the
> same rules automatically; it intentionally duplicates rather than replaces
> the root doc.
--- ---
## Sidebar ## Sidebar
- **Expanded width**: 100px (NOT 80px) - **Expanded width**: 200px (not 80px — that was the original pre-build mockup spec)
- **Collapsed width**: 60px (NOT 50px) - **Collapsed width**: 64px (icon only)
- **Logo size**: 40px expanded, 28px collapsed — must have gold glow drop-shadow - **Manually collapsible** via a toggle button (not just responsive breakpoints)
- **Logo text "ARCHNEST"**: 9px, bold, tracking 2.5px, gold, with subtle glow - **Active indicator**: gold left border + gold text
- **Nav icons**: 20px, strokeWidth 2 when active, 1.5 when inactive - **System status**: bottom of sidebar, colored dot + text, driven by live
- **Nav labels**: 10px, below icon, font-medium integration-status polling (not a static config)
- **Active indicator**: 3px gold left bar with glow shadow - Main content `margin-left` must match the sidebar width exactly
- **System status**: at bottom, green dot with glow, text 8-9px
- **Manually collapsible** via toggle button (not just responsive)
## Top Bar ## Top Bar
- **Page title**: 18px, bold, uppercase, tracking-wide, **TEXT COLOR IS GOLD (#C8A434)** — NOT white - **Page title**: 18px, bold, uppercase, tracking-wide, **gold (#C8A434)** — not white
- **Height**: 56px, sticky, z-40 - **Height**: 56px, sticky, z-40 (72px + larger 28px title on pages with a
- **Search bar**: 260px, 32px height, rounded-full, 12px text subtitle — currently only BookNest, via the `pageSubtitles` map)
- **Avatar**: 36px, gold border + gold glow shadow, initials inside - **Search bar**: ~300px, rounded-full, searches across pages/integrations/bookmarks
- **Avatar**: 36px, gold border + glow, initials or uploaded image
- **Dropdown menu**: Profile, Appearance, Security, Help & Support, Sign Out (red) - **Dropdown menu**: Profile, Appearance, Security, Help & Support, Sign Out (red)
## Hero Banner (pages that have it: Glance, Infrastructure, Network, BookNest) ## Hero Banner
- **Image positioning**: `object-cover` with `object-position: center 30%` — shows upper portion (skyline), NOT centered - Shown on: Glance, Infrastructure, BookNest (not Network — there is no
- **KPI status cards OVERLAP the bottom** of the banner (negative margin -mt-12) Network page; Infrastructure has a disabled "Network" sub-tab instead)
- **Cards have backdrop-blur** and 95% opacity background for glass effect over banner - Not shown on: Terminal, Tunnels, Files, Containers, Remote Desktop,
- **Banner height**: 200px on Glance, 120px on sub-pages (Infra, Network, BookNest) Host Metrics, Settings, Help
- **No banner** on Terminal or Settings - `object-cover` with a tuned `object-position` per page (configured in
`App.tsx`'s `heroObjectPosition` map) to show the upper portion, not center-crop
- Status/KPI cards overlap the bottom of the banner via negative margin
- If the image fails to load, the banner area just shows the card background
color — no broken-image icon
## KPI Status Cards ## KPI / Status Cards
- **Asymmetric widths**: Cards 1 and 4 are wider (1.3fr), cards 2 and 3 are narrower (1fr) - Background `#141518`, border `1px solid #1E2025`, 12px radius, no box-shadow
- **Grid**: `grid-cols-[1.3fr_1fr_1fr_1.3fr]` with 12px gap - Padding ~16px for KPI cards, ~20-24px for content cards
- **Padding**: 16px (compact, not 20-24px) - Hover: border transitions to gold, 0.2s ease
- **Font sizes**: Title 10px uppercase tracking 1.5px, numbers 24px bold, subtitles 10px, breakdowns 9px - Card titles: 10-11px uppercase, tracking-[1.5px], secondary color
- **Icons in KPIs**: 16px, gold color - Large numbers: 24-28px bold, primary color
- **Dots in breakdowns**: 6px (1.5 tailwind) diameter
## Content Rows ## Content Rows
- **Must align width-wise** with the KPI cards above — use consistent horizontal padding (px-8 for middle/bottom rows matches px-6 + px-2 on the banner area) - All rows in a page share the same horizontal padding so the hero banner,
- **Middle row**: 3 columns 30%/40%/30% status cards, and content rows line up left/right
- **Bottom row**: 2 columns 65%/35% - No footer/status bar on any page — don't add one unless explicitly requested
## No Footer ## Colors
- The Glance page has **NO footer/status bar** at the bottom | Role | Value |
- Other pages: check their specific .md spec |------|-------|
| Page background | `#0D0E10` |
| Card background | `#141518` |
| Sidebar background | `#0A0B0D` |
| Border | `#1E2025` |
| Gold accent | `#C8A434` |
| Success | `#2ECC71` |
| Warning | `#E67E22` |
| Danger | `#E74C3C` |
| Text primary | `#E8E6E0` |
| Text secondary | `#7A7D85` |
## Typography (exact sizes used) ## State Management
| Element | Size | Weight | Color | - **No Zustand or other global state library is used.** State is plain React
|---------|------|--------|-------| component state plus `localStorage` for a small number of client-only
| Page title | 18px | bold | gold | preferences (Terminal theme/font prefs; `AuthContext`'s JWT). All
| Card titles | 10-11px | medium | secondary (#7A7D85) | dashboard data (integrations, bookmarks, resources, events, etc.) is
| Large KPI numbers | 24px | bold | primary (#E8E6E0) | fetched live from the Fastify backend via `src/lib/api.ts` — there is no
| KPI subtitles | 10px | normal | secondary | client-side cache/store layer to keep in sync with the server.
| Breakdown dots text | 9px | normal | secondary |
| Activity titles | 13px | medium | primary |
| Activity subtitles | 11px | normal | secondary |
| Timestamps | 11px | normal | secondary |
| Progress bar labels | 13px | normal | primary |
| Progress bar values | 12px | normal | secondary |
## Card Styling
- Background: #141518 at 95% opacity (with backdrop-blur when over banner)
- Border: 1px solid #1E2025
- Radius: 12px
- Padding: 16px for KPI cards, 20px for content cards
- Hover: border → gold, 0.2s ease transition
- **NO box-shadow** (flat design)
## Colors — Final
- Page bg: #0D0E10
- Card bg: #141518
- Sidebar bg: #0A0B0D
- Border: #1E2025
- Gold accent: #C8A434
- Success: #2ECC71
- Warning: #E67E22
- Danger: #E74C3C
- Text primary: #E8E6E0
- Text secondary: #7A7D85
- Teal: #1ABC9C
## Target Screen ## Target Screen
- Primary design target: **16-inch display** (1920px+ viewport) - Primary design target: 16-inch display / 1920px+ viewport
- Should feel spacious, not cramped - Should feel spacious, not cramped — use the full width
- Use the full width — don't constrain to a narrow container
## See also
- `/design-decisions.md` — full per-page implementation notes (what each
page actually renders and where its data comes from)
- `/README.md` — architecture overview, page list, backend routes
- `/HANDOFF.md` — current task state and what to work on next

23
README.md
View file

@ -211,11 +211,20 @@ Actions secrets, DNS/Nginx Proxy Manager pointed at the host.
set was built (originally scoped as a migration from a forked Termix set was built (originally scoped as a migration from a forked Termix
project, hence the name). Useful for historical "why was it built this project, hence the name). Useful for historical "why was it built this
way" context on those specific features. way" context on those specific features.
- **`.kiro/steering/design-rules.md`** — a condensed duplicate of
`design-decisions.md`'s Global Rules, auto-injected into every Kiro IDE
session (the Kiro extension reads `.kiro/steering/*` automatically). If you
update a global design rule, update both files in the same change —
`design-decisions.md` is canonical, this one just needs to stay in sync so
Kiro doesn't steer on stale info.
Two older docs were deleted as part of a documentation cleanup Three older docs were deleted as part of a documentation cleanup:
(`archnest-blueprint.md`, the original 6-page mockup pitch with fictional `archnest-blueprint.md` and `glance.md` (the original 6-page mockup pitch and
config files and placeholder numbers; `glance.md`, an early Glance-only spec an early Glance-only spec, both describing fictional config files and
with the same problem). Their still-accurate content (color palette, placeholder numbers that never matched the real build), and
dropdown menu shape, card styling) was folded into `design-decisions.md`, `.kiro/specs/archnest-dashboard/` (an abandoned Kiro spec — requirements-only,
and everything else was superseded by the real, deployed implementation no `design.md`/`tasks.md` ever followed — describing the same stale 6-page/
described above. 80px-sidebar/Zustand-based vision). Their still-accurate content (color
palette, dropdown menu shape, card styling) was folded into
`design-decisions.md` and `.kiro/steering/design-rules.md`; everything else
was superseded by the real, deployed implementation described above.