docs(ui): record the presentation rules

This commit is contained in:
sam committed 2026-10-18 14:57:50 +11:00
1 parent 2ab58b98b9
commit 7c6ca17ebe
1 file changed
+54 -3
+54 -3
View File
@@ -25,6 +25,24 @@ state; the UI presents them and submits operator choices.
where they occur; an unreadable list must not look like an empty one.
- Async views must discard stale responses after their task, attempt or route
changes. A setting must save through the API and show its applied state.
- Build in safety. Edits go to a draft and reach the running workflow only when
you publish.
- Never lose work silently. If two things can write the same state (e.g., Archie
and the operator), lock one out or merge them; never let one silently overwrite
the other.
- Phone width is a real target. No global CSS rule may deform controls. Desktop
layouts must collapse cleanly: dropdowns instead of side lists, stacked panes,
and nothing overlapping the canvas.
## Product scope
- Respect the existing feature set. New features honour instructions, policies,
grants and the access model (ReBAC/ABAC with Cedar). An agent tool never reaches
further than its caller could through the dashboard.
- Agentic automation, not a coding agent. A repository is one optional input to
a workflow, not the frame for anything.
- Smallest change first. Reuse what exists, such as the change-review list, drafts
and the existing MCP bridge, before adding new mechanism.
## Components and interaction
@@ -36,9 +54,30 @@ state; the UI presents them and submits operator choices.
- Keep controls compact and contextual. Use on-demand panels and inline
hover/focus icon actions rather than permanent chrome. Do not repeat labels
in explanatory text or add controls without working behavior.
- Text states a problem or an action, never what the view already shows. No
captions like "Compared with the current definition" or "Refreshed every 5
seconds"; delete them on sight.
- Text states a problem or an action, nothing else. Delete lines that only
describe what the screen already shows (e.g., "Compared with the current
definition", "Same as the current definition", "Refreshed every 5 seconds",
"Showing recent matches…", "Live only").
- Do not label a control that explains itself. A switch needs no "Enabled"
beside it, and `+` needs no "New workflow" next to it. Put the name in the
accessible name or tooltip.
- Option labels do not repeat their category. Under "Checks", list "Repository",
"Diff size" and "Diff rules", not "Repository gate".
- Name things after what you are working with. The page sets context, so use
"Restore default" not "Restore shipped workflows".
- No filler or guidance text. Delete empty-state essays, hints that repeat the
label, and sentences explaining how the UI works.
- Product names are our own. The editor helper is "Build with Archie" or
"Iterate with Archie", never generic terms like "Ask bar".
- Actions live where their scope lives. Bulk or instance-wide actions (e.g.,
restoring defaults) belong on the settings page for that area, not in a
working view's header menu.
- No side panels for editing workflows. Settings, trigger and steps expand
in place on the canvas, one at a time, with the main field first and the rest
tucked away.
- Editor and live view are one surface. Runs show on the same cards you edit.
- Use Select components wherever the options are known. Avoid native selects
and free text. Use the same button and badge styles as the settings pages.
- Preserve keyboard operation, visible focus, accessible names, dialog titles
and table semantics. A hover action must also be reachable by keyboard.
- Keep filtering and pagination consistent with the server. State limitations
@@ -82,3 +121,15 @@ npm audit # after dependency changes
not just a screenshot or successful HTTP response.
- Track work and follow-ups in Beads. Keep rules here only when they change a
decision; do not add task history or Markdown TODO lists.
## Working with you
- A clear direction is the go-ahead. Act in the same turn; do not restate the
plan, offer options, or ask "shall I proceed?".
- Say each correction once. When you correct something, fix every instance and
record the rule here so you do not repeat it.
- Delegate to pi workers when asked, and verify their output. Check for overlap
before merging, rerun their checks on the combined result, and fix what they
find.
- Deploy with the approved sequence (build, scp, install, restart) once work is
finished and the gate passes. Report what changed and what was verified, briefly.