Added a note about shortcut rendering in the spec.

1 files changed, 11 insertions, 1 deletions

diff --git a/Spec.md b/Spec.md
index 9a8663a..3f4b3ba 100644
--- a/Spec.md
+++ b/Spec.md
@@ -12,4 +12,14 @@ Please stay high-level when writing the spec, do not document particular classes
 * If the shortcut is Cmd-W or Cmd-Q, the recording must be cancelled and the keypress passed through to the system, closing the window or quitting the app.
 * If a shortcut is already taken by system and is enabled, it must be rejected. (Examples: Cmd-S, Cmd-N. TBD: What exactly does it mean that the shortcut is “enabled”?)
 * TBD: Option-key handling.
-* All other shortcuts must be accepted. (Examples: Ctrl-Esc, Cmd-Delete, F16.)
\ No newline at end of file
+* All other shortcuts must be accepted. (Examples: Ctrl-Esc, Cmd-Delete, F16.)
+
+# Rendering Shortcuts
+
+On different keyboard layouts (such as US and Czech), a single shortcut (a combination of physical keys) can have different “names”.
+
+For example, the default system shortcut for toggling directly to Space #2 is Control–2. But when you switch to the Czech keyboard layout, the physical key with the `2` label now inserts the `ě` character. Thus, on most keyboard layouts the shortcut for toggling to Space #2 is `^2`, but on the Czech layout it’s `^ě`. (I stress that this is the same combination of hardware keys.)
+
+This is reflected by the system: When you open the System Preferences → Keyboard → Shortcuts pane, the shortcuts displayed depend on the currently selected keyboard layout (try switching between the US and Czech keyboard layouts and reopening the preference pane).
+
+This means that the “identity” of a shortcut is given by its key code and modifiers (such as `kVK_ANSI_2` and `NSControlKeyMask`), not the `keyCodeString` returned by the `MASShortcut` class. This string may change depending on the current keyboard layout: `^2` with the US keyboard active, but `^ě` with the Czech keyboard active.
\ No newline at end of file