From efddb808a25edde8f74b62b59779762c78f64dec Mon Sep 17 00:00:00 2001
From: Ethan Graf <ethan@Beacon.local>
Date: Wed, 13 May 2026 21:46:47 -0400
Subject: [PATCH] Add design skill

---
 .gitignore                                    |  3 +
 .opencode/skills/README.md                    | 11 +++
 .opencode/skills/textile-design/SKILL.md      | 77 +++++++++++++++
 .opencode/skills/textile-design/a11y.md       | 53 +++++++++++
 .opencode/skills/textile-design/components.md | 72 ++++++++++++++
 .opencode/skills/textile-design/motion.md     | 42 +++++++++
 .opencode/skills/textile-design/tokens.md     | 94 +++++++++++++++++++
 7 files changed, 352 insertions(+)
 create mode 100644 .opencode/skills/README.md
 create mode 100644 .opencode/skills/textile-design/SKILL.md
 create mode 100644 .opencode/skills/textile-design/a11y.md
 create mode 100644 .opencode/skills/textile-design/components.md
 create mode 100644 .opencode/skills/textile-design/motion.md
 create mode 100644 .opencode/skills/textile-design/tokens.md

diff --git a/.gitignore b/.gitignore
index eae9b77..a5208bf 100644
--- a/.gitignore
+++ b/.gitignore
@@ -96,3 +96,6 @@ out/
 .vscode
 
 dist
+
+# Cursor skill symlink (canonical skill lives under .opencode/skills/)
+.cursor/skills/textile-design
diff --git a/.opencode/skills/README.md b/.opencode/skills/README.md
new file mode 100644
index 0000000..e5b7b78
--- /dev/null
+++ b/.opencode/skills/README.md
@@ -0,0 +1,11 @@
+# Agent skills (OpenCode)
+
+Skills live in subfolders with `SKILL.md` (see [OpenCode skills docs](https://opencode.ai/docs/skills)).
+
+**Cursor:** after clone, link the design skill so Cursor discovers it:
+
+```bash
+mkdir -p .cursor/skills && ln -sf ../../.opencode/skills/textile-design .cursor/skills/textile-design
+```
+
+Run from the repository root (`textile/`).
diff --git a/.opencode/skills/textile-design/SKILL.md b/.opencode/skills/textile-design/SKILL.md
new file mode 100644
index 0000000..358574b
--- /dev/null
+++ b/.opencode/skills/textile-design/SKILL.md
@@ -0,0 +1,77 @@
+---
+name: textile-design
+description: Apply Textile's design system when building or modifying UI in the Textile Electron app. Covers calm-but-alive aesthetic, semantic theming via CSS variables, radius/spacing/motion tokens, accessibility for Electron + macOS, and canonical component patterns. Use when adding, editing, or reviewing any React component, page, modal, or styling in textile/.
+---
+
+# Textile design
+
+## Philosophy
+
+Textile is a **calm, lived-in surface**: low noise, generous rhythm, and motion that reassures without demanding attention. The product tenets in `PRODUCT.md` apply directly—**frictionless access**, **editor-grade performance**, and **the user should live inside Textile**. UI work should feel like a premium home base, not a flashy landing page.
+
+This skill intentionally **differs** from maximalist “frontend-design” prompts: avoid novelty for its own sake, loud palettes, and busy animation. **Refinement and consistency** carry the premium feel.
+
+## Before you ship UI
+
+Use this checklist on every new or changed surface:
+
+- [ ] **Colors**: only semantic tokens (`bg-background`, `text-foreground`, `border-border`, `bg-primary`, etc.)—no raw hex/oklch in JSX or one-off colors unless adding a new token in `src/index.css`.
+- [ ] **Radius**: pick the tier from [tokens.md](tokens.md) (`rounded` / `rounded-md` / `rounded-lg` / `rounded-full`) and stay consistent within one surface (e.g. do not mix `rounded` and `rounded-md` on sibling list rows).
+- [ ] **Spacing**: icon `size-4`; icon+label `gap-2`; compact chrome `p-3`; roomy panels `p-5`; list rows `px-2 py-1.5` unless a denser pattern is documented.
+- [ ] **Focus**: interactive controls get a visible `focus-visible` ring (see [components.md](components.md)); never `outline-none` without a replacement.
+- [ ] **Motion**: prefer CSS transitions on a small set of properties; honor `prefers-reduced-motion` (see [motion.md](motion.md)).
+- [ ] **Accessibility**: labels for icon-only controls, correct roles for dialogs/switches/lists, hit targets ≥ 44×44px where practical—see [a11y.md](a11y.md).
+
+## Theming model
+
+1. **Theme source**: `:root` and `:root[data-theme='dark']` define `--semantic-*` variables in `src/index.css`.
+2. **Tailwind bridge**: `@theme` maps those variables to utilities (`background`, `foreground`, `primary`, `accent`, `border`, `destructive`).
+3. **Components**: consume **only** utilities derived from tokens (including opacity modifiers like `text-foreground/60`). Future user themes swap the CSS variables; JSX should not assume fixed colors.
+
+When adding a new conceptual color (e.g. “warning”), add `--semantic-*` in both light and dark blocks, wire it in `@theme`, then use the new utility—do not spread ad-hoc OKLCH across components.
+
+Planned token extensions (`--radius-*`, `--motion-*`, `--font-*`, surface/muted) are specified in [tokens.md](tokens.md) for a follow-up CSS PR; until then, use the Tailwind class conventions listed there.
+
+## Token cheat sheet
+
+| Area        | Rule |
+|------------|------|
+| Page shell | `bg-background text-foreground` |
+| Hairlines  | `border-border` (1px borders) |
+| Primary CTA | `bg-primary text-primary-foreground` |
+| Links / key accents in prose | `text-accent` (per `EditPad`) |
+| Danger     | `text-destructive` for copy; full destructive buttons TBD |
+| Muted copy | `text-foreground/60`–`/80` until `--semantic-muted-fg` lands |
+
+Full tables and proposed CSS variables: [tokens.md](tokens.md).
+
+## Motion
+
+Default global transitions (~320ms) already apply to background, color, border, fill, stroke, shadow. Layer **short** transitions for layout chrome (e.g. sidebar width ~200ms). Details and anti-patterns: [motion.md](motion.md).
+
+## Accessibility
+
+Electron uses Chromium: treat the renderer like a **desktop web app** for a11y (keyboard, focus, ARIA, contrast). macOS VoiceOver is the primary screen reader to verify. Electron- and title-bar-specific notes: [a11y.md](a11y.md).
+
+## Component patterns
+
+Canonical snippets and file references: [components.md](components.md).
+
+## Anti-patterns
+
+- Hard-coded colors (`#fff`, `oklch(...)`) in class strings or inline styles for product chrome.
+- `transition-all` or animating `width`/`height` on heavy subtrees without a performance pass.
+- Icon-only buttons without `aria-label` (decorative icons: `aria-hidden`).
+- Removing outlines without an equivalent `focus-visible` style.
+- Inconsistent radius or gap within one list or one modal.
+
+## Cursor setup
+
+The committed skill path is `.opencode/skills/textile-design/`. For Cursor, create a symlink (ignored by git): see [../README.md](../README.md).
+
+## Additional resources
+
+- [tokens.md](tokens.md) — semantic colors, proposed radii/motion/fonts, spacing vocabulary.
+- [motion.md](motion.md) — durations, easings, reduced motion.
+- [a11y.md](a11y.md) — Electron, custom title bar, ARIA recipes, VoiceOver smoke test.
+- [components.md](components.md) — patterns and migration notes.
diff --git a/.opencode/skills/textile-design/a11y.md b/.opencode/skills/textile-design/a11y.md
new file mode 100644
index 0000000..739ee5c
--- /dev/null
+++ b/.opencode/skills/textile-design/a11y.md
@@ -0,0 +1,53 @@
+# Accessibility (Textile, Electron renderer)
+
+## Mental model
+
+The renderer is **Chromium**. Follow the same baseline as a SPA:
+
+- Full **keyboard** operation for chrome, modals, and settings.
+- Visible **focus** for every focusable control.
+- Correct **roles** and **ARIA** for dialogs, switches, lists, and tabs (when introduced).
+- **Color contrast** for text and icons against `background` / surfaces (WCAG 2.2 AA: 4.5:1 normal text, 3:1 large text/UI graphics where applicable).
+
+Screen reader testing: **VoiceOver on macOS** (primary platform today).
+
+## Electron-specific
+
+- **Window Controls Overlay / custom title bar:** any interactive control in the drag region must use `WebkitAppRegion: 'no-drag'` so clicks reach the button (see `AppTitleBar`). Do not place the only copy of an action inside a pure drag region.
+- **Native menus and accelerators:** when features move to the OS menu, keep **accessible names** in the renderer in sync so VoiceOver and keyboard users are not worse off than menu-only users.
+- **Modal dialogs:** backdrop + panel should trap focus in the dialog while open, restore focus on close, and block inert content (future hardening—today verify tab order manually).
+
+## Patterns in the codebase
+
+| Pattern | Expectation |
+|---------|-------------|
+| **Dialog** | `role="dialog"`, `aria-modal="true"`, `aria-label` or labelled-by; Esc to close when appropriate. |
+| **Icon-only button** | `aria-label` on `<button>`; `aria-hidden` on decorative `<svg>`. |
+| **Toggle / switch** | `role="switch"`, `aria-checked`, `aria-label` (see theme control in `SettingsModal`). |
+| **Sidebar toggle** | `aria-controls` pointing at sidebar `id`, `aria-pressed` for open state. |
+| **Decorative icons** | `aria-hidden` on SVG when adjacent text conveys meaning. |
+| **Lists of actions** | Prefer native list semantics (`role="list"` / `listitem`) or ensure roving tabindex if building composite widgets. |
+
+## Focus rings
+
+Use `focus-visible` (not `focus`) so mouse users do not see a ring on every click. Pair `outline-none` with an explicit ring or outline (see file row button in `AppSidebar`).
+
+## Hit targets
+
+Aim for at least **44×44px** for primary chrome controls where layout allows. If visual size is smaller, expand the interactive padding (`p-1.5` on a `size-4` icon ≈ 32px—acceptable for dense chrome; avoid going tighter without a design pass).
+
+## VoiceOver smoke test (manual)
+
+1. Turn on VoiceOver (Cmd+F5).
+2. **Title bar:** toggle sidebar—announce label changes, button remains activatable.
+3. **Open Settings** (⌘,): focus lands in dialog; tab cycles **within** dialog; Close works.
+4. **Settings sidebar:** category buttons announce state (consider `aria-current="true"` on selected category—future improvement).
+5. **Theme switch:** announces as switch; toggling updates `aria-checked`.
+6. **Editor:** placeholder and content are readable; focus ring visible in `EditPad`.
+
+## Further reading
+
+- [Electron accessibility](https://www.electronjs.org/docs/latest/tutorial/accessibility)
+- [WCAG 2.2](https://www.w3.org/TR/WCAG22/)
+
+Return to [SKILL.md](SKILL.md).
diff --git a/.opencode/skills/textile-design/components.md b/.opencode/skills/textile-design/components.md
new file mode 100644
index 0000000..7592f46
--- /dev/null
+++ b/.opencode/skills/textile-design/components.md
@@ -0,0 +1,72 @@
+# Component patterns (Textile)
+
+Reference implementations live under `src/components/` unless noted.
+
+## Modal shell
+
+**Reference:** `Modal.tsx`
+
+- Overlay: dim + optional blur; `role="dialog"`, `aria-modal="true"`, `aria-label`.
+- Panel: `rounded-lg`, `border-border`, `shadow-xl`, `max-w-[92vw]`.
+- Header row: `h-11`, `border-b`, title centered, close control `aria-label="Close modal"`, icon `aria-hidden`.
+
+## Settings layout
+
+**Reference:** `SettingsPane.tsx` — sidebar `w-60`, `p-3`, `border-r`; main `p-5`.
+
+## List row (file / nav)
+
+**Reference:** `AppSidebar.tsx` (file buttons)
+
+- `flex w-full items-center gap-2 rounded-md px-2 py-1.5 text-left text-sm`
+- Icon: `size-4 shrink-0`, muted `text-foreground/50`
+- Selection: `aria-current="true"`, `bg-border/50`
+- Focus: `outline-none focus-visible:ring-2 focus-visible:ring-accent/50`
+
+## Icon-only control (chrome)
+
+**Reference:** `AppTitleBar.tsx` (sidebar toggle), `Modal.tsx` (close)
+
+- Button: `rounded` or `rounded-md` + `p-1` / `p-1.5`
+- `aria-label` describing action; `aria-pressed` if toggle
+- SVG decorative: `aria-hidden`
+
+## Primary / secondary buttons
+
+**Primary CTA:** `bg-primary text-primary-foreground`, adequate padding (`px-3 py-2`), optional `hover:opacity-90`, `disabled:opacity-50`.
+
+**Secondary / ghost:** `border-border bg-background text-foreground hover:bg-border/30` with `rounded-md` and `border` where shown as a pill-shaped outline button.
+
+**Migrate:** `SettingsModal` “Sign in” uses `rounded` + `text-xs`—consider `rounded-md` + `text-sm` for consistency with inputs and touch targets.
+
+## Form fields
+
+**Reference:** `SettingsModal` account input
+
+- Input: `rounded-md border border-border bg-background px-3 py-2 text-sm`
+- Associate `<label htmlFor>` with input `id`
+
+## Editor surface
+
+**Reference:** `EditPad.tsx`
+
+- 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.
+
+## Theme switch
+
+**Reference:** `SettingsModal.tsx`
+
+- `role="switch"`, `aria-checked`, `aria-label`
+- `rounded-full` track; knob uses `transition-transform` + `duration-500` (see [motion.md](motion.md) for reduced-motion considerations).
+
+## Migration / consistency backlog
+
+| Item | Suggestion |
+|------|------------|
+| Settings category rows (`rounded` vs `rounded-md`) | Use `rounded-md` to match `AppSidebar` rows |
+| “Sign in” sizing | Align with `text-sm` + `rounded-md` where it is a primary action |
+| Settings category selected state | Add `aria-current="true"` on active category button |
+| Modal focus trap | Add roving focus / focus trap library or manual implementation |
+
+Return to [SKILL.md](SKILL.md).
diff --git a/.opencode/skills/textile-design/motion.md b/.opencode/skills/textile-design/motion.md
new file mode 100644
index 0000000..371e976
--- /dev/null
+++ b/.opencode/skills/textile-design/motion.md
@@ -0,0 +1,42 @@
+# Motion (Textile)
+
+## Principles
+
+- **Calm:** one clear transition per state change; avoid staggered novelty animations on every mount.
+- **Purpose:** motion explains **where** something went (sidebar collapse, modal open, theme toggle) or **that** state changed—not decoration.
+- **Performance:** prefer `transform` and `opacity` for high-frequency effects; avoid `transition-all`. Be cautious animating `width` on large content (sidebar uses width but keeps inner width fixed—acceptable pattern).
+
+## Built-in baseline (`src/index.css`)
+
+Global transition on `*`:
+
+- Properties: `background-color`, `color`, `border-color`, `fill`, `stroke`, `box-shadow`
+- Duration: **320ms**
+- Easing: `ease-in-out`
+- **`prefers-reduced-motion: reduce`:** duration forced to **0ms** for those rules
+
+Any **additional** motion (transform, width, layout) must respect reduced motion: pair with `@media (prefers-reduced-motion: reduce)` and cut duration/transform, or supply an instant alternative.
+
+## Durations in use today
+
+| Surface | Duration | Easing | Location |
+|---------|----------|--------|----------|
+| Theme colors / borders | 320ms | ease-in-out | Global `@layer base` |
+| Sidebar width | 200ms (width), 320ms (colors) | ease-out / ease-in-out | `AppSidebar` inline `style` |
+| Theme switch knob | 500ms | ease-in-out | `SettingsModal` `transition-transform` |
+
+Proposed standard names: `--motion-fast` (160ms), `--motion-base` (320ms), `--motion-slow` (500ms)—see [tokens.md](tokens.md).
+
+## Do
+
+- Use **explicit** `transition-property` lists when overriding globals on an element.
+- Use **short** durations for spatial layout (sidebars, drawers); keep **320ms** for palette/border changes so theme toggles feel soft, not sluggish.
+- Test with macOS “Reduce motion” enabled (System Settings → Accessibility → Display).
+
+## Do not
+
+- `transition-all` (hard to reason about and expensive).
+- Long bounce/elastic easing on chrome (reserve personality for rare celebratory moments, if any).
+- Animations that block reading or input (no infinite distracting loops in chrome).
+
+Return to [SKILL.md](SKILL.md).
diff --git a/.opencode/skills/textile-design/tokens.md b/.opencode/skills/textile-design/tokens.md
new file mode 100644
index 0000000..ebadcfd
--- /dev/null
+++ b/.opencode/skills/textile-design/tokens.md
@@ -0,0 +1,94 @@
+# Design tokens (Textile)
+
+## Current semantic colors (`src/index.css`)
+
+Defined on `:root` and overridden on `:root[data-theme='dark']`, then exposed via `@theme` as Tailwind colors:
+
+| Variable | Tailwind utilities |
+|----------|---------------------|
+| `--semantic-bg` | `bg-background` |
+| `--semantic-fg` | `text-foreground` |
+| `--semantic-primary` | `bg-primary`, `text-primary`, ring usage as needed |
+| `--semantic-primary-fg` | `text-primary-foreground` |
+| `--semantic-accent` | `text-accent`, `bg-accent` (if used) |
+| `--semantic-border` | `border-border`, hairline dividers |
+| `--semantic-destructive` | `text-destructive`, `bg-destructive` (if used) |
+
+**Rule:** components reference **Tailwind utilities**, not `--semantic-*` directly, except inside global CSS or when defining new `@theme` entries.
+
+## Proposed additions (document only — implement in a later PR)
+
+These tighten theming and reduce repeated opacity hacks.
+
+### Surfaces and muted text
+
+```css
+:root {
+  --semantic-surface: oklch(0.97 0 0); /* example: slightly above bg */
+  --semantic-muted-fg: oklch(0.45 0 0);
+}
+:root[data-theme='dark'] {
+  --semantic-surface: oklch(0.22 0.02 260);
+  --semantic-muted-fg: oklch(0.72 0.02 260);
+}
+```
+
+Then map in `@theme` (e.g. `--color-muted-foreground: var(--semantic-muted-fg)`) and migrate `text-foreground/60` call sites gradually.
+
+### Radii (align with existing Tailwind usage)
+
+| Token (proposed) | Value | Tailwind mapping | Use for |
+|------------------|-------|------------------|---------|
+| `--radius-sm` | 4px | `rounded` | Compact icon hit areas, small chips |
+| `--radius-md` | 6px | `rounded-md` | Inputs, list rows, `EditPad` container |
+| `--radius-lg` | 10px | `rounded-lg` | Modal panels, large cards |
+| — | pill | `rounded-full` | Switches, avatars |
+
+**Consistency rule:** within a single scrollable list or form, use **one** radius tier for sibling controls.
+
+### Motion (proposed CSS variables)
+
+| Token | ms | Notes |
+|-------|-----|------|
+| `--motion-fast` | 160 | Sidebar width, small positional tweens |
+| `--motion-base` | 320 | Matches global transition in `@layer base` today |
+| `--motion-slow` | 500 | Theme toggle thumb (`SettingsModal`) |
+
+Wire to Tailwind in a later PR (e.g. `@theme { --duration-base: var(--motion-base); }`) so components use `duration-base` instead of magic numbers.
+
+### Typography (future theme fonts)
+
+```css
+:root {
+  --font-sans: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
+  --font-serif: ui-serif, Georgia, Cambria, 'Times New Roman', Times, serif;
+  --font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+}
+body {
+  font-family: var(--font-sans);
+}
+```
+
+Until this lands, keep the stack in `src/index.css` `body` as the single source of truth.
+
+## Spacing vocabulary (Tailwind, no new tokens)
+
+Use these defaults unless a layout clearly needs an exception:
+
+| Context | Classes |
+|---------|---------|
+| Icon size (inline, lists) | `size-4` |
+| Icon ↔ label | `gap-2` |
+| List / nav row | `px-2 py-1.5` |
+| Icon button (title bar, modal close) | `p-1` or `p-1.5` with `rounded` |
+| Sidebar / tight panels | `p-3`, section gaps `gap-4` |
+| Settings main column | `p-5` (`SettingsPaneLayout`) |
+| Dense vertical stacks | `space-y-1`–`space-y-4` |
+
+## Migration notes (current codebase)
+
+- **Aligned:** `Modal` uses `rounded-lg`; `AppSidebar` file rows use `rounded-md`, `gap-2`, `size-4`; `EditPad` wrapper uses `rounded-md border`.
+- **Unify later:** `SettingsModal` category buttons use `rounded` while file rows use `rounded-md`—pick `rounded-md` for parity (see [components.md](components.md)).
+- **Primary actions:** `Sign in` uses `rounded` + `text-xs`; consider `rounded-md` + `text-sm` for touch/readability when touching that flow.
+
+Return to [SKILL.md](SKILL.md).
-- 
2.51.2