@adia-ai/web-components 0.6.32 → 0.6.34

package/components/combobox/combobox.yaml

@@ -0,0 +1,369 @@
+# Hand-authored — SPEC-036 (2026-05-24).
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UICombobox
+tag: combobox-ui
+status: stable
+component: Combobox
+category: input
+version: 1
+description: |
+  Typeahead-filterable single-select primitive — the constrained-choice
+  combobox per WAI-APG "Combobox With List Autocomplete (manual
+  selection)". The committed value MUST come from the options list
+  unless `[free-text]` is set. Distinct from `<select-ui searchable>`
+  (button-first dropdown) and `<autocomplete-input-ui>` (free-form).
+  Form-bearing via UIFormElement: `[name]`, `[value]`, `[required]`,
+  `[disabled]`, fires `change`. Options via native `<option>` /
+  `<optgroup>` children OR programmatic `.options` array.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - icon-ui  # caret-down / x / magnifying-glass affixes (created in render)
+props:
+  name:
+    description: Form control name for form data submission
+    type: string
+    default: ""
+  size:
+    description: >-
+      Sizing scale via universal `[size]` attribute system. Matches
+      Input + Select sizing tokens so a Combobox rendered alongside
+      either feels coherent in a form row.
+    type: string
+    default: md
+    enum: [sm, md, lg]
+    reflect: true
+  required:
+    description: Marks the field as required for form validation
+    type: boolean
+    default: false
+    reflect: true
+  disabled:
+    description: Disables interaction and dims the control
+    type: boolean
+    default: false
+    reflect: true
+  readonly:
+    description: Prevents selection changes while keeping the field focusable + popover-open allowed
+    type: boolean
+    default: false
+    reflect: true
+  error:
+    description: Validation error message
+    type: string
+    default: ""
+  hint:
+    description: |-
+      Caption text below the field; wires `aria-describedby` on the host
+      so screen readers announce it as a description.
+    type: string
+    default: ""
+  label:
+    description: |-
+      Inline label rendered above the field. Wrap with <field-ui> for
+      proper `<label for>` association in form-row compositions.
+    type: string
+    default: ""
+  placeholder:
+    description: Placeholder text in the input when value is empty
+    type: string
+    default: Select...
+  value:
+    description: >-
+      Currently selected option value. Must be a member of `options[].value`
+      unless `[free-text]` is set. With declarative <option> children,
+      a child carrying the native `selected` attribute sets the initial
+      value when this attribute is absent.
+    type: string
+    default: ""
+  options:
+    description: >-
+      Programmatic option list. Array of {value, label, disabled?, group?}
+      or grouped {label, options:[…]}. Alternative to declarative
+      <option> / <optgroup> children.
+    type: array
+    default: []
+  open:
+    description: Reflects popover open / closed state
+    type: boolean
+    default: false
+    reflect: true
+  free-text:
+    description: |-
+      Allow typed text not in the options list. Blurs the distinction
+      with <autocomplete-input-ui>; prefer the dedicated primitive
+      unless the value model truly needs both modes (tag-with-suggestions,
+      email-with-recent-recipients).
+    type: boolean
+    default: false
+    reflect: true
+  creatable:
+    description: |-
+      Implies `[free-text]`; on Enter with unmatched typed text fires a
+      `create` event with detail.value so the consumer can run a
+      backend create-then-refresh-options flow.
+    type: boolean
+    default: false
+    reflect: true
+  clearable:
+    description: Renders an `x` clear button when value is set
+    type: boolean
+    default: false
+    reflect: true
+  filter-mode:
+    description: Client-side filter algorithm.
+    type: string
+    default: substring
+    enum: [substring, prefix, fuzzy]
+    reflect: true
+  loading:
+    description: Shows a loading spinner inside the popover; consumer drives async fetch
+    type: boolean
+    default: false
+    reflect: true
+  max-options:
+    description: Cap on rendered options. Overflow shows a "scroll for more" hint
+    type: number
+    default: 100
+    reflect: true
+  highlight-match:
+    description: Wraps the matched substring in `<mark>` inside option labels
+    type: boolean
+    default: true
+    reflect: true
+events:
+  input:
+    description: Fired on each keystroke (filter typing); not a commit. Detail carries the typed query.
+    detail:
+      value:
+        type: string
+        description: Current input text (the user's typed query).
+      query:
+        type: string
+        description: Lowercased filter query.
+  change:
+    description: |-
+      Fired when value is committed — option clicked, Enter on active
+      option, or programmatic `.value =`. Detail.option resolves to the
+      matching `{label,value,...}` or null in free-text/cleared paths.
+    detail:
+      value:
+        type: string
+        description: Committed value.
+      option:
+        type: object
+        description: Resolved option object or null when free-text / cleared.
+      source:
+        type: string
+        description: One of `click` / `keyboard` / `programmatic`.
+  create:
+    description: |-
+      Fired when `[creatable]` is set and the user presses Enter on
+      typed text that doesn't match any option. Consumer wires this to
+      a backend create flow and then refreshes `.options`.
+    detail:
+      value:
+        type: string
+        description: The typed text the user is trying to create.
+  open:
+    description: Popover opened.
+    detail:
+      trigger:
+        type: string
+        description: One of `click` / `keyboard` / `typing`.
+  close:
+    description: Popover closed.
+    detail:
+      reason:
+        type: string
+        description: One of `escape` / `outside` / `select` / `blur`.
+  invalid:
+    description: |-
+      Fired when `[free-text]` is false and the user presses Enter on
+      typed text that doesn't match any option. The value is NOT
+      committed; the input is restored to the last committed value.
+    detail:
+      query:
+        type: string
+        description: The unmatched typed text.
+slots:
+  default:
+    description: Native <option> / <optgroup> children for declarative authoring
+  empty:
+    description: Custom no-matches content (defaults to "No matches")
+  loading:
+    description: Custom loading content (defaults to a spinner)
+  footer:
+    description: Footer area inside the popover (e.g. "Press Enter to create…" affordance)
+  prefix:
+    description: Leading icon / element inside the input chrome
+  suffix:
+    description: Trailing icon / element (defaults to `caret-down`)
+states:
+  - name: idle
+    description: Closed; not focused.
+  - name: focused
+    description: Input focused; popover closed.
+    attribute: ":focus-within"
+  - name: open
+    description: Popover visible; filtered options listed.
+    attribute: open
+  - name: loading
+    description: Spinner shown; options stale (consumer-driven async fetch).
+    attribute: loading
+  - name: disabled
+    description: Non-interactive; dimmed.
+    attribute: disabled
+  - name: readonly
+    description: Focusable + popover-open allowed; commits blocked.
+    attribute: readonly
+traits: []
+tokens:
+  --combobox-bg:
+    description: Input background color
+  --combobox-fg:
+    description: Input text color
+  --combobox-radius:
+    description: Input border radius
+  --combobox-popover-bg:
+    description: Popover background color
+  --combobox-popover-border:
+    description: Popover border color
+  --combobox-popover-radius:
+    description: Popover border radius
+  --combobox-popover-shadow:
+    description: Popover elevation shadow
+  --combobox-option-bg-active:
+    description: Background for the currently active (arrow-navigated) option
+  --combobox-option-fg-active:
+    description: Foreground for the currently active option
+  --combobox-option-bg-selected:
+    description: Background for the currently committed option
+  --combobox-match-bg:
+    description: Background for `<mark>` spans that highlight matched substrings
+requiredIcons:
+  - caret-down
+  - x-circle
+  - check
+a2ui:
+  rules:
+    - >-
+      Use <combobox-ui> for typeahead-filterable single-select with
+      a constrained-choice value model. `value` MUST be one of
+      `options[].value` unless `[free-text]` is set. For ≤ 4 options,
+      use <segmented-ui> or <radio-ui> instead.
+    - >-
+      For free-form text entry with suggestions, use
+      <autocomplete-input-ui> (SPEC-035) — combobox is constrained-choice.
+      For button-first dropdowns where the trigger should be closed by
+      default, use <select-ui searchable>.
+    - >-
+      Compose options via native <option> / <optgroup> children, OR set
+      `.options` programmatically as an array of
+      `{value, label, disabled?}` (grouped form: `{label, options:[…]}`).
+      Setting `value` to a string not in `options` is invalid mid-state
+      (free-text=false) and the validator should reject it.
+    - >-
+      `[creatable]` implies `[free-text]` and adds the "Create '{value}'"
+      footer affordance + `create` event. Consumer wires the create
+      event to a backend flow.
+    - >-
+      Multi-select goes through <multi-select-ui> (SPEC-040), not
+      combobox. Combobox is single-select.
+anti_patterns:
+  - wrong: |
+      {"component": "Combobox", "value": "xx", "options": [{"value": "us", "label": "United States"}]}
+    why: |
+      `value` is "xx" but only "us" is in options. With free-text:false (default), this is an invalid
+      mid-state — set value: "us" or add an option with value: "xx".
+    fix: |
+      {"component": "Combobox", "value": "us", "options": [{"value": "us", "label": "United States"}]}
+  - wrong: |
+      {"component": "Combobox", "options": [{"value": "a", "label": "A"}, {"value": "b", "label": "B"}]}
+    why: |
+      Only 2 options. Combobox is overkill — use SegmentedControl or Radio.
+    fix: |
+      {"component": "SegmentedControl", "options": [{"value": "a", "label": "A"}, {"value": "b", "label": "B"}]}
+  - wrong: |
+      {"component": "Combobox", "multiple": true, "options": [...]}
+    why: |
+      Combobox is single-select. Multi-select goes through MultiSelect.
+    fix: |
+      {"component": "MultiSelect", "options": [...]}
+examples:
+  - name: country-picker
+    description: Country picker — canonical declarative <option> children inside a <field-ui>.
+    a2ui: >-
+      [
+        {"id": "root", "component": "Card", "children": ["sec"]},
+        {"id": "sec", "component": "Section", "children": ["country"]},
+        {
+          "id": "country",
+          "component": "Combobox",
+          "name": "country",
+          "label": "Country",
+          "placeholder": "Select country…",
+          "options": [
+            {"value": "us", "label": "United States"},
+            {"value": "gb", "label": "United Kingdom"},
+            {"value": "de", "label": "Germany"},
+            {"value": "fr", "label": "France"},
+            {"value": "es", "label": "Spain"}
+          ],
+          "value": "us"
+        }
+      ]
+  - name: creatable-tag-picker
+    description: Tag picker with create-new affordance — fires `create` event on unmatched Enter.
+    a2ui: >-
+      [
+        {"id": "root", "component": "Card", "children": ["sec"]},
+        {"id": "sec", "component": "Section", "children": ["tag"]},
+        {
+          "id": "tag",
+          "component": "Combobox",
+          "name": "tag",
+          "label": "Tag",
+          "creatable": true,
+          "placeholder": "Pick or create a tag…",
+          "options": [
+            {"value": "bug", "label": "bug"},
+            {"value": "feature", "label": "feature"},
+            {"value": "chore", "label": "chore"}
+          ]
+        }
+      ]
+keywords:
+  - combobox
+  - autocomplete
+  - typeahead
+  - select
+  - filter
+  - picker
+  - country-picker
+  - timezone-picker
+  - member-picker
+synonyms:
+  autocomplete:
+    - combobox
+    - typeahead
+    - suggest
+  combobox:
+    - autocomplete
+    - typeahead
+    - filter
+    - picker
+  typeahead:
+    - combobox
+    - autocomplete
+    - search
+  picker:
+    - combobox
+    - select
+    - dropdown
+related:
+  - select
+  - search
+  - input
+  - field

package/components/command/command.css

@@ -4,85 +4,85 @@
        No default width or height — the host pattern (dialog, popover,
        app-shell search slot, etc.) is responsible for sizing the palette.
        This keeps the component composable across overlay and inline use. */
-    --command-radius:             var(--a-radius-lg);
-    --command-px:                 var(--a-space-3);
-    --command-py:                 var(--a-space-3);
-    --command-gap:                var(--a-space-2);
-    --command-list-px:            var(--a-space-1);
-    --command-list-py:            var(--a-space-1);
-    --command-group-gap:          var(--a-space-1);
+    --command-radius-default:             var(--a-radius-lg);
+    --command-px-default:                 var(--a-space-3);
+    --command-py-default:                 var(--a-space-3);
+    --command-gap-default:                var(--a-space-2);
+    --command-list-px-default:            var(--a-space-1);
+    --command-list-py-default:            var(--a-space-1);
+    --command-group-gap-default:          var(--a-space-1);
 
     /* ── Colors ── */
-    --command-bg:                 var(--a-bg-subtle);
-    --command-fg:                 var(--a-fg);
-    --command-fg-muted:           var(--a-fg-muted);
-    --command-border:             var(--a-border-subtle);
+    --command-bg-default:                 var(--a-bg-subtle);
+    --command-fg-default:                 var(--a-fg);
+    --command-fg-muted-default:           var(--a-fg-muted);
+    --command-border-default:             var(--a-border-subtle);
 
     /* ── Elevation ── */
-    --command-shadow:             var(--a-shadow-lg);
+    --command-shadow-default:             var(--a-shadow-lg);
 
     /* ── Typography ── */
-    --command-font-size:          var(--a-ui-size);
-    --command-input-font-size:    var(--a-body-size);
+    --command-font-size-default:          var(--a-ui-size);
+    --command-input-font-size-default:    var(--a-body-size);
 
     /* ── Transition ── */
-    --command-duration:           var(--a-duration-fast);
-    --command-easing:             var(--a-easing);
+    --command-duration-default:           var(--a-duration-fast);
+    --command-easing-default:             var(--a-easing);
 
     /* ── Item ── */
-    --command-item-height:        var(--a-size);
-    --command-item-radius:        var(--a-radius-md);
-    --command-item-px:            var(--a-space-2);
-    --command-item-py:            var(--a-space-2);
-    --command-item-fg:            var(--a-fg-subtle);
-    --command-item-fg-hover:      var(--a-fg-hover);
-    --command-item-bg-hover:      var(--a-bg-hover);
-    --command-item-fg-disabled:   var(--a-ui-text-disabled);
+    --command-item-height-default:        var(--a-size);
+    --command-item-radius-default:        var(--a-radius-md);
+    --command-item-px-default:            var(--a-space-2);
+    --command-item-py-default:            var(--a-space-2);
+    --command-item-fg-default:            var(--a-fg-subtle);
+    --command-item-fg-hover-default:      var(--a-fg-hover);
+    --command-item-bg-hover-default:      var(--a-bg-hover);
+    --command-item-fg-disabled-default:   var(--a-ui-text-disabled);
 
     /* ── Shortcut ── */
-    --command-shortcut-fg:        var(--a-fg-muted);
-    --command-shortcut-font-size: var(--a-ui-sm);
+    --command-shortcut-fg-default:        var(--a-fg-muted);
+    --command-shortcut-font-size-default: var(--a-ui-sm);
 
     /* ── Group label ── */
-    --command-group-fg:           var(--a-fg-muted);
-    --command-group-font-size:    var(--a-ui-sm);
-    --command-group-font-weight:  var(--a-weight-medium);
-    --command-group-label-px:     var(--a-space-2);
-    --command-group-label-py:     var(--a-space-2);
+    --command-group-fg-default:           var(--a-fg-muted);
+    --command-group-font-size-default:    var(--a-ui-sm);
+    --command-group-font-weight-default:  var(--a-weight-medium);
+    --command-group-label-px-default:     var(--a-space-2);
+    --command-group-label-py-default:     var(--a-space-2);
 
     /* ── Empty state ── */
-    --command-empty-fg:           var(--a-fg-muted);
+    --command-empty-fg-default:           var(--a-fg-muted);
 
     /* ── Header ── */
-    --command-header-px:          var(--a-space-4);
-    --command-header-py:          var(--a-space-4);
+    --command-header-px-default:          var(--a-space-4);
+    --command-header-py-default:          var(--a-space-4);
 
     /* ── Footer ── */
-    --command-footer-fg:          var(--a-fg-muted);
-    --command-footer-font-size:   var(--a-ui-sm);
-    --command-footer-px:          var(--command-px);
-    --command-footer-py:          var(--command-py);
+    --command-footer-fg-default:          var(--a-fg-muted);
+    --command-footer-font-size-default:   var(--a-ui-sm);
+    --command-footer-px-default:          var(--command-px, var(--command-px-default));
+    --command-footer-py-default:          var(--command-py, var(--command-py-default));
 
     /* ── Footer kbd ── */
-    --command-kbd-border:         var(--a-border-subtle);
-    --command-kbd-radius:         var(--a-radius-sm);
-    --command-kbd-bg:             var(--a-bg-muted);
-    --command-kbd-fg:             var(--a-fg-muted);
+    --command-kbd-border-default:         var(--a-border-subtle);
+    --command-kbd-radius-default:         var(--a-radius-sm);
+    --command-kbd-bg-default:             var(--a-bg-muted);
+    --command-kbd-fg-default:             var(--a-fg-muted);
 
     /* ── Hint ── */
-    --command-hint-gap:           var(--a-space-0-5);
-    --command-hint-kbd-px:        var(--a-space-0-5);
+    --command-hint-gap-default:           var(--a-space-0-5);
+    --command-hint-kbd-px-default:        var(--a-space-0-5);
   }
 
   :scope {
     box-sizing: border-box;
     display: flex;
     flex-direction: column;
-    background: var(--command-bg);
-    border: 1px solid var(--command-border);
-    border-radius: var(--command-radius);
-    box-shadow: var(--command-shadow);
-    font-size: var(--command-font-size);
+    background: var(--command-bg, var(--command-bg-default));
+    border: 1px solid var(--command-border, var(--command-border-default));
+    border-radius: var(--command-radius, var(--command-radius-default));
+    box-shadow: var(--command-shadow, var(--command-shadow-default));
+    font-size: var(--command-font-size, var(--command-font-size-default));
     overflow: hidden;
   }
 
@@ -90,15 +90,15 @@
   & > header {
     display: flex;
     align-items: center;
-    gap: var(--command-gap);
-    padding: var(--command-header-py) var(--command-header-px);
-    border-bottom: 1px solid var(--command-border);
+    gap: var(--command-gap, var(--command-gap-default));
+    padding: var(--command-header-py, var(--command-header-py-default)) var(--command-header-px, var(--command-header-px-default));
+    border-bottom: 1px solid var(--command-border, var(--command-border-default));
     flex-shrink: 0;
   }
 
   & > header icon-ui {
     flex-shrink: 0;
-    color: var(--command-fg-muted);
+    color: var(--command-fg-muted, var(--command-fg-muted-default));
     --a-icon-size: 1rem;
   }
 
@@ -108,15 +108,15 @@
     border: none;
     outline: none;
     background: transparent;
-    color: var(--command-fg);
+    color: var(--command-fg, var(--command-fg-default));
     font-family: inherit;
-    font-size: var(--command-input-font-size);
+    font-size: var(--command-input-font-size, var(--command-input-font-size-default));
     line-height: 1.4;
     padding: 0;
   }
 
   & > header input::placeholder {
-    color: var(--command-fg-muted);
+    color: var(--command-fg-muted, var(--command-fg-muted-default));
   }
 
   /* Suppress focus ring on the input — the palette itself is the focused surface */
@@ -133,7 +133,7 @@
   [slot="list"] {
     flex: 1;
     overflow-y: auto;
-    padding: var(--command-list-py) var(--command-list-px);
+    padding: var(--command-list-py, var(--command-list-py-default)) var(--command-list-px, var(--command-list-px-default));
     scrollbar-width: none;
   }
 
@@ -143,22 +143,22 @@
   [role="option"] {
     display: flex;
     align-items: center;
-    gap: var(--command-gap);
-    min-height: var(--command-item-height);
-    padding: 0 var(--command-item-px);
-    border-radius: var(--command-item-radius);
-    color: var(--command-item-fg);
+    gap: var(--command-gap, var(--command-gap-default));
+    min-height: var(--command-item-height, var(--command-item-height-default));
+    padding: 0 var(--command-item-px, var(--command-item-px-default));
+    border-radius: var(--command-item-radius, var(--command-item-radius-default));
+    color: var(--command-item-fg, var(--command-item-fg-default));
     cursor: pointer;
     white-space: nowrap;
     transition:
-      background var(--command-duration) var(--command-easing),
-      color var(--command-duration) var(--command-easing);
+      background var(--command-duration, var(--command-duration-default)) var(--command-easing, var(--command-easing-default)),
+      color var(--command-duration, var(--command-duration-default)) var(--command-easing, var(--command-easing-default));
   }
 
   [role="option"] icon-ui {
-    --a-icon-size: var(--command-font-size);
+    --a-icon-size: var(--command-font-size, var(--command-font-size-default));
     flex-shrink: 0;
-    color: var(--command-fg-muted);
+    color: var(--command-fg-muted, var(--command-fg-muted-default));
   }
 
   [role="option"] [data-text] {
@@ -169,8 +169,8 @@
   }
 
   [role="option"] [data-shortcut] {
-    color: var(--command-shortcut-fg);
-    font-size: var(--command-shortcut-font-size);
+    color: var(--command-shortcut-fg, var(--command-shortcut-fg-default));
+    font-size: var(--command-shortcut-font-size, var(--command-shortcut-font-size-default));
     margin-inline-start: auto;
     flex-shrink: 0;
   }
@@ -178,32 +178,32 @@
   /* ── State: hover / active ── */
   [role="option"]:not([aria-disabled]):hover,
   [role="option"][data-active] {
-    background: var(--command-item-bg-hover);
-    color: var(--command-item-fg-hover);
+    background: var(--command-item-bg-hover, var(--command-item-bg-hover-default));
+    color: var(--command-item-fg-hover, var(--command-item-fg-hover-default));
   }
 
   [role="option"]:not([aria-disabled]):hover icon-ui,
   [role="option"][data-active] icon-ui {
-    color: var(--command-item-fg-hover);
+    color: var(--command-item-fg-hover, var(--command-item-fg-hover-default));
   }
 
   /* ── State: disabled ── */
   [role="option"][aria-disabled] {
-    color: var(--command-item-fg-disabled);
+    color: var(--command-item-fg-disabled, var(--command-item-fg-disabled-default));
     cursor: not-allowed;
     pointer-events: none;
   }
 
   /* ── Groups ── */
   [data-group] {
-    padding: var(--command-list-py) var(--command-list-px);
+    padding: var(--command-list-py, var(--command-list-py-default)) var(--command-list-px, var(--command-list-px-default));
   }
 
   [data-group-label] {
-    padding: var(--command-group-label-py) var(--command-group-label-px);
-    font-size: var(--command-group-font-size);
-    font-weight: var(--command-group-font-weight);
-    color: var(--command-group-fg);
+    padding: var(--command-group-label-py, var(--command-group-label-py-default)) var(--command-group-label-px, var(--command-group-label-px-default));
+    font-size: var(--command-group-font-size, var(--command-group-font-size-default));
+    font-weight: var(--command-group-font-weight, var(--command-group-font-weight-default));
+    color: var(--command-group-fg, var(--command-group-fg-default));
     text-transform: uppercase;
     letter-spacing: 0.05em;
     white-space: nowrap;
@@ -211,8 +211,8 @@
 
   /* ── Empty state ── */
   [data-empty] {
-    padding: var(--command-py) var(--command-px);
-    color: var(--command-empty-fg);
+    padding: var(--command-py, var(--command-py-default)) var(--command-px, var(--command-px-default));
+    color: var(--command-empty-fg, var(--command-empty-fg-default));
     text-align: center;
   }
 
@@ -220,18 +220,18 @@
   & > footer {
     display: flex;
     align-items: center;
-    gap: var(--command-px);
-    padding: var(--command-footer-py) var(--command-footer-px);
-    border-top: 1px solid var(--command-border);
-    font-size: var(--command-footer-font-size);
-    color: var(--command-footer-fg);
+    gap: var(--command-px, var(--command-px-default));
+    padding: var(--command-footer-py, var(--command-footer-py-default)) var(--command-footer-px, var(--command-footer-px-default));
+    border-top: 1px solid var(--command-border, var(--command-border-default));
+    font-size: var(--command-footer-font-size, var(--command-footer-font-size-default));
+    color: var(--command-footer-fg, var(--command-footer-fg-default));
     flex-shrink: 0;
   }
 
   [data-hint] {
     display: inline-flex;
     align-items: center;
-    gap: var(--command-hint-gap);
+    gap: var(--command-hint-gap, var(--command-hint-gap-default));
   }
 
   [data-hint] kbd {
@@ -239,13 +239,13 @@
     align-items: center;
     justify-content: center;
     min-width: 1.25em;
-    padding: 0 var(--command-hint-kbd-px);
-    border: 1px solid var(--command-kbd-border);
-    border-radius: var(--command-kbd-radius);
+    padding: 0 var(--command-hint-kbd-px, var(--command-hint-kbd-px-default));
+    border: 1px solid var(--command-kbd-border, var(--command-kbd-border-default));
+    border-radius: var(--command-kbd-radius, var(--command-kbd-radius-default));
     font-family: inherit;
     font-size: inherit;
     line-height: 1.6;
-    color: var(--command-kbd-fg);
-    background: var(--command-kbd-bg);
+    color: var(--command-kbd-fg, var(--command-kbd-fg-default));
+    background: var(--command-kbd-bg, var(--command-kbd-bg-default));
   }
 }