Starlight_Lancher/.agents/skills/oiloil-ui-ux-guide/references/system-principles.md

System-Level Guiding Principles

Use these as first-order constraints before choosing specific components or page patterns.

Concept constancy

• Definition: The same business concept keeps the same name, meaning, and interaction semantics across the system.
• Review question: If a user learns this concept in one place, can they transfer that understanding everywhere else?

Primary task focus

• Definition: Each screen has one dominant objective with the highest visual and interaction priority.
• Review question: Can users identify the most important action within 3 seconds?

UI copy source discipline (for product development)

• Definition: visible UI copy should come from business content, not from implementation constraints or generation instructions.
• Preferred copy sources:
  • User task: what the user is trying to do.
  • System state: what is happening now (loading, empty, error, success, permission).
  • Result + next step: what changed and what users can do next.
  • Risk/trust context: only when it prevents mistakes or improves confidence.
• Internal-only sources (do not render directly in product UI by default):
  • Visual/style constraints (e.g., "minimal", "black-and-white", "modern").
  • Technical constraints and implementation notes.
  • Prompt instructions, review rubrics, and generation meta text.
• User-facing copy framing heuristic (general, not title-specific):
  • Applies to any prominent UI copy: titles, section headers, callouts, badges, CTA labels, and empty states.
  • Prefer user-outcome framing: describe the user's goal and the result they get.
  • Avoid self-referential/process framing for end-user product UI (e.g., "to showcase", "this page demonstrates", "showing the skill's value").
  • Exception: if the surface is explicitly a demo/tutorial/spec page for builders, self-referential/process copy can be acceptable when it improves understanding.

State perceptibility (high-level, cross-system)

• Problem: users make errors when an important internal state is not perceivable (mode, scope, selection, unsaved changes, environment, permission).
• Principle: make state visible using the lowest-noise signal that reliably changes behavior.
• Preferred signals (in order):
  • Structural change: the layout/components clearly switch (read -> edit; list -> selection; view -> compare).
  • Control state: the control that changes behavior shows its state (tabs, toggles, segmented controls).
  • Inline signifiers: local cues near the affected area (selection count, scope chip, disabled reason).
  • Post-action feedback: clear results + next step (reduces evaluation gulf).
  • Only if needed: persistent banners/labels for high-risk, sticky modes.
• Avoid: redundant "status labels" that restate what the structure already makes obvious (they add noise but not clarity).
• Practical workflow:
  • First build a content model (task/state/result/risk).
  • Then apply visual constraints through layout, hierarchy, and component styling.
  • Run a final copy pass: if a sentence does not help task completion, state understanding, or trust, move it to internal notes.
• Review question: is each visible sentence useful for end users, or only useful for builders/reviewers?

Help text layering (avoid "hint sprawl")

• Problem this prevents: dumping all tips onto the UI feels "safe", but it destroys hierarchy and increases scanning cost.
• Placement heuristic:
  • L0 (Always visible): only information needed to complete the task correctly.
  • L1 (Nearby): short guidance for high-risk / high-ambiguity inputs.
  • L2 (On demand): examples, advanced details, "learn more".
  • L3 (After action): result, error, recovery, and next step.
• Copy budget heuristic:
  • Prefer one clear helper line over multiple repetitive hints.
  • If a page needs many persistent hints, improve IA or defaults first.

Feedback loop closure

• Definition: Every user action must complete a full loop: received, in progress, result, and clear next step.
• Review question: At any moment, can users tell what the system is doing and what they should do next?

Prevention first + recoverability

• Definition: Reduce error probability before submission, and provide recovery paths for high-risk outcomes.
• Review question: Is the path designed to be easy to do right and safe to recover when wrong?

Progressive complexity

• Definition: Show minimum-required controls by default; reveal advanced capability only when context requires it.
• Review question: Can novices complete the core task quickly without limiting expert throughput?

Action perceptibility (affordance + signifiers)

• Definition: Interactive targets and likely outcomes are perceivable from structure and visual cues, without guesswork.
• Review question: Without reading help text, can users predict what is actionable and what will happen?

Cognitive load budget

• Definition: Limit new rules, terms, and interaction modes per screen; prioritize reuse over novelty.
• Review question: As information grows, does comprehension cost stay stable?

Evolution with semantic continuity

• Definition: Introduce new components/patterns only when existing ones cannot solve the problem, and keep semantic compatibility.
• Review question: Is this necessary innovation or avoidable interaction drift?