From 97402b8814f003fc4fb58fa98b4f3f3eca2e69b6 Mon Sep 17 00:00:00 2001
From: Ethan Graf <ethan@Beacon.local>
Date: Sat, 30 May 2026 18:18:35 -0400
Subject: [PATCH] Update tooltip standards in design skill

---
 .opencode/skills/textile-design/components.md | 24 +++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/.opencode/skills/textile-design/components.md b/.opencode/skills/textile-design/components.md
index 7f4fad4..0278bf1 100644
--- a/.opencode/skills/textile-design/components.md
+++ b/.opencode/skills/textile-design/components.md
@@ -53,6 +53,30 @@ Reference implementations live under `src/components/` unless noted.
 - Outer chrome: `rounded-md border`, `bg-background`, `min-h-0` flex discipline for scroll.
 - Prose links: `text-accent`; focus ring uses semantic accent via arbitrary property.
 
+## Tooltip
+
+**Reference:** `AppSidebar.tsx` (new-document buttons), `CommandPalette.tsx` (action rows)
+
+Use the **native `title` attribute**. No custom CSS, no custom markup.
+
+```tsx
+<button title="New document in Habitat" ...>
+```
+
+```tsx
+<div title={action.description} ...>
+```
+
+The browser renders the OS-native tooltip:
+- macOS: dark translucent bubble below the element
+- Windows/Linux: follows OS theme
+
+**Rules:**
+- Every interactive control that needs extra context gets a `title`
+- Icon-only buttons **must** also have `aria-label` (screen readers don't read `title` reliably)
+- Never build a custom tooltip with CSS/JS when `title` is sufficient
+- If you need rich markup in the tooltip, use `aria-describedby` pointing at visually-hidden content rather than a custom floating element
+
 ## Theme switch
 
 **Reference:** `SettingsModal.tsx`
-- 
2.51.2