GitHub

Keycap

A keycap for rendering keyboard hints — /, Tab, Esc, ↑ ↓ ↵. Renders a real , token-driven, so it re-skins with the active theme.

Stable .astro import EsaKbd from '@esa/ecology/esa-kbd.astro';

Preview

/ 
<Kbd>/</Kbd>

Labels

The cap sizes to its content from a 19px square minimum, so single characters stay square and words stretch. No size prop: keycaps sit inline with body or meta text and take their scale from --font-size-100.

/ K Esc Tab Enter ↑ ↓ ↵ 
<Kbd>/</Kbd>
<Kbd>K</Kbd>
<Kbd>Esc</Kbd>
<Kbd>Tab</Kbd>
<Kbd>Enter</Kbd>
<Kbd>↑</Kbd>
<Kbd>↓</Kbd>
<Kbd>↵</Kbd>

Chords

A chord is separate caps with a literal separator between them — not one cap reading Cmd+K. Each cap is a key the user physically presses; the + is prose.

⌘ + K Shift + ? 
<Kbd>⌘</Kbd> + <Kbd>K</Kbd>
<Kbd>Shift</Kbd> + <Kbd>?</Kbd>

In context

Keycaps are hints, not controls — they belong beside the thing the key operates: a search trigger, a menu row, a footer legend in a dialog.

Press / to search.

↑ ↓ navigate ↵ select Esc close 
<p>Press <Kbd>/</Kbd> to search.</p>

<div class="legend">
  <span><Kbd>↑</Kbd><Kbd>↓</Kbd> navigate</span>
  <span><Kbd>↵</Kbd> select</span>
  <span><Kbd>Esc</Kbd> close</span>
</div>

API

No props — the key label is the slot.

SlotTypeDefaultDescription
default slot — The key label — a character, a word (Esc, Tab), or a glyph (↑ ↓ ↵ ⌘).

Accessibility

  • Renders a real <kbd>, so assistive tech announces it as keyboard input rather than as a decorative box.
  • A keycap documents a shortcut — it never provides one. The shortcut must be bound and reachable without it; the cap is not focusable and not a button.
  • Prefer word labels over bare glyphs where a glyph is ambiguous read aloud: Enter announces better than ↵, and ⌘ is announced inconsistently across screen readers.
  • Don't state a platform-specific chord unconditionally — a Windows user reading ⌘ has no such key. Branch on platform, or say "Ctrl/⌘".

Theming surface

Every public token this component reads, extracted from its source at build time, split by blast radius: the hooks that belong to this component, then the shared and system tokens it consumes alongside everything else. The Resolves to column walks each token's real lineage — component → semantic → primitive → raw value — so you can see exactly where re-pointing it lands. A spoke re-skins by overriding these in its theme-<slug>.css; component internals are never edited. No hook for what you need? File it with /request-lego.

Type roles it names

This component does not set a size, weight, face or tracking of its own — it names a composite, and the composite carries all five. A composite is a class rather than a token, so none of it appears in the tables below; re-theme text by re-pointing the token family, not by editing the component.

RoleRe-pointReach
.typography-microcopy-xs
  • --typography-microcopy-xs-font-family 'DM Sans', sans-serif via --typography-font-family-sans → --font-family-dm-sans
  • --typography-microcopy-xs-font-size clamp(0.625rem, 0.56rem + 0.32vw, 0.75rem) via --font-size-100
  • --typography-microcopy-xs-font-weight 500 via --typography-font-weight-medium → --font-weight-500
  • --typography-microcopy-xs-letter-spacing 0.01em via --letter-spacing-default
  • --typography-microcopy-xs-line-height 1 via --line-height-none
+6 more components esa-app-shell, esa-button, esa-button-toggle, esa-filter-pills, esa-pill, esa-range-slider

Wired to this component

None. This component has no hooks of its own — it themes entirely through the shared tokens below, so every override here also moves its siblings.

Shared tokens it reads

Owned by a family or by the semantic layer. Still overridable — but scope the override (esa-foo { --form-border-color: … }) unless you mean to move everything that reads it. Reach says what else that is.

Token Reach Resolves to
--border-width-default semantic every component 1px via --border-width-100
--color-background-elevation-raised semantic every component #fcfcfc via --color-gray-1
--color-border-default semantic every component one role per property, so a theme can move the ring's weight and its colour independently. Tier 3's --focus-ring-width now reads this instead of holding a bare 2px, which is the same shape --focus-ring-color has always had (a thin tier-3 alias over a tier-2 role) — width was simply never given the tier-2 half. * * This role was rejected once, and the rejection is worth recording because its PREMISE was wrong rather than its reasoning. The argument against an `emphasis` width was that every 2px border in the kit is micro-geometry — spinner rings, the kbd keycap lip, a chevron. The focus ring was not in that enumeration and does not fit it: 33 components render it, more than read any other tier-3 token, and it is not micro-geometry but an accessibility affordance whose weight is a legitimate brand axis (a spoke that needs a heavier ring for contrast has to be able to reach it). It is also not a `border` in any component — every consumer paints it with `outline` or `box-shadow` — which is precisely why a survey of BORDERS missed it. The name still says `border` because tier 2 already calls the ring's colour --color-border-default-focus
--color-content-default-secondary semantic every component #646464 via --color-gray-11
--radius-sm semantic every component 0.25rem via --radius-100