@warp-ds/elements 2.10.0-next.1 → 2.10.0-next.11

package/dist/docs/affix/affix.md

@@ -4,8 +4,6 @@
 
 This component is usually used in other components like form elements to show a prefix or suffix. See for example `w-textfield`.
 
-[See Storybook for usage examples](https://warp-ds.github.io/elements/?path=/docs/forms-affix--docs)
-
 ## Usage
 
 `w-affix` is typically used inside form controls to render prefix/suffix text or icon actions.
@@ -144,6 +142,8 @@ Clicking the clear button will reset the textfield
 
 </elements-example>
 
+## Styling API
+
 ## `<w-affix>` API
 
 Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).

package/dist/docs/affix/styling.md

@@ -0,0 +1 @@
+## Styling API

package/dist/docs/alert/alert.md

@@ -6,8 +6,6 @@ Alert is an inline component used for displaying different types of messages.
 
 For accessibility reasons, alert should appear close to the element that triggered it.
 
-[See Storybook for usage examples](https://warp-ds.github.io/elements/?path=/docs/feedback-alert--docs)
-
 ## Usage
 
 Alert is an inline component used for displaying different types of messages.
@@ -152,6 +150,8 @@ attribute on [MDN](https://developer.mozilla.org/en-US/docs/Web/Accessibility/AR
 </script>
 ```
 
+## Styling API
+
 ## `<w-alert>` API
 
 Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).

package/dist/docs/alert/styling.md

@@ -0,0 +1 @@
+## Styling API

package/dist/docs/attention/attention.md

@@ -246,6 +246,8 @@ When `can-close` is used, ensure your app listens to the `close` event and updat
 
 </elements-example>
 
+## Styling API
+
 ## `<w-attention>` API
 
 Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).

package/dist/docs/attention/styling.md

@@ -0,0 +1 @@
+## Styling API

package/dist/docs/badge/badge.md

@@ -176,6 +176,8 @@ If the same information is already available in nearby accessible text and the b
 
 </elements-example>
 
+## Styling API
+
 ## `<w-badge>` API
 
 Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).

package/dist/docs/badge/styling.md

@@ -0,0 +1 @@
+## Styling API

package/dist/docs/box/box.md

@@ -4,8 +4,6 @@
 
 Box is a layout component used for separating content areas on a page.
 
-[See Storybook for usage examples](https://warp-ds.github.io/elements/?path=/docs/layout-box--docs)
-
 ## Usage
 
 Box is a layout component for visually separating a section of content from the surrounding page.
@@ -89,13 +87,8 @@ If you must use box for a purely visual grouping, set role none:
 
 ### Basic
 
-<style-isolate>
-  <w-box aria-labelledby="delivery-heading">
-    <h2 id="delivery-heading">Delivery</h2>
-    <p>Choose how you want the item delivered.</p>
-  </w-box>
-</style-isolate>
-
+<elements-example>
+  
 ```html
 <w-box aria-labelledby="delivery-heading">
   <h2 id="delivery-heading">Delivery</h2>
@@ -103,14 +96,11 @@ If you must use box for a purely visual grouping, set role none:
 </w-box>
 ```
 
+</elements-example>
+
 ### Neutral
 
-<style-isolate>
-  <w-box neutral aria-labelledby="order-summary-heading">
-    <h2 id="order-summary-heading">Order summary</h2>
-    <p>Review the item price, delivery, and total before continuing.</p>
-  </w-box>
-</style-isolate>
+<elements-example>
 
 ```html
 <w-box neutral aria-labelledby="order-summary-heading">
@@ -119,14 +109,11 @@ If you must use box for a purely visual grouping, set role none:
 </w-box>
 ```
 
+</elements-example>
+
 ### Info
 
-<style-isolate>
-  <w-box info aria-labelledby="good-to-know-heading">
-    <h2 id="good-to-know-heading">Good to know</h2>
-    <p>You can change the delivery method before payment.</p>
-  </w-box>
-</style-isolate>
+<elements-example>
 
 ```html
 <w-box info aria-labelledby="good-to-know-heading">
@@ -135,14 +122,11 @@ If you must use box for a purely visual grouping, set role none:
 </w-box>
 ```
 
+</elements-example>
+
 ### Bordered
 
-<style-isolate>
-  <w-box bordered aria-labelledby="contact-seller-heading">
-    <h2 id="contact-seller-heading">Contact seller</h2>
-    <p>Send a message to ask about pickup times.</p>
-  </w-box>
-</style-isolate>
+<elements-example>
 
 ```html
 <w-box bordered aria-labelledby="contact-seller-heading">
@@ -151,16 +135,11 @@ If you must use box for a purely visual grouping, set role none:
 </w-box>
 ```
 
+</elements-example>
+
 ### Bleed
 
-<style-isolate>
-  <div style="padding: 0 16px;">
-    <w-box neutral bleed aria-labelledby="summary-heading">
-      <h2 id="summary-heading">Summary</h2>
-      <p>This box extends into the horizontal gutter on narrow screens.</p>
-    </w-box>
-  </div>
-</style-isolate>
+<elements-example>
 
 ```html
 <div style="padding: 0 16px;">
@@ -171,13 +150,12 @@ If you must use box for a purely visual grouping, set role none:
 </div>
 ```
 
+</elements-example>
+
+
 ### Visual Grouping Without Accessibility Landmarking
 
-<style-isolate>
-  <w-box role="none">
-    <p>This box is only a visual container.</p>
-  </w-box>
-</style-isolate>
+<elements-example>
 
 ```html
 <w-box role="none">
@@ -185,6 +163,10 @@ If you must use box for a purely visual grouping, set role none:
 </w-box>
 ```
 
+</elements-example>
+
+## Styling API
+
 ## `<w-box>` API
 
 Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).

package/dist/docs/box/examples.md

@@ -2,13 +2,8 @@
 
 ### Basic
 
-<style-isolate>
-  <w-box aria-labelledby="delivery-heading">
-    <h2 id="delivery-heading">Delivery</h2>
-    <p>Choose how you want the item delivered.</p>
-  </w-box>
-</style-isolate>
-
+<elements-example>
+  
 ```html
 <w-box aria-labelledby="delivery-heading">
   <h2 id="delivery-heading">Delivery</h2>
@@ -16,14 +11,11 @@
 </w-box>
 ```
 
+</elements-example>
+
 ### Neutral
 
-<style-isolate>
-  <w-box neutral aria-labelledby="order-summary-heading">
-    <h2 id="order-summary-heading">Order summary</h2>
-    <p>Review the item price, delivery, and total before continuing.</p>
-  </w-box>
-</style-isolate>
+<elements-example>
 
 ```html
 <w-box neutral aria-labelledby="order-summary-heading">
@@ -32,14 +24,11 @@
 </w-box>
 ```
 
+</elements-example>
+
 ### Info
 
-<style-isolate>
-  <w-box info aria-labelledby="good-to-know-heading">
-    <h2 id="good-to-know-heading">Good to know</h2>
-    <p>You can change the delivery method before payment.</p>
-  </w-box>
-</style-isolate>
+<elements-example>
 
 ```html
 <w-box info aria-labelledby="good-to-know-heading">
@@ -48,14 +37,11 @@
 </w-box>
 ```
 
+</elements-example>
+
 ### Bordered
 
-<style-isolate>
-  <w-box bordered aria-labelledby="contact-seller-heading">
-    <h2 id="contact-seller-heading">Contact seller</h2>
-    <p>Send a message to ask about pickup times.</p>
-  </w-box>
-</style-isolate>
+<elements-example>
 
 ```html
 <w-box bordered aria-labelledby="contact-seller-heading">
@@ -64,16 +50,11 @@
 </w-box>
 ```
 
+</elements-example>
+
 ### Bleed
 
-<style-isolate>
-  <div style="padding: 0 16px;">
-    <w-box neutral bleed aria-labelledby="summary-heading">
-      <h2 id="summary-heading">Summary</h2>
-      <p>This box extends into the horizontal gutter on narrow screens.</p>
-    </w-box>
-  </div>
-</style-isolate>
+<elements-example>
 
 ```html
 <div style="padding: 0 16px;">
@@ -84,16 +65,17 @@
 </div>
 ```
 
+</elements-example>
+
+
 ### Visual Grouping Without Accessibility Landmarking
 
-<style-isolate>
-  <w-box role="none">
-    <p>This box is only a visual container.</p>
-  </w-box>
-</style-isolate>
+<elements-example>
 
 ```html
 <w-box role="none">
   <p>This box is only a visual container.</p>
 </w-box>
 ```
+
+</elements-example>

package/dist/docs/box/styling.md

@@ -0,0 +1 @@
+## Styling API

package/dist/docs/breadcrumbs/breadcrumbs.md

@@ -5,8 +5,6 @@
 Shows the navigation structure for the current page.
 Renders direct child links and non-link elements as a breadcrumb trail, inserts separators between items, and exposes the trail as navigation.
 
-[See Storybook for usage examples](https://warp-ds.github.io/elements/?path=/docs/navigation-breadcrumbs--docs)
-
 ## Usage
 
 Breadcrumbs show where the current page sits in a site hierarchy and let users move back to parent pages.
@@ -98,6 +96,7 @@ Breadcrumbs should support orientation within the site hierarchy. They should no
 ### Basic
 
 <elements-example>
+
 ```html
   <w-breadcrumbs>
     <a href="#/real-estate">Real estate</a>
@@ -105,11 +104,13 @@ Breadcrumbs should support orientation within the site hierarchy. They should no
     <span aria-current="page">Oslo</span>
   </w-breadcrumbs>
 ```
+
 </elements-example>
 
 ### Custom Accessible Label
 
 <elements-example>
+
 ```html
   <w-breadcrumbs aria-label="Product category path">
     <a href="#/marketplace">Marketplace</a>
@@ -117,19 +118,24 @@ Breadcrumbs should support orientation within the site hierarchy. They should no
     <span aria-current="page">Sofas</span>
   </w-breadcrumbs>
 ```
+
 </elements-example>
 
 ### Short Path
 
 <elements-example>
+
 ```html
   <w-breadcrumbs>
     <a href="#/help">Help</a>
     <span aria-current="page">Contact us</span>
   </w-breadcrumbs>
 ```
+
 </elements-example>
 
+## Styling API
+
 ## `<w-breadcrumbs>` API
 
 Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).

package/dist/docs/breadcrumbs/examples.md

@@ -3,6 +3,7 @@
 ### Basic
 
 <elements-example>
+
 ```html
   <w-breadcrumbs>
     <a href="#/real-estate">Real estate</a>
@@ -10,11 +11,13 @@
     <span aria-current="page">Oslo</span>
   </w-breadcrumbs>
 ```
+
 </elements-example>
 
 ### Custom Accessible Label
 
 <elements-example>
+
 ```html
   <w-breadcrumbs aria-label="Product category path">
     <a href="#/marketplace">Marketplace</a>
@@ -22,15 +25,18 @@
     <span aria-current="page">Sofas</span>
   </w-breadcrumbs>
 ```
+
 </elements-example>
 
 ### Short Path
 
 <elements-example>
+
 ```html
   <w-breadcrumbs>
     <a href="#/help">Help</a>
     <span aria-current="page">Contact us</span>
   </w-breadcrumbs>
 ```
-</elements-example>
+
+</elements-example>

package/dist/docs/breadcrumbs/styling.md

@@ -0,0 +1 @@
+## Styling API

package/dist/docs/button/button.md

@@ -5,8 +5,6 @@
 Performs an action or renders a link with button styling.
 Use button variants to match action priority, risk, and context.
 
-[See Storybook for usage examples](https://warp-ds.github.io/elements/?path=/docs/buttons-button--docs)
-
 ## 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.
@@ -270,6 +268,79 @@ For backwards compatibility, if `href` is set, `w-button` renders a link with bu
 
 </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).

package/dist/docs/button/styling.md

@@ -0,0 +1,72 @@
+## 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).

package/dist/docs/card/accessibility.md

@@ -1 +1,75 @@
 ## Accessibility
+
+Card is a visual container. It does not create a heading, landmark, list item, link, button, or other semantic structure for the slotted content.
+
+### Provide Semantic Content
+
+Use semantic HTML inside the card so assistive technologies can understand the content.
+
+```html
+<w-card>
+  <article style="padding: 16px;" aria-labelledby="listing-heading">
+    <h3 id="listing-heading">Apartment in Oslo</h3>
+    <p>Bright 3-room apartment with balcony.</p>
+  </article>
+</w-card>
+```
+
+Do not rely on the card surface, border, or selected styling to communicate meaning.
+
+### Selected State
+
+Use `selected` only when the card represents a selected item or choice.
+
+```html
+<w-card selected>
+  <div style="padding: 16px;">
+    <h3>Standard delivery</h3>
+    <p>Delivered in 2-4 business days.</p>
+  </div>
+</w-card>
+```
+
+The selected state should also be clear from the surrounding context, such as a group label, heading, or visible text.
+
+### Clickable Cards
+
+Use `clickable` only when the whole card has one action or represents one selectable choice.
+
+```html
+<w-card clickable>
+  <div style="padding: 16px;">
+    <h3>Home delivery</h3>
+    <p>Delivered to your door.</p>
+  </div>
+</w-card>
+```
+
+The visible card content should describe what will be selected or activated. Do not put separate links, buttons, form controls, or other interactive elements inside a clickable card.
+
+### Prefer Specific Interactive Elements
+
+If only part of the card is interactive, use the appropriate element for that action.
+
+Use a link for navigation:
+
+```html
+<w-card>
+  <div style="padding: 16px;">
+    <h3><a href="/listings/123">Apartment in Oslo</a></h3>
+    <p>Bright 3-room apartment with balcony.</p>
+  </div>
+</w-card>
+```
+
+Use a button for an action on the current page:
+
+```html
+<w-card>
+  <div style="padding: 16px;">
+    <h3>Apartment in Oslo</h3>
+    <p>Bright 3-room apartment with balcony.</p>
+    <w-button variant="primary">Contact seller</w-button>
+  </div>
+</w-card>
+```

package/dist/docs/card/api.md

@@ -7,9 +7,9 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 | Name | Type | Default | Summary |
 |-|-|-|-|
 | buttonText (JS only) | `unknown` | `-` | - |
-| clickable | `boolean` | `false` | - |
-| flat | `boolean` | `false` | - |
-| selected | `boolean` | `false` | - |
+| clickable | `boolean` | `false` | Whether the whole card is interactive. |
+| flat | `boolean` | `false` | Whether the card uses the flat visual treatment. |
+| selected | `boolean` | `false` | Whether the card is visually selected. |
 
 ### Property Details
 
@@ -22,21 +22,27 @@ Unless otherwise noted all properties are HTML attributes (as opposed to JavaScr
 
 #### clickable
 
+Whether the whole card is interactive.
 
+When set, the card becomes keyboard focusable and Enter or Space triggers a click on the card. Use this only when the whole card has one action or represents one selectable choice.
 
 - Type: `boolean`
 - Default: `false`
 
 #### flat
 
+Whether the card uses the flat visual treatment.
 
+Flat cards use a bordered surface instead of the default elevated surface. Use this for denser layouts or when the card sits inside another surface.
 
 - Type: `boolean`
 - Default: `false`
 
 #### selected
 
+Whether the card is visually selected.
 
+Use this when the card represents a selected item or choice. This only controls the visual selected state; update it from your application state when the selection changes.
 
 - Type: `boolean`
 - Default: `false`