gadget/gadget-code/docs/ui-design-guide.md

Gadget Code IDE Style Guide

Gadget Code is an Agentic Integrated Development Environment (AIDE). It is a tool for professional software developers and project managers to use in the creation of software applications and solutions, to include: code, documentation, configuration, etc.

The brand color is #c20600, a rich red. It is to be used when printing Gadget Code.

The Gadget Code IDE (hereafter: IDE) is an HTML5 web app building using the latest stable ReactJS 19 and Tailwind CSS 4. The IDE delivers only industrial and purposeful dark theme that uses mostly blacks, near-black, and dark gray with light gray and brand color highlights.

Information-dense status and property panels. Tight margins and padding.

This is NOT a consumer news blog with giant bloated hero sections, etc. We prefer flat material design with thoughtful borders that help the eye find the information and focus on it - not distract from it.

Theme Colors

The IDE uses the following color palette (CSS custom properties):

--color-brand: #c20600
--color-bg-primary: #0a0a0a (main background - pure black)
--color-bg-secondary: #121212 (panels, sidebars)
--color-bg-tertiary: #1a1a1a (cards, dropdowns)
--color-bg-elevated: #202020 (hover states)
--color-text-primary: #d4d4d4 (main text)
--color-text-secondary: #a3a3a3 (muted text)
--color-text-muted: #737373 (disabled, hints)
--color-border-subtle: #1a1a1a (subtle dividers)
--color-border-default: #2a2a2a (default borders)
--color-border-highlight: #3a3a3a (emphasis borders)

Font stack:

• Primary: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif
• Code/Retro: Courier New, Courier, monospace

View Layout (Whole Application)

The root element is given fixed positioning to fill the browser view entirely, and presents a full-width/full-height Flex column that spans the entire view.

#root {
  height: 100vh;
  display: flex;
  flex-direction: column;
  overflow: hidden;
}

The top row is the header bar (48px). The 2nd row is the content area (flex-1). The 3rd/bottom row is the status bar (32px).

Header Bar

The header bar is basically our "window title bar" like for a desktop application:

GADGET CODE v1.0.0                                          [Username ▼]

• Left: Application title + version using Courier New font
• Right: User dropdown menu (display name, click to open)
  • Settings (placeholder)
  • Logout

Implementation: frontend/src/components/Header.tsx

Status Bar

The status bar displays:

Ready.                                                   my-project | BUILD | ●

• Left: Status message ("Ready." default)
• Center-right: Active project slug (when selected), Session mode (PLAN/BUILD/TEST/SHIP/DEV)
• Right: Connection indicator (● = connected, animates when healthy)

Implementation: frontend/src/components/StatusBar.tsx

Content Area

Between the header and status bars is the Content Area. It uses React Router for URL-based navigation:

Route	View
/	Home (authenticated dashboard or unauthenticated)
/projects	Project Manager (list view)
/projects/:slug	Project Manager (project selected)
/projects/new	New project form
/sign-in	Sign in page
/sign-out	Signs out and redirects to /

Unauthenticated Home View

The logged-out home view displays a retro-styled "GADGET CODE" wordmark in ANSI Art style:

• VGA color palette: #0000AA, #00AA00, #00AAAA, #AA0000, #AA00AA, #AAAA00, #AAAAAA, #555555
• Font: Courier New (monospace)
• Background: #0a0a0a (pure black)
• Boxed with 2px border using border-default color
• [Sign In] button styled as [ Sign In ] bracket format

Users do not "sign up" for Gadget Code - accounts are administered via CLI (pnpm cli).

Implementation: frontend/src/pages/Home.tsx - AnsiLogo component

Authenticated Home View (Dashboard)

The authenticated home view presents:

[Welcome, Username!]
Your dashboard is under construction.
Select a project or chat session from the sidebar to get started.

[Open Project Manager]

+---------------------------+-----------------------+
|                           | Clock (AM/PM)         |
| Reserved for future        | Date                   |
| dashboard content       +-----------------------+
|                         | Projects    [+]       |
|                         | - project-1           |
|                         | - project-2           |
|                         +-----------------------+
|                         | Drones               |
|                         | - drone-alpha ●       |
|                         | - drone-beta ○       |
|                         +-----------------------+
|                         | Recent Chats          |
|                         | (loading...)         |
+---------------------------+-----------------------+

Components:

1. Clock - local time in AM/PM format, current date
2. Projects list - links to /projects/:slug, [+]/link navigates to /projects
3. Drones list - status indicator (green=available, yellow=busy, gray=offline)
4. Recent Chats - loading placeholder (stubbed, requires ChatSession API)

Implementation: frontend/src/pages/Home.tsx - DashboardSidebar component

Project Manager View

The Project Manager presents:

+---------------------------+------------------------------------+
| [New Project]            | Project Inspector                  |
|---------------------------|                                  |
| Projects (2)             | Select a project to view details  |
| [project-one      ]       | or create a new project          |
| [project-two    ]        |                                |
|                         |                                |
+---------------------------+------------------------------------+

When a project is selected:

+---------------------------+------------------------------------+
| [New Project]            | Project Inspector                  |
|---------------------------|                                  |
| Projects (2)             | Name: project-one                |
| [project-one ●]           | Slug: project-one              |
| [project-two   ]          | Git URL: https://github.com/...  |
|                         | Status: active                 |
|                         | Created: 2026-04-28          |
|                         |                              |
|                         | [Delete Project]               |
|                         +-------------------------------+
|                         | Chat Sessions                 |
|                         | (loading...)               |
+---------------------------+------------------------------------+

Features:

• Left sidebar: Project list with [+ New Project] button
• Project Inspector: Shows name, slug, gitUrl, status, createdAt
• Delete: Confirmation before deletion
• Chat Sessions placeholder (requires ChatSession API)

URL-based: /projects (list), /projects/:slug (selected)

Implementation: frontend/src/pages/ProjectManager.tsx

New Project Form

Triggered by [New Project] button or /projects/new route:

• Fields: Project Name*, Project Slug*, Git Repository URL
• Slug tip: "Unique identifier for the project directory"
• Submit: "Create Project" button (brand color)
• Cancel: Returns to project list

Authentication

Frontend Token Management

• Token stored in localStorage: dtp_auth_token
• User stored in localStorage: dtp_user
• Project stored in localStorage: dtp_current_project

API Requests

All API requests include the JWT in the Authorization header:

headers['Authorization'] = `Bearer ${token}`;

Backend Session Restoration

The backend restores user sessions from:

1. Authorization: Bearer <token> header (JWT)
2. Express session (fallback)

The requireUser() middleware ensures endpoints are authenticated.

Security

Password Field Handling

Password credentials are NEVER exposed:

• Mongoose select: false on password fields in models
• Population uses select: "-passwordSalt -password" to exclude from queries
• Frontend User interface only includes: _id, email, displayName, flags

Chat Session View (Planned)

The Chat Session View presents:

Work Area                                     | Session Status
----------------------------------------------|---------------
Chat Messages                                 | Chat: name
                                             | ID: ...
                                             | Model: ...
------------------------------------------|---------------
[Prompt input           ][Expand][Send]        | TC | FO | SA
----------------------------------------------|---------------
Log                                           | Files
                                              |

Implemented components:

• Chat Messages (stubbed)
• Prompt Input (stubbed)
• Session Status sidebar (stubbed)
• File Browser (stubbed)

Mobile Devices and Responsive Design

Nope. Gadget Code is a desktop workstation experience with one or more high-resolution displays, keyboard, mouse, webcam, microphone, and ample networking. There is no planned support for mobile devices.

Buttons are normal-sized, not bloated for finger use.

Accessibility

The IDE wants to be as accessible as possible, providing aria tags as much as possible. Build first with an eye toward accessibility, then take a 2nd pass after the build is accepted to add accessibility enhancements.

Tests

Unit Tests

Location: tests/**/*.test.ts (excluding tests/e2e/)

Run: pnpm test

E2E Tests

Location: tests/e2e/**/*.test.ts

Run: npx playwright test

Prerequisites: Running pnpm dev:backend and pnpm dev:frontend

Target: https://code-dev.g4dge7.com:5174

Build Commands

cd gadget-code
pnpm dev:backend    # Backend on https://localhost:3443
pnpm dev:frontend  # Frontend on https://localhost:5174
pnpm build         # Build all (backend -> dist/, frontend -> frontend/dist/)
pnpm test          # Unit tests
npx playwright test # E2E tests