@livestorm/ui-vue 3.0.0 → 4.0.0

package/src/components/UiTag/UiTag.vue

@@ -16,7 +16,10 @@
     </span>
 
     <!-- Label content -->
-    <span class="ui-tag-label">
+    <span
+      v-if="$slots.default || label"
+      class="ui-tag-label"
+    >
       <slot>{{ label }}</slot>
     </span>
   </span>
@@ -25,30 +28,9 @@
 <script setup lang="ts">
 import { computed } from 'vue'
 
-interface Props {
-  /**
-   * Size of the tag
-   */
-  size?: 'xxs' | 'xs' | 'sm' | 'md'
-  /**
-   * Color variant of the tag
-   */
-  color?: 'primary' | 'neutral' | 'danger' | 'warning' | 'success' | 'neutral-invert'
-  /**
-   * Variant of the tag
-   */
-  variant?: 'light' | 'strong'
-  /**
-   * Label text for the tag
-   */
-  label?: string
-  /**
-   * Whether to show hover effects
-   */
-  withHoverEffect?: boolean
-}
+import type { UiTagProps } from './UiTag.types'
 
-const props = withDefaults(defineProps<Props>(), {
+const props = withDefaults(defineProps<UiTagProps>(), {
   size: 'md',
   color: 'neutral',
   variant: 'light',
@@ -61,7 +43,7 @@ const tagClasses = computed(() => {
     'ui-tag',
     'inline-flex',
     'items-center',
-    'rounded-3xl',
+    'rounded-full',
     'transition-colors',
     'duration-150',
     'ease-in-out',
@@ -71,36 +53,36 @@ const tagClasses = computed(() => {
   // Size classes
   const sizeClasses = {
     xxs: ['px-1.5', 'gap-1', 'text-content-badges-bold-md', 'h-4'],
-    xs: ['px-1.5', 'py-1', 'gap-1', 'text-content-badges-bold-md', 'h-6'],
-    sm: ['px-2', 'py-1', 'gap-1', 'text-content-text-md-bold', 'h-8'],
-    md: ['px-3', 'py-1', 'gap-2', 'text-content-text-md-bold', 'h-10'],
+    xs: ['px-2', 'py-1', 'gap-1', 'text-content-badges-bold-md', 'h-6'],
+    sm: ['px-3', 'py-1', 'gap-1', 'text-content-text-md-bold', 'h-8'],
+    md: ['px-4', 'py-1', 'gap-2', 'text-content-text-md-bold', 'h-10'],
   }
 
   // Color and variant classes
   const colorVariantClasses = {
     primary: {
-      light: ['bg-actions-primary-active-overlay', 'text-actions-primary-idle'],
-      strong: ['bg-actions-primary-idle-alpha-strong', 'text-actions-neutral-invert-idle'],
+      light: ['bg-actions-primary-active-overlay', 'text-text-primary-title'],
+      strong: ['bg-actions-primary-idle-alpha-strong', 'text-text-neutral-invert-base'],
     },
     neutral: {
-      light: ['bg-actions-neutral-active-overlay', 'text-actions-neutral-idle'],
-      strong: ['bg-actions-neutral-idle-alpha-strong', 'text-actions-neutral-invert-idle'],
+      light: ['bg-actions-neutral-active-overlay', 'text-text-neutral-base'],
+      strong: ['bg-actions-neutral-idle-alpha-strong', 'text-text-neutral-invert-base'],
     },
     danger: {
-      light: ['bg-actions-danger-active-overlay', 'text-actions-danger-idle'],
-      strong: ['bg-actions-danger-idle-alpha-strong', 'text-actions-neutral-invert-idle'],
+      light: ['bg-actions-danger-active-overlay', 'text-text-danger-base'],
+      strong: ['bg-actions-danger-idle-alpha-strong', 'text-text-neutral-invert-base'],
     },
     warning: {
-      light: ['bg-actions-warning-active-overlay', 'text-actions-warning-idle'],
-      strong: ['bg-actions-warning-idle-alpha-strong', 'text-actions-neutral-invert-idle'],
+      light: ['bg-actions-warning-active-overlay', 'text-text-warning-base'],
+      strong: ['bg-actions-warning-idle-alpha-strong', 'text-text-neutral-invert-base'],
     },
     success: {
-      light: ['bg-actions-success-active-overlay', 'text-actions-success-idle'],
-      strong: ['bg-actions-success-idle-alpha-strong', 'text-actions-neutral-invert-idle'],
+      light: ['bg-actions-success-active-overlay', 'text-text-success-base'],
+      strong: ['bg-actions-success-idle-alpha-strong', 'text-text-neutral-invert-base'],
     },
     'neutral-invert': {
-      light: ['bg-actions-neutral-invert-active-overlay', 'text-actions-neutral-invert-idle'],
-      strong: ['bg-actions-neutral-invert-idle-alpha-strong', 'text-actions-neutral-idle'],
+      light: ['bg-actions-neutral-invert-active-overlay', 'text-text-neutral-invert-base'],
+      strong: ['bg-actions-neutral-invert-idle-alpha-strong', 'text-text-neutral-base'],
     },
   }
 
@@ -129,7 +111,7 @@ const iconClasses = computed(() => {
 
 /* Focus ring */
 .ui-tag:focus-visible {
-  @apply ring-2 ring-inset ring-focus-ring;
+  @apply focus-ring;
 }
 
 /* Hover states - only apply when withHoverEffect is true */
@@ -182,6 +164,6 @@ const iconClasses = computed(() => {
 }
 
 .ui-tag-label {
-  @apply flex-1;
+  @apply flex-1 truncate;
 }
 </style>

package/src/components/UiTag/index.ts

@@ -0,0 +1,2 @@
+export { default } from './UiTag.vue'
+export type { UiTagColor, UiTagProps, UiTagSize, UiTagVariant } from './UiTag.types'

package/src/components/UiTextField/UiTextField.vue

@@ -2,6 +2,8 @@
 import { computed, nextTick, ref, useSlots } from 'vue'
 import UiFieldWrapper from '../UiFieldWrapper/UiFieldWrapper.vue'
 import { useIconSize } from '../../composables/useIconSize'
+import { useControlShape } from '../../composables/useControlShape'
+import { useFieldFocusEvents } from '../../composables/useFieldFocusEvents'
 import type { TextFieldSize } from './types'
 
 interface UiTextFieldProps {
@@ -9,6 +11,10 @@ interface UiTextFieldProps {
   modelValue?: string
   placeholder?: string
   disabled?: boolean
+  /**
+   * The value can be selected and copied but not edited
+   */
+  readonly?: boolean
   loading?: boolean
   error?: boolean
   label?: string
@@ -28,6 +34,7 @@ interface UiTextFieldProps {
 const props = withDefaults(defineProps<UiTextFieldProps>(), {
   size: 'md',
   disabled: false,
+  readonly: false,
   loading: false,
   error: false,
   required: false,
@@ -49,22 +56,17 @@ const emit = defineEmits<{
 
 const slots = useSlots()
 const textFieldRef = ref<HTMLInputElement | null>(null)
-const isFocused = ref(false)
+const { isFocused, handleFocus, handleBlur, handleKeydown, handleKeyup } = useFieldFocusEvents(emit)
 
 const iconSizeClass = useIconSize(() => props.size)
+const shape = useControlShape('field', () => props.size)
 
 const hasLeftIcon = computed(() => !!slots.icon)
 const hasRightAction = computed(() => !!slots['right-action'])
-const showClearButton = computed(() => props.clearable && !!props.modelValue && !props.disabled && !props.loading)
+const showClearButton = computed(() => props.clearable && !!props.modelValue && !props.disabled && !props.readonly && !props.loading)
 
 const textFieldClasses = computed(() => {
-  const classes = ['ui-text-field-field']
-
-  // Size classes
-  if (props.size === 'sm') classes.push('h-8 text-content-text-md-regular')
-  if (props.size === 'md') classes.push('h-10 text-content-text-md-regular')
-  if (props.size === 'lg') classes.push('h-12 text-content-text-md-regular')
-  if (props.size === 'xl') classes.push('h-16 text-content-text-md-regular')
+  const classes = ['ui-text-field-field', shape.value.radius, shape.value.height, 'text-content-text-md-regular']
 
   // State classes
   if (props.error) {
@@ -90,24 +92,6 @@ function handleClear () {
   textFieldRef.value?.focus()
 }
 
-function handleFocus (event: FocusEvent) {
-  isFocused.value = true
-  emit('focus', event)
-}
-
-function handleBlur (event: FocusEvent) {
-  isFocused.value = false
-  emit('blur', event)
-}
-
-function handleKeydown (event: KeyboardEvent) {
-  emit('keydown', event)
-}
-
-function handleKeyup (event: KeyboardEvent) {
-  emit('keyup', event)
-}
-
 defineExpose({
   focus: () => textFieldRef.value?.focus(),
   blur: () => textFieldRef.value?.blur(),
@@ -164,11 +148,12 @@ defineExpose({
           :value="modelValue"
           :placeholder="placeholder"
           :disabled="disabled || loading"
+          :readonly="readonly"
           :autocomplete="autocomplete"
           :aria-label="ariaLabel"
           :aria-invalid="error || undefined"
           :aria-describedby="ariaDescribedby || ((helperMessage || errorMessage) ? `${fieldId}-message` : undefined)"
-          class="ui-text-field-element text-text-neutral-base placeholder:text-text-neutral-tertiary"
+          class="ui-text-field-element text-text-neutral-base placeholder:text-control-placeholder"
           @input="handleInput"
           @focus="handleFocus"
           @blur="handleBlur"
@@ -217,12 +202,12 @@ defineExpose({
 @reference '@livestorm/ui-tokens/output/supernova/index.css';
 
 .ui-text-field-field {
-  @apply relative flex items-center gap-1.5 w-full rounded-lg border transition-all;
+  @apply relative flex items-center gap-1.5 w-full border transition-all;
   @apply pl-3 pr-0;
 }
 
 .ui-text-field-field--default {
-  @apply bg-actions-neutral-idle-alpha-light border-borders-neutral-strong;
+  @apply bg-control-field-bg border-control-field-border;
 
   &:not(.ui-text-field-field--disabled) {
     &:hover .ui-text-field-overlay {
@@ -230,7 +215,7 @@ defineExpose({
     }
 
     &.ui-text-field-field--focused {
-      @apply border-actions-primary-idle-alpha-strong ring-1 ring-inset ring-focus-ring;
+      @apply bg-control-field-bg-focus focus-ring;
 
       .ui-text-field-overlay {
         background: transparent;
@@ -240,7 +225,7 @@ defineExpose({
 }
 
 .ui-text-field-field--error {
-  @apply bg-actions-danger-idle-alpha-light border-borders-danger-strong;
+  @apply bg-actions-danger-idle-alpha-light border-control-error-border;
 
   &:not(.ui-text-field-field--disabled) {
     &:hover .ui-text-field-overlay {
@@ -248,7 +233,7 @@ defineExpose({
     }
 
     &.ui-text-field-field--focused {
-      @apply border-borders-danger-strong ring-1 ring-inset ring-borders-danger-strong;
+      @apply focus-ring;
 
       .ui-text-field-overlay {
         background: transparent;
@@ -262,7 +247,7 @@ defineExpose({
 }
 
 .ui-text-field-overlay {
-  @apply absolute inset-0 rounded-lg pointer-events-none transition-colors;
+  @apply absolute -inset-px rounded-[inherit] pointer-events-none transition-colors;
   z-index: 1;
 }
 
@@ -336,7 +321,7 @@ defineExpose({
 }
 
 .ui-text-field-actions {
-  @apply flex items-center justify-center px-3 h-full rounded-lg;
+  @apply flex items-center justify-center px-3 h-full rounded-[inherit];
   position: relative;
   z-index: 2;
 }
@@ -359,7 +344,7 @@ defineExpose({
   padding: 0;
 
   &:focus-visible {
-    @apply ring-2 ring-borders-neutral-strong rounded;
+    @apply focus-ring rounded-row;
   }
 }
 </style>

package/src/components/UiTooltip/UiTooltipContent.vue

@@ -63,7 +63,7 @@ const maxWidthClass = computed(() => {
       v-bind="{ ...forwarded, ...$attrs }"
       :data-colors-semantic="props.colorsSemantic"
       :class="[
-        'ui-tooltip-content py-1.5 px-3 bg-surface-neutral-invert-bg-alpha text-text-neutral-invert-base text-content-text-md-regular rounded-md text-center z-50 shadow-shadows-drop-shadow-lg',
+        'ui-tooltip-content py-1.5 px-3 bg-surface-neutral-invert-bg-alpha text-text-neutral-invert-base text-content-text-md-regular rounded-row text-center z-overlay shadow-shadows-drop-shadow-lg',
         'data-[state=delayed-open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=delayed-open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=delayed-open]:zoom-in-95',
         maxWidthClass
       ]"

package/src/components/UiTooltip/UiTooltipProvider.vue

@@ -5,6 +5,9 @@ import { TooltipProvider } from 'reka-ui'
 withDefaults(defineProps<TooltipProviderProps>(), {
   delayDuration: 700,
   skipDelayDuration: 300,
+  // A tap is how touch opens a tooltip, and the click that follows it would
+  // close it again straight away unless the trigger stops closing on click.
+  disableClosingTrigger: true,
 })
 </script>
 

package/src/components/UiTooltip/UiTooltipTrigger.vue

@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import type { TooltipTriggerProps } from 'reka-ui'
-import { TooltipTrigger, useForwardProps } from 'reka-ui'
+import { TooltipTrigger, injectTooltipRootContext, useForwardProps } from 'reka-ui'
 
 const props = defineProps<TooltipTriggerProps>()
 
@@ -8,11 +8,26 @@ const props = defineProps<TooltipTriggerProps>()
 // consumed here and never reach TooltipTrigger, so `as-child` would be ignored
 // and reka would wrap the slot in its own <button>.
 const forwarded = useForwardProps(props)
+
+const rootContext = injectTooltipRootContext()
+
+// this is to open the tooltip on touch devices, which can't hover
+// Bound to `pointerup` so a scroll that starts on the trigger does not open it.
+function toggleOnTouch(event: PointerEvent) {
+  if (event.pointerType !== 'touch' || rootContext.disabled.value) return
+
+  if (rootContext.open.value) {
+    rootContext.onClose()
+  } else {
+    rootContext.onOpen()
+  }
+}
 </script>
 
 <template>
   <TooltipTrigger
     v-bind="{ ...forwarded, ...$attrs }"
+    @pointerup="toggleOnTouch"
   >
     <slot />
   </TooltipTrigger>

package/src/composables/storedThemingApplies.ts

@@ -0,0 +1,19 @@
+/**
+ * Does stored theming output apply?
+ *
+ * The theme picker (and its playground) is the only writer of deliberate
+ * theming choices: the stored modes in `themeAndMode` and the seed token map
+ * in `customThemeTokens`. A stored value alone is not a choice signal —
+ * `useStorage` persists the light/light defaults for every visitor — so
+ * stored theming is consumed only where the picker exists, and every surface
+ * ships its own defaults otherwise (the dashboard light/light, the room
+ * dark shell over light content).
+ *
+ * This is the single place that rule lives. `ls-internal-theming` itself
+ * gates the picker's visibility; it does not gate any rendering path.
+ * When a real user-facing theming choice ships (workspace setting, OS
+ * follow), its mechanism replaces this predicate.
+ */
+export function storedThemingApplies (): boolean {
+  return typeof localStorage !== 'undefined' && localStorage.getItem('ls-internal-theming') === 'true'
+}

package/src/composables/useButtonStyles.ts

@@ -1,7 +1,7 @@
 import { computed, type MaybeRefOrGetter, toValue } from 'vue'
 
 // Single source of truth for the action-button visual language (background,
-// text, border, hover/active overlays) keyed by `variant` × `color`. Both
+// text, hover/active overlays) keyed by `variant` × `color`. Both
 // `UiButton` and `UiDropdownTrigger` consume this so a trigger styled as a
 // tertiary button stays pixel-identical to a real `UiButton` without copying
 // token names around.
@@ -81,16 +81,6 @@ const TEXT_MAP: Record<ButtonVariant, Record<ButtonColor, string>> = {
   },
 }
 
-// Border — only `secondary` draws one.
-const BORDER_MAP: Record<ButtonColor, string[]> = {
-  'primary': ['border', 'border-borders-primary-strong'],
-  'neutral': ['border', 'border-borders-neutral-strong'],
-  'neutral-invert': ['border', 'border-borders-neutral-invert-strong'],
-  'success': ['border', 'border-borders-success-strong'],
-  'warning': ['border', 'border-borders-warning-strong'],
-  'error': ['border', 'border-borders-danger-strong'],
-}
-
 // Hover overlay tints keyed by `variant-color`, in both the `group-hover:`
 // flavor (layered button overlay element) and the `before:` flavor
 // (single-element trigger pseudo). Kept as literals for Tailwind extraction.
@@ -205,9 +195,14 @@ export function useButtonStyles(options: UseButtonStylesOptions) {
   /** Text color class for the current variant × color. */
   const textClass = computed(() => TEXT_MAP[variant.value][color.value])
 
-  /** Border classes — only `secondary` paints a border. */
+  /** Soft border of the secondary fill layer; transparent except in the accessible look. */
   const borderClasses = computed(() =>
-    variant.value === 'secondary' ? (BORDER_MAP[color.value] ?? []) : [],
+    variant.value === 'secondary' ? ['border', 'border-control-soft-border'] : [],
+  )
+
+  /** Tertiary labels are underlined in the accessible look. */
+  const decorationClass = computed(() =>
+    variant.value === 'tertiary' ? '[text-decoration-line:var(--control-link-decoration)] underline-offset-3' : '',
   )
 
   /**
@@ -236,6 +231,7 @@ export function useButtonStyles(options: UseButtonStylesOptions) {
     bgClass,
     textClass,
     borderClasses,
+    decorationClass,
     overlayClasses,
     beforeHoverOverlayClass,
   }

package/src/composables/useChoiceboxSurface.ts

@@ -0,0 +1,36 @@
+import { computed, type ComputedRef, type MaybeRefOrGetter, toValue } from 'vue'
+import type { ChoiceControl } from '../components/UiChoice/types'
+
+interface ChoiceboxState {
+  control: ChoiceControl
+  selected: boolean
+  disabled: boolean
+  error?: boolean
+}
+
+// Only the row's own control rings the surface: a control in the content slot keeps its own focus
+const FOCUS_RING: Record<ChoiceControl, string> = {
+  radio: 'has-[[role=radio]:focus-visible]:focus-ring',
+  switch: 'has-[[role=switch]:focus-visible]:focus-ring',
+  checkbox: 'has-[[type=checkbox]:focus-visible]:focus-ring',
+}
+
+/** Border, fill, radius and focus ring of a UiChoice choicebox */
+export function useChoiceboxSurface (state: MaybeRefOrGetter<ChoiceboxState>): ComputedRef<string[]> {
+  return computed(() => {
+    const { control, selected, disabled, error } = toValue(state)
+    const classes = ['rounded-row border', FOCUS_RING[control]]
+
+    if (error) {
+      classes.push('bg-actions-danger-idle-alpha-light', selected ? 'border-actions-danger-idle' : 'border-control-error-border')
+    } else if (disabled) {
+      classes.push('bg-control-choice-bg-disabled border-control-choice-border-disabled')
+    } else if (selected) {
+      classes.push('bg-control-choice-selected-bg border-control-choice-selected-border hover:bg-control-choice-selected-bg-hover')
+    } else {
+      classes.push('bg-control-choice-bg border-control-choice-border hover:bg-control-choice-bg-hover hover:border-control-choice-border-hover')
+    }
+
+    return classes
+  })
+}

package/src/composables/useContentMode.ts

@@ -1,5 +1,6 @@
-import { computed, onMounted, ref, type Ref } from 'vue'
+import { computed, onMounted, onUnmounted, ref, type Ref } from 'vue'
 import useThemeAndModes from './useThemeAndModes'
+import { storedThemingApplies } from './storedThemingApplies'
 
 /**
  * Registers an element as a page "content" surface so the stored content mode
@@ -7,26 +8,29 @@ import useThemeAndModes from './useThemeAndModes'
  * behaviour `UiPage` gives its page content, without pulling in the full page
  * layout (and its `<main>`).
  *
- * The content historically forces light mode. That pin is only lifted when the
- * internal theming tooling is enabled, so the stored content mode can apply;
- * everyone else stays light regardless of what localStorage may hold.
+ * Content ships light. The stored content mode applies where the picker
+ * exists (see storedThemingApplies); everyone else gets the shipped default
+ * regardless of what localStorage may hold.
  *
- * The flag is read in onMounted, not at setup: setup also runs during SSR (no
- * localStorage), and server + client-hydration markup must be identical — the
- * pin lifts right after mount for the internal tooling instead.
+ * The predicate is read in onMounted, not at setup: setup also runs during
+ * SSR (no localStorage), and server + client-hydration markup must be
+ * identical — stored modes take over right after mount instead.
  *
  * @param element  Template ref of the content element to watch.
  * @param selector Unique key for the watch registry — one per logical surface
  *                 (e.g. `[data-name="ui-page-content"]`).
- * @returns `contentMode`, to bind to the element's `data-colors-semantic`, and
- *          `isInternalThemingEnabled` for any mode-dependent styling.
+ * @returns `contentMode`, to bind to the element's `data-colors-semantic`.
  */
 export function useContentMode (
   element: Ref<HTMLElement | undefined>,
   selector: string,
 ) {
-  const { addElementToWatch, currentContentMode } = useThemeAndModes()
-  const isInternalThemingEnabled = ref(false)
+  const { addElementToWatch, removeElementToWatch, currentContentMode } = useThemeAndModes()
+  const storedApplies = ref(false)
+
+  // Captured at registration: Vue has already nulled the template ref by the
+  // time onUnmounted runs, and unregistering needs the element it registered.
+  let registered: HTMLElement | undefined
 
   // Always resolve to a concrete mode, never undefined. useThemeAndModes also
   // sets this attribute imperatively; if the binding resolved to undefined,
@@ -34,20 +38,29 @@ export function useContentMode (
   // flag flip, and the content would silently inherit the *shell* mode from
   // <body> — reading as "content mode resets to dark on every navigation".
   const contentMode = computed(() => (
-    isInternalThemingEnabled.value ? currentContentMode.value : 'light'
+    storedApplies.value ? currentContentMode.value : 'light'
   ))
 
   onMounted(() => {
-    isInternalThemingEnabled.value = localStorage.getItem('ls-internal-theming') === 'true'
+    storedApplies.value = storedThemingApplies()
 
     if (!element.value) { return }
 
+    registered = element.value
     addElementToWatch('content', {
       selector,
-      element: element.value,
-      ...(isInternalThemingEnabled.value ? {} : { modeOverride: 'light' }),
+      element: registered,
+      ...(storedApplies.value ? {} : { modeOverride: 'light' }),
     })
   })
 
-  return { contentMode, isInternalThemingEnabled }
+  // The registry outlives this component, so a surface that unmounts without
+  // this stays referenced and keeps being written to.
+  onUnmounted(() => {
+    if (registered) {
+      removeElementToWatch('content', { selector, element: registered })
+    }
+  })
+
+  return { contentMode }
 }

package/src/composables/useControlModes.ts

@@ -0,0 +1,11 @@
+/**
+ * Applies the accessibility look on the app root: `data-accessibility="on"`.
+ * The control tokens read this attribute.
+ */
+export function applyControlModes (
+  { accessibility }: { accessibility: boolean },
+  root: HTMLElement = document.body,
+) {
+  if (accessibility) root.setAttribute('data-accessibility', 'on')
+  else root.removeAttribute('data-accessibility')
+}

package/src/composables/useControlShape.ts

@@ -0,0 +1,34 @@
+import { computed, type ComputedRef, type MaybeRefOrGetter, toValue } from 'vue'
+
+// NOTE: every class must be a complete literal string: Tailwind's static
+// extractor can't see interpolated class names.
+
+export type FieldSize = 'sm' | 'md' | 'lg' | 'xl'
+type ButtonSize = 'xs' | 'sm' | 'md' | 'lg'
+
+interface FieldShape { height: string, radius: string, chevron: string }
+
+const FIELD_SHAPES: Record<FieldSize, FieldShape> = {
+  sm: { height: 'h-field-sm', radius: 'rounded-field-sm', chevron: 'size-3.5' },
+  md: { height: 'h-field-md', radius: 'rounded-field-md', chevron: 'size-4' },
+  lg: { height: 'h-field-lg', radius: 'rounded-field-lg', chevron: 'size-5' },
+  xl: { height: 'h-field-xl', radius: 'rounded-field-xl', chevron: 'size-6' },
+}
+
+const BUTTON_SHAPES: Record<ButtonSize, { height: string, square: string, radius: string }> = {
+  xs: { height: 'h-button-xs', square: 'size-button-xs', radius: 'rounded-button-xs' },
+  sm: { height: 'h-button-sm', square: 'size-button-sm', radius: 'rounded-button-sm' },
+  md: { height: 'h-button-md', square: 'size-button-md', radius: 'rounded-button-md' },
+  lg: { height: 'h-button-lg', square: 'size-button-lg', radius: 'rounded-button-lg' },
+}
+
+interface ControlShapes {
+  field: { size: FieldSize, shape: FieldShape }
+  button: { size: ButtonSize, shape: { height: string, square: string, radius: string } }
+}
+
+export function useControlShape<K extends keyof ControlShapes> (kind: K, size: MaybeRefOrGetter<ControlShapes[K]['size']>): ComputedRef<ControlShapes[K]['shape']> {
+  return computed(() => (kind === 'field'
+    ? FIELD_SHAPES[toValue(size) as FieldSize]
+    : BUTTON_SHAPES[toValue(size) as ButtonSize]) as ControlShapes[K]['shape'])
+}

package/src/composables/useFieldFocusEvents.ts

@@ -0,0 +1,30 @@
+import { ref } from 'vue'
+
+export function useFieldFocusEvents(emit: {
+  (event: 'focus', payload: FocusEvent): void
+  (event: 'blur', payload: FocusEvent): void
+  (event: 'keydown', payload: KeyboardEvent): void
+  (event: 'keyup', payload: KeyboardEvent): void
+}) {
+  const isFocused = ref(false)
+
+  function handleFocus(event: FocusEvent) {
+    isFocused.value = true
+    emit('focus', event)
+  }
+
+  function handleBlur(event: FocusEvent) {
+    isFocused.value = false
+    emit('blur', event)
+  }
+
+  function handleKeydown(event: KeyboardEvent) {
+    emit('keydown', event)
+  }
+
+  function handleKeyup(event: KeyboardEvent) {
+    emit('keyup', event)
+  }
+
+  return { isFocused, handleFocus, handleBlur, handleKeydown, handleKeyup }
+}

package/src/composables/useIconSize.ts

@@ -26,3 +26,18 @@ export type IconSizeName = keyof typeof ICON_SIZES
 export function useIconSize(size: MaybeRefOrGetter<IconSizeName>) {
   return computed(() => ICON_SIZES[toValue(size)])
 }
+
+// A button's trailing icon (external link, chevron) sits one step below its
+// leading icon so it reads as an affordance, not as content.
+const TRAILING_ICON_SIZES = {
+  xs: 'size-2.5',
+  sm: 'size-3.5',
+  md: 'size-4',
+  lg: 'size-5',
+  xl: 'size-6',
+} as const
+
+/** Reactive trailing icon size class for a control's `size`. */
+export function useTrailingIconSize(size: MaybeRefOrGetter<IconSizeName>) {
+  return computed(() => TRAILING_ICON_SIZES[toValue(size)])
+}