token-lens

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import type { LensElement, LensReport, LensToken } from '../types'
5import { check, cssTokens, jsonTokens, parseProbe, probeScript, PROPERTIES, resolveTokens } from './lens'
6
7const PANE = 'token-lens'
8const TITLE = 'トークン照合'
9const BROWSER_TOOL = /^mcp__(?:remote-devices__)?claude-in-chrome__/
10const JS_TOOL = 'mcp__claude-in-chrome__javascript_tool'
11const MAX_FILES = 200
12
13const tokens = atom({ plugin: 'token-lens', key: 'tokens' } as const, [] as LensToken[])
14const report = atom({ plugin: 'token-lens', key: 'report' } as const, null as LensReport | null)
15const tabId = atom({ plugin: 'token-lens', key: 'tabId' } as const, null as number | null)
16
17async function git($: EngineInterface, root: string, argv: string[]): Promise<string | undefined> {
18  const ran = await $.process.run(['git', ...argv], { cwd: root, timeoutMs: 15_000 }).catch(() => undefined)
19  return ran?.exitCode === 0 ? ran.stdout : undefined
20}
21
22/** The repository's tokens: custom properties and SCSS variables of its stylesheets, and tokens JSON. */
23async function loadTokens($: EngineInterface): Promise<LensToken[]> {
24  const root = (await $.session.repo())?.root ?? (await $.session.cwd())
25  const listed = await git($, root, ['ls-files', '--', '*.css', '*.scss', '*.sass', '*.less', '*tokens*.json', '*.tokens'])
26  const files = (listed ?? '').split('\n').filter(path => path !== '' && !path.includes('node_modules/') && !/\.min\.css$/.test(path)).slice(0, MAX_FILES)
27  const raw: { name: string; value: string; source: string }[] = []
28  for (const path of files) {
29    const text = await $.fs.read(`${root}/${path}`).then(String).catch(() => undefined)
30    if (text === undefined || text.length > 2_000_000) continue
31    if (path.endsWith('.json') || path.endsWith('.tokens')) {
32      try {
33        raw.push(...jsonTokens(JSON.parse(text), path))
34      } catch {
35        // Not JSON after all: nothing to read from it.
36      }
37    } else raw.push(...cssTokens(text, path))
38  }
39  const list = resolveTokens(raw)
40  await update($, tokens, () => list)
41  return list
42}
43
44function elementsOf(probe: NonNullable<ReturnType<typeof parseProbe>>, list: readonly LensToken[]): LensElement[] {
45  return probe.elements.map(el => ({
46    label: `${el.label}${el.text ? ` 「${el.text}」` : ''}`,
47    checks: PROPERTIES.map(property => check(property, el.style[property] ?? '', list)).filter(one => one.status !== 'skip'),
48  }))
49}
50
51const offCount = (r: LensReport) => r.elements.reduce((n, el) => n + el.checks.filter(c => c.status === 'off').length, 0)
52
53export const register: Register = on => {
54  on('session.start', async ($, e, next) => {
55    await $.command.register({
56      name: 'token-lens',
57      description: 'ブラウザの要素の色・余白・字体を登録済みデザイントークンと照合（/token-lens <セレクタ> · 引数なしでページ上の選択範囲 · tokens · reload）',
58      argumentHint: '[セレクタ | tokens | reload]',
59    })
60    return next(e)
61  })
62
63  // The tab Claude drives: a probe goes to the same one.
64  on('tool.call', async ($, e, next) => {
65    const ran = await next(e)
66    const id = (e as unknown as { tabId?: unknown }).tabId
67    if (BROWSER_TOOL.test(String(e.tool)) && typeof id === 'number' && ran.deny === undefined) await update($, tabId, () => id)
68    return ran
69  }).catch(($, e, next) => next(e))
70
71  on('command.run', { command: 'token-lens' }, async ($, e) => {
72    const args = e.args.trim()
73    if (args === 'reload' || args === 'tokens') {
74      const list = args === 'reload' || (await read($, tokens)).length === 0 ? await loadTokens($) : await read($, tokens)
75      const by = (kind: string) => list.filter(t => t.kind === kind).length
76      return { text: `🎨 トークン ${list.length}件（色 ${by('color')} · 長さ ${by('length')} · 字体 ${by('font')}）${list.length === 0 ? ' — CSS 変数・SCSS 変数・tokens JSON が見つかりません' : ''}` }
77    }
78    const list = (await read($, tokens)).length > 0 ? await read($, tokens) : await loadTokens($)
79    const tab = await read($, tabId)
80    const at = await $.clock.now()
81    await $.ui.open({ id: PANE, title: TITLE })
82    if (tab === null) {
83      await update($, report, () => ({ at, query: args, elements: [], note: 'Claude in Chrome で操作中のタブがありません。先に Claude にページを開かせてください。' }))
84      return { text: '🎨 照合するタブがありません（Claude in Chrome でページを開いてから実行してください）。' }
85    }
86    const ran = await $.tool.call({ tool: JS_TOOL, action: 'javascript_exec', text: probeScript(args), tabId: tab } as never).catch(err => ({ deny: String(err) }))
87    if (ran.deny !== undefined || ran.isError === true) {
88      const why = ran.deny ?? ran.text ?? ''
89      await update($, report, () => ({ at, query: args, elements: [], note: `ページのスタイルを読めませんでした: ${why.slice(0, 200)}` }))
90      return { text: '🎨 ページのスタイルを読めませんでした。' }
91    }
92    const probe = parseProbe(ran.text ?? '')
93    if (probe === undefined || probe.elements.length === 0) {
94      const note = args === '' ? 'ページ上でテキストを選択してから実行するか、セレクタを指定してください。' : `「${args}」に合う要素がありません。`
95      await update($, report, () => ({ at, query: args, elements: [], note }))
96      return { text: `🎨 ${note}` }
97    }
98    const result: LensReport = { at, query: args, ...(probe.url === undefined ? {} : { url: probe.url }), elements: elementsOf(probe, list), ...(list.length === 0 ? { note: 'トークンが見つからないため、すべて独自値として出ます（/token-lens tokens）。' } : {}) }
99    await update($, report, () => result)
100    const lines = result.elements.flatMap(el => [
101      `${el.label}`,
102      ...el.checks.filter(c => c.status === 'off').map(c => `  ✗ ${c.property}: ${c.value}${c.nearest ? `（最寄り ${c.nearest.name} = ${c.nearest.value}、差 ${c.nearest.distance}）` : ''}`),
103    ])
104    return { text: [`🎨 ${result.elements.length}要素 · 独自値 ${offCount(result)}件`, ...lines].join('\n') }
105  })
106
107  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
108    const { Box, Text } = $.ui.resolve(e)
109    const shown = await read($, report)
110    if (shown === null) return <Text dimColor>/token-lens &lt;セレクタ&gt; で要素をトークンと照合します。</Text>
111    const room = Math.max(4, (e.props.scroll.bodyRows ?? 24) - 3)
112    const rows = shown.elements.flatMap(el => [
113      { key: `h-${el.label}`, text: el.label, color: undefined as string | undefined, bold: true },
114      ...el.checks.map(c => ({
115        key: `${el.label}-${c.property}`,
116        text: c.status === 'token' ? `  ✓ ${c.property}: ${c.value} = ${c.tokens.slice(0, 2).join(', ')}` : `  ✗ ${c.property}: ${c.value}${c.nearest ? `  → 最寄り ${c.nearest.name} (${c.nearest.value}, 差 ${c.nearest.distance})` : ''}`,
117        color: c.status === 'token' ? 'green' : 'yellow',
118        bold: false,
119      })),
120    ])
121    return (
122      <Box flexDirection="column">
123        <Text bold wrap="truncate-end">{`🎨 ${shown.query || '選択範囲'}${shown.url ? ` · ${shown.url}` : ''} · 独自値 ${offCount(shown)}件`}</Text>
124        {shown.note !== undefined && <Text color="yellow">{shown.note}</Text>}
125        {rows.slice(0, room).map(row => (
126          <Text key={row.key} wrap="truncate-end" color={row.color} bold={row.bold}>
127            {row.text}
128          </Text>
129        ))}
130        {rows.length > room && <Text dimColor>{`…ほか ${rows.length - room} 行`}</Text>}
131      </Box>
132    )
133  })
134}
135

1// The lens, pure: tokens read from CSS, SCSS and tokens JSON, values normalised, and an
2// element's computed style checked against them.
3
4import type { LensCheck, LensToken, LensTokenKind } from '../types'
5
6export type Rgba = [number, number, number, number]
7
8const NAMED: Record<string, Rgba> = { white: [255, 255, 255, 1], black: [0, 0, 0, 1], transparent: [0, 0, 0, 0], red: [255, 0, 0, 1], blue: [0, 0, 255, 1], green: [0, 128, 0, 1], gray: [128, 128, 128, 1], grey: [128, 128, 128, 1] }
9
10function hsl(h: number, s: number, l: number): [number, number, number] {
11  const k = (n: number) => (n + h / 30) % 12
12  const a = s * Math.min(l, 1 - l)
13  const f = (n: number) => l - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)))
14  return [Math.round(f(0) * 255), Math.round(f(8) * 255), Math.round(f(4) * 255)]
15}
16
17/** A CSS colour as RGBA: hex, rgb()/rgba() (commas or spaces), hsl()/hsla(), a few names. */
18export function parseColor(text: string): Rgba | undefined {
19  const value = text.trim().toLowerCase()
20  if (NAMED[value] !== undefined) return NAMED[value]
21  const hex = value.match(/^#([0-9a-f]{3,8})$/)?.[1]
22  if (hex !== undefined) {
23    const full = hex.length <= 4 ? [...hex].map(ch => ch + ch).join('') : hex
24    if (full.length !== 6 && full.length !== 8) return undefined
25    const n = (i: number) => parseInt(full.slice(i, i + 2), 16)
26    return [n(0), n(2), n(4), full.length === 8 ? Math.round((n(6) / 255) * 100) / 100 : 1]
27  }
28  const fn = value.match(/^(rgba?|hsla?)\(([^)]*)\)$/)
29  if (fn === null) return undefined
30  const parts = (fn[2] as string).split(/[\s,/]+/).filter(Boolean)
31  const num = (part: string | undefined, scale: number) => (part === undefined ? undefined : part.endsWith('%') ? (parseFloat(part) / 100) * scale : parseFloat(part))
32  const alpha = parts[3] === undefined ? 1 : (num(parts[3], 1) as number)
33  if ((fn[1] as string).startsWith('rgb')) {
34    const [r, g, b] = [num(parts[0], 255), num(parts[1], 255), num(parts[2], 255)]
35    if (r === undefined || g === undefined || b === undefined || [r, g, b].some(Number.isNaN)) return undefined
36    return [Math.round(r), Math.round(g), Math.round(b), alpha]
37  }
38  const [h, s, l] = [parseFloat(parts[0] ?? ''), (num(parts[1], 1) ?? NaN) as number, (num(parts[2], 1) ?? NaN) as number]
39  if ([h, s, l].some(Number.isNaN)) return undefined
40  return [...hsl(h, s, l), alpha]
41}
42
43/** A length in px: px, rem and em at 16px, unitless 0. */
44export function parseLength(text: string, rootPx = 16): number | undefined {
45  const m = text.trim().toLowerCase().match(/^(-?\d*\.?\d+)(px|rem|em)?$/)
46  if (m === null) return undefined
47  const n = parseFloat(m[1] as string)
48  if (m[2] === undefined) return n === 0 ? 0 : undefined
49  return m[2] === 'px' ? n : n * rootPx
50}
51
52const firstFamily = (text: string) => text.split(',')[0]?.trim().replace(/^['"]|['"]$/g, '').toLowerCase() ?? ''
53
54export function kindOf(value: string): LensTokenKind {
55  if (parseColor(value) !== undefined) return 'color'
56  if (parseLength(value) !== undefined) return 'length'
57  if (/^['"]?[A-Za-z][\w -]*['"]?\s*(?:,\s*['"]?[\w -]+['"]?\s*)+$/.test(value.trim()) || /\b(?:serif|sans-serif|monospace|system-ui)\b/.test(value)) return 'font'
58  return 'other'
59}
60
61/** `--name: value;` and `$name: value;` declarations of a stylesheet's lines. */
62export function cssTokens(text: string, source: string): { name: string; value: string; source: string }[] {
63  const out: { name: string; value: string; source: string }[] = []
64  for (const m of text.matchAll(/(?:^|[\s;{])(--[A-Za-z0-9_-]+|\$[A-Za-z][\w-]*)\s*:\s*([^;{}\n]+?)\s*(?:!default\s*)?(?:;|$)/gm)) {
65    out.push({ name: m[1] as string, value: (m[2] as string).trim(), source })
66  }
67  return out
68}
69
70/** Tokens of a design-tokens JSON (`{ color: { primary: { $value: "#..." } } }`, `value` too). */
71export function jsonTokens(json: unknown, source: string, path: string[] = []): { name: string; value: string; source: string }[] {
72  if (typeof json !== 'object' || json === null) return []
73  const node = json as Record<string, unknown>
74  const leaf = node.$value ?? node.value
75  if (typeof leaf === 'string' || typeof leaf === 'number') return [{ name: path.join('.'), value: String(leaf), source }]
76  return Object.entries(node).flatMap(([key, child]) => (key.startsWith('$') ? [] : jsonTokens(child, source, [...path, key])))
77}
78
79/** Tokens with `var(--x)`, `$x` and `{x.y}` references resolved, and their kind. */
80export function resolveTokens(raw: readonly { name: string; value: string; source: string }[]): LensToken[] {
81  const byName = new Map<string, string>()
82  for (const one of raw) if (!byName.has(one.name)) byName.set(one.name, one.value)
83  const resolve = (value: string, depth: number): string => {
84    if (depth > 6) return value
85    return value
86      .replace(/var\(\s*(--[\w-]+)\s*(?:,\s*([^)]+))?\)/g, (all, name: string, fallback?: string) => {
87        const found = byName.get(name)
88        return found !== undefined ? resolve(found, depth + 1) : (fallback?.trim() ?? all)
89      })
90      .replace(/^\$([\w-]+)$/, (all, name: string) => {
91        const found = byName.get(`$${name}`)
92        return found !== undefined ? resolve(found, depth + 1) : all
93      })
94      .replace(/^\{([\w.-]+)\}$/, (all, name: string) => {
95        const found = byName.get(name)
96        return found !== undefined ? resolve(found, depth + 1) : all
97      })
98  }
99  const seen = new Set<string>()
100  const out: LensToken[] = []
101  for (const one of raw) {
102    if (seen.has(one.name)) continue
103    seen.add(one.name)
104    const value = resolve(one.value, 0)
105    out.push({ name: one.name, value, kind: kindOf(value), source: one.source })
106  }
107  return out
108}
109
110export const PROPERTIES = [
111  'color',
112  'background-color',
113  'border-top-color',
114  'outline-color',
115  'margin-top',
116  'margin-right',
117  'margin-bottom',
118  'margin-left',
119  'padding-top',
120  'padding-right',
121  'padding-bottom',
122  'padding-left',
123  'row-gap',
124  'column-gap',
125  'border-top-left-radius',
126  'border-top-width',
127  'font-family',
128  'font-size',
129  'font-weight',
130  'line-height',
131  'letter-spacing',
132] as const
133
134const COLOR_PROPS = new Set(['color', 'background-color', 'border-top-color', 'outline-color'])
135const distance = (a: Rgba, b: Rgba) => Math.round(Math.sqrt((a[0] - b[0]) ** 2 + (a[1] - b[1]) ** 2 + (a[2] - b[2]) ** 2) + Math.abs(a[3] - b[3]) * 100)
136
137/** One property's computed value against the tokens. */
138export function check(property: string, value: string, tokens: readonly LensToken[]): LensCheck {
139  const skip: LensCheck = { property, value, status: 'skip', tokens: [] }
140  const v = value.trim()
141  if (v === '' || v === 'normal' || v === 'none' || v === 'auto') return skip
142  if (COLOR_PROPS.has(property)) {
143    const color = parseColor(v)
144    if (color === undefined || color[3] === 0) return skip
145    const scored = tokens.flatMap(t => {
146      const c = t.kind === 'color' ? parseColor(t.value) : undefined
147      return c === undefined ? [] : [{ t, d: distance(color, c) }]
148    })
149    const equal = scored.filter(one => one.d <= 1).map(one => one.t.name)
150    if (equal.length > 0) return { property, value: v, status: 'token', tokens: equal }
151    const best = scored.sort((a, b) => a.d - b.d)[0]
152    return { property, value: v, status: 'off', tokens: [], ...(best === undefined ? {} : { nearest: { name: best.t.name, value: best.t.value, distance: best.d } }) }
153  }
154  if (property === 'font-family') {
155    const family = firstFamily(v)
156    const equal = tokens.filter(t => (t.kind === 'font' || t.kind === 'other') && firstFamily(t.value) === family).map(t => t.name)
157    return equal.length > 0 ? { property, value: v, status: 'token', tokens: equal } : { property, value: v, status: 'off', tokens: [] }
158  }
159  if (property === 'font-weight') {
160    const equal = tokens.filter(t => /weight/i.test(t.name) && t.value.trim() === v).map(t => t.name)
161    return equal.length > 0 ? { property, value: v, status: 'token', tokens: equal } : tokens.some(t => /weight/i.test(t.name)) ? { property, value: v, status: 'off', tokens: [] } : skip
162  }
163  const px = parseLength(v)
164  if (px === undefined || px === 0) return skip
165  const scored = tokens.flatMap(t => {
166    const n = t.kind === 'length' ? parseLength(t.value) : undefined
167    return n === undefined ? [] : [{ t, d: Math.abs(n - px) }]
168  })
169  const equal = scored.filter(one => one.d < 0.5).map(one => one.t.name)
170  if (equal.length > 0) return { property, value: v, status: 'token', tokens: equal }
171  const best = scored.sort((a, b) => a.d - b.d)[0]
172  return { property, value: v, status: 'off', tokens: [], ...(best === undefined ? {} : { nearest: { name: best.t.name, value: best.t.value, distance: Math.round(best.d * 10) / 10 } }) }
173}
174
175/** The script run in the page: the computed style of the elements a selector picks, or of the selected text. */
176export function probeScript(selector: string): string {
177  return `(() => {
178  const selector = ${JSON.stringify(selector)};
179  let els = [];
180  if (selector) { els = Array.from(document.querySelectorAll(selector)).slice(0, 5); }
181  else {
182    const s = window.getSelection();
183    const n = s && s.rangeCount > 0 ? s.getRangeAt(0).commonAncestorContainer : null;
184    const el = n ? (n.nodeType === 1 ? n : n.parentElement) : null;
185    if (el && el !== document.body && el !== document.documentElement) els = [el];
186  }
187  const props = ${JSON.stringify(PROPERTIES)};
188  return JSON.stringify({ url: location.href, elements: els.map(el => {
189    const cs = getComputedStyle(el);
190    const style = {};
191    for (const p of props) style[p] = cs.getPropertyValue(p);
192    const cls = typeof el.className === 'string' ? el.className.trim().split(/\\s+/).slice(0, 3).join('.') : '';
193    return { label: el.tagName.toLowerCase() + (el.id ? '#' + el.id : '') + (cls ? '.' + cls : ''), text: (el.textContent || '').trim().slice(0, 30), style };
194  }) });
195})()`
196}
197
198export type Probe = { url?: string; elements: { label: string; text?: string; style: Record<string, string> }[] }
199
200/**
201 * The probe's answer, out of whatever text the tool wrapped it in: the object as it is, or as a
202 * JSON string literal (quotes inside its values escaped), each read by the JSON parser itself.
203 */
204export function parseProbe(text: string): Probe | undefined {
205  const read = (body: string): unknown => {
206    try {
207      const value: unknown = JSON.parse(body)
208      return typeof value === 'string' ? read(value) : value
209    } catch {
210      return undefined
211    }
212  }
213  const raw = text.indexOf('{"url"')
214  const quoted = text.indexOf('"{\\"url\\"')
215  const candidates = [
216    text.trim(),
217    raw >= 0 ? text.slice(raw, text.lastIndexOf('}') + 1) : '',
218    quoted >= 0 ? text.slice(quoted, text.lastIndexOf('}"') + 2) : '',
219  ]
220  for (const body of candidates) {
221    const value = body === '' ? undefined : read(body)
222    if (typeof value === 'object' && value !== null && Array.isArray((value as Probe).elements)) return value as Probe
223  }
224  return undefined
225}
226

1export type LensTokenKind = 'color' | 'length' | 'font' | 'other'
2
3/** A registered design token, its value resolved. */
4export type LensToken = { name: string; value: string; kind: LensTokenKind; source: string }
5
6/** One property of an element against the tokens. */
7export type LensCheck = {
8  property: string
9  value: string
10  /** token: equal to a token; off: a value no token has; skip: nothing to check (0, transparent, normal). */
11  status: 'token' | 'off' | 'skip'
12  /** The tokens it equals. */
13  tokens: string[]
14  /** For an off-token value, the closest token and how far off (colour distance, or px). */
15  nearest?: { name: string; value: string; distance: number }
16}
17
18export type LensElement = { label: string; checks: LensCheck[] }
19
20export type LensReport = { at: number; query: string; url?: string; elements: LensElement[]; note?: string }
21
22declare module 'claude-code' {
23  interface PluginState {
24    'token-lens': {
25      tokens: LensToken[]
26      report: LensReport | null
27      /** The browser tab Claude drove last, as its calls named it. */
28      tabId: number | null
29    }
30  }
31}
32