Frontend Interaction Craft

Frontend Interaction Craft

When to use

Open this skill when the question is how should this behave rather than how should this look. A new onboarding flow. A form that feels clunky. An empty state that needs work. A loading state that takes too long. A button that does not feel right on press. This is the how-to for the interactions themselves.

Do not use this skill for visual design fundamentals — that is frontend-visual-foundations. Do not use it for psychology, retention, or win-mapping decisions — those are product-psychology-craft and product-psychology-retention.

The five principles

Every interaction problem decomposes into these five. Diagnose by naming which one is broken.

1. Friction sweet spot

Friction is not the enemy — unguided flow is. Too much friction burns users out. Too little friction leaves them confused about what to do or why it matters. The craft is finding the level that moves them to value without overwhelming them.

Two working examples from the source:

• Onboarding carousel (Spark): the welcome screen is an IG-story-style carousel — multiple value props in one screen, not a multi-screen onboarding sequence. The actual card setup appears within the first five screens so users reach the core job fast.
• Expanded tooltips (crypto platform): secondary-but-important data is hidden behind expandable tooltips, not dumped on the main view. Users see the headline numbers and drill in only when they care.

The instinct to "just show everything" (less friction!) or "just strip it down" (less friction!) both fail. Neither is the sweet spot. Pick friction deliberately, per-flow.

2. Progressive disclosure

If everything is visible, nothing is visible. Progressive disclosure is the tool that implements the friction sweet spot at the screen level.

• Primary information up front. What does the user need to make the next decision?
• Secondary information on demand. Tooltips, expandable sections, "see more" links, carousels for sequential value.
• Tertiary information buried. Settings, edge-case docs, audit history — reachable, not present.

A good test: can a first-time user complete the primary action without reading anything they did not need? If no, something secondary is in the primary layer.

3. State completeness

Every interactive element has more states than just happy path. Design them all, or the product feels broken the first time reality intrudes.

The minimum set for any screen or component:

| State | Question | |---|---| | Default / idle | What does it look like at rest? | | Hover / focus | Does it react to pointer or keyboard? | | Active / pressed | Does it confirm the touch the instant it happens? | | Loading | What does the user see while waiting? | | Empty | What fills the space when there is no data yet? | | Error | What does the user see when it broke, and how do they recover? | | Success | How is the win acknowledged? | | Disabled | Why is it unavailable, and what fixes that? |

Skipping any of these is how a product earns its "feels cheap" reputation. Small inconsistencies here compound — the same obsessive QA discipline that governs visual consistency governs interaction states.

Deep dive: see references/state-patterns.md for state-by-state defaults, form validation timing, and error recovery patterns.

4. Affordance and feedback

Affordance is how the user knows what they can do. Feedback is how the user knows what just happened.

• Affordance: buttons look pressable. Inputs look typable. Links look linkable. Use learned conventions — tap targets, card shadows, underlined text — rather than inventing new signifiers the user has to learn.
• Feedback: every user action gets an immediate reaction. Press a button → it reacts on press, not just on release. Submit a form → something happens in the UI the same frame. Tap a toggle → the toggle moves with the finger, not after the request completes.

If the user has to wonder "did that work," the feedback layer failed. Feedback is the difference between an app that feels alive and one that feels dead — even when the underlying logic is identical.

5. Interaction consistency

Same action, same pattern, every time. A trust-sensitive user — which is every user, for the lifetime of the product — re-judges consistency on every screen.

• Same control = same treatment. A primary button behaves identically across flows. Confirmation modals follow one pattern, not three.
• Same motion = same meaning. A slide-in-from-right means "new screen pushed on the stack." It should not also mean "toast notification."
• Same validation = same format. Inline errors look the same on every form.

QA every screen obsessively — microcopy, precise timings, exact motion on every element. The compounding cost of ignoring this is invisible per screen and fatal in aggregate.

Deep dive: see references/motion-and-feedback.md for micro-interaction timing, easing defaults, and when motion helps vs. when it decorates.

Quick checklist

Run this on any flow or component in under a minute:

1. Friction — which friction is deliberate? Which is accidental? Would the flow work with one less step? With one more signpost?
2. Disclosure — is primary information in front of the user and secondary information one tap away? Any tertiary info cluttering the primary layer?
3. States — can I point to the design for idle, hover, active, loading, empty, error, success, and disabled? Any "we will do that later"?
4. Affordance and feedback — does every interactive element look interactive? Does every action get an immediate reaction?
5. Consistency — does the same control behave the same way elsewhere in the product? Does the same motion mean the same thing?

If any answer is "no" or "I'm not sure," that is the issue to fix.

Before / after patterns

Over-stripped onboarding

• Before: Four-screen onboarding reduced to one logo and one "get started" button. No context, no value prop. User signs up, lands on an empty dashboard, bounces.
• After: IG-story-style welcome carousel reinforces the value prop in one screen. The core action (first task setup) appears within the first five screens. Fast to value, not starved of context.

Data-dump dashboard

• Before: Every metric, balance, and transaction on one screen. Users hesitate, scroll, and leave without acting.
• After: Headline numbers surface. Secondary metrics behind expandable tooltips or an "advanced" toggle. Tertiary audit data on its own screen, reachable from a link. One clear primary action above the fold.

Broken state coverage

• Before: Form with only the happy-path design. On error, users see a red banner with the server message. On slow network, the submit button does nothing visible while the request is in flight.
• After: Button enters loading state on press (spinner, disabled). Errors render inline next to the offending field with recovery guidance. Success state confirms the submission before transitioning away.

Inconsistent feedback

• Before: One toggle animates instantly, another waits for the server response, a third snaps back on error with no explanation. Users cannot tell which ones "work."
• After: All toggles animate optimistically on tap. On failure, they reverse with a short inline error. One rule, applied everywhere.

When to read the references

• references/state-patterns.md — when designing loading, empty, error, or success states for a new screen, or auditing whether all states are covered on an existing one. Covers form validation timing and error recovery patterns.
• references/motion-and-feedback.md — when deciding what should animate, how long, and with what easing. Covers micro-interaction timing conventions and the distinction between meaningful and decorative motion.

If the checklist above answers the question, you do not need the references.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jmadriano2
• Source: jmadriano2/Claude-Skills
• License: MIT

Install and usage instructions live in the source repository linked above.