UI Guidelines¶
Updated: 2026-06-05
Guidelines for creating user interfaces when the company builds small apps, tools, games, websites, and client deliverables.
Operating Rule¶
Every UI must make the primary workflow obvious, usable, and testable. Pretty is not enough; the user must be able to complete the job without guessing.
Product Principles¶
| Principle | Meaning |
|---|---|
| Workflow first | Start from the user's task, not from decoration or a landing page. |
| First screen matters | The main product, tool, game, or offer must be visible immediately. |
| Complete states | Empty, loading, success, error, disabled, and permission-denied states are part of the UI. |
| Responsive by default | Desktop and mobile layouts must both be usable unless the spec explicitly excludes one. |
| Familiar controls | Use standard controls for standard jobs: buttons, inputs, tabs, filters, menus, sliders, toggles, and icons. |
| Accessibility baseline | Text must be readable, focus states visible, forms labeled, and color not the only way meaning is shown. |
Spec Requirements¶
plan: output for UI work must include:
- Target user and primary workflow
- Main screen or view list
- Required states: empty, loading, error, success, disabled
- Responsive expectations: desktop, mobile, or both
- Visual tone: work-focused, playful, premium, simple, or client-specific
- UI acceptance criteria that can be checked by a human or tester
Implementation Checklist¶
| Area | Check |
|---|---|
| Navigation | User can tell where they are and how to move to the next action. |
| Forms | Inputs have labels, validation, clear errors, and useful defaults where possible. |
| Layout | Text does not overlap, buttons do not resize unexpectedly, and key actions remain visible. |
| Mobile | Content fits without horizontal scrolling unless the UI is a deliberate data grid. |
| Visual polish | Spacing, hierarchy, contrast, and button states look intentional. |
| Assets | Websites and games use relevant real or generated visual assets where visuals matter. |
| Screenshots | Tester reviews at least one desktop and one mobile screenshot for UI-facing work. |
Agent Expectations¶
| Agent | UI responsibility |
|---|---|
| Planner | Defines workflow, states, responsive scope, and UI acceptance criteria. |
| Implementer | Builds the complete UI states, not only the happy path. |
| Tester | Checks workflow completion, state coverage, screenshots, and text/layout overlap. |