J3W1 / DESIGN SYSTEM
Icon button
A square ghost button whose only content is a 16px line icon; it always carries an accessible name and, as a toggle, aria-pressed.
stable · LIGHT DOM · 1.1.0
Light DOM retains static content, native semantics, label relationships and host composition without duplicating controls.
Live variants
default
<j3w1-icon-button id="example-icon-button-default"><button class="icon-button" type="button" aria-label="Close panel">
<svg class="icon-button-icon" aria-hidden="true" focusable="false" width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="square"><path d="M3.5 3.5l9 9M12.5 3.5l-9 9"></path></svg>
</button></j3w1-icon-button>toggle
<j3w1-icon-button id="example-icon-button-toggle"><button class="icon-button" type="button" aria-label="Pin window" aria-pressed="false">
<svg class="icon-button-icon" aria-hidden="true" focusable="false" width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linejoin="miter"><path d="M6 2h4v4l2 2v2H4V8l2-2z"></path><path d="M8 10v4"></path></svg>
</button></j3w1-icon-button>Install and register
Use the exact version. If npm publication is pending, install the release tarball from the installation guide.
npm install --save-exact @j3w1/ui@1.1.0import '@j3w1/ui/tokens.css';
import '@j3w1/ui/styles/icon-button.css';
import '@j3w1/ui/register/icon-button';Insert the maintained markup above after loading these imports. Its native children provide accessible names and form behavior; the empty custom tag alone does not create a control.
Copy the complete implementation
npx --package=@j3w1/ui@1.1.0 j3w1-ui copy icon-button --out ./vendor/j3w1/icon-buttonThe CLI verifies every file before writing and refuses overwrites. Serve the output over HTTP and open index.html. Keep its modules, CSS, tokens and licence notices together.
Public API
attributes
| Name | Type / signature | Meaning |
|---|---|---|
disabled | CustomEvent | Disable the native controls owned by this instance. |
loading | CustomEvent | Mark the primary control busy and prevent duplicate activation. |
tone | CustomEvent | Button tone: primary, secondary, tertiary or destructive. |
properties
| Name | Type / signature | Meaning |
|---|---|---|
disabled | boolean | Delegates disabled state to native children. |
name | string | Native control name; application form keys remain explicit. |
methods
| Name | Type / signature | Meaning |
|---|---|---|
refresh | (): void | Reconnect behavior after replacing native child structure. |
focus | (options?: FocusOptions): void | Focus the first usable native control. |
events
| Name | Type / signature | Meaning |
|---|---|---|
j3w1-action | CustomEvent | A native button activated. Prevent default on this event to cancel the associated native default action. |
Dependencies and verification
Registered components: none. Style dependencies: none.
Package presence establishes an available implementation. Actual passes depend on the tested artifact and environment. Read specification execution evidence; read packed-consumer evidence; inspect the complete state matrix.
Full implementation manifest, API and token dependency closure
Canonical specification
Purpose
A button whose whole content is one icon: toolbar actions, close and clear affordances, and boolean toggles such as pin, mute or wrap. It is the tertiary tone constrained to a square. Any icon button needs an accessible name and a tooltip; if the label must be visible it is a button.
Anatomy
A native <button> sized to the density control height in both axes with a
single 16px inline SVG inside. The border is 1px and transparent at rest so
the active and toggled borders do not shift the layout.
States
| State | Visual | Non-colour channel |
|---|---|---|
| default | color.action.tertiary.text icon on nothing; transparent 1px border | — |
| hover | background → color.action.tertiary.hover-bg | cursor: pointer; hover-capable pointers only |
| focus-visible | ring 1px dashed color.interaction.focus.ring at −2px | the ring |
| active | background → color.interaction.pressed.bg; border → color.border.active | border change; no translation |
| disabled | color.text.disabled on color.interaction.disabled.bg with 1px color.border.disabled; no hover | disabled; cursor: not-allowed |
| toggled | fill color.interaction.selection.bg with color.interaction.selection.text; border color.border.selected-indicator; the icon draws in its filled form | aria-pressed="true"; the filled icon shape; the border |
| toggled+focus-visible | the selection fill and a ring in color.interaction.focus.ring-container | both visible at once |
Precedence: disabled > toggled > active > hover; focus-visible is always drawn.
Keyboard
Native. The toggle variant flips aria-pressed on Enter and Space and does
not move focus. Inside a toolbar the host applies roving tabindex; the
button itself binds nothing.
Accessibility
aria-label (or aria-labelledby) names the button; the tooltip repeats
the same text and is not the name. The SVG is aria-hidden="true" and
focusable="false". A toggle uses aria-pressed, whose value is announced;
the name never changes with the state (“Mute”, not “Mute” / “Unmute”).
Contrast: icon 8.65:1 at rest, 12.47:1 on the selection fill; ring 4.69:1,
container ring 7.48:1 on the selection fill. Target ≥ 24×24 CSS pixels with
4px between neighbours in compact density.
Portability
Square, fill, border, outline; the icon is currentColor so it follows every state without its own colour. Hosts without inline SVG use their icon theme at 16px and record the substitution. Hosts without dashed outlines draw a solid 1px ring.
Non-examples
A circle. An icon button without an accessible name. A toggle that changes
its label instead of aria-pressed. A hover that recolours the icon alone.
An emoji or icon-font glyph in place of the SVG. A toggled state shown by
colour alone with a line icon. A shadow or scale on press.