# design-sync notes — KKTerm

KKTerm is a Tauri terminal **app**, not a component-library package. There is no
library `dist/` of exportable components, so this sync runs the package shape in
**synth-entry mode** against a hand-written barrel.

## Layout (off the converter's default path)
- `entry.tsx` — barrel re-exporting the curated components + the dialog primitive
  family. Passed to the converter via `--entry .design-sync/entry.tsx`. With this
  entry, `PKG_DIR` resolves to the repo root (the named `package.json`).
- `componentSrcMap` pins exactly the curated set; with no `.d.ts` and a real
  `--entry`, that map is the whole component list (no synth-from-all-src blowup).
- `kkterm-ds.css` — flattened stylesheet, the `cssEntry`. Generated by
  `build-css.mjs` from the app's real CSS (colorSchemes/dialogs/moduleHeader/
  colorPalettePicker + the toggle-switch slice). **Re-run `node .design-sync/build-css.mjs`
  whenever those sources change**, then rebuild.
- Tokens come from `colorSchemes.css` `:root` (light theme default — coherent
  Apple-esque palette). Brand fonts: Inter + JetBrains Mono, re-declared in the
  cssEntry preamble with `.design-sync/`-relative `url()`s so `extractFonts` copies
  them into `fonts/`.

## Curated set (first cut — "curated small set first")
Sheet, ConfirmSheet, ToggleSwitch, ModuleHeader, ColorPalettePicker.
The bundle (`window.KKTerm`) also carries the full dialog family (Btn, Field,
TextInput, Select, Switch, Segmented, Group, GRow, Stepper, Swatches, ConnTile,
DialogShell, Actions, DIcon…) so previews can compose realistically.

## Project
Synced to **KKTerm Design System** — `projectId` `8f7bb0f3-c9f0-4632-b0db-5fa06b1f9bec`
(recorded in config.json). https://claude.ai/design/p/8f7bb0f3-c9f0-4632-b0db-5fa06b1f9bec

## Accepted substitutions
- **[FONT_MISSING] "SF Pro Text" / "SF Pro Display"** — these appear only as the
  first entries of the body font stack (`-apple-system, … "SF Pro Text", … Inter`).
  SF Pro is Apple-proprietary and can't ship; the stack degrades to the shipped
  **Inter**, which is exactly the app's own platform-aware behavior (SF Pro on
  macOS, Inter elsewhere). Accepted — not an action item.

## Known render warns
- `[FONT_MISSING] "SF Pro Text", "SF Pro Display"` — accepted, see above.

## Guidelines
- `guidelinesGlob` is pinned to `["docs/DESIGN_LANGUAGE.md"]`. The default glob
  swept in 18 unrelated app docs (ROADMAP/PRD/ARCHITECTURE/…) — don't widen it
  without intent; those are app internals, not design guidelines.

## Re-sync risks
- `kkterm-ds.css` is generated — if app CSS changes and `build-css.mjs` isn't
  re-run, the synced look goes stale silently. Re-run it first on every sync.
- ConfirmSheet/ColorPalettePicker call `useTranslation` (react-i18next). With no
  i18n provider it returns keys; previews pass explicit labels to avoid showing
  raw keys. If a card shows `common.cancel`-style text, pass the label as a prop.
- The toggle-switch CSS is inlined in `build-css.mjs` (not sliced from
  settings.css). If the app restyles the toggle, update the inlined block.
