k1e1n04/claude-skills

ux-design-for-architects

A guide for architects to design and review the UX of non-UI user touchpoints (API / Configuration / Extensions). It does not cover UI screen design (colors, layout, etc.).

UX extends beyond the UI to every point of contact between the system and the user. Poor UX at these touchpoints is hard to change later (because users depend on it) and lowers the overall probability of success. Therefore, decide on UX before implementation.

How to Proceed

1. Identify the touchpoint: The target is one (or more) of: API, Configuration, or Extensions.
2. Identify the user (Principle 1): Who uses it, for what purpose, and at what technical level?
3. Read the detailed guide for the relevant touchpoint:
   • Configuration → references/configuration.md
   • API → references/api.md
   • Extensions → references/extensions.md
4. Check against the 6 principles (see below). If proposing a design, include a brief rationale referencing the principles.
5. For a review, format findings according to references/review-checklist.md.
6. If opinions differ, confirm with the user using a hypothesis (AskUserQuestion).

The 6 UX Principles

#	Principle	Key Point	Why
1	Understand the user	Grasp goals, technical level, mental model, and typical workflows. Make the system behave as expected (principle of least surprise)	Users act differently than we predict. Observing and measuring is more effective than asking
2	Do the minimum necessary	Offer only necessary features. Adopt widely used standards (OAuth, OpenID, etc.) if available	Everything you provide becomes debt. Once released, users get used to it and it becomes hard to change
3	Make manuals unnecessary	Make usage self-evident; guide with recommendations and cues	Users don't read manuals. If they can't solve the problem, they blame the product
4	Think in terms of information exchange	Avoid asking > ask less > ask in an easy-to-answer format. Never ask the same thing twice	Input is a burden. Reduce it through inference, memory, and derivation
5	Keep simple things simple	Remove barriers for the first few operations. Provide pre-configured clients or samples	Beginners are most likely to drop off. The first experience determines retention
6	Design UX before implementation	Design UX before architecture; iterate with feedback	Changing UX after implementation is costly. Delay implementation; deepen design

Deciding When to Ask for Information (Elaboration of Principle 4)

Think in terms of priority:

1. Don't ask: Use reasonable defaults, auto-detection, remembering past inputs, and deriving from known information.
2. Ask less: Only ask for what is truly necessary.
3. Ask in an easy-to-answer way: Frame questions in terms the user can answer without mental calculation, not in internal implementation terms (e.g., instead of "maximum cache entry count," use "memory limit for cache" or derive details from a mode choice like "server or client").

Returning Output / Responses (Principle 4)

Unless there is a performance issue, return information generously in a form the user can understand, making the next action predictable. When passing the result of one call as input to another, allow the user to pass it on with minimal processing.

Summary by Touchpoint

• Configuration: The best configuration is "no configuration." Next best is automatic determination, and last is with reasonable defaults. The question is: "Does the user have better context than we do?" — Only add a setting if the answer is Yes. Do not silently ignore unknown keys or failed applications; report errors. Validate settings at startup or when they are applied.
• API: Users are developers. Make it easy to learn, hard to misuse, and always make the next step clear. Do one thing well. Don't make users write boilerplate code. Follow standards. Version from the start. Delay public release until necessary; first use it internally.
• Extensions: Wait until you deeply understand the use case before adding them (they can be added through refactoring later). Do one thing well. Define inputs and outputs; do not expose internal structure. Once published, they are hard to change.

Common Mistakes (Suspect During Design or Review)

• Lack of UX expertise / Delaying involvement of experts
• Focusing only on UI while neglecting UX of APIs, configuration, and extensions
• Technical leaders making UX decisions and only asking experts for UI tweaks
• Ignoring expert proposals
• Getting stuck between two options and using a configuration setting to escape (pushing the problem onto the user)

If no expert is available, state this explicitly and recommend involving a UX expert early. However, do not stop designing due to a lack of advice; produce a provisional plan following this guide.

Connection to Iterative Approaches

• Derive design from user journeys → Apply this guide to each touchpoint in the journey.
• Slice iteratively → Only build the touchpoints needed for the first slice (public APIs and extensions can often wait until after an MVP).
• Design deeply and implement slowly for things that are hard to change → UX is the prime example. Learn by observing real usage.

Output Format

• Design proposal: State concisely in the order: "Target touchpoint → User profile → Proposal → Relevant principles and reasons → Open issues."
• Review: Use the format from references/review-checklist.md.