1 files changed, 23 insertions, 0 deletions

diff --git a/docs/dev/style.md b/docs/dev/style.md
index 67cbc6744..9859f6148 100644
--- a/docs/dev/style.md
+++ b/docs/dev/style.md
@@ -78,6 +78,8 @@ Use original span for FileId
 
 This makes it easier to prepare a changelog.
 
+If the change adds a new user-visible functionality, consider recording a GIF with [peek](https://github.com/phw/peek) and pasting it into the PR description.
+
 **Rationale:** clean history is potentially useful, but rarely used.
 But many users read changelogs.
 
@@ -643,6 +645,27 @@ assert!(x >= lo && x <= hi>);
 **Rationale:** Less-then comparisons are more intuitive, they correspond spatially to [real line](https://en.wikipedia.org/wiki/Real_line).
 
 
+## Token names
+
+Use `T![foo]` instead of `SyntaxKind::FOO_KW`.
+
+```rust
+// GOOD
+match p.current() {
+    T![true] | T![false] => true,
+    _ => false,
+}
+
+// BAD
+
+match p.current() {
+    SyntaxKind::TRUE_KW | SyntaxKind::FALSE_KW => true,
+    _ => false,
+}
+```
+
+**Rationale:** The macro uses the familiar Rust syntax, avoiding ambiguities like "is this a brace or bracket?".
+
 ## Documentation
 
 For `.md` and `.adoc` files, prefer a sentence-per-line format, don't wrap lines.