kokoro-tuner

Tune your app's look by hand — and keep your own design laws in one file.

1. Tune — sliders and color pickers for every color, size, spacing and radius in your app's look block. Each move rewrites only those values in your file, so your own dev server redraws the app while you watch. No AI, no key, nothing is sent anywhere.
2. Design laws — one file of your own look rules (~/.kokoro/laws.md). Specs made with npx kokoro-baton include the laws you marked [○], so the AI that builds your app follows your taste, not its default.
3. Law candidates — from what you actually changed while tuning, get suggestions for laws you keep applying (uses your own Anthropic API key).

npx kokoro-tuner ./my-app          # open the tuner (no key needed)
npx kokoro-tuner laws              # where your laws file and decisions are
export ANTHROPIC_API_KEY=sk-ant-...
npx kokoro-tuner candidates        # suggest laws from your decisions

The look block

The tuner looks for one block of CSS variables, between these two lines, in any file of your app (CSS, HTML, JSX, Vue, Svelte…):

/* ==== STYLE START ==== */
:root {
  --bg: #1a1a1f;         /* background */
  --bg-btn: #2a2a32;     /* button background */
  --bg-btn-hover: #3a3a46; /* button background on hover */
  --radius-btn: 8px;     /* button corner radius */
}
/* ==== STYLE END ==== */

• The comment after each value is shown as its name in the tuner.
• Values whose names end with a state (-hover, -active, -pressed, -selected, -focus, -disabled…) are grouped under their main value. Move the main one and they follow, keeping their difference. Open the group to fine-tune one.
• The two marker lines are CSS comments: keep them inside <style> (or your CSS file).

Specs written by npx kokoro-baton already ask the AI to put the look in this block.

Tuning

npx kokoro-tuner [app folder or file] [--lang ja|en] [--no-open] [--port N]

• Opens a page on 127.0.0.1. Run your dev server as usual and watch the app change as you move things.
• Overall color (lightness, saturation, hue) shifts every color at once.
• Decide these values keeps them. If the folder has kokoro-spec.md, they are added to "Decisions made while building", so the next build (and Kokoro Aegis) uses the same values. The decision is also recorded in ~/.kokoro/decisions.json.
• Put back, and stopping with Ctrl+C, return the file to the last decided values.
• If something else (for example your AI coding tool) changes the file while you tune, the tuner does not overwrite it: it reloads the file instead.
• Not here: highlighting where a value is used (that needs to run inside the app, which the Kokoro OS screens do).

Design laws

~/.kokoro/laws.md is a plain Markdown file you can edit:

- [○] Don't paint buttons pure black
- [?] Keep a lot of white space
- [×] Use only one accent color

• [○] laws go into specs; [?] and [×] don't. Change the mark to decide.
• If you use Kokoro OS, its Baton screen can export your laws to this file and import your edits back (your account stays the source).

Law candidates

npx kokoro-tuner candidates [--lang ja|en]

• Needs your decisions from at least 3 apps, or 10 decisions.
• Each candidate comes with the decisions it is based on. Candidates are added to your laws file as [?] — change them to [○] to make them laws.
• AI costs are billed to your Anthropic API key. Your decisions go straight from your machine to Anthropic — not through the Kokoro OS server — and are not stored.

License

PolyForm Shield 1.0.0 — see LICENSE.

日本語

作品の見た目を手で整え、自分のデザインの法則を 1 枚の紙に持つ道具です。

• npx kokoro-tuner ./作品のフォルダ … 見た目を動かす画面を開きます（AI なし・キー不要）。動かすたびにファイルの STYLE の塊の値だけを書き換えるので、いつもの開発サーバで見ながら整えられます。「この値で決める」で kokoro-spec.md の「作りながら決めたこと」に足し、決めた記録を ~/.kokoro/decisions.json に残します。
• npx kokoro-tuner laws … 法則の紙（~/.kokoro/laws.md）と決めた記録の場所・数。[○] の法則だけが npx kokoro-baton の指示書に入ります。
• npx kokoro-tuner candidates … 決めた記録（作品 3 つか決定 10 回）から、法則の候補を [?] で紙に足します（AI・あなたの Anthropic のキー・あなたのパソコンから直接 Anthropic に送り、Kokoro OS のサーバーは通りません）。
• Kokoro OS を使っていれば、Baton の「デザインの法則」で紙に書き出し・紙から取り込みができます（元はアカウント）。