@olympusoss/canvas 4.0.0 → 5.0.0

package/src/atoms/input/input.shared.tsx

@@ -0,0 +1,203 @@
+import { useState } from "react";
+import { type GestureResponderEvent, type TextStyle } from "react-native";
+import { View, Pressable, Text, TextInput, useTheme, type ColorTokens, type StyleProp, type ViewStyle } from "../../style/index.js";
+import { Icon } from "../icon/icon.js";
+import { type InputSkin, type Size } from "./input.styles.js";
+
+// Shared Input shell. The structure (bare field vs. grouped addon layout, the
+// prefix/suffix boxes, overlaid icons, the optional action button), the
+// public boolean-prop API, the size precedence, the border-color precedence
+// (error > focus > default), accessibility, refs, and handlers all live here
+// once. A platform file supplies only its skin (field shape, fill, border,
+// height, the Android active-indicator underline, press feedback) and calls
+// createInput.
+
+// Glyphs an overlaid leading/trailing icon can name. Maps the scalar `icon`
+// string to the Icon atom's flat boolean prop, so the playground stays
+// serializable (a name string, not a React element).
+const ICON_BOOL: Record<string, "search" | "mail" | "lock" | "user" | "key" | "globe"> = {
+  search: "search",
+  mail: "mail",
+  lock: "lock",
+  user: "user",
+  key: "key",
+  globe: "globe",
+};
+
+// react-native-web paints a default focus outline on the field; in the grouped
+// (addon) layout that ring is clipped by the rounded, overflow-hidden container
+// and reads as half-baked, so it is suppressed there and the group shows focus
+// on its shared border instead. No-op on native, which has no CSS outline.
+const FIELD_OUTLINE_RESET = { outlineStyle: "none", outlineWidth: 0 } as unknown as TextStyle;
+
+export interface InputProps {
+  /** Current text value (controlled). */
+  value?: string;
+  /** Called with the new text on each keystroke. */
+  onChangeText?: (text: string) => void;
+  /** Placeholder shown while the field is empty. */
+  placeholder?: string;
+  // State (orthogonal). `error` (alias `invalid`) flags a validation problem.
+  error?: boolean;
+  invalid?: boolean;
+  disabled?: boolean;
+  /** Read-only: shows the value but blocks editing without the dimmed look. */
+  readOnly?: boolean;
+  // Size (pick one; default is the medium field).
+  small?: boolean;
+  large?: boolean;
+  /** Full-width field (the default); pass to be explicit. */
+  block?: boolean;
+  /** Multi-line text area instead of a single-line field. Ignored when addons
+   *  (prefix/suffix/icons/action) are present, which are single-line only. */
+  multiline?: boolean;
+
+  // Addons. Passing any of these switches the field to the grouped layout: a
+  // single control where a leading prefix and/or trailing suffix share one outer
+  // border with the field (squared joined edges, 1px inner separators), so they
+  // read as one piece rather than detached. Addons are plain strings, so no icon
+  // library is required at this layer.
+  /** Leading addon content (e.g. "https://", "$", an icon glyph). */
+  prefix?: string;
+  /** Trailing addon content (e.g. "@canvas.dev", "USD", "Copy"). */
+  suffix?: string;
+  // Overlaid glyph mode. Unlike prefix/suffix (a bordered addon box), these
+  // float a real Lucide glyph INSIDE the field with no separator, and pad the
+  // text away from it (pl-9 / pr-9). `icon` names which glyph (see ICON_BOOL).
+  /** Render `icon` as a passive glyph inside the left of the field. */
+  leadingIcon?: boolean;
+  /** Render `icon` as a passive glyph inside the right of the field. */
+  trailingIcon?: boolean;
+  /** Glyph name for leadingIcon/trailingIcon (e.g. "search", "mail"). */
+  icon?: string;
+  /** Render the suffix as a pressable action button rather than a passive label. */
+  action?: boolean;
+  /** Called when the action suffix is pressed (action only). */
+  onActionPress?: (event: GestureResponderEvent) => void;
+
+  /** Escape hatch for layout/positioning composition (mainly width). */
+  style?: StyleProp<ViewStyle>;
+}
+
+// Size precedence when more than one is passed: first match wins.
+function sizeOf(p: InputProps): Size {
+  if (p.large) return "large";
+  if (p.small) return "small";
+  return "base";
+}
+
+/** Build an Input component from a platform skin. */
+export function createInput(skin: InputSkin) {
+  return function Input(props: InputProps) {
+    const {
+      value,
+      onChangeText,
+      placeholder,
+      disabled,
+      readOnly,
+      multiline,
+      prefix,
+      suffix,
+      leadingIcon,
+      trailingIcon,
+      icon,
+      action,
+      onActionPress,
+      style,
+    } = props;
+    const isError = !!(props.error || props.invalid);
+    const size = sizeOf(props);
+    const [focused, setFocused] = useState(false);
+    const { tokens } = useTheme();
+
+    // Border-color precedence: error > focus > default input border. Shared by
+    // both layouts; in the grouped layout it lives on the outer border so prefix
+    // + field + suffix light up together as one control. The skin decides how
+    // that color is used (a full border on iOS/web, the bottom active indicator
+    // on Android).
+    const borderColor: keyof ColorTokens = isError ? "destructive" : focused ? "ring" : "input";
+    const text = skin.text(tokens, size);
+    const iconName = icon != null ? ICON_BOOL[icon] : undefined;
+    const hasAddons = prefix != null || suffix != null || !!leadingIcon || !!trailingIcon || !!action;
+
+    const common = {
+      value,
+      onChangeText,
+      placeholder,
+      placeholderTextColor: tokens["muted-foreground"],
+      editable: !disabled && !readOnly,
+      selectionColor: tokens.primary, // brand cursor / selection on every platform
+      onFocus: () => setFocused(true),
+      onBlur: () => setFocused(false),
+    };
+
+    // Bare field (and the multiline text area): no addons.
+    if (!hasAddons) {
+      return (
+        <TextInput
+          style={[
+            skin.bareField(tokens, borderColor, focused, isError),
+            skin.bareBox(size, !!multiline),
+            text,
+            disabled ? { opacity: skin.disabledOpacity } : null,
+            style,
+          ]}
+          multiline={multiline}
+          textAlignVertical={multiline ? "top" : "center"}
+          {...common}
+        />
+      );
+    }
+
+    // Grouped field: prefix/suffix addons, overlaid icons, optional action button.
+    // The whole group shares one border, so it owns the focus state and the inner
+    // field's default outline is suppressed (see FIELD_OUTLINE_RESET).
+    const height = skin.groupedHeight(size);
+    return (
+      <View
+        style={[skin.groupContainer(tokens, borderColor, focused, isError), disabled ? { opacity: skin.disabledOpacity } : null, style]}
+      >
+        {prefix != null ? (
+          <View style={skin.addonBox(tokens, "left", height)}>
+            <Text style={[skin.addonText(tokens), text]}>{prefix}</Text>
+          </View>
+        ) : null}
+
+        {leadingIcon && iconName != null ? (
+          <View style={skin.iconOverlay("left")} pointerEvents="none">
+            <Icon {...{ [iconName]: true }} muted size={16} />
+          </View>
+        ) : null}
+
+        <TextInput style={[skin.groupField(tokens, !!leadingIcon, !!trailingIcon), text, FIELD_OUTLINE_RESET]} {...common} />
+
+        {trailingIcon && iconName != null ? (
+          <View style={skin.iconOverlay("right")} pointerEvents="none">
+            <Icon {...{ [iconName]: true }} muted size={16} />
+          </View>
+        ) : null}
+
+        {suffix != null ? (
+          action ? (
+            <Pressable
+              style={({ pressed }) => [
+                skin.addonBox(tokens, "right", height),
+                skin.pressedOpacity != null && pressed ? { opacity: skin.pressedOpacity } : null,
+              ]}
+              onPress={onActionPress}
+              disabled={disabled}
+              android_ripple={skin.ripple ? skin.ripple(tokens) : undefined}
+              accessibilityRole="button"
+            >
+              <Text style={[skin.actionText(tokens), text]}>{suffix}</Text>
+            </Pressable>
+          ) : (
+            <View style={skin.addonBox(tokens, "right", height)}>
+              <Text style={[skin.addonText(tokens), text]}>{suffix}</Text>
+            </View>
+          )
+        ) : null}
+      </View>
+    );
+  };
+}

package/src/atoms/input/input.styles.ts

@@ -0,0 +1,286 @@
+import { type ViewStyle, type TextStyle } from "react-native";
+import { type ColorTokens } from "../../style/index.js";
+
+// Co-located Input skins, one per platform. The BRAND survives on every platform
+// (the cursor/selection is always the indigo `primary`, the focus accent is the
+// `ring`, never a platform default), and only the native SHAPE, sizing, fill,
+// border treatment, and press feedback change per OS:
+//   iOS (HIG, iOS 26+/Liquid Glass): a PLAIN text field — the value text sits on
+//     a TRANSPARENT surface with a single bottom HAIRLINE rule (1pt `border`
+//     separator) and NO fill, NO surrounding box, NO rounded capsule. Focus
+//     thickens/tints the hairline to the brand (`ring`), error to `destructive`;
+//     press (action suffix) = opacity dim (~0.8). The cursor/selection stays the
+//     indigo `primary`.
+//   Android (Material 3 filled): a subtle fill (`muted`), TOP corners ~4 radius
+//     and a flat bottom, a bottom active-indicator underline (1dp `border` at
+//     rest -> 2dp `ring` on focus, `destructive` on error), ~56dp tall; the
+//     action suffix uses android_ripple; disabled opacity 0.38.
+//   Web: the established Canvas look (the current input, lifted verbatim) — full
+//     1px border (error > focus > input), 6 radius, background fill, 36/32/40
+//     tall, opacity 0.5 disabled, action press opacity 0.9.
+
+export type Size = "small" | "base" | "large";
+
+// The contract a platform skin fulfills. Both layouts (bare field, grouped addon
+// row) and the size/state inputs the shell resolves are passed in; the skin maps
+// them to RN style objects. `borderColor` is a token key (error > focus > input)
+// the shell already resolved; the skin reads tokens[borderColor].
+export interface InputSkin {
+  /** Type scale per size; the field and its addons share it so they line up. */
+  text: (t: ColorTokens, size: Size) => TextStyle;
+  /** Height (single line) or min-height (multiline) of the bare field. */
+  bareBox: (size: Size, multiline: boolean) => TextStyle;
+  /** Fixed row height for the grouped layout (addon boxes set it). */
+  groupedHeight: (size: Size) => number;
+  /** The bare field surface: shape, fill, border/underline for the active state. */
+  bareField: (t: ColorTokens, borderColor: keyof ColorTokens, focused: boolean, error: boolean) => TextStyle;
+  /** The grouped (addon) outer: the row that shares one border/underline. */
+  groupContainer: (t: ColorTokens, borderColor: keyof ColorTokens, focused: boolean, error: boolean) => ViewStyle;
+  /** The inner field inside the group (grows to fill; pads away from icons). */
+  groupField: (t: ColorTokens, leadingIcon: boolean, trailingIcon: boolean) => TextStyle;
+  /** A prefix/suffix addon box. */
+  addonBox: (t: ColorTokens, side: "left" | "right", height: number) => ViewStyle;
+  addonText: (t: ColorTokens) => TextStyle;
+  actionText: (t: ColorTokens) => TextStyle;
+  /** Overlaid icon position inside the field (left or right gutter). */
+  iconOverlay: (side: "left" | "right") => ViewStyle;
+  /** Opacity applied to the field when disabled. */
+  disabledOpacity: number;
+  /** iOS/web dim the action suffix on press; Android uses a ripple instead (null). */
+  pressedOpacity: number | null;
+  /** Android ripple over the action suffix; null on iOS/web. */
+  ripple: ((t: ColorTokens) => { color: string; borderless: boolean }) | null;
+}
+
+// --- shared type scale (identical across platforms; brand type, not a face) --
+function webText(_t: ColorTokens, size: Size): TextStyle {
+  if (size === "large") return { fontSize: 16, lineHeight: 24 };
+  if (size === "small") return { fontSize: 12, lineHeight: 16 };
+  return { fontSize: 14, lineHeight: 20 };
+}
+
+// ---------- Web: the established Canvas look ----------
+export const webSkin: InputSkin = {
+  text: webText,
+  bareBox: (size, multiline) => {
+    if (multiline) return { minHeight: size === "large" ? 96 : size === "small" ? 64 : 80 };
+    return { height: size === "large" ? 40 : size === "small" ? 32 : 36 };
+  },
+  groupedHeight: (size) => (size === "large" ? 40 : size === "small" ? 32 : 36),
+  bareField: (t, borderColor) => ({
+    width: "100%",
+    borderRadius: 6,
+    borderWidth: 1,
+    borderColor: t[borderColor],
+    backgroundColor: t.background,
+    paddingHorizontal: 12,
+    paddingVertical: 8,
+    color: t.foreground,
+  }),
+  groupContainer: (t, borderColor) => ({
+    flexDirection: "row",
+    alignItems: "stretch",
+    width: "100%",
+    borderWidth: 1,
+    borderColor: t[borderColor],
+    borderRadius: 6,
+    overflow: "hidden",
+    backgroundColor: t.background,
+  }),
+  groupField: (t, leadingIcon, trailingIcon) => ({
+    flexGrow: 1,
+    flexShrink: 1,
+    flexBasis: "0%",
+    height: "100%",
+    paddingHorizontal: 12,
+    paddingVertical: 8,
+    color: t.foreground,
+    ...(leadingIcon ? { paddingLeft: 36 } : null),
+    ...(trailingIcon ? { paddingRight: 36 } : null),
+  }),
+  addonBox: (t, side, height) => ({
+    justifyContent: "center",
+    backgroundColor: t.muted,
+    paddingHorizontal: 12,
+    borderColor: t.border,
+    ...(side === "left" ? { borderRightWidth: 1 } : { borderLeftWidth: 1 }),
+    height,
+  }),
+  addonText: (t) => ({ color: t["muted-foreground"] }),
+  actionText: (t) => ({ fontWeight: "500", color: t.foreground }),
+  iconOverlay: (side) => ({
+    position: "absolute",
+    top: 0,
+    bottom: 0,
+    zIndex: 10,
+    justifyContent: "center",
+    ...(side === "left" ? { left: 0, paddingLeft: 12 } : { right: 0, paddingRight: 12 }),
+  }),
+  disabledOpacity: 0.5,
+  pressedOpacity: 0.9,
+  ripple: null,
+};
+
+// ---------- iOS (HIG, iOS 26+/Liquid Glass): plain field, transparent, bottom hairline ----------
+// Apple's plain text field on iOS 26+: the value text sits directly on a
+// TRANSPARENT surface with a single bottom HAIRLINE rule (1pt separator) and no
+// fill, no surrounding box, no rounded capsule. Canvas keeps the brand by
+// thickening + tinting that hairline to the brand `ring` on focus (and
+// `destructive` on error); at rest it is the faint `border` separator. The
+// cursor/selection is always the indigo `primary` (set in the shell).
+function iosHairline(t: ColorTokens, borderColor: keyof ColorTokens, focused: boolean, error: boolean): ViewStyle {
+  // Rest = the faint `border` separator; focus/error thicken to 2pt and tint to
+  // the brand color the shell resolved (ring on focus, destructive on error).
+  const active = focused || error;
+  return {
+    borderBottomWidth: active ? 2 : 1,
+    borderBottomColor: active ? t[borderColor] : t.border,
+  };
+}
+export const iosSkin: InputSkin = {
+  text: webText,
+  bareBox: (size, multiline) => {
+    if (multiline) return { minHeight: size === "large" ? 110 : size === "small" ? 76 : 92 };
+    return { height: size === "large" ? 50 : size === "small" ? 36 : 44 };
+  },
+  groupedHeight: (size) => (size === "large" ? 50 : size === "small" ? 36 : 44),
+  bareField: (t, borderColor, focused, error) => ({
+    width: "100%",
+    // Plain field: transparent surface, no box/radius, only a bottom hairline.
+    backgroundColor: "transparent",
+    ...iosHairline(t, borderColor, focused, error),
+    // No horizontal inset so the value text aligns flush with the hairline edge,
+    // as in the iOS 27 render.
+    paddingHorizontal: 0,
+    paddingVertical: 10,
+    color: t.foreground,
+  }),
+  groupContainer: (t, borderColor, focused, error) => ({
+    flexDirection: "row",
+    alignItems: "stretch",
+    width: "100%",
+    // The whole row shares the single bottom hairline; no fill, no box, no radius.
+    backgroundColor: "transparent",
+    ...iosHairline(t, borderColor, focused, error),
+  }),
+  groupField: (t, leadingIcon, trailingIcon) => ({
+    flexGrow: 1,
+    flexShrink: 1,
+    flexBasis: "0%",
+    height: "100%",
+    paddingHorizontal: 0,
+    paddingVertical: 10,
+    color: t.foreground,
+    ...(leadingIcon ? { paddingLeft: 28 } : null),
+    ...(trailingIcon ? { paddingRight: 28 } : null),
+  }),
+  // Addons are inline on the transparent field (no filled box, no separator) so
+  // the row reads as one plain line over the shared hairline.
+  addonBox: (_t, side, height) => ({
+    justifyContent: "center",
+    backgroundColor: "transparent",
+    ...(side === "left" ? { paddingRight: 8 } : { paddingLeft: 8 }),
+    height,
+  }),
+  addonText: (t) => ({ color: t["muted-foreground"] }),
+  actionText: (t) => ({ fontWeight: "600", color: t.primary }),
+  iconOverlay: (side) => ({
+    position: "absolute",
+    top: 0,
+    bottom: 0,
+    zIndex: 10,
+    justifyContent: "center",
+    ...(side === "left" ? { left: 0 } : { right: 0 }),
+  }),
+  disabledOpacity: 0.5,
+  pressedOpacity: 0.8,
+  ripple: null,
+};
+
+// ---------- Android (Material 3 filled): subtle fill, top radius, bottom active indicator ----------
+// M3 filled text field: a ~56dp container with a subtle fill (`muted` ~
+// surface-container-highest), the TOP corners rounded ~4dp and a flat bottom,
+// and a bottom active-indicator underline — 1dp `border` at rest, 2dp `ring`
+// (brand) on focus, `destructive` on error. The brand survives via the focused
+// indicator color and the action suffix's primary label + ripple.
+const ANDROID_TOP_RADIUS = 4;
+function androidUnderline(t: ColorTokens, borderColor: keyof ColorTokens, focused: boolean, error: boolean): ViewStyle {
+  // M3 active indicator: a VISIBLE baseline at rest (on-surface-variant ~ the
+  // `muted-foreground` token), thickening to 2dp in the brand `ring` on focus /
+  // `destructive` on error. The rest color must read clearly so the filled field is
+  // distinct from the iOS lineless capsule (the regression this fixes).
+  const active = focused || error;
+  return {
+    borderBottomWidth: active ? 2 : 1,
+    borderBottomColor: active ? t[borderColor] : t["muted-foreground"],
+  };
+}
+export const androidSkin: InputSkin = {
+  // M3 body input is 16sp; nudge the base/large up, keep small readable.
+  text: (_t, size) => {
+    if (size === "large") return { fontSize: 18, lineHeight: 26 };
+    if (size === "small") return { fontSize: 14, lineHeight: 20 };
+    return { fontSize: 16, lineHeight: 24 };
+  },
+  bareBox: (size, multiline) => {
+    if (multiline) return { minHeight: size === "large" ? 120 : size === "small" ? 88 : 104 };
+    return { height: size === "large" ? 60 : size === "small" ? 48 : 56 };
+  },
+  groupedHeight: (size) => (size === "large" ? 60 : size === "small" ? 48 : 56),
+  bareField: (t, borderColor, focused, error) => ({
+    width: "100%",
+    borderTopLeftRadius: ANDROID_TOP_RADIUS,
+    borderTopRightRadius: ANDROID_TOP_RADIUS,
+    borderBottomLeftRadius: 0,
+    borderBottomRightRadius: 0,
+    ...androidUnderline(t, borderColor, focused, error),
+    backgroundColor: t.muted,
+    paddingHorizontal: 16,
+    paddingVertical: 8,
+    color: t.foreground,
+  }),
+  groupContainer: (t, borderColor, focused, error) => ({
+    flexDirection: "row",
+    alignItems: "stretch",
+    width: "100%",
+    borderTopLeftRadius: ANDROID_TOP_RADIUS,
+    borderTopRightRadius: ANDROID_TOP_RADIUS,
+    ...androidUnderline(t, borderColor, focused, error),
+    overflow: "hidden",
+    backgroundColor: t.muted,
+  }),
+  groupField: (t, leadingIcon, trailingIcon) => ({
+    flexGrow: 1,
+    flexShrink: 1,
+    flexBasis: "0%",
+    height: "100%",
+    paddingHorizontal: 16,
+    paddingVertical: 8,
+    color: t.foreground,
+    ...(leadingIcon ? { paddingLeft: 44 } : null),
+    ...(trailingIcon ? { paddingRight: 44 } : null),
+  }),
+  // The addon shares the field fill (M3 leading/trailing content sits inside the
+  // filled container) with a hairline separator.
+  addonBox: (t, side, height) => ({
+    justifyContent: "center",
+    backgroundColor: t.muted,
+    paddingHorizontal: 16,
+    borderColor: t.border,
+    ...(side === "left" ? { borderRightWidth: 1 } : { borderLeftWidth: 1 }),
+    height,
+  }),
+  addonText: (t) => ({ color: t["muted-foreground"] }),
+  actionText: (t) => ({ fontWeight: "500", color: t.primary, textTransform: "uppercase", letterSpacing: 0.5 }),
+  iconOverlay: (side) => ({
+    position: "absolute",
+    top: 0,
+    bottom: 0,
+    zIndex: 10,
+    justifyContent: "center",
+    ...(side === "left" ? { left: 0, paddingLeft: 16 } : { right: 0, paddingRight: 16 }),
+  }),
+  disabledOpacity: 0.38, // M3 disabled opacity
+  pressedOpacity: null, // Android uses a ripple instead
+  ripple: (t) => ({ color: t.primary, borderless: false }),
+};

package/src/atoms/input/input.tsx

@@ -0,0 +1,6 @@
+import { createInput } from "./input.shared.js";
+import { webSkin } from "./input.styles.js";
+
+// Web Input (the base; Metro falls back to it on native, web bundlers resolve it).
+export const Input = createInput(webSkin);
+export type { InputProps } from "./input.shared.js";

package/src/atoms/kbd/kbd.md

@@ -0,0 +1,91 @@
+# Kbd
+
+Keyboard shortcut indicator badge.
+
+## Usage
+
+```tsx
+<View style={{ flexDirection: "row", alignItems: "center", gap: 4 }}>
+  <Kbd>⌘</Kbd>
+  <Text style={{ fontSize: 12, lineHeight: 16, color: tokens["muted-foreground"] }}>+</Text>
+  <Kbd>K</Kbd>
+</View>
+```
+
+## Variants
+
+### Mode - single
+
+```tsx
+<Kbd>⌘</Kbd>
+```
+
+### Mode - in a sentence
+
+```tsx
+<View style={{ flexDirection: "row", flexWrap: "wrap", alignItems: "center", gap: 4 }}>
+  <Text style={{ fontSize: 14, lineHeight: 20, color: tokens.foreground }}>Press </Text>
+  <Kbd>⌘</Kbd>
+  <Kbd>K</Kbd>
+  <Text style={{ fontSize: 14, lineHeight: 20, color: tokens.foreground }}> to search.</Text>
+</View>
+```
+
+## Do & Don't
+
+### Single
+
+**Do** — Use the single mode for one real key; give each cap exactly one key.
+
+```tsx
+<Kbd>Esc</Kbd>
+```
+
+**Don't** — Packing a whole shortcut into one key cap reads as a single keystroke that does not exist.
+
+```tsx
+<Kbd>⌘K</Kbd>
+```
+
+### Combo
+
+**Do** — Separate each key with a + so the combo reads as keys pressed together.
+
+```tsx
+<View style={{ flexDirection: "row", alignItems: "center", gap: 4 }}>
+  <Kbd>⌘</Kbd>
+  <Text style={{ fontSize: 12, lineHeight: 16, color: tokens["muted-foreground"] }}>+</Text>
+  <Kbd>⇧</Kbd>
+  <Text style={{ fontSize: 12, lineHeight: 16, color: tokens["muted-foreground"] }}>+</Text>
+  <Kbd>P</Kbd>
+</View>
+```
+
+**Don't** — Caps butted together with no separator blur into one token and hide that it is a chord.
+
+```tsx
+<View style={{ flexDirection: "row", alignItems: "center" }}>
+  <Kbd>⌘</Kbd>
+  <Kbd>⇧</Kbd>
+  <Kbd>P</Kbd>
+</View>
+```
+
+### In a sentence
+
+**Do** — Wrap each key in a kbd so shortcuts read as physical keys.
+
+```tsx
+<View style={{ flexDirection: "row", alignItems: "center", gap: 4 }}>
+  <Text style={{ fontSize: 14, lineHeight: 20 }}>Press</Text>
+  <Kbd>Ctrl</Kbd>
+  <Kbd>K</Kbd>
+  <Text style={{ fontSize: 14, lineHeight: 20 }}>to search.</Text>
+</View>
+```
+
+**Don't** — Plain-text shortcuts blend into the prose and are easy to miss.
+
+```tsx
+<Text style={{ fontSize: 14, lineHeight: 20 }}>Press Ctrl+K to search.</Text>
+```

package/src/atoms/kbd/kbd.styles.ts

@@ -0,0 +1,33 @@
+import { type ViewStyle, type TextStyle } from "react-native";
+import { type ColorTokens } from "../../style/index.js";
+
+// Co-located Kbd styles. The cap has one fixed look (no axes), so the layout-only
+// box geometry is a static fragment and the colored surface (border + muted fill)
+// plus the muted label color are functions of the active tokens (so the cap
+// follows light/dark and reads as glass at the theming level).
+
+// The key-cap box: a centered row, fixed cap height, a minimum width so a single
+// glyph still reads as a key, the small radius, a hairline border, and snug
+// horizontal padding.
+export const capBox: ViewStyle = {
+  flexDirection: "row",
+  height: 20,
+  minWidth: 20,
+  alignItems: "center",
+  justifyContent: "center",
+  borderRadius: 4,
+  borderWidth: 1,
+  paddingHorizontal: 6,
+};
+
+// The cap surface: the muted fill and the hairline border color.
+export function capSurface(tokens: ColorTokens): ViewStyle {
+  return { borderColor: tokens.border, backgroundColor: tokens.muted };
+}
+
+// The key label: small, medium-weight, muted text.
+export const labelType: TextStyle = { fontSize: 12, lineHeight: 16, fontWeight: "500" };
+
+export function labelColor(tokens: ColorTokens): TextStyle {
+  return { color: tokens["muted-foreground"] };
+}

package/src/atoms/kbd/kbd.tsx

@@ -0,0 +1,27 @@
+import { type ReactNode } from "react";
+import { View, Text, useTheme, type StyleProp, type ViewStyle } from "../../style/index.js";
+import * as s from "./kbd.styles.js";
+
+// Kbd: a keyboard shortcut indicator. Renders a single key cap, a small
+// bordered, slightly raised label with monospace-ish small text. The key label
+// comes from children. One cap = one key; compose multiple Kbd caps with a
+// separator for a chord (e.g. ⌘ + K), per the docs.
+//
+// The cap has one fixed look (no size or intent variants), so there are no
+// boolean axes to map: the markup mirrors the docs' kbdCls exactly.
+
+export interface KbdProps {
+  children?: ReactNode;
+  /** Escape hatch for layout/positioning composition (mainly width). */
+  style?: StyleProp<ViewStyle>;
+}
+
+export function Kbd({ children, style }: KbdProps) {
+  const { tokens } = useTheme();
+
+  return (
+    <View style={[s.capBox, s.capSurface(tokens), style]}>
+      {children != null ? <Text style={[s.labelType, s.labelColor(tokens)]}>{children}</Text> : null}
+    </View>
+  );
+}