@universal-material/web 3.7.2 → 3.9.0

package/shared/text-field-base/text-field-base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"text-field-base.d.ts","sourceRoot":"","sources":["../../../src/shared/text-field-base/text-field-base.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAK/D,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAGxD,8BAAsB,eAAgB,SAAQ,WAAW;IACvD,MAAM,CAAC,QAAQ,CAAC,cAAc,QAAQ;IAEtC,OAAgB,MAAM,EAAE,cAAc,CAAgC;IAEtE,OAAgB,iBAAiB,EAAE,cAAc,CAG/C;IAEF;;OAEG;IACM,KAAK,UAAQ;IAEO,WAAW,SAAM;IAE9C,IAAI,IAAI,IAAI,eAAe,GAAG,IAAI,CAEjC;IAED,SAAS,CAAC,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;;CAMvD"}
+{"version":3,"file":"text-field-base.d.ts","sourceRoot":"","sources":["../../../src/shared/text-field-base/text-field-base.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAK/D,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAGtD,qFAAqF;AACrF,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,kBAAkB,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,8BAAsB,aAAc,SAAQ,SAAS;IACnD,MAAM,CAAC,QAAQ,CAAC,cAAc,QAAQ;IAEtC,OAAgB,MAAM,EAAE,cAAc,CAA8B;IAEpE,OAAgB,iBAAiB,EAAE,cAAc,CAG/C;IAEF;;OAEG;IACM,KAAK,UAAQ;IAEtB;;OAEG;IAC0B,WAAW,SAAM;IAE9C;;;OAGG;IACyC,QAAQ,UAAS;IAE7D,IAAI,IAAI,IAAI,eAAe,GAAG,IAAI,CAEjC;IAED,6EAA6E;IAC7E,IAAI,QAAQ,IAAI,aAAa,CAE5B;IAED,yEAAyE;IACzE,IAAI,iBAAiB,IAAI,MAAM,CAE9B;IAED,SAAS,CAAC,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;;IAOtD;;;;OAIG;IACH,SAAS,CAAC,YAAY,IAAI,aAAa;IASvC,2EAA2E;IAC3E,SAAS,CAAC,aAAa,IAAI,IAAI;IAa/B,4EAA4E;IAC5E,aAAa,IAAI,OAAO;IAKxB;;;OAGG;IACH,cAAc,IAAI,OAAO;cAON,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;CAK1D"}

package/shared/text-field-base/text-field-base.js

@@ -1,11 +1,11 @@
 import { __decorate } from "tslib";
 import { LitElement } from 'lit';
 import { property } from 'lit/decorators.js';
-import { UmFieldBase } from '../../field/field-base.js';
+import { FieldBase } from '../../field/field-base.js';
 import { styles } from './text-field-base.styles.js';
-export class UmTextFieldBase extends UmFieldBase {
+export class TextFieldBase extends FieldBase {
     static { this.formAssociated = true; }
-    static { this.styles = [UmFieldBase.styles, styles]; }
+    static { this.styles = [FieldBase.styles, styles]; }
     static { this.shadowRootOptions = {
         ...LitElement.shadowRootOptions,
         delegatesFocus: true,
@@ -13,17 +13,79 @@ export class UmTextFieldBase extends UmFieldBase {
     get form() {
         return this.elementInternals.form;
     }
+    /** The live `ValidityState` of the field (mirrors a native form control). */
+    get validity() {
+        return this.elementInternals.validity;
+    }
+    /** The message shown by `reportValidity()` when the field is invalid. */
+    get validationMessage() {
+        return this.elementInternals.validationMessage;
+    }
     constructor() {
         super();
         /**
          * Whether the field is empty or not. This changes the behavior of the floating label when the field is not focused.
          */
         this.empty = true;
+        /**
+         * The placeholder text shown when the field is empty
+         */
         this.placeholder = '';
+        /**
+         * Whether the field must have a value to satisfy constraint validation.
+         * Drives `checkValidity()`/`reportValidity()` and blocks native form submit.
+         */
+        this.required = false;
         this.elementInternals = this.attachInternals();
     }
+    /**
+     * Reports the current validity. Subclasses override to delegate to a native
+     * input (`u-text-field`) or compute their own (`u-select`). The default only
+     * enforces `required` against the empty state.
+     */
+    _getValidity() {
+        const valueMissing = this.required && this.empty;
+        return {
+            flags: { valueMissing },
+            message: valueMissing ? 'Please fill out this field.' : '',
+        };
+    }
+    /** Pushes the subclass's validity into the ElementInternals form state. */
+    _syncValidity() {
+        const { flags, message, anchor } = this._getValidity();
+        const isValid = !Object.values(flags).some(Boolean);
+        if (isValid) {
+            this.elementInternals.setValidity({});
+            return;
+        }
+        // A non-empty message is required when any flag is set.
+        this.elementInternals.setValidity(flags, message || 'Invalid value.', anchor);
+    }
+    /** Returns whether the field is valid (fires an `invalid` event if not). */
+    checkValidity() {
+        this._syncValidity();
+        return this.elementInternals.checkValidity();
+    }
+    /**
+     * Like `checkValidity()`, but also surfaces the native validation bubble and
+     * reflects the result onto the visual `invalid` state.
+     */
+    reportValidity() {
+        this._syncValidity();
+        const valid = this.elementInternals.reportValidity();
+        this.invalid = !valid;
+        return valid;
+    }
+    updated(changed) {
+        super.updated(changed);
+        // Keep the form-level validity current so native submit honors constraints.
+        this._syncValidity();
+    }
 }
 __decorate([
     property({ reflect: true })
-], UmTextFieldBase.prototype, "placeholder", void 0);
+], TextFieldBase.prototype, "placeholder", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], TextFieldBase.prototype, "required", void 0);
 //# sourceMappingURL=text-field-base.js.map

package/shared/text-field-base/text-field-base.js.map

@@ -1 +1 @@
-{"version":3,"file":"text-field-base.js","sourceRoot":"","sources":["../../../src/shared/text-field-base/text-field-base.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,KAAK,CAAC;AACjC,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE7C,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AAErD,MAAM,OAAgB,eAAgB,SAAQ,WAAW;aACvC,mBAAc,GAAG,IAAI,AAAP,CAAQ;aAEtB,WAAM,GAAmB,CAAC,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,AAA/C,CAAgD;aAEtD,sBAAiB,GAAmB;QAClD,GAAG,UAAU,CAAC,iBAAiB;QAC/B,cAAc,EAAE,IAAI;KACrB,AAHgC,CAG/B;IASF,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC;IACpC,CAAC;IAID;QACE,KAAK,EAAE,CAAC;QAdV;;WAEG;QACM,UAAK,GAAG,IAAI,CAAC;QAEO,gBAAW,GAAG,EAAE,CAAC;QAU5C,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,eAAe,EAAE,CAAC;IACjD,CAAC;;AAX4B;IAA5B,QAAQ,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;oDAAkB","sourcesContent":["import { CSSResultGroup } from '@lit/reactive-element/css-tag';\n\nimport { LitElement } from 'lit';\nimport { property } from 'lit/decorators.js';\n\nimport { UmFieldBase } from '../../field/field-base.js';\nimport { styles } from './text-field-base.styles.js';\n\nexport abstract class UmTextFieldBase extends UmFieldBase {\n  static readonly formAssociated = true;\n\n  static override styles: CSSResultGroup = [UmFieldBase.styles, styles];\n\n  static override shadowRootOptions: ShadowRootInit = {\n    ...LitElement.shadowRootOptions,\n    delegatesFocus: true,\n  };\n\n  /**\n   * Whether the field is empty or not. This changes the behavior of the floating label when the field is not focused.\n   */\n  override empty = true;\n\n  @property({ reflect: true }) placeholder = '';\n\n  get form(): HTMLFormElement | null {\n    return this.elementInternals.form;\n  }\n\n  protected readonly elementInternals: ElementInternals;\n\n  constructor() {\n    super();\n    this.elementInternals = this.attachInternals();\n  }\n}\n"]}
+{"version":3,"file":"text-field-base.js","sourceRoot":"","sources":["../../../src/shared/text-field-base/text-field-base.ts"],"names":[],"mappings":";AAGA,OAAO,EAAE,UAAU,EAAE,MAAM,KAAK,CAAC;AACjC,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE7C,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AASrD,MAAM,OAAgB,aAAc,SAAQ,SAAS;aACnC,mBAAc,GAAG,IAAI,AAAP,CAAQ;aAEtB,WAAM,GAAmB,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,AAA7C,CAA8C;aAEpD,sBAAiB,GAAmB;QAClD,GAAG,UAAU,CAAC,iBAAiB;QAC/B,cAAc,EAAE,IAAI;KACrB,AAHgC,CAG/B;IAkBF,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,gBAAgB,CAAC,IAAI,CAAC;IACpC,CAAC;IAED,6EAA6E;IAC7E,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC;IACxC,CAAC;IAED,yEAAyE;IACzE,IAAI,iBAAiB;QACnB,OAAO,IAAI,CAAC,gBAAgB,CAAC,iBAAiB,CAAC;IACjD,CAAC;IAID;QACE,KAAK,EAAE,CAAC;QAjCV;;WAEG;QACM,UAAK,GAAG,IAAI,CAAC;QAEtB;;WAEG;QAC0B,gBAAW,GAAG,EAAE,CAAC;QAE9C;;;WAGG;QACyC,aAAQ,GAAG,KAAK,CAAC;QAoB3D,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,eAAe,EAAE,CAAC;IACjD,CAAC;IAED;;;;OAIG;IACO,YAAY;QACpB,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,KAAK,CAAC;QAEjD,OAAO;YACL,KAAK,EAAE,EAAE,YAAY,EAAE;YACvB,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,6BAA6B,CAAC,CAAC,CAAC,EAAE;SAC3D,CAAC;IACJ,CAAC;IAED,2EAA2E;IACjE,aAAa;QACrB,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;QACvD,MAAM,OAAO,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAEpD,IAAI,OAAO,EAAE,CAAC;YACZ,IAAI,CAAC,gBAAgB,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;YACtC,OAAO;QACT,CAAC;QAED,wDAAwD;QACxD,IAAI,CAAC,gBAAgB,CAAC,WAAW,CAAC,KAAK,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,CAAC,CAAC;IAChF,CAAC;IAED,4EAA4E;IAC5E,aAAa;QACX,IAAI,CAAC,aAAa,EAAE,CAAC;QACrB,OAAO,IAAI,CAAC,gBAAgB,CAAC,aAAa,EAAE,CAAC;IAC/C,CAAC;IAED;;;OAGG;IACH,cAAc;QACZ,IAAI,CAAC,aAAa,EAAE,CAAC;QACrB,MAAM,KAAK,GAAG,IAAI,CAAC,gBAAgB,CAAC,cAAc,EAAE,CAAC;QACrD,IAAI,CAAC,OAAO,GAAG,CAAC,KAAK,CAAC;QACtB,OAAO,KAAK,CAAC;IACf,CAAC;IAEkB,OAAO,CAAC,OAAuB;QAChD,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACvB,4EAA4E;QAC5E,IAAI,CAAC,aAAa,EAAE,CAAC;IACvB,CAAC;;AA9E4B;IAA5B,QAAQ,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;kDAAkB;AAMF;IAA3C,QAAQ,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;+CAAkB","sourcesContent":["import { PropertyValues } from '@lit/reactive-element';\nimport { CSSResultGroup } from '@lit/reactive-element/css-tag';\n\nimport { LitElement } from 'lit';\nimport { property } from 'lit/decorators.js';\n\nimport { FieldBase } from '../../field/field-base.js';\nimport { styles } from './text-field-base.styles.js';\n\n/** The validity flags a subclass reports, plus the message/anchor for the bubble. */\nexport interface FieldValidity {\n  flags: ValidityStateFlags;\n  message: string;\n  anchor?: HTMLElement;\n}\n\nexport abstract class TextFieldBase extends FieldBase {\n  static readonly formAssociated = true;\n\n  static override styles: CSSResultGroup = [FieldBase.styles, styles];\n\n  static override shadowRootOptions: ShadowRootInit = {\n    ...LitElement.shadowRootOptions,\n    delegatesFocus: true,\n  };\n\n  /**\n   * Whether the field is empty or not. This changes the behavior of the floating label when the field is not focused.\n   */\n  override empty = true;\n\n  /**\n   * The placeholder text shown when the field is empty\n   */\n  @property({ reflect: true }) placeholder = '';\n\n  /**\n   * Whether the field must have a value to satisfy constraint validation.\n   * Drives `checkValidity()`/`reportValidity()` and blocks native form submit.\n   */\n  @property({ type: Boolean, reflect: true }) required = false;\n\n  get form(): HTMLFormElement | null {\n    return this.elementInternals.form;\n  }\n\n  /** The live `ValidityState` of the field (mirrors a native form control). */\n  get validity(): ValidityState {\n    return this.elementInternals.validity;\n  }\n\n  /** The message shown by `reportValidity()` when the field is invalid. */\n  get validationMessage(): string {\n    return this.elementInternals.validationMessage;\n  }\n\n  protected readonly elementInternals: ElementInternals;\n\n  constructor() {\n    super();\n    this.elementInternals = this.attachInternals();\n  }\n\n  /**\n   * Reports the current validity. Subclasses override to delegate to a native\n   * input (`u-text-field`) or compute their own (`u-select`). The default only\n   * enforces `required` against the empty state.\n   */\n  protected _getValidity(): FieldValidity {\n    const valueMissing = this.required && this.empty;\n\n    return {\n      flags: { valueMissing },\n      message: valueMissing ? 'Please fill out this field.' : '',\n    };\n  }\n\n  /** Pushes the subclass's validity into the ElementInternals form state. */\n  protected _syncValidity(): void {\n    const { flags, message, anchor } = this._getValidity();\n    const isValid = !Object.values(flags).some(Boolean);\n\n    if (isValid) {\n      this.elementInternals.setValidity({});\n      return;\n    }\n\n    // A non-empty message is required when any flag is set.\n    this.elementInternals.setValidity(flags, message || 'Invalid value.', anchor);\n  }\n\n  /** Returns whether the field is valid (fires an `invalid` event if not). */\n  checkValidity(): boolean {\n    this._syncValidity();\n    return this.elementInternals.checkValidity();\n  }\n\n  /**\n   * Like `checkValidity()`, but also surfaces the native validation bubble and\n   * reflects the result onto the visual `invalid` state.\n   */\n  reportValidity(): boolean {\n    this._syncValidity();\n    const valid = this.elementInternals.reportValidity();\n    this.invalid = !valid;\n    return valid;\n  }\n\n  protected override updated(changed: PropertyValues): void {\n    super.updated(changed);\n    // Keep the form-level validity current so native submit honors constraints.\n    this._syncValidity();\n  }\n}\n"]}

package/skills/badge/SKILL.md

@@ -0,0 +1,43 @@
+---
+description: Show a u-badge — a small count or status dot. Floating over an icon by default, or `static` for an inline count next to text.
+---
+
+# Badge
+
+`<u-badge>` is a small count/dot with two modes.
+
+## Floating (default) — over an icon
+
+By default the badge is **absolutely positioned**, dotting the top-right corner of its nearest positioned ancestor (usually an icon). Put it inside the icon, or in a component's `badge` slot:
+
+```html
+<!-- over an icon button -->
+<u-icon-button aria-label="Notifications">
+  <span class="material-symbols-outlined">notifications<u-badge>3</u-badge></span>
+</u-icon-button>
+
+<!-- nav-bar / nav-rail item: the `badge` slot floats over the item's icon -->
+<u-navigation-bar-item>
+  <span class="material-symbols-outlined" slot="icon">inbox</span>
+  Inbox
+  <u-badge slot="badge">12</u-badge>
+</u-navigation-bar-item>
+```
+
+An empty `<u-badge></u-badge>` renders a small **dot** (no number).
+
+## `static` — inline count next to text
+
+Add `static` to render the badge **in flow** (not floating) — for a count chip beside a heading or label:
+
+```html
+<div class="flex items-center gap-2">
+  <span class="u-title-l">Alerts</span>
+  <u-badge static>3</u-badge>
+</div>
+```
+
+## Caveats
+
+- **Don't put a floating `<u-badge>` in a `<u-drawer-item>`'s `badge` slot** — there the badge must sit inline at the row's trailing edge, so use a plain `<span slot="badge">12</span>` (the drawer item styles it). A floating `<u-badge>` would position absolutely and land in the wrong place. (Nav-rail / nav-bar items are the opposite — their `badge` slot *does* take a floating `<u-badge>`, since it overlays the icon.)
+- The floating badge anchors to the nearest positioned ancestor (the icon/button provides one). For an inline count next to plain text, use `static`.

package/skills/buttons/SKILL.md

@@ -0,0 +1,115 @@
+---
+description: Use Material 3 common buttons — u-button (filled, tonal, elevated, outlined, text), u-icon-button, u-button-set for grouping.
+---
+
+# Common buttons
+
+## `<u-button>` — text + optional icon
+
+Five variants (`filled` default, `tonal`, `elevated`, `outlined`, `text`) and four colors (`primary` default, `secondary`, `tertiary`, `error`):
+
+```html
+<u-button>Save</u-button>
+<u-button variant="tonal">Save</u-button>
+<u-button variant="elevated">Save</u-button>
+<u-button variant="outlined">Save</u-button>
+<u-button variant="text">Save</u-button>
+
+<u-button color="error">Delete</u-button>
+```
+
+With an icon (default position: before the label):
+
+```html
+<u-button>
+  <span class="material-symbols-outlined" slot="icon">save</span>
+  Save
+</u-button>
+```
+
+Trailing icon:
+
+```html
+<u-button trailing-icon>
+  Open
+  <span class="material-symbols-outlined" slot="icon">arrow_outward</span>
+</u-button>
+```
+
+## Sizes and shapes
+
+```html
+<u-button size="extra-small">XS</u-button>
+<u-button size="small">S</u-button>
+<u-button size="medium">M</u-button>
+<u-button size="large">L</u-button>
+<u-button size="extra-large">XL</u-button>
+
+<u-button shape="square">Square</u-button>
+<u-button shape="round">Round (default)</u-button>
+```
+
+## Toggling
+
+```html
+<u-button toggle [selected]="favorited" (change)="favorited = $event.target.selected">
+  <span class="material-symbols-outlined" slot="icon">favorite_border</span>
+  <span class="material-symbols-outlined" slot="icon-selected">favorite</span>
+  Favorite
+</u-button>
+```
+
+Use `toggle-shape` to morph between `round` and `square` when toggled.
+
+## Forms
+
+`<u-button>` is form-associated. It submits the parent `<form>` by default (`type="submit"`). Override with `type="button"` or `type="reset"`.
+
+## `<u-icon-button>` — icon only
+
+```html
+<u-icon-button>
+  <span class="material-symbols-outlined">favorite</span>
+</u-icon-button>
+
+<u-icon-button variant="filled" color="primary">
+  <span class="material-symbols-outlined">add</span>
+</u-icon-button>
+```
+
+Variants: `standard` (default), `filled`, `tonal`, `outlined`. Widths: `default`, `narrow`, `wide`.
+
+For toggle icon buttons, use the `selected` slot for the "active" icon:
+
+```html
+<u-icon-button toggle>
+  <span class="material-symbols-outlined">favorite_border</span>
+  <span class="material-symbols-outlined" slot="selected">favorite</span>
+</u-icon-button>
+```
+
+## `<u-button-set>` — grouping
+
+Standardizes spacing and alignment for a row of action buttons. Default alignment is `end` (right-aligned), which matches dialog/form action rows.
+
+```html
+<u-button-set>
+  <u-button variant="text">Cancel</u-button>
+  <u-button>Save</u-button>
+</u-button-set>
+
+<u-button-set alignment="start">…</u-button-set>
+<u-button-set alignment="center">…</u-button-set>
+<u-button-set alignment="end">…</u-button-set>
+
+<u-button-set stack>
+  <u-button>Continue</u-button>
+  <u-button variant="outlined">Sign in instead</u-button>
+  <u-button variant="text">Cancel</u-button>
+</u-button-set>
+```
+
+## Caveats
+
+- For alignment to be visible the button-set must have available width. In a flex-row parent that's content-sized, set `width: 100%` or a fixed width on the button-set.
+- A button-set accepts any button-like child (`<u-button>`, `<u-icon-button>`, `<u-fab>`) and aligns them on the same baseline.

package/skills/card/SKILL.md

@@ -0,0 +1,162 @@
+---
+description: Use u-card for Material 3 cards — filled, outlined and elevated variants. Slot media in `before-content`; put body content directly inside the card (no manual u-card-content wrapper).
+---
+
+# Card
+
+A container for related content. Three visual variants — `filled` (default), `outlined`, `elevated` — chosen via the `variant` attribute.
+
+## Anatomy
+
+`<u-card>` wraps the default slot in an internal padded region automatically. It exposes three slots:
+
+| Slot | Purpose |
+| --- | --- |
+| `before-content` | Banner / media / hero placed flush to the card edges (no padding). Use for `<u-card-media>` or any custom hero element. |
+| default | Body content. Gets the standard 16dp padding from the card itself. |
+| `after-content` | Footer placed flush to the bottom edge (no padding). Use for full-bleed action bars. |
+
+## Basic
+
+```html
+<u-card>
+  <div class="u-title-l">Article title</div>
+  <div class="u-body-m u-text-low-emphasis">
+    Supporting paragraph with a short summary of the article content.
+  </div>
+</u-card>
+```
+
+Body content goes **directly** inside `<u-card>`. The card pads it for you.
+
+## Variants
+
+```html
+<u-card variant="filled">…</u-card>     <!-- default -->
+<u-card variant="outlined">…</u-card>
+<u-card variant="elevated">…</u-card>
+```
+
+### Recommendation: keep sibling cards on the same variant
+
+When several cards sit side-by-side and represent **information of the same importance** — KPI grids, product catalogs, list-of-articles, anything where each item is one "row" of equal weight — prefer using a single variant across all of them.
+
+Mixing variants in a sibling group (e.g. alternating filled/outlined/elevated) creates a visual hierarchy the data doesn't have: the elevated card looks more important than the outlined one even though both are just "another KPI" or "another product." The eye reads weight, not content, and gets the wrong signal first.
+
+```html
+<!-- ✅ Consistent: each KPI gets the same weight -->
+<div class="u-grid">
+  <u-card variant="outlined">…KPI 1…</u-card>
+  <u-card variant="outlined">…KPI 2…</u-card>
+  <u-card variant="outlined">…KPI 3…</u-card>
+</div>
+
+<!-- ❌ Mixing variants makes some KPIs visually "heavier" than others
+     even when they're peers in the data model. -->
+<div class="u-grid">
+  <u-card variant="elevated">…KPI 1…</u-card>
+  <u-card variant="outlined">…KPI 2…</u-card>
+  <u-card variant="filled">…KPI 3…</u-card>
+</div>
+```
+
+**Use different variants for different roles, not for variety.** A page can absolutely mix variants when the cards serve different purposes — e.g. the main content card `elevated`, the sidebar helper cards `outlined`, the inline tip cards `filled`. The cue should match the meaning.
+
+This is a guideline, not a hard rule — there are layouts where mixing is intentional (a "featured" card among regulars, an A/B test, a hero among supporting cards). The point is to be deliberate about why the variants differ.
+
+## With media (correct pattern)
+
+Place `<u-card-media>` in `slot="before-content"` so it sits flush against the card edges (no inner padding from the body region):
+
+```html
+<u-card variant="outlined">
+  <u-card-media slot="before-content">
+    <img src="…" alt="" />
+  </u-card-media>
+
+  <div class="u-title-l">Card with media</div>
+  <div class="u-body-m u-text-low-emphasis">Body content below the media — directly in the card, no wrapper.</div>
+</u-card>
+```
+
+`<u-card-media>` defaults to a square aspect ratio. Add the `wide` attribute for 16:9:
+
+```html
+<u-card-media wide slot="before-content">
+  <img src="…" alt="" />
+</u-card-media>
+```
+
+**Banner caveat:** `wide` sets a 16:9 *aspect ratio*, so at full container width the media becomes very tall (≈1200px on a wide page; the default square is worse). For a profile/detail **banner**, set an explicit height instead of `wide`:
+
+```html
+<u-card-media slot="before-content" style="height: 180px">…</u-card-media>
+```
+
+For a profile header (banner with an avatar straddling its bottom edge), pull the body up over the flush media with a negative top margin:
+
+```html
+<u-card variant="outlined">
+  <u-card-media slot="before-content" style="height: 160px">…</u-card-media>
+  <div style="display: flex; align-items: flex-end; gap: 16px; margin-top: -48px">
+    <span class="avatar" style="border: 4px solid var(--u-color-surface)">AB</span>
+    <div class="u-title-l">Name</div>
+  </div>
+</u-card>
+```
+
+## Actions
+
+Put action buttons inside a `<u-button-set>` at the bottom of the card:
+
+```html
+<u-card variant="outlined">
+  <div class="u-title-l">Confirm subscription</div>
+  <p class="u-body-m u-text-low-emphasis">
+    You'll receive weekly updates by email.
+  </p>
+  <u-button-set>
+    <u-button variant="text">Not now</u-button>
+    <u-button>Subscribe</u-button>
+  </u-button-set>
+</u-card>
+```
+
+For full-bleed footers (e.g. a divider + action bar that touches both card edges), use `slot="after-content"`:
+
+```html
+<u-card variant="outlined">
+  <div class="u-title-l">Card with full-bleed footer</div>
+  <p class="u-body-m">Body content with the standard padding.</p>
+
+  <div slot="after-content" style="border-top: 1px solid var(--u-color-outline-variant); padding: 12px 16px;">
+    <u-button variant="text">Action</u-button>
+  </div>
+</u-card>
+```
+
+## Overlays on the media
+
+When you need a chip, badge or icon overlaid on the media, wrap your media in a `<div style="position: relative">` and absolute-position the overlay inside it:
+
+```html
+<u-card>
+  <u-card-media wide slot="before-content">
+    <div style="position: relative; width: 100%; height: 100%;">
+      <img src="…" alt="" style="width: 100%; height: 100%; object-fit: cover;" />
+      <u-chip elevated style="position: absolute; top: 8px; left: 8px;">New</u-chip>
+    </div>
+  </u-card-media>
+
+  <div class="u-title-l">Title</div>
+</u-card>
+```
+
+Don't put `position: absolute` chips as direct children of `<u-card-media>` — slot positioning across shadow DOM boundaries is unreliable. Always wrap in a regular div.
+
+## Caveats
+
+- **Don't use `<u-card-content>` manually.** The card already wraps the default slot in a padded region — adding `<u-card-content>` on top stacks two layers of padding and is being phased out of the public API. Body content goes directly inside `<u-card>`.
+- `<u-card>` is just a container; it doesn't impose a layout on its children. Use `u-grid`, `u-column`, flex, etc. for the body's internal layout.
+- For clickable cards, wrap the entire card in `<a>` or `<button>`, or add an absolute-positioned overlay button (M3 doesn't define a built-in clickable card variant in this lib).
+- The internal padded region uses 16dp. Override via **`--u-card-padding`** (set on the card; it inherits to the internal content region) if you need a different value, or use `slot="before-content"` / `slot="after-content"` for sections that need to escape the padding entirely. (Note: it is `--u-card-padding`, not `--u-card-content-padding`.)

package/skills/chips/SKILL.md

@@ -0,0 +1,95 @@
+---
+description: Use u-chip, u-chip-set (groups), and u-chip-field (chip input) — including toggle vs clickable semantics for selectors.
+---
+
+# Chips
+
+Three pieces:
+- `<u-chip>` — a compact element representing an attribute, filter, or action.
+- `<u-chip-set>` — groups chips with consistent spacing/wrapping.
+- `<u-chip-field>` — text field that renders each entered value as a chip.
+
+## Single chip
+
+```html
+<u-chip>Default</u-chip>
+
+<u-chip>
+  <span class="material-symbols-outlined" slot="leading-icon">label</span>
+  With icon
+</u-chip>
+
+<u-chip elevated>Elevated</u-chip>
+
+<u-chip removable (remove)="onRemove($event)">Removable</u-chip>
+```
+
+## Selection: `clickable` vs `toggle`
+
+This distinction matters and is easy to get wrong:
+
+- **`clickable`** — chip fires `click` and shows ripple/hover. Use for **radio-like** patterns: combine with `[selected]="x === value"` + `(click)="x = value"` so one is always selected.
+- **`toggle`** — chip flips its own `selected` state on click and emits `change`. Use for **independent boolean filters** where multiple can be on/off.
+
+Radio-like (one of several):
+
+```html
+<u-chip-set>
+  <u-chip clickable [selected]="format === 'short'" (click)="format = 'short'">
+    <span class="material-symbols-outlined" slot="icon-selected">done</span>
+    Short
+  </u-chip>
+  <u-chip clickable [selected]="format === 'long'" (click)="format = 'long'">
+    <span class="material-symbols-outlined" slot="icon-selected">done</span>
+    Long
+  </u-chip>
+</u-chip-set>
+```
+
+Independent filters:
+
+```html
+<u-chip-set>
+  <u-chip toggle [(selected)]="showImages">Images</u-chip>
+  <u-chip toggle [(selected)]="showVideos">Videos</u-chip>
+  <u-chip toggle [(selected)]="showAudio">Audio</u-chip>
+</u-chip-set>
+```
+
+A plain `<u-chip>` (no `clickable`, no `toggle`) is a static informational chip — no ripple, no hover.
+
+## `<u-chip-set>`
+
+Spaces and wraps chips for you. No props needed for the basics. The chip's **`remove` event bubbles and composes**, so you can delegate on the set instead of wiring each chip:
+
+```ts
+chipSet.addEventListener('remove', (e) => {
+  const chip = e.target;            // the <u-chip> being removed
+  // e.preventDefault() here to keep the chip in the DOM (drive removal from your own state)
+});
+```
+
+## `<u-chip-field>` — chip input
+
+A text field where each typed value (separated by Enter or comma) becomes a removable chip:
+
+```html
+<u-chip-field label="Tags" #tags></u-chip-field>
+
+<script>
+  document.querySelector('u-chip-field').value = ['ts', 'lit'];
+  document.querySelector('u-chip-field').addEventListener('change', e => {
+    console.log(e.target.value); // string[]
+  });
+</script>
+```
+
+For object-valued chips (e.g. typeahead-driven), set `.value` to `Array<{ value, label }>` and the field renders the label.
+
+## Caveats
+
+- Always include `<span slot="icon-selected">done</span>` on `clickable`/`toggle` chips so users see the check when selected.
+- Don't use `toggle` for radio-like selectors — the user could deselect the only choice and the UI ends up in an invalid empty state.
+- `<u-chip-field>` is form-associated; pair with a `<form>` for native submit.
+- **The `remove` event bubbles and composes** — listen on the chip or delegate on the parent `<u-chip-set>`. The chip also **removes itself from the DOM** on remove unless you `preventDefault()` the event (do so when the chip's presence is driven by your own state).
+- **`<u-chip-field>` value:** reassign `.value = [...]` to re-render (mutating the array in place does not). Use `add(value, triggerChange?)` / `removeAt(index, triggerChange?)` to mutate, and set a `formatter` (`value => string`) for object items — otherwise objects render as `[object Object]`. The `change` event only fires on user add/remove (or when `triggerChange` is true).

package/skills/collapse/SKILL.md

@@ -0,0 +1,37 @@
+---
+description: Use u-collapse to animate an element between zero height and its natural content height.
+---
+
+# Collapse
+
+A primitive wrapper that animates its `max-height` between `0` and the slotted content's measured `scrollHeight`. Toggle the `open` attribute to play the animation. A `ResizeObserver` watches the content so dynamic children stay in sync.
+
+```html
+<u-button id="toggle">Expand</u-button>
+<u-collapse id="demo">
+  <p>Hidden until expanded.</p>
+</u-collapse>
+
+<script type="module">
+  const btn = document.getElementById('toggle');
+  const collapse = document.getElementById('demo');
+  btn.addEventListener('click', () => { collapse.open = !collapse.open; });
+</script>
+```
+
+Compose with other surfaces:
+
+```html
+<u-card variant="outlined" style="padding: 1rem;">
+  <u-button variant="text" onclick="this.nextElementSibling.open = !this.nextElementSibling.open">More</u-button>
+  <u-collapse>
+    <div style="padding-top: .5rem;">Reveal-on-demand content.</div>
+  </u-collapse>
+</u-card>
+```
+
+## Caveats
+
+- The component measures `scrollHeight` via `ResizeObserver`. The headless `mcp__Claude_Preview__*` environment does NOT fire `ResizeObserver` — verify the animation in a real browser.
+- `u-collapse` does not own a button or trigger — it's a pure container. Pair it with whatever toggle UI fits.
+- For a header + chevron + ripple combo, use [[expansion-panel]] instead.