From 879f40195fdff67dce8767fba4b9c1fa1ca283e4 Mon Sep 17 00:00:00 2001 From: Sawyer Cutler Date: Sun, 1 Nov 2026 10:01:59 -0800 Subject: [PATCH] docs: extend existing UX and APIs instead of adding parallel ones --- AGENTS.md | 3 +++ apps/web/AGENTS.md | 40 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 43 insertions(+) create mode 100644 apps/web/AGENTS.md diff --git a/AGENTS.md b/AGENTS.md index 7f5ab11c..2f6b7a53 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,6 +22,9 @@ These are the ones no check catches: reimplementing it, and raise what falls between Interchange, Corbits packages and Builder before building it ([who owns what](https://github.com/corbitsdev/corbits-builder/blob/main/docs/IMPLEMENTATION.md#who-owns-what)). +- Extend the existing module, package, API or component before adding one + that overlaps it; Builder keeps one way to do each thing. Interface work + follows [apps/web/AGENTS.md](apps/web/AGENTS.md). - The interface talks to the hub through `@corbits-builder/client`. - A change to `vendor/interchange` is its own `(vendor)` commit that also updates `vendor/interchange.manifest.json`. diff --git a/apps/web/AGENTS.md b/apps/web/AGENTS.md new file mode 100644 index 00000000..0b13ab85 --- /dev/null +++ b/apps/web/AGENTS.md @@ -0,0 +1,40 @@ +# Building Builder's interface + +Builder is one product and every part of it should feel the same. A new +setting, button, page, document view or agent interaction looks and behaves +like what is already there, and extends it rather than standing beside it. +[DESIGN.md](./DESIGN.md) is the workspace design contract. + +## Before adding anything + +- Check what the surrounding interface already offers, and extend that. Never + add a second way to do something the interface already does. +- Build with `@corbits/react-ui` components and the existing design tokens + first, so everything keeps the same theme and brand. Add no new colours, + spacing, type scales or one-off styles. +- Build a new component or area that isn't specific to Builder, such as a + richer table, here first, matching the rest of the interface. Note on the + issue and the pull request that it may fit better in `@corbits/react-ui`; + maintainers decide whether it moves. +- Wording lives in the interface's config. + +## Every artifact kind is a first-class document + +A new kind (a sheet, a deck, a diagram) is integrated everywhere a document +is, not shown as a standalone widget: + +- **Tab:** it opens as a tab in the document pane. The tab names it, so the + view adds no second title and no outer margin; content sits flush. +- **Floating bar:** every action on it (download, share, search, filters, + copy, quote, versions, compare) goes in the document pane's one floating + bar, supplied by the view. Views draw no toolbars, inline links or buttons + of their own. +- **Tab menu:** per-document commands that aren't everyday actions, such as + print, go in the tab's context menu next to the existing items. +- **Quote:** whatever the person points at, whether a passage, a cell range or + a slide element, can be quoted into their message through the existing quote + offer, naming the document, the version and the location. +- **Versions and changes:** the version menu and comparison work for it, or + say plainly why a version can't be compared. +- **States:** loading, empty and error states are the same short status + lines every document uses.