Skip to main content

UX Guidelines

The layer above component selection — how components combine into flows, what states a screen needs, page-level accessibility, and content that fits the audience. Applies to all UX work in Orbit.

Component-level correctness — the right component, the right token, the right variant — does not guarantee a good user experience. These guidelines cover the layer above component selection: composition, flow, state completeness, and content. They are what separates “this used the right component” from “this is good UX.”

The rules are short, imperative, and checkable. Use them as a design and review checklist while building a screen. They are also written to be pasted verbatim into an AI tool’s project or system instructions — a Claude Project, a Cursor or Copilot workspace, or any assistant that accepts a context file — and are folded into /llms.txt and /specs/design.md alongside component-level context. When you’re reviewing AI-assisted output they double as guardrails; see Using Orbit with AI for how that fits the AI workflow.

1. Composition & flow

  • Before adding a component to solve a sub-problem, check whether the screen already has an interruption pattern active (Modal, Notification Modal). Do not stack more than one interruption pattern in a single flow.
  • If a form specification exceeds 8 visible fields, flag for chunking (multi-step flow, grouped sections, or progressive disclosure) rather than adding more Form Controls to a single view.
  • When two solutions are equally component-correct, prefer whichever is already used elsewhere in the suite for the same interaction. Suite-first is a tiebreaker, not just a principle.
  • Do not select a component in isolation from the screen it lives on. Check what else is already present before adding to it.

2. State completeness (per screen, not per component)

  • For every screen produced or reviewed, confirm five states are specified or explicitly deferred: empty, loading, error, partial-data, permission-denied.
  • Any screen containing a Table, Data Display, or async content must have loading and error states specified before it is considered complete.
  • Do not treat the happy path as the deliverable. The happy path is the starting point.

3. Accessibility at the page level

  • Confirm heading hierarchy is unbroken across the full assembled page — not just within one component’s markup.
  • Confirm tab order matches visual order once components are combined. A component’s focus order being correct in isolation does not guarantee it is correct in context.
  • Flag duplicate or missing landmark regions that appear only once components are assembled onto a real page.

4. Content & tone alignment

  • Before generating UI copy, identify the audience: professional (Open Point) or community-facing (Social Point). Apply the matching tone from Voice & tone — community-facing is warmer, plainer, assumes no prior platform knowledge.
  • Never write copy for a destructive or high-stakes action without following the Confirmation dialogs pattern: exact verb repeated as the primary action, no “Are you sure?”, no softened language.
  • Flag copy that uses jargon, passive voice, vague CTAs (“Click here”, “Learn more”), or apologetic empty-state phrasing. These are named “what to avoid” in Voice & tone and should be caught, not just avoided by default.

5. Suite-first consistency

  • Before proposing a new pattern, check for existing precedent in Open Point and Social Point that solves the same interaction.
  • Do not present a newly invented pattern as settled. Flag it as a Guild proposal candidate.

6. Escalation triggers — do not decide alone

Work must be flagged for human/Guild review, not shipped as-is, when it touches:

  • A novel component or pattern with no existing precedent
  • Any Social Point surface where the public participates directly (consultation, feedback, community-facing trust surfaces)
  • A conflict between accessibility requirements and brand/visual direction
  • An ambiguous component lifecycle or status call
  • Anything that would otherwise require a Guild decision

7. Pre-ship review rubric

Before UX work ships — especially anything an AI tool produced a first pass of — a reviewer should confirm:

  • Flow coherence — does the assembled screen make sense as a whole, not just each component in isolation
  • Tone match — does copy match the correct audience (professional vs community-facing)
  • State completeness — empty, loading, error, partial-data, permission-denied all addressed
  • Suite consistency — no unnecessary new pattern invented where precedent exists
  • Page-level accessibility — heading hierarchy, tab order, landmarks checked in context, not just per component
  • Escalation flags — anything matching Section 6 has been raised, not silently resolved

Was this page helpful?