Luigit
repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by admin

pi/agent/skills/graphical-user-interface/SKILL.md

Raw
Rendered preview

name: graphical-user-interface description: "Design/review HCI across GUI/TUI/CLI/web/desktop/mobile. Use for flows, models, feedback, responsiveness, a11y, errors, medium fit. Not styling/components."

Human-computer interaction

Design the relationship between human intent and machine behavior, not a collection of UI elements. Apply principles proportionally; surface consequential trade-offs, not a mandatory design ceremony.

Establish context

  • Identify intended users, tasks, frequency, stakes, environment, and project goals before choosing priorities.
  • Inspect relevant project contracts, existing interfaces, and observed workflows before asking questions they can answer.
  • Treat precedent as evidence, not authority; challenge inherited interaction when task benefits justify relearning and migration costs.
  • Ask when consequential priorities remain unresolved; disclosed assumptions are not evidence.
  • Let context decide novice/expert emphasis and acceptable learning cost; do not impose one universal audience or simplicity ideal.
  • Treat conflicts between project goals and informed choice as explicit project decisions; this skill is not standing authorization for misleading behavior.

Fit the medium

  • Preserve task intent across media; adapt interaction rather than transplanting another medium's model or brute-forcing its limitations.
  • Assess actual input, output, persistence, accessibility, connectivity, surrounding tools, and resource constraints, not just platform labels or viewport size.
  • Exploit strengths that help the task; do not require features merely because the medium supports them.
  • Respect useful host capabilities and conventions; consistency means transferable expectations, not identical presentation everywhere.
  • Support equivalent core-task completion through accessible alternatives; equivalent need not mean identical interaction.

Minimize whole-task effort

  • Optimize completion, understanding, search, memory, navigation, errors, and repeated-use effort together; neither density nor minimalism wins by default.
  • Make available actions, scope, current state, and likely consequences discoverable where needed.
  • Match language and information organization to users' tasks and mental models, not implementation structure.
  • Remove incidental complexity; decide contextually when to teach necessary concepts versus abstract them away.
  • Support progression toward mastery without making recall or hidden shortcuts the only usable path.
  • Disclose secondary complexity when helpful without hiding frequent operations, necessary comparisons, or material consequences.
  • Preserve orientation and useful context across interruption; require attention only when it helps the task.

Respect both sides of the interface

  • Give human usability and mechanical sympathy equal design standing: account for CPU, memory, storage, bandwidth, energy, scheduling, and communication costs.
  • Keep semantic state structured and machine-suitable; derive task-specific human views rather than parsing presentation back into application truth.
  • Preserve precision, identity, units, and meaning internally even when a human view rounds, summarizes, localizes, or reorders them.
  • Choose internal and exchange representations for their actual workloads; machine-readable does not mean one prescribed serialization everywhere.
  • Expose stable machine interfaces when workflows, integration needs, or project contracts warrant them; do not add external automation solely because internal state is structured.
  • Treat latency, throughput, working-set size, and energy as interacting costs; improving one does not prove overall improvement.

Make time part of the design

  • Prefer responsiveness; establish resource exceptions from domain, app, project, and relevant existing interfaces, then ask if unresolved.
  • Separate input acknowledgment, useful result, and durable completion; immediate acknowledgment must not imply work is finished.
  • Remove avoidable waiting before decorating it; keep unnecessary computation, transfers, redraws, and blocking work outside the interaction's critical path.
  • Consider incremental work, locality, caching, or speculation only with their correctness and resource costs; preloading can reduce waiting, not guarantee instant results.
  • Keep useful work available during unavoidable delays; provide truthful state and meaningful cancellation, safe exit, or resumption according to stakes and workflow.
  • Distinguish pending, locally retained, synchronized, failed, and durably completed states wherever those differences affect user decisions.
  • Do not invent progress, promise unsupported completion times, or hide stale results as current truth.
  • Set timing expectations for the actual interaction; continuous manipulation, discrete actions, and long jobs need different treatment.

Support error and recovery

  • Prevent costly slips and misunderstandings without making every action a confirmation ritual.
  • Make scope and irreversible consequences understandable before commitment; support correction and reversal where appropriate.
  • Preserve useful work through errors and interruption; establish unknown retention stakes before weakening protection against potentially irreversible loss.
  • A justified exception for explicitly disposable data does not settle unknown stakes, accessibility, or other agency trade-offs.
  • Explain failure in task terms, preserve valid input, and offer an actionable recovery path.

Ground decisions

  • Connect recommendations to task evidence, project constraints, or established principles; identify which support each claim.
  • Use reversible prototypes when representative observations are unavailable; predicted benefits remain hypotheses until tested.
  • Evaluate representative tasks and relevant failure states, including constrained environments; inspect completion, effort, mistakes, recovery, accessibility, and perceived control.
  • Measure input-to-feedback, useful-result latency, completion, and resource costs relevant to the decision; averages or throughput alone can hide interaction stalls.
  • Report observed results and remaining uncertainty; profile, verify rendered fidelity, and test as the change warrants.

Research

Read research and interpretation when source authority, evidence limits, medium-specific application, or a contested trade-off needs explanation. Keep frameworks, component catalogs, visual style rules, and platform implementation recipes outside this skill.

---
name: graphical-user-interface
description: "Design/review HCI across GUI/TUI/CLI/web/desktop/mobile. Use for flows, models, feedback, responsiveness, a11y, errors, medium fit. Not styling/components."
---

# Human-computer interaction

Design the relationship between human intent and machine behavior, not a collection of UI elements.
Apply principles proportionally; surface consequential trade-offs, not a mandatory design ceremony.

## Establish context

- Identify intended users, tasks, frequency, stakes, environment, and project goals before choosing priorities.
- Inspect relevant project contracts, existing interfaces, and observed workflows before asking questions they can answer.
- Treat precedent as evidence, not authority; challenge inherited interaction when task benefits justify relearning and migration costs.
- Ask when consequential priorities remain unresolved; disclosed assumptions are not evidence.
- Let context decide novice/expert emphasis and acceptable learning cost; do not impose one universal audience or simplicity ideal.
- Treat conflicts between project goals and informed choice as explicit project decisions; this skill is not standing authorization for misleading behavior.

## Fit the medium

- Preserve task intent across media; adapt interaction rather than transplanting another medium's model or brute-forcing its limitations.
- Assess actual input, output, persistence, accessibility, connectivity, surrounding tools, and resource constraints, not just platform labels or viewport size.
- Exploit strengths that help the task; do not require features merely because the medium supports them.
- Respect useful host capabilities and conventions; consistency means transferable expectations, not identical presentation everywhere.
- Support equivalent core-task completion through accessible alternatives; equivalent need not mean identical interaction.

## Minimize whole-task effort

- Optimize completion, understanding, search, memory, navigation, errors, and repeated-use effort together; neither density nor minimalism wins by default.
- Make available actions, scope, current state, and likely consequences discoverable where needed.
- Match language and information organization to users' tasks and mental models, not implementation structure.
- Remove incidental complexity; decide contextually when to teach necessary concepts versus abstract them away.
- Support progression toward mastery without making recall or hidden shortcuts the only usable path.
- Disclose secondary complexity when helpful without hiding frequent operations, necessary comparisons, or material consequences.
- Preserve orientation and useful context across interruption; require attention only when it helps the task.

## Respect both sides of the interface

- Give human usability and mechanical sympathy equal design standing: account for CPU, memory, storage, bandwidth, energy, scheduling, and communication costs.
- Keep semantic state structured and machine-suitable; derive task-specific human views rather than parsing presentation back into application truth.
- Preserve precision, identity, units, and meaning internally even when a human view rounds, summarizes, localizes, or reorders them.
- Choose internal and exchange representations for their actual workloads; machine-readable does not mean one prescribed serialization everywhere.
- Expose stable machine interfaces when workflows, integration needs, or project contracts warrant them; do not add external automation solely because internal state is structured.
- Treat latency, throughput, working-set size, and energy as interacting costs; improving one does not prove overall improvement.

## Make time part of the design

- Prefer responsiveness; establish resource exceptions from domain, app, project, and relevant existing interfaces, then ask if unresolved.
- Separate input acknowledgment, useful result, and durable completion; immediate acknowledgment must not imply work is finished.
- Remove avoidable waiting before decorating it; keep unnecessary computation, transfers, redraws, and blocking work outside the interaction's critical path.
- Consider incremental work, locality, caching, or speculation only with their correctness and resource costs; preloading can reduce waiting, not guarantee instant results.
- Keep useful work available during unavoidable delays; provide truthful state and meaningful cancellation, safe exit, or resumption according to stakes and workflow.
- Distinguish pending, locally retained, synchronized, failed, and durably completed states wherever those differences affect user decisions.
- Do not invent progress, promise unsupported completion times, or hide stale results as current truth.
- Set timing expectations for the actual interaction; continuous manipulation, discrete actions, and long jobs need different treatment.

## Support error and recovery

- Prevent costly slips and misunderstandings without making every action a confirmation ritual.
- Make scope and irreversible consequences understandable before commitment; support correction and reversal where appropriate.
- Preserve useful work through errors and interruption; establish unknown retention stakes before weakening protection against potentially irreversible loss.
- A justified exception for explicitly disposable data does not settle unknown stakes, accessibility, or other agency trade-offs.
- Explain failure in task terms, preserve valid input, and offer an actionable recovery path.

## Ground decisions

- Connect recommendations to task evidence, project constraints, or established principles; identify which support each claim.
- Use reversible prototypes when representative observations are unavailable; predicted benefits remain hypotheses until tested.
- Evaluate representative tasks and relevant failure states, including constrained environments; inspect completion, effort, mistakes, recovery, accessibility, and perceived control.
- Measure input-to-feedback, useful-result latency, completion, and resource costs relevant to the decision; averages or throughput alone can hide interaction stalls.
- Report observed results and remaining uncertainty; profile, verify rendered fidelity, and test as the change warrants.

## Research

Read [research and interpretation](references/research.md) when source authority, evidence limits, medium-specific application, or a contested trade-off needs explanation.
Keep frameworks, component catalogs, visual style rules, and platform implementation recipes outside this skill.