286 lines
20 KiB
Markdown
286 lines
20 KiB
Markdown
# 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 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.
|
|
|
|
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.
|
|
|
|
## 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.
|
|
|
|
### Header Bar
|
|
|
|
The header bar is basically our "window title bar" like for a desktop application, and will display:
|
|
|
|
```
|
|
GADGET CODE v1.0.0 robc
|
|
```
|
|
|
|
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.
|
|
|
|
### Status Bar
|
|
|
|
```
|
|
Ready. project-slug | PLAN | 🟢
|
|
```
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
### 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.
|
|
|
|
It will usually offer:
|
|
|
|
- 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)
|
|
|
|
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.
|
|
|
|
#### Home View
|
|
|
|
The home view has two modes:
|
|
|
|
- Unauthenticated / not logged in
|
|
- Authenticated / logged in
|
|
|
|
##### Unauthenticated Home View
|
|
|
|
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
|
|
|
|
```
|
|
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
|
|
```
|
|
|
|
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:
|
|
|
|
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)
|
|
|
|
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).
|
|
|
|
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
|
|
|
|
```
|
|
HEADER BAR
|
|
--------------------------------------------------------------------------------
|
|
|[New Project] | Project Inspector |Chat Sessions |
|
|
|----------------|-------------------------------------------------------------|
|
|
|Project List | |This list will |
|
|
| | |populate with |
|
|
| | |chat sessions |
|
|
| | |for the |
|
|
| | |selected |
|
|
| | |project. |
|
|
| | | |
|
|
| | | |
|
|
| | | |
|
|
| | | |
|
|
| | | |
|
|
| | | |
|
|
| | | |
|
|
| | | |
|
|
--------------------------------------------------------------------------------
|
|
STATUS BAR
|
|
```
|
|
|
|
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:
|
|
|
|
```
|
|
HEADER BAR
|
|
--------------------------------------------------------------------------------
|
|
Work Area-----------------------------------------------------|Session Status--|
|
|
| |
|
|
| |
|
|
| |
|
|
|----------------|
|
|
|TC | FO | SA |
|
|
|----------------|
|
|
| |
|
|
| |
|
|
| |
|
|
Log-----------------------------------------------------------|File Browser----|
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
--------------------------------------------------------------------------------
|
|
STATUS BAR
|
|
```
|
|
|
|
The user can navigate Back to wherever they came from (Home or Project Manager).
|
|
|
|
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.
|
|
|
|
##### Chat View
|
|
|
|
```
|
|
HEADER BAR
|
|
--------------------------------------------------------------------------------
|
|
Chat Messages-------------------------------------------------|Session Status--|
|
|
| |
|
|
| |
|
|
| |
|
|
|----------------|
|
|
|TC | FO | SA |
|
|
|----------------|
|
|
| |
|
|
| |
|
|
[Prompt Text Input bar ][Expand][Send] | |
|
|
Log-----------------------------------------------------------|File Browser----|
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
--------------------------------------------------------------------------------
|
|
STATUS BAR
|
|
```
|
|
|
|
If the User selects [Expand] then the entire Work Area becomes an enlarged multi-line <textarea>. Enter inserts a newline. Ctrl+Enter sends the Prompt and closes the expanded Prompt Editor. This lets the User compose complex and highly-detailed prompts for the Gadget Code agent to process. The User can also press Esc or click a close button to exitt expanded prompt editor without sending the prompt. When closing the expanded prompt editor, the user's prompt is cleared and the regular text input bar is emptied.
|
|
|
|
The user uses the Prompt Text Input Bar for shorter prompts, and for sending course-correcting prompts while the agent is working. The input is not disabled while the agent is working - the User can send the agent messages and they will be queued for delivery when possible at the next iteration of the Agentic Workflow Loop in the drone.
|
|
|
|
When the User sends a prompt, a new Turn is created in the Scrolling Chat Messages. The User's prompt is added to the turn, and the Agent's response is added to the turn. The Agent's response will receive thinking and response text updtes as they stream in from the agent.
|
|
|
|
The Session Status sidebar panel displays the name of the current ChatSession, the ID of the chat session, the service provider and model being used, the live value of API API response values done and done_reason, and a tabbed view with the following three tabs:
|
|
|
|
1. Tool Calls (shown as TC in diagram)
|
|
2. File Operations (shown as FO in diagram)
|
|
3. Subagents (shown as SA in diagram)
|
|
|
|
As drones send Tool Call reports, their data is appended to the Tool Calls list. As Drones report File Operations, their data is appended to the File Operations list. Subagent processing is slightly more complex.
|
|
|
|
When a Drone spawns a subagent to perform a task, it will send a subagent-create message. The subagent will then send tool call and file operation events of its own, which are all filed against the subagent entry in the list. The drone eventually sends subagent-done with a report, which is all saved by gadget-code, and able to be viewed here.
|
|
|
|
##### Subagent Inspector
|
|
|
|
If the User selects an entry in the Subagents list, it opens the Subagent Inspector to cover the Chat area (messages AND input) with the Subagent Inspector, letting the user see the subagent's thinking, response, tool call and file operation information. This resembles a Chat View without a Prompt Input bar, and exists within the Chat Messages area, and is composed as follows:
|
|
|
|
```
|
|
Subagent Observer---------------------------------------------|Session Status--|
|
|
thinking: text content |TC | FO | |
|
|
response: text content |-----------------| |
|
|
thinking: ... | | |
|
|
response: ... | |----------------|
|
|
| |TC | FO | SA |
|
|
| |----------------|
|
|
| | |
|
|
```
|
|
|
|
The User needs a close gadget to exit the Subagent Inspector. The User can open a Subagent Inspector while the subagent is running, and view updates in this view as they arrive.
|
|
|
|
##### File Editor
|
|
|
|
When working in a Chat Session with the Gadget Code AI agent, and the Agent is NOT working on the project, the User can open a file in the Files pane to view (and edit) the file fullscreen. This just means the file will occupy the entire Content Area. The header/status bars always remain.
|
|
|
|
```
|
|
HEADER BAR
|
|
--------------------------------------------------------------------------------
|
|
ACE Editor--------------------------------------|File Sidebar-|Session Status--|
|
|
| | |
|
|
| | |
|
|
| | |
|
|
| | |
|
|
| | |
|
|
| | |
|
|
|-------------| |
|
|
|[C] [S][B][C]| |
|
|
Log-----------------------------------------------------------|Files-----------|
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
--------------------------------------------------------------------------------
|
|
STATUS BAR
|
|
```
|
|
|
|
We will integrate the ACE editor. ACE offers "themes" for color syntax highlighting and appearance. The File Editor should, therefore, be as neutral as possible to stay out of the way of the code - which is the FOCUS of the User when using this view.
|
|
|
|
The sidebar is for selecting the ACE theme, viewing metadata about the file (size, type, git annotation/history, etc.). A User Actions bar is located at the bottom of the right-side sidebar offering:
|
|
|
|
```
|
|
[C]lose [S]ave [B]uild [C]ommit
|
|
```
|
|
|
|
If the User selects Close and the file is dirty, we confirm that they want to discard their edit and close the file. If the User clicks Save, the file is written to disk via the Drone we've locked to the ChatSession.
|
|
|
|
If the User selects [Build], the build command is sent to the Drone. The Log will display build output for the User's review.
|
|
|
|
## 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. The entire focus is on delivering the absolute best DESKTOP WORKSTATION experience possible with a professional fit, finish, look, and feel.
|
|
|
|
Buttons can be normal, not bloated for finger use. Checkboxes can be normal. There are no UI gestures. Gadget Code is an IDE intended to make the agentic programming experience observable to scientists. It is not a plaything.
|
|
|
|
## Accessibility
|
|
|
|
The IDE wants to be as accessible as possible, providing aria tags as much as possible, to make use of the application as accessible as possible for those with physical impairments. HTML5 provides wonderful tools for enabling those with disabilities, and we will do our best to support those standards. Our process is to buld first and focus on the build with an eye toward accessibility, then take a 2nd pass after the build is accepted, and add the accessibility. The User will ask you to perform an accessibility pass when desired, and you can recommend, "Now would be a good time to take an accessibility pass over the UI," and get the User's approval.
|