dtp/gadget
1
0
Fork 0
Code Actions Packages Projects Releases Activity
07a760c7b5
gadget/gadget-code/docs/ui-design-guide.md
Rob Colbert 09a0f0a258 repaired
2026-05-05 11:55:33 -04:00

294 lines
10 KiB
Markdown
Raw Blame History

# 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 "System Ready" prompt dialog.
- Font: Courier New (monospace)
- Background: #0a0a0a (pure black)
- Boxed with 2px border using border-default color
- Sign In button
Users do not "sign up" for Gadget Code - accounts are administered via CLI (`pnpm cli`).
Implementation: `frontend/src/pages/Home.tsx` - SystemReady 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:
```typescript
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
```bash
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
```
View Git Blame Copy Permalink