diff --git a/gadget-code/docs/ui-design-guide.md b/gadget-code/docs/ui-design-guide.md index 1c8a9af..1f4b9f2 100644 --- a/gadget-code/docs/ui-design-guide.md +++ b/gadget-code/docs/ui-design-guide.md @@ -4,282 +4,285 @@ Gadget Code is an Agentic Integrated Development Environment (AIDE). It is a too 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 and Tailwind CSS. 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. +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. -The top row is the header bar. The 2nd row is the content area. The 3rd/bottom row is the status bar. +``` +#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, and will display: +The header bar is basically our "window title bar" like for a desktop application: ``` -GADGET CODE v1.0.0 robc +GADGET CODE v1.0.0 [Username ▼] ``` -It displays the application title and current version (available from `env.pkg.version`). It then displays the User menu top-right, giving the User access to their Settings, Logout action, etc. +- 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. project-slug | PLAN | 🟢 +Ready. my-project | BUILD | ● ``` -The status bar will always display the current status message, or Ready. when there is no message to display. This will expand to fill the width of the bar until we hit the right-side components. +- 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) -On the right, when the User has a Project open in the IDE, the project's slug will be displayed. When the User is also in a Chat Session, the current ChatSessionMode will be displayed (PLAN, BUILD, TEST, SHIP, DEV). - -Where i have typed a 🟢 above, the intent is for that to indicate the IDE's connection status to the gadget-code Socket.IO server. - -- 🟢 fully connected, healthy (should animate/strobe/glow) -- 🟡 connection problems of any kind (flat/non-animated) -- 🔴 connection errors of any kind (should blink/flash and glow when lit) -- ⚫ not connected (flat, dull, off) - -This lets the User know the SCOPE of their current work. If they submit a prompt, a drone will execute the prompt in the [Current Project] project. - -The User needs this information at all times. So the header bar is persistent. +Implementation: `frontend/src/components/StatusBar.tsx` ### Content Area -Between the header and status bars filling the width of the view is the Content Area. This will present everything from the multi-mode Home view (auth/no-auth), the Project Manager, the Chat Session View, the Debugger View, etc. ALL application views are rendered to the Content Area. +Between the header and status bars is the Content Area. It uses React Router for URL-based navigation: -It will usually offer: +| 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 `/` | -- A full-width view, such as when using the "Fullscreen File Editor" -- Left sidebar and content (Project Manager) -- Content and right sidebar (the Chat Session view and File Editor) -- Left sidebar, content, and right sidebar (Debugger) +## Unauthenticated Home View -There are no other layouts. The User will instruct to use one of these layouts. If the User doesn't specify, recommend a layout and ask the User if they agree or would like something different. The User is not allowed to give you an ad-hoc layout. They MUST extend this document first. THEN you can use the new layout. +The logged-out home view displays a retro-styled "GADGET CODE" wordmark in ANSI Art style: -#### Home View +- 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 -The home view has two modes: +Users do not "sign up" for Gadget Code - accounts are administered via CLI (`pnpm cli`). -- Unauthenticated / not logged in -- Authenticated / logged in +Implementation: `frontend/src/pages/Home.tsx` - AnsiLogo component -##### Unauthenticated Home View +## Authenticated Home View (Dashboard) -The logged-out home view displays a retro-styled "Gadget Code" word type logo rendered reminiscent of early 1990s Bulletin Board Service "ANSI Art" - colored text. Should use the Courier New font in a typical IBM PC VGA color palette on a black background. But the border should be pure CSS, sophisticated, and modern. - -Users do not "sign up" for Gadget Code, it is an administered system. A system administrator will use [Gadget Code CLI](../src/web-cli.ts) by running `pnpm cli` to add, remove, and manage User accounts. - -##### Authenticated Home View +The authenticated home view presents: ``` -HEADER BAR --------------------------------------------------------------------------------- -User Dashboard (reserved content area)------------------------|Calendar+Clock--| - | | -This area will eventually present project statistics, AI use | | -statistics, project analytics, etc. | | - |Projects--------| -For now, it is left empty. | | - | | - | | - | | - |Recent Chats----| - | | - | | - | | - |Drones----------| - | | - | | --------------------------------------------------------------------------------- -STATUS BAR +[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...) | ++---------------------------+-----------------------+ ``` -The authenticated/logged-in home view is the Home Dashboard, which reserves a left content area, and provides a right sidebar that we populate with the following components: +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) -1. Calendar View with current local time (AM/PM format) -2. Project List (sorted alphabetically) -3. Registered Drones (sorted alphabetically, active/busy first) -4. Recent chat sessions (title, project name, # turns, # tool calls) +Implementation: `frontend/src/pages/Home.tsx` - DashboardSidebar component -The User needs to be able to navigate to the Project Manager from the authenticated home. That is where they can create new projects, open existing projects, and otherwise manage projects (rename, delete, edit info, etc). +## Project Manager View -The User can select a Project to open the Project Manager with that Project open. - -The User can select a Recent Chat to open the Chat Session View with that chat session loaded and open. - -The User can select a Drone to open the Drone Inspector to view a drone's current status and recent activity such as ChatHistory records (chat session turns), and the forthcoming DroneOperation logs - which are operations taken by a Drone while managing projects (git clones of new repos, project synchronization processes, etc.). - -#### Project Manager View +The Project Manager presents: ``` -HEADER BAR --------------------------------------------------------------------------------- -|[New Project] | Project Inspector |Chat Sessions | -|----------------|-------------------------------------------------------------| -|Project List | |This list will | -| | |populate with | -| | |chat sessions | -| | |for the | -| | |selected | -| | |project. | -| | | | -| | | | -| | | | -| | | | -| | | | -| | | | -| | | | -| | | | --------------------------------------------------------------------------------- -STATUS BAR ++---------------------------+------------------------------------+ +| [New Project] | Project Inspector | +|---------------------------| | +| Projects (2) | Select a project to view details | +| [project-one ] | or create a new project | +| [project-two ] | | +| | | ++---------------------------+------------------------------------+ ``` -The User clicks the [New Project] button to create [Project](../src/models/project.ts) records for tracking a software development project in Gadget Code. A Developer only cares about their own projects. It's not a security violation for a User to see another User's projects. It's just superflous information. John doesn't care about Nancy's projects. John works on John's projects, and he owns them. - -Projects have a display name (name), slug, git URL, and some metadata. The User enters a project's name, slug, git URL when creating a project. Project slugs must be unique per-User because they are the name of the project directory in a Drone's workspace. - -When the User selects a project in the Project List, that project is opened in the Project Inspector on the right, and displays all available information for the project in the Project Inspector. Additionally, when a Project is selected in the list, the ChatSession records for that Project are displayed in the Chat Sessions -list on the right with the most recent at the top. - -The User can navigate Back to the Authenticated Home view. - -#### Chat Session View - -The Chat Session View presents as follows: +When a project is selected: ``` -HEADER BAR --------------------------------------------------------------------------------- -Work Area-----------------------------------------------------|Session Status--| - | | - | | - | | - |----------------| - |TC | FO | SA | - |----------------| - | | - | | - | | -Log-----------------------------------------------------------|File Browser----| - | | - | | - | | - | | - | | --------------------------------------------------------------------------------- -STATUS BAR ++---------------------------+------------------------------------+ +| [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...) | ++---------------------------+------------------------------------+ ``` -The user can navigate Back to wherever they came from (Home or Project Manager). +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) -The Work Area pane has modes, and can display the Chat View (messages + prompt input), the Expanded Prompt Editor, various Inspectors, and the File Editor. The remainder of the view always presents the Session sidebar, Log, and File Browser. +URL-based: `/projects` (list), `/projects/:slug` (selected) -##### Chat View +Implementation: `frontend/src/pages/ProjectManager.tsx` -``` -HEADER BAR --------------------------------------------------------------------------------- -Chat Messages-------------------------------------------------|Session Status--| - | | - | | - | | - |----------------| - |TC | FO | SA | - |----------------| - | | - | | -[Prompt Text Input bar ][Expand][Send] | | -Log-----------------------------------------------------------|File Browser----| - | | - | | - | | - | | - | | --------------------------------------------------------------------------------- -STATUS BAR +### 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}`; ``` -If the User selects [Expand] then the entire Work Area becomes an enlarged multi-line