Spec — IDE integration

Facet Develop of Koder Design. Cross-link with tools/design-kit-export.kmd.

Source ticket: meta/docs/stack#021. Spec stays here; impl distributed across IDE-specific tickets in projects/koder-stack/.

Target IDEs

Shared LSP server

Single LSP server (koder-design-lsp) powers all IDEs that speak LSP. Implements:

• textDocument/hover — spec preview
• textDocument/completion — token autocomplete
• textDocument/codeAction — quick fixes (replace hardcoded color with token)
• textDocument/publishDiagnostics — drift detection warnings

LSP lives at engines/sdk/koder-design-lsp/ (new repo / module); written in Go for distribution as a single binary.

Per-IDE extensions are thin wrappers: they install the LSP binary, spawn it as a subprocess, and forward requests.

R1 — Spec preview on hover

When user hovers over a Koder widget reference in source code:

KoderTitleBar(   // hover here
  ...
)

LSP returns Hover content:

KoderTitleBar — Custom title bar for desktop variants
─────────────────────────────────────────────────────
Spec: specs/desktop-apps/title-bar-double-click.kmd

Drag in non-interactive area moves window; double-tap
toggles maximize. Uses `koder_kit` v0.16.0+.

[Open spec on kds.koder.dev ↗]

Hover contents include:

• Component name + 1-sentence summary
• Spec file path
• 1 paragraph of R1 (the canonical rule)
• Link to live spec page on kds.koder.dev

Recognition:

• Symbols matching Koder<Name> from koder_kit / koder_web_kit imports
• Token references like KoderTokens.surfacePrimary
• HTML custom elements <koder-*> in web sources

R2 — Token autocomplete

When user types in a context expecting a color value:

Suggestion includes:

• Token name
• Hex preview swatch in completion popup
• Light + dark hex side-by-side
• Light + dark contrast against current surface (info)

R3 — Drift detection

When source contains a hardcoded color that does NOT match any token:

Container(
  color: Color(0xFF1976D2),  // ← yellow underline
)

Diagnostic:

Koder Design drift: hardcoded color #1976D2 has no matching token.
- Closest token: KoderTokens.surfacePrimary (#1976D2 in material3 light)
- Quick fix: replace with KoderTokens.surfacePrimary

Severity: warning by default; configurable via workspace settings.

Detection scope:

• Files declaring koder_kit / koder_web_kit / koder-design imports → drift detection active
• Other files → off (don't false-positive non-Koder code)

R4 — Quick fixes

Code actions provided:

• Replace hardcoded color with token — replaces with closest matching KoderTokens.*
• Open spec — opens the matching component spec in browser
• Insert Koder import — when a Koder* widget is used but the import is missing

R5 — Live theme preview

(Advanced feature; ships in v2.)

When the workspace contains a Koder app, the extension renders a preview pane showing how the current source renders under the selected preset.

• Powered by the same WASM module used by tools/theme-builder.kmd
• Updates live as code changes
• Preset switcher in pane header

R6 — Configuration

Workspace settings (.vscode/settings.json / .zed/settings.json):

{
  "koder.design.preset": "material3",
  "koder.design.driftDetection": "warning",
  "koder.design.driftSensitivity": 10,
  "koder.design.hoverPreview": true,
  "koder.design.tokensVersion": "auto"
}

R7 — Distribution

Extension auto-update from the marketplace; LSP binary downloaded on first activation per koder.design.tokensVersion.

R8 — Telemetry

Per errors/reporting.kmd and policies/identity-data-retention.kmd contracts:

• Default: OFF
• Opt-in toggle in extension settings
• Reports: extension activation count, drift detection hit count, token autocomplete acceptance rate
• No file contents, no code, no PII — only counts + extension version

R9 — Accessibility

• Hover panels: keyboard-accessible (Ctrl+K hover, Escape closes)
• Diagnostics: screen reader announces drift warnings
• Spec links: have full accessible names (not just "Open ↗")
• Token swatches: include hex text label (not color-only)

R10 — Versioning

LSP + extensions follow Koder Design semver:

• koder-design-lsp v1.x.0 matches koder-design v1.x.0 token schema
• Extensions can run with LSP one minor version newer / older
• Major LSP bump = extension hard-requires matching major

R11 — Forbidden patterns

• ❌ Sending source code to a remote server (drift + hover MUST run locally via LSP)
• ❌ Auto-applying quick fixes without user action (always user-driven)
• ❌ Diagnostics with severity error by default (yellow / warning is correct level for drift)
• ❌ Hardcoded token list in extension (always pulled from @koder/design-tokens package)
• ❌ Telemetry that ships file content / paths / identifiers

Cross-link

• tools/design-kit-export.kmd — token source (extension consumes @koder/design-tokens)
• develop/code-samples-toggle.kmd — analogous cross-cutting devexp
• themes/color-roles.kmd — token schema for autocomplete
• errors/reporting.kmd — telemetry contract

Implementation tracking

Per-IDE impl tickets (in projects/koder-stack/):

• #132 — VSCode extension (Koder Design preview + spec browser)
• #133 — Zed extension
• #134 — Drift detection lint rule (LSP capability)
• #135 — Token autocomplete LSP capability
• #136 — JetBrains plugin (Tier 2, future)
• Shared LSP server lives at engines/sdk/koder-design-lsp/

Ticket meta/docs/stack#021 closed as consolidated-into-this-spec plus the per-IDE tickets above.