From b3b913f12aa023d806d086bd25c98f12c5ed5cb3 Mon Sep 17 00:00:00 2001 From: Rob Colbert Date: Tue, 28 Apr 2026 15:13:29 -0400 Subject: [PATCH] created --- gadget-code/docs/chat-session.md | 0 gadget-code/docs/project.md | 29 --- gadget-code/docs/ui-design-guide.md | 285 ++++++++++++++++++++++++++++ 3 files changed, 285 insertions(+), 29 deletions(-) delete mode 100644 gadget-code/docs/chat-session.md delete mode 100644 gadget-code/docs/project.md create mode 100644 gadget-code/docs/ui-design-guide.md diff --git a/gadget-code/docs/chat-session.md b/gadget-code/docs/chat-session.md deleted file mode 100644 index e69de29..0000000 diff --git a/gadget-code/docs/project.md b/gadget-code/docs/project.md deleted file mode 100644 index 7712cdf..0000000 --- a/gadget-code/docs/project.md +++ /dev/null @@ -1,29 +0,0 @@ -# Gadget Code: Projects - -The User will create one or more Project records for tracking a software development project in Gadget Code. - -It will be uncommon to query this model/collection without a User. System administrators and managers will have interest in the global Projects list. Developers will not. 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. - -## createdAt - -The date and time at which the User created the Project record in Gadget Code. This is not necessarily when the project itself was created or started. This is just when Gadget Code got involved. - -## user - -The User for whom the Project was created. The User is the owner of the project. Users can only see their own Projects. A user is thought of as working in their project. If multiple Users are in the chat, one of them is the Project Owner and will be marked as such. The other Users in the chat session are reffered to as Collaborators. - -## name - -The name of the project as displayed in lists, headers, title areas, etc. - -## slug - -The project's slug (my-project), which is used as it's directory name in the workspace directory by [Gadget Drone](./gadget-drone.md). - -## gitUrl - -The URL of the project's git repository (optional). This will be used to clone the project into the workspace directory on the drones. If this is not set, a new git repo will be created in the workspace directory and the url will be stored here. - -If a gitUrl is not set for a Project and the User selects to delete the project, the project directory will be removed, and it will NOT be pushed to git. The User should be informed that the contents of the directory will be lost, and should have to confirm that this is what they want to do. diff --git a/gadget-code/docs/ui-design-guide.md b/gadget-code/docs/ui-design-guide.md new file mode 100644 index 0000000..1c8a9af --- /dev/null +++ b/gadget-code/docs/ui-design-guide.md @@ -0,0 +1,285 @@ +# 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