@warp-ds/elements 2.9.2-next.1 → 2.10.0-next.10

package/dist/docs/button/button.md

@@ -2,16 +2,345 @@
 
 ## Description
 
-Buttons are used to perform actions, widh different visuals for different needs.
-
-[See Storybook for usage examples](https://warp-ds.github.io/elements/?path=/docs/buttons-button--docs)
+Performs an action or renders a link with button styling.
+Use button variants to match action priority, risk, and context.
 
 ## Usage
 
+Button is used for actions. Use it when the user can submit, save, confirm, cancel, open, close, or trigger something on the current page.
+
+Use a link instead when the user is navigating to another page. If the control should look like a button but navigate like a link, use `w-link`.
+
+### Basic Button
+
+```html
+<w-button>Save</w-button>
+```
+
+The default `variant` is `secondary` and the default `type` is `button`.
+
+### Variants
+
+Choose the variant based on the action's priority and context:
+
+- `primary`: the main action in a view or flow
+- `secondary`: secondary or tertiary actions; this is the default
+- `negative`: destructive or high-risk actions
+- `negativeQuiet`: low-emphasis destructive actions
+- `utility`: compact utility actions
+- `utilityQuiet`: low-emphasis utility actions
+- `quiet`: low-emphasis actions, often near other buttons
+- `link`: (@deprecated) action styled like an inline link
+- `pill`: circular icon-style controls
+- `overlay`, `overlayQuiet`, `overlayInverted`, `overlayInvertedQuiet`: controls placed on top of media or elevated surfaces
+
+```html
+<w-button variant="primary">Publish</w-button>
+<w-button variant="secondary">Cancel</w-button>
+<w-button variant="negative">Delete</w-button>
+<w-button variant="utility">Filter</w-button>
+```
+
+### Sizes And Width
+
+Use `small` for compact layouts. Use `full-width` when the button should fill its parent, such as in narrow mobile layouts.
+
+```html
+<w-button variant="primary" small>Save</w-button>
+<w-button variant="primary" full-width>Continue</w-button>
+```
+
+### Icon-Only Buttons
+
+Use `variant="pill"` for circular icon-only controls. Include accessible text in the slotted content so the internal button has a name.
+
+```html
+<w-button variant="pill" icon-only>
+  <w-icon name="Close"></w-icon>
+  <span class="sr-only">Close</span>
+</w-button>
+```
+
+### Loading
+
+Use `loading` after the user triggers an action and the action is in progress.
+
+```html
+<w-button variant="primary" loading>Saving</w-button>
+```
+
+Keep the button text descriptive while loading. Do not rely on the loading animation alone to explain what is happening.
+
+### Form Buttons
+
+Use `type="submit"` to submit the containing form and `type="reset"` to reset it. Use `name` and `value` when the button value should be included in form handling.
+
+```html
+<form>
+  <w-button type="submit" name="intent" value="save">Save</w-button>
+  <w-button type="reset">Reset</w-button>
+</form>
+```
+
+### Link Styled As Button
+
+Use an `a` tag if you need a link that looks and behaves like a link, do not use `w-button`.
+
+### Link Styled As Button
+
+Use `w-link` if you need a link that looks like a button.
+
+### Disabled Actions
+
+Avoid disabled buttons where possible. Disabled controls often make it harder for users to understand what is missing or how to continue.
+
+Prefer an enabled button with clear validation or explanatory feedback near the related field.
+
 ## Accessibility
 
+Buttons must have a clear accessible name and should describe the action they perform.
+
+### Use Descriptive Text
+
+Prefer visible text that names the action.
+
+```html
+<w-button>Save changes</w-button>
+```
+
+Avoid vague labels when the action is not obvious from context.
+
+```html
+<!-- Avoid -->
+<w-button>OK</w-button>
+```
+
+### Icon-Only Buttons
+
+If a button does not have visible text, include text for assistive technologies in the slotted content.
+
+```html
+<w-button variant="pill">
+  <w-icon name="Close"></w-icon>
+  <span class="sr-only">Close</span>
+</w-button>
+```
+
+The accessible text should describe the action, not the icon shape.
+
+### Disabled Buttons
+
+Avoid disabled buttons. A disabled control can prevent keyboard users from reaching it and often does not explain what must happen before the action becomes available.
+
+Prefer keeping the button available and showing validation or explanatory feedback when the user tries to continue.
+
+### Button Or Link
+
+Use a w-button for actions on the current page. Use a w-link for navigation.
+
+For backwards compatibility, if `href` is set, `w-button` renders a link with button styling. The accessible behavior is link behavior, even though the component looks like a button. This is deprecated behaviour and you should instead use the w-link component if you need to render a link that looks like a button.
+
 ## Examples
 
+### Primary
+
+<elements-example>
+
+```html
+<w-button variant="primary">Publish</w-button>
+```
+
+</elements-example>
+
+### Secondary
+
+<elements-example>
+
+```html
+<w-button variant="secondary">Cancel</w-button>
+```
+
+</elements-example>
+
+### Negative
+
+<elements-example>
+
+```html
+<w-button variant="negative">Delete</w-button>
+```
+
+</elements-example>
+
+### Utility
+
+<elements-example>
+
+```html
+<w-button variant="utility">Filter</w-button>
+```
+
+</elements-example>
+
+### Quiet
+
+<elements-example>
+
+```html
+<w-button variant="quiet">Skip</w-button>
+```
+
+</elements-example>
+
+### Icon Only
+
+<elements-example>
+
+```html
+<w-button variant="pill" icon-only>
+  <w-icon name="Close"></w-icon>
+  <span class="sr-only">Close</span>
+</w-button>
+```
+
+</elements-example>
+
+### Small
+
+<elements-example>
+
+```html
+<w-button variant="primary" small>Save</w-button>
+```
+
+</elements-example>
+
+### Full Width
+
+<elements-example>
+
+```html
+<w-button variant="primary" full-width>Continue</w-button>
+```
+
+</elements-example>
+
+### Loading
+
+<elements-example>
+
+```html
+<w-button variant="primary" loading>Saving</w-button>
+```
+
+</elements-example>
+
+### Link Styled As Button
+
+<elements-example>
+
+```html
+<w-button href="/messages/new" variant="primary">New message</w-button>
+```
+
+</elements-example>
+
+### External Link
+
+<elements-example>
+
+```html
+<w-button href="https://example.com" target="_blank">Visit example</w-button>
+```
+
+</elements-example>
+
+### Form Actions
+
+<elements-example>
+
+```html
+<form>
+  <w-button type="submit" name="intent" value="save">Save</w-button>
+  <w-button type="reset">Reset</w-button>
+</form>
+```
+
+</elements-example>
+
+## Styling API
+
+This component supports styling through **component tokens** (CSS custom properties with a --w-c- prefix) and **parts**.
+
+### Parts
+
+Use `::part(...)` from outside the component.
+
+- `base` — the clickable element (`<button>` or `<w-link>`)
+
+Example:
+
+```css
+w-button::part(base) {
+  text-transform: uppercase;
+}
+```
+
+### Component tokens
+
+Set these on `w-button` to override visuals.
+
+```css
+w-button {
+  --w-c-button-bg: var(--w-s-color-background-primary);
+  --w-c-button-color: var(--w-s-color-text-inverted);
+}
+```
+
+#### Layout & typography
+
+- `--w-c-button-radius`
+- `--w-c-button-font-size`
+- `--w-c-button-line-height`
+- `--w-c-button-font-weight`
+- `--w-c-button-padding-x`
+- `--w-c-button-padding-y`
+
+#### Background
+
+- `--w-c-button-bg`
+- `--w-c-button-bg-hover`
+- `--w-c-button-bg-active`
+
+#### Text color
+
+- `--w-c-button-color`
+- `--w-c-button-color-hover`
+- `--w-c-button-color-active`
+
+#### Border
+
+- `--w-c-button-border-width`
+- `--w-c-button-border-color`
+- `--w-c-button-border-color-hover`
+- `--w-c-button-border-color-active`
+
+#### Focus
+
+- `--w-c-button-outline-width`
+- `--w-c-button-outline-color`
+- `--w-c-button-outline-offset`
+
+#### Motion
+
+- `--w-c-button-transition`
+
+### Notes
+
+- Variant defaults are set internally using fallbacks, so overriding tokens works across variants.
+- The `quiet` boolean is supported for backwards compatibility. Prefer `variant="quiet"` going forward.
+- When `loading` is set, the button is treated as disabled (no pointer interaction).
+
 ## `<w-button>` API
 
 Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).
@@ -20,36 +349,31 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 | Name | Type | Default | Summary |
 |-|-|-|-|
-| ariaValueTextLoading (JS only) | `unknown` | `-` | - |
-| autofocus | `boolean` | `false` | - |
-| button-class | `string` | `-` | **Deprecated**: This class is applied inside the shadow DOM and is unlikely to have the desired effect. Use attributes or CSS variables to customize the appearance of the button. |
-| disabled | `boolean` | `false` | - |
-| full-width | `boolean` | `false` | - |
-| href | `string` | `-` | - |
-| icon-only | `boolean` | `false` | - |
-| loading | `boolean` | `false` | - |
-| name | `string` | `-` | - |
-| quiet | `boolean` | `false` | **Deprecated**: Use `variant="quiet"` instead |
-| rel | `string` | `-` | - |
-| shadowRootOptions (JS only) | `object` | `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }` | - |
-| small | `boolean` | `false` | - |
-| target | `string` | `-` | - |
-| type | [`ButtonType`](#buttontype) | `-` | - |
-| value | `string` | `-` | - |
-| variant | [`ButtonVariant`](#buttonvariant) | `-` | - |
+| autofocus | `boolean` | `false` | Focuses the button when it is first rendered. |
+| button-class | `string` | `-` | Deprecated class applied to the internal control. **Deprecated**: This class is applied inside the shadow DOM and is unlikely to have the desired effect. Use attributes or CSS variables to customize the appearance of the button. |
+| command | `string` | `-` | The [command HTML attribute](https://developer.mozilla.org/en-US/docs/Web/API/Invoker_Commands_API#html_attributes) for Invoker Commands. |
+| commandfor | `string` | `-` | The [commandfor HTML attribute](https://developer.mozilla.org/en-US/docs/Web/API/Invoker_Commands_API#html_attributes) for Invoker Commands. |
+| disabled | `boolean` | `false` | Visually disables the button. |
+| full-width | `boolean` | `false` | Makes the button fill its parent width. |
+| href | `string` | `-` | URL for rendering the button as a link. |
+| icon-only | `boolean` | `false` | Marks the button as icon-only. |
+| loading | `boolean` | `false` | Shows the loading state. |
+| name | `string` | `-` | Form control name. |
+| quiet | `boolean` | `false` | Deprecated quiet visual treatment flag. **Deprecated**: Use `variant="quiet"` instead |
+| rel | `string` | `-` | Link relationship. |
+| shadowRootOptions (JS only) | `object` | `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }` | Shadow root configuration. |
+| small | `boolean` | `false` | Renders the compact button size. |
+| target | `string` | `-` | Link browsing context. |
+| type | [`ButtonType`](#buttontype) | `-` | Native button type. |
+| value | `string` | `-` | Form control value. |
+| variant | [`ButtonVariant`](#buttonvariant) | `-` | Visual style of the button. |
 
 ### Property Details
 
-#### ariaValueTextLoading (JS only)
-
-
-
-- Type: `unknown`
-- Default: `-`
-
 #### autofocus
 
-
+Focuses the button when it is first rendered.
+Applies only when the component renders a native button. Link buttons with `href` do not autofocus through this component.
 
 - Type: `boolean`
 - Default: `false`
@@ -58,49 +382,70 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 **Deprecated**: This class is applied inside the shadow DOM and is unlikely to have the desired effect. Use attributes or CSS variables to customize the appearance of the button.
 
+Deprecated class applied to the internal control
+This class is applied inside the shadow DOM and is unlikely to have the desired effect. Use attributes or CSS variables to customize the button appearance.
 
+- Type: `string`
+- Default: `-`
+
+#### command
+
+The [command HTML attribute](https://developer.mozilla.org/en-US/docs/Web/API/Invoker_Commands_API#html_attributes) for Invoker Commands.
 
 - Type: `string`
 - Default: `-`
 
-#### disabled
+#### commandfor
 
+The [commandfor HTML attribute](https://developer.mozilla.org/en-US/docs/Web/API/Invoker_Commands_API#html_attributes) for Invoker Commands.
 
+- Type: `string`
+- Default: `-`
+
+#### disabled
+
+Visually disables the button.
+Disabled buttons are discouraged because they can hide the reason an action is unavailable.
 
 - Type: `boolean`
 - Default: `false`
 
 #### full-width
 
-
+Makes the button fill its parent width.
+Useful in narrow layouts where the button should span the available inline space.
 
 - Type: `boolean`
 - Default: `false`
 
 #### href
 
-
+URL for rendering the button as a link.
+When set, the component renders `w-link` instead of a native `button`.
 
 - Type: `string`
 - Default: `-`
 
 #### icon-only
 
-
+Marks the button as icon-only.
+Use this when the button has no visible text. Include accessible text in the slotted content so the internal button has a name.
 
 - Type: `boolean`
 - Default: `false`
 
 #### loading
 
-
+Shows the loading state.
+Use after the user has triggered an action and the action is in progress.
 
 - Type: `boolean`
 - Default: `false`
 
 #### name
 
-
+Form control name.
+Used when the button participates in form handling.
 
 - Type: `string`
 - Default: `-`
@@ -109,56 +454,64 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 **Deprecated**: Use `variant="quiet"` instead
 
-
+Deprecated quiet visual treatment flag
+Use `variant="quiet"` instead.
 
 - Type: `boolean`
 - Default: `false`
 
 #### rel
 
-
+Link relationship.
+Passed to the rendered link when `href` is set. If `target="_blank"` is set and `rel` is omitted, `noopener` is used.
 
 - Type: `string`
 - Default: `-`
 
 #### shadowRootOptions (JS only)
 
-
+Shadow root configuration.
+Delegates focus from the host to the internal control.
 
 - Type: `object`
 - Default: `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }`
 
 #### small
 
-
+Renders the compact button size.
+Use this in dense layouts where the default button size is too large.
 
 - Type: `boolean`
 - Default: `false`
 
 #### target
 
-
+Link browsing context.
+Passed to the rendered link when `href` is set.
 
 - Type: `string`
 - Default: `-`
 
 #### type
 
-
+Native button type.
+Controls whether the internal button behaves as a regular button, submits a form, or resets a form. Defaults to `button`.
 
 - Type: [`ButtonType`](#buttontype)
 - Default: `-`
 
 #### value
 
-
+Form control value.
+Used with `name` when the button participates in form handling. Resets to its initial value when the form is reset.
 
 - Type: `string`
 - Default: `-`
 
 #### variant
 
-
+Visual style of the button.
+Defaults to `secondary`. Use the variant that matches the action priority, risk, and placement.
 
 - Type: [`ButtonVariant`](#buttonvariant)
 - Default: `-`

package/dist/docs/button/examples.md

@@ -1 +1,127 @@
 ## Examples
+
+### Primary
+
+<elements-example>
+
+```html
+<w-button variant="primary">Publish</w-button>
+```
+
+</elements-example>
+
+### Secondary
+
+<elements-example>
+
+```html
+<w-button variant="secondary">Cancel</w-button>
+```
+
+</elements-example>
+
+### Negative
+
+<elements-example>
+
+```html
+<w-button variant="negative">Delete</w-button>
+```
+
+</elements-example>
+
+### Utility
+
+<elements-example>
+
+```html
+<w-button variant="utility">Filter</w-button>
+```
+
+</elements-example>
+
+### Quiet
+
+<elements-example>
+
+```html
+<w-button variant="quiet">Skip</w-button>
+```
+
+</elements-example>
+
+### Icon Only
+
+<elements-example>
+
+```html
+<w-button variant="pill" icon-only>
+  <w-icon name="Close"></w-icon>
+  <span class="sr-only">Close</span>
+</w-button>
+```
+
+</elements-example>
+
+### Small
+
+<elements-example>
+
+```html
+<w-button variant="primary" small>Save</w-button>
+```
+
+</elements-example>
+
+### Full Width
+
+<elements-example>
+
+```html
+<w-button variant="primary" full-width>Continue</w-button>
+```
+
+</elements-example>
+
+### Loading
+
+<elements-example>
+
+```html
+<w-button variant="primary" loading>Saving</w-button>
+```
+
+</elements-example>
+
+### Link Styled As Button
+
+<elements-example>
+
+```html
+<w-button href="/messages/new" variant="primary">New message</w-button>
+```
+
+</elements-example>
+
+### External Link
+
+<elements-example>
+
+```html
+<w-button href="https://example.com" target="_blank">Visit example</w-button>
+```
+
+</elements-example>
+
+### Form Actions
+
+<elements-example>
+
+```html
+<form>
+  <w-button type="submit" name="intent" value="save">Save</w-button>
+  <w-button type="reset">Reset</w-button>
+</form>
+```
+
+</elements-example>