Button or Link? Choose Agent-Generated Controls by Their Effect

A matching visual style can hide different behaviors

A frontend agent makes every control in a directory card look like the same rounded pill. View details, Copy command and Save now look consistent. But the implementation uses a clickable container for all three.

The screenshot cannot reveal the problem. One control should navigate to a resource, another should copy text and the third should change a saved state. Their visual family can be shared without making their semantics identical.

This guide is for product engineers reviewing agent-generated interfaces. Its practical deliverable is an effect map: a short description of what each control actually does before the agent chooses an HTML element.

Selection methodology and scope

We reviewed the W3C Authoring Practices Guide patterns for buttons and links, plus MDN's button reference, on October 5, 2026. We use a hypothetical skill-directory card to compare navigation, local actions and form submission.

This is a documentation-based review method. We did not run a browser or assistive-technology compatibility study for the example, and no component or Skill is certified by this article.

The earlier form error recovery guide addresses invalid inputs and unsuccessful submissions. Here the question comes earlier: which interaction has the user been offered in the first place?

Start with an effect map

Ask the agent to fill out this table before styling a card. The examples are proposed product decisions, not a description of every current OpenAgentSkill control.

The last row is deliberately unresolved. Get started could navigate to documentation, open a dialog or submit a request. The wording alone cannot select the element.

Keep effects narrow. Copying an installation command is not installing software. If a control will execute something, that needs a different explanation and appropriate authorization. Do not let a friendly label conceal an expanded action.

Use links for destinations

The W3C link pattern recommends native links with an href. Adding a link role to an arbitrary element does not automatically provide navigation or context-menu behavior. The pattern describes Enter as the activation key.

For our View details example, the implementation review should find an actual destination for the selected item. Ask whether the link can be copied or opened separately, not merely whether one mouse click changes the screen.

When using a routing abstraction, inspect its rendered element and behavior. A component named Link is not evidence by itself. Preserve a meaningful destination rather than substituting a dummy fragment and making all navigation depend on a click handler.

Do not attach the card's navigation handler to every nested action. A person copying a command should not unexpectedly leave the page because the surrounding card also reacted.

Use buttons for actions, and decide the state model

The W3C button pattern covers actions such as opening dialogs and submitting forms, with Space and Enter activation. It also describes a toggle pattern using aria-pressed and a stable label. A changing action label is an alternative design, not something that always needs the same toggle attribute.

For a Save control, choose the product model explicitly. One design uses a stable Save label with a pressed state indicating membership. Another offers changing actions such as Save and Remove from saved. Review what a user hears and sees in each state instead of casually combining both approaches.

For Copy command, define success and failure feedback separately from the click. A click is an attempt; the interface should not claim that the clipboard changed before the operation succeeds. This is our recommended acceptance condition, not a measured property of an existing component.

The same restrained border, spacing and typography can style links and buttons. Semantic correctness does not require visually unrelated widgets.

Make form behavior explicit

MDN's button reference explains button types and warns that a button associated with a form can submit it when the type is not appropriately specified. Use type="button" for a local action that must not submit, and type="submit" for the intended submission control.

Consider a preview button beside a submission button. An agent may place both inside the same form for layout convenience. The preview must not become an accidental submission path.

Our review recommendation is to inspect the surrounding form as well as the isolated component. A reusable button that behaves correctly on a standalone page may do something different when placed inside a form. Keep this behavior explicit in the component contract.

Review behavior before approving the screenshot

Use a non-production fixture containing a card and a form. The following are proposed acceptance exercises, not tests executed for this article:

• Tab through the controls and verify that focus is visible and follows a useful order.
• Activate the destination link with Enter and inspect its destination and context-menu options.
• Activate action buttons with Enter and Space; verify the requested action occurs without unintended navigation.
• Copy a command and verify that the implementation does not execute it.
• Toggle a saved state and inspect both its visible and accessible state.
• Activate a local preview control inside the form and verify that it does not submit.
• Submit through the intended control and check that the action is not duplicated by overlapping handlers.

Record the tested browser, input method, observed result and unresolved checks. If the agent only inspected markup, report that narrower evidence instead of calling the whole interaction verified.

Limitations and the handoff

This effect map does not cover every custom widget, focus transition, disabled state, security requirement or accessibility standard. Dialogs, menus and complex composite controls need additional review. Correct elements also do not guarantee search rankings.

Use the skills directory to find frontend workflows, then ask the chosen workflow for an effect map alongside its proposed design. Keep design tokens shared, but preserve the difference between going somewhere, doing something and submitting information.

The final acceptance question is simple: does each control behave like the promise made by its name and semantics, including without a mouse?