diff --git a/README.md b/README.md
index 08bd086..d5df43a 100644
--- a/README.md
+++ b/README.md
@@ -1019,6 +1019,62 @@ Key points:
 
 ---
 
+## Known Patterns & Gotchas
+
+### Disabled / read-only form elements in display-only contexts
+
+`base.css` applies aggressive visibility reduction to `:disabled` and `[readonly]` form elements:
+
+```css
+.lt-input:disabled, .lt-select:disabled, .lt-textarea:disabled,
+.lt-input[readonly], .lt-textarea[readonly] {
+  opacity: 0.45;
+  color: var(--text-muted);  /* #3e607a — ~3.2:1 contrast, fails WCAG AA on dark backgrounds */
+}
+.lt-checkbox:disabled { opacity: 0.4; }
+```
+
+This is intentional for *genuinely* disabled controls (submission forms, locked fields). However, if you use `disabled` purely to make a field **non-interactive for display**, the result is nearly unreadable on dark/OLED screens.
+
+**Pattern: display-only selects / inputs (edit-mode toggle)**
+
+A common pattern is disabling fields in view-mode and enabling them in edit-mode. Apply a scoping class and override in your app CSS:
+
+```css
+/* In your app's CSS — override base.css fading for display-only fields */
+.your-display-field:disabled,
+.your-display-field[disabled] {
+  opacity: 1;
+  color: var(--text-secondary);  /* #7fa3bf — full legibility */
+  cursor: default;
+  pointer-events: none;
+}
+```
+
+**Pattern: copy-to-clipboard inputs (readonly)**
+
+`[readonly]` triggers the same `opacity: 0.45` rule. For API key / token display fields where the user must read and copy the value, restore opacity inline or via class:
+
+```html
+<input type="text" readonly class="lt-input" style="opacity:1;cursor:text">
+```
+
+**Pattern: description / content display areas**
+
+Avoid rendering multi-line content in a `disabled` textarea — use a styled `<div>` instead. Apply `white-space: pre-wrap` on that div to preserve newlines and multiple spaces (required for ASCII art / diagrams to align correctly, since the body font is already monospace):
+
+```css
+.your-description-view {
+  white-space: pre-wrap;
+  word-break: break-word;
+  color: var(--text-primary);
+}
+```
+
+Set `innerHTML = escHtml(rawText)` — no `<br>` replacement needed when `white-space: pre-wrap` is active.
+
+---
+
 ## Changelog
 
 ### v1.2 (current)