@rokkit/cli 1.1.1 → 1.1.5

package/dist/src/doctor.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Build the default named-token starter config source used by `doctor --fix`.
+ * @returns {string}
+ */
+export function defaultStarterSource(): string;
 /**
  * Run all doctor checks against the given filesystem adapter.
  * @param {{ exists: (p: string) => boolean, read: (p: string) => string, resolve: (p: string) => string }} fs
@@ -15,10 +20,41 @@ export function runChecks(fs: {
     fix: string;
     autoFix?: string;
 }>;
+/**
+ * Scan files for legacy z-scale utilities and suggest named-token equivalents.
+ * Advisory only — z-scale still resolves via the preset's back-compat layer.
+ * @param {Array<{ path: string, content: string }>} files
+ * @returns {{ count: number, byFile: Array<{ path: string, hits: Array<{ token: string, suggestion: string }> }> }}
+ */
+export function findLegacyZUtilities(files: Array<{
+    path: string;
+    content: string;
+}>): {
+    count: number;
+    byFile: Array<{
+        path: string;
+        hits: Array<{
+            token: string;
+            suggestion: string;
+        }>;
+    }>;
+};
+/**
+ * Validate a parsed rokkit config for the named-token system. All advisory (warn).
+ * @param {Record<string, unknown> | null} config
+ * @returns {Array<{ id: string, label: string, status: 'warn', fixable: false, fix: string }>}
+ */
+export function validateConfigShape(config: Record<string, unknown> | null): Array<{
+    id: string;
+    label: string;
+    status: "warn";
+    fixable: false;
+    fix: string;
+}>;
 /**
  * Interactive doctor command — validates project setup.
  * @param {{ fix?: boolean }} [opts]
  */
 export function doctor(opts?: {
     fix?: boolean;
-}): void;
+}): Promise<void>;

package/dist/src/init.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Serialize a rokkit config object to a JS module string with a header comment.
+ * @param {Record<string, unknown>} config
+ * @returns {string}
+ */
+export function serializeRokkitConfig(config: Record<string, unknown>): string;
 /**
  * Detect if the current directory is a SvelteKit project.
  * @param {string} cwd
@@ -22,25 +28,42 @@ export function generateChartConfig({ chartColors, chartShades }: {
     chartColors: string;
     chartShades: string;
 }): Record<string, unknown>;
+/**
+ * Build the Zen-Sumi OKLCH starter (ink-on-paper, dual-palette dark mode).
+ * @param {{ themes?: string[], defaultTheme?: string, switcher?: string,
+ *   includeChart?: boolean, chartColors?: string, chartShades?: string }} [opts]
+ * @returns {Record<string, unknown>}
+ */
+export function generateZenSumiConfig(opts?: {
+    themes?: string[];
+    defaultTheme?: string;
+    switcher?: string;
+    includeChart?: boolean;
+    chartColors?: string;
+    chartShades?: string;
+}): Record<string, unknown>;
+/**
+ * Build a Rokkit config object from the user's init choices.
+ * Emits the named-token `skin` shape (skin + colorSpace + tokens), plus
+ * optional `icons` and `chart` sections.
+ * @param {{ palette: string, customColors?: Record<string, string>, icons?: string,
+ *   iconPath?: string, iconStyle?: string, themes: string[], defaultTheme?: string,
+ *   switcher: string, includeChart?: boolean, chartColors?: string, chartShades?: string }} opts
+ * @returns {Record<string, unknown>}
+ */
 export function generateConfig({ palette, customColors, icons, iconPath, iconStyle, themes, defaultTheme, switcher, includeChart, chartColors, chartShades }: {
-    palette: any;
-    customColors: any;
-    icons: any;
-    iconPath: any;
-    iconStyle: any;
-    themes: any;
-    defaultTheme: any;
-    switcher: any;
-    includeChart: any;
-    chartColors: any;
-    chartShades: any;
-}): {
-    colors: Record<string, unknown>;
-    themes: any;
-    defaultTheme: any;
-    switcher: any;
-    storageKey: string;
-};
+    palette: string;
+    customColors?: Record<string, string>;
+    icons?: string;
+    iconPath?: string;
+    iconStyle?: string;
+    themes: string[];
+    defaultTheme?: string;
+    switcher: string;
+    includeChart?: boolean;
+    chartColors?: string;
+    chartShades?: string;
+}): Record<string, unknown>;
 /**
  * Generate the content for uno.config.js.
  * @returns {string}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/cli",
-  "version": "1.1.1",
+  "version": "1.1.5",
   "description": "Command line utilities for icon bundling and conversion.",
   "repository": {
     "type": "git",

package/src/doctor.js

@@ -1,7 +1,15 @@
 /* eslint-disable no-console */
-import { existsSync, readFileSync, writeFileSync } from 'fs'
-import { resolve } from 'path'
-import { generateUnoConfig, generateAppCssImports, generateInitScript, generateChartConfig } from './init.js'
+import { existsSync, readFileSync, writeFileSync, readdirSync } from 'fs'
+import { resolve, extname } from 'path'
+import { loadConfig as loadParsedConfig } from './config.js'
+import {
+	generateUnoConfig,
+	generateAppCssImports,
+	generateInitScript,
+	generateChartConfig,
+	generateConfig,
+	serializeRokkitConfig
+} from './init.js'
 
 const KNOWN_THEMES = [
 	'rokkit',
@@ -11,6 +19,23 @@ const KNOWN_THEMES = [
 	'zen-sumi'
 ]
 
+/**
+ * Build the default named-token starter config source used by `doctor --fix`.
+ * @returns {string}
+ */
+export function defaultStarterSource() {
+	const config = generateConfig({
+		palette: 'default',
+		icons: 'rokkit',
+		themes: ['rokkit'],
+		switcher: 'manual',
+		includeChart: true,
+		chartColors: 'default',
+		chartShades: 'standard'
+	})
+	return serializeRokkitConfig(config)
+}
+
 /**
  * Check config file existence
  * @param {Object} fs
@@ -163,7 +188,7 @@ function createFsAdapter(cwd) {
  */
 function applyGenerateConfig(cwd, label) {
 	const configPath = resolve(cwd, 'rokkit.config.js')
-	writeFileSync(configPath, 'export default {}\n')
+	writeFileSync(configPath, defaultStarterSource())
 	console.info(`  Fixed: ${label}`)
 }
 
@@ -331,16 +356,159 @@ function handleResults(checks, cwd, failures, fix) {
 	}
 }
 
+// z-slot → named token (matches @rokkit/core Z_COLLAPSE maps).
+const SURFACE_Z = {
+	z0: 'paper', z1: 'paper-soft', z2: 'paper-mute', z3: 'paper-mute', z4: 'paper-edge',
+	z5: 'ink-soft', z6: 'ink-soft', z7: 'ink-mute', z8: 'ink-mute', z9: 'ink', z10: 'ink'
+}
+const INK_Z = {
+	z0: 'ink', z1: 'ink-mute', z2: 'ink-mute', z3: 'ink-soft', z4: 'ink-soft',
+	z5: 'paper-edge', z6: 'paper-edge', z7: 'paper-mute', z8: 'paper-mute', z9: 'paper-soft', z10: 'paper'
+}
+
+/**
+ * Map a z-scale role+slot to its nearest named token.
+ * @param {string} role
+ * @param {string} z — e.g. 'z5'
+ * @returns {string}
+ */
+function suggestNamedToken(role, z) {
+	if (role === 'surface') return SURFACE_Z[z]
+	if (role === 'ink') return INK_Z[z]
+	// accent + status roles collapse z0–z2 to their `-soft` tint (matches
+	// @rokkit/core theme.ts getZAliasesOther: zNum <= 2). primary has no `-soft`.
+	if (role !== 'primary' && Number(z.slice(1)) <= 2) return `${role}-soft`
+	return role
+}
+
+const Z_UTILITY_RE =
+	/\b(bg|text|border(?:-[tblr])?|fill|stroke|ring|outline|divide)-(surface|ink|primary|accent|success|warning|danger|error|info)-(z(?:10|[0-9]))\b/g
+
+/**
+ * Scan files for legacy z-scale utilities and suggest named-token equivalents.
+ * Advisory only — z-scale still resolves via the preset's back-compat layer.
+ * @param {Array<{ path: string, content: string }>} files
+ * @returns {{ count: number, byFile: Array<{ path: string, hits: Array<{ token: string, suggestion: string }> }> }}
+ */
+export function findLegacyZUtilities(files) {
+	const byFile = []
+	let count = 0
+	for (const { path: filePath, content } of files) {
+		const hits = []
+		for (const match of content.matchAll(Z_UTILITY_RE)) {
+			const [token, prefix, role, z] = match
+			hits.push({ token, suggestion: `${prefix}-${suggestNamedToken(role, z)}` })
+		}
+		if (hits.length > 0) {
+			byFile.push({ path: filePath, hits })
+			count += hits.length
+		}
+	}
+	return { count, byFile }
+}
+
+const SCAN_EXTS = new Set(['.svelte', '.css', '.ts', '.js'])
+
+/**
+ * Recursively gather scannable source files under cwd/src.
+ * Skips node_modules, symlinks (avoids recursion loops), and uno.config.js
+ * (its safelist legitimately lists z-utilities).
+ * @param {string} cwd
+ * @returns {Array<{ path: string, content: string }>}
+ */
+function gatherSrcFiles(cwd) {
+	const root = resolve(cwd, 'src')
+	if (!existsSync(root)) return []
+	const out = []
+	const walk = (dir) => {
+		for (const dirent of readdirSync(dir, { withFileTypes: true })) {
+			if (dirent.isSymbolicLink() || dirent.name === 'node_modules') continue
+			const full = resolve(dir, dirent.name)
+			if (dirent.isDirectory()) {
+				walk(full)
+			} else if (dirent.isFile() && SCAN_EXTS.has(extname(dirent.name)) && !full.endsWith('uno.config.js')) {
+				out.push({ path: full.slice(cwd.length + 1), content: readFileSync(full, 'utf-8') })
+			}
+		}
+	}
+	walk(root)
+	return out
+}
+
+/**
+ * Validate a parsed rokkit config for the named-token system. All advisory (warn).
+ * @param {Record<string, unknown> | null} config
+ * @returns {Array<{ id: string, label: string, status: 'warn', fixable: false, fix: string }>}
+ */
+export function validateConfigShape(config) {
+	if (!config) return []
+	const checks = []
+	const usesColorsAlias =
+		typeof config.colors === 'object' && config.colors !== null && !Array.isArray(config.colors) && !config.skin
+	const colormap = config.skins?.default ?? config.skin ?? config.colors ?? {}
+
+	if (!('ink' in colormap)) {
+		checks.push({
+			id: 'skin-ink-role',
+			label: 'skin defines an `ink` role',
+			status: 'warn',
+			fixable: false,
+			fix: "Add `ink: '<palette>'` (reusing the surface palette is fine) — without it, ink-* text tokens fall back to the surface palette."
+		})
+	}
+	if (config.colorSpace === 'oklch' && Object.keys(config.palettes ?? {}).length === 0) {
+		checks.push({
+			id: 'oklch-needs-palettes',
+			label: 'colorSpace `oklch` has a `palettes` block',
+			status: 'warn',
+			fixable: false,
+			fix: 'oklch values need a `palettes` block of bare "L C H" components; Tailwind named colors are rgb.'
+		})
+	}
+	if (usesColorsAlias) {
+		checks.push({
+			id: 'colors-alias',
+			label: 'config uses `skin` (not the legacy `colors` alias)',
+			status: 'warn',
+			fixable: false,
+			fix: 'Rename `colors:` to `skin:` — `colors` is a back-compat alias.'
+		})
+	}
+	return checks
+}
+
 /**
  * Interactive doctor command — validates project setup.
  * @param {{ fix?: boolean }} [opts]
  */
-export function doctor(opts = {}) {
+export async function doctor(opts = {}) {
 	const cwd = process.cwd()
 	const checks = runChecks(createFsAdapter(cwd))
 
 	console.info('Rokkit Doctor\n')
 	const failures = printChecks(checks)
+
+	const parsed = await loadParsedConfig({ cwd })
+	const shapeChecks = validateConfigShape(parsed)
+	if (shapeChecks.length > 0) {
+		console.info('\nConfig shape:')
+		for (const c of shapeChecks) {
+			console.info(`  WARN  ${c.label}`)
+			console.info(`        ${c.fix}`)
+		}
+	}
+
+	const { count, byFile } = findLegacyZUtilities(gatherSrcFiles(cwd))
+	if (count > 0) {
+		console.info(`\nLegacy z-scale utilities (advisory — ${count} in ${byFile.length} file(s)):`)
+		for (const { path: filePath, hits } of byFile.slice(0, 10)) {
+			const examples = [...new Map(hits.map((h) => [h.token, h.suggestion]))]
+			const shown = examples.slice(0, 3).map(([t, s]) => `${t} → ${s}`).join(', ')
+			console.info(`  ${filePath}: ${shown}${examples.length > 3 ? ', …' : ''}`)
+		}
+		console.info('        Named tokens are preferred; z-scale still works via back-compat.')
+	}
+
 	handleResults(checks, cwd, failures, opts.fix ?? false)
 	console.info('')
 }

package/src/init.js

@@ -8,6 +8,42 @@ import { detectPackageManager, buildInstallCommand } from './upgrade.js'
 const ROKKIT_PACKAGES = ['@rokkit/ui', '@rokkit/unocss', '@rokkit/themes', '@rokkit/icons']
 const LOCKFILES = ['bun.lock', 'bun.lockb', 'pnpm-lock.yaml', 'yarn.lock', 'package-lock.json']
 
+const NAMED_TOKEN_HEADER = `/**
+ * Rokkit token configuration — consumed by presetRokkit() in uno.config.js.
+ *
+ * Maps semantic roles (surface, ink, primary, accent, status…) to palettes.
+ * The preset emits the named-token vocabulary used throughout components:
+ *
+ *   Surface  bg-paper · bg-paper-soft · bg-paper-mute · border-paper-edge
+ *   Text     text-ink · text-ink-mute · text-ink-soft · text-ink-faint
+ *   Accent   bg-primary · text-on-primary · bg-accent · bg-accent-soft
+ *   Status   bg-success-soft · text-success   (+ warning / danger / error / info)
+ *
+ * Tokens flip automatically under [data-mode="dark"]. The older z-scale
+ * utilities (bg-surface-z0, text-primary-z5) still resolve for back-compat,
+ * but new code should prefer the named tokens above.
+ *
+ * tokens: 'core' emits the named vocabulary; 'extended' also emits the full
+ * 11-shade palette ladder per role (for charts / data-viz).
+ */
+`
+
+const OKLCH_PALETTES_NOTE = `/**
+ * palettes: bare OKLCH "L C H" components (colorSpace: 'oklch'). surface/ink use
+ * a { light, dark } dual palette — kami (warm paper) in light, sumi (ink) in dark.
+ */
+`
+
+/**
+ * Serialize a rokkit config object to a JS module string with a header comment.
+ * @param {Record<string, unknown>} config
+ * @returns {string}
+ */
+export function serializeRokkitConfig(config) {
+	const palettesNote = config.palettes ? OKLCH_PALETTES_NOTE : ''
+	return `${NAMED_TOKEN_HEADER}${palettesNote}export default ${JSON.stringify(config, null, 2)}\n`
+}
+
 /**
  * Detect if the current directory is a SvelteKit project.
  * @param {string} cwd
@@ -61,12 +97,23 @@ const CHART_SHADE_PRESETS = {
 	soft:     { light: { fill: '400', stroke: '600' }, dark: { fill: '600', stroke: '300' } }
 }
 
+// Base rgb skin — named-token roles only (no secondary/tertiary; ink defaults to surface).
+const DEFAULT_SKIN_BASE = {
+	primary: 'orange',
+	accent: 'sky',
+	surface: 'slate',
+	success: 'green',
+	warning: 'yellow',
+	danger: 'red',
+	error: 'red',
+	info: 'cyan'
+}
+
 const SKIN_PRESETS = {
-	default: { primary: 'orange', secondary: 'pink', accent: 'sky', surface: 'slate' },
-	vibrant: { primary: 'blue', secondary: 'purple', accent: 'sky', surface: 'slate' },
+	default: {},
+	vibrant: { primary: 'blue', accent: 'sky', surface: 'slate' },
 	seaweed: {
 		primary: 'sky',
-		secondary: 'green',
 		accent: 'blue',
 		surface: 'zinc',
 		danger: 'rose',
@@ -77,26 +124,66 @@ const SKIN_PRESETS = {
 	}
 }
 
-const DEFAULT_COLORS = {
-	primary: 'orange',
-	secondary: 'pink',
-	accent: 'sky',
-	surface: 'slate',
-	success: 'green',
-	warning: 'yellow',
-	danger: 'red',
-	error: 'red',
-	info: 'cyan'
-}
-
 /**
- * Generate a Rokkit config object from user choices.
- * @param {{ palette: string, customColors?: Record<string, string>, icons: string, iconPath?: string, themes: string[], switcher: string }} opts
- * @returns {Record<string, unknown>}
+ * Resolve a named-token rgb skin from a preset or custom colors.
+ * `ink` defaults to the `surface` palette. Only the named-token roles are
+ * emitted; `secondary`/`tertiary` are intentionally omitted (no named token
+ * reads them). A consumer who needs them can add them to their config's skin
+ * directly — @rokkit/unocss's loadConfig merges extra roles through.
+ * @param {string} palette
+ * @param {Record<string, string>} [customColors]
+ * @returns {Record<string, string>}
  */
-function resolveColors(palette, customColors) {
-	if (palette === 'custom') return { ...DEFAULT_COLORS, ...customColors }
-	return { ...DEFAULT_COLORS, ...(SKIN_PRESETS[palette] || {}) }
+function resolveSkin(palette, customColors) {
+	const merged =
+		palette === 'custom'
+			? { ...DEFAULT_SKIN_BASE, ...customColors }
+			: { ...DEFAULT_SKIN_BASE, ...(SKIN_PRESETS[palette] || {}) }
+	return {
+		surface: merged.surface,
+		ink: merged.ink ?? merged.surface,
+		primary: merged.primary,
+		accent: merged.accent,
+		success: merged.success,
+		warning: merged.warning,
+		danger: merged.danger,
+		error: merged.error,
+		info: merged.info
+	}
+}
+
+// Zen-Sumi OKLCH palettes — bare "L C H" components (colorSpace: 'oklch').
+const ZEN_SUMI_PALETTES = {
+	kami: {
+		50: '0.985 0.005 85', 100: '0.975 0.008 85', 200: '0.955 0.010 85',
+		300: '0.920 0.012 85', 400: '0.850 0.010 70', 500: '0.750 0.008 50',
+		600: '0.580 0.010 50', 700: '0.380 0.012 50', 800: '0.280 0.012 50',
+		900: '0.220 0.012 50', 950: '0.170 0.010 50'
+	},
+	sumi: {
+		50: '0.170 0.010 50', 100: '0.210 0.012 50', 200: '0.250 0.012 50',
+		300: '0.320 0.012 50', 400: '0.420 0.010 50', 500: '0.570 0.010 50',
+		600: '0.420 0.012 85', 700: '0.600 0.010 85', 800: '0.780 0.008 85',
+		900: '0.940 0.008 85', 950: '0.975 0.008 85'
+	},
+	shu: {
+		50: '0.970 0.020 35', 100: '0.940 0.040 35', 200: '0.880 0.070 35',
+		300: '0.800 0.100 35', 400: '0.700 0.130 35', 500: '0.580 0.150 35',
+		600: '0.500 0.140 35', 700: '0.420 0.120 35', 800: '0.350 0.100 35',
+		900: '0.280 0.080 35', 950: '0.220 0.060 35'
+	},
+	hisui: {
+		50: '0.970 0.015 160', 100: '0.940 0.030 160', 200: '0.880 0.050 160',
+		300: '0.800 0.065 160', 400: '0.720 0.075 160', 500: '0.620 0.080 160',
+		600: '0.540 0.075 160', 700: '0.460 0.065 160', 800: '0.380 0.055 160',
+		900: '0.300 0.045 160', 950: '0.240 0.035 160'
+	},
+	kohaku: {
+		50: '0.980 0.020 75', 100: '0.950 0.040 75', 200: '0.900 0.070 75',
+		300: '0.850 0.095 75', 400: '0.790 0.110 75', 500: '0.720 0.120 75',
+		600: '0.640 0.110 75', 700: '0.560 0.095 75', 800: '0.470 0.080 75',
+		900: '0.380 0.065 75', 950: '0.300 0.050 75'
+	}
 }
 
 /**
@@ -111,6 +198,53 @@ export function generateChartConfig({ chartColors, chartShades }) {
 	}
 }
 
+/**
+ * Build the Zen-Sumi OKLCH starter (ink-on-paper, dual-palette dark mode).
+ * @param {{ themes?: string[], defaultTheme?: string, switcher?: string,
+ *   includeChart?: boolean, chartColors?: string, chartShades?: string }} [opts]
+ * @returns {Record<string, unknown>}
+ */
+export function generateZenSumiConfig(opts = {}) {
+	const { themes, defaultTheme, switcher, includeChart, chartColors, chartShades } = opts
+	const config = {
+		palettes: ZEN_SUMI_PALETTES,
+		colorSpace: 'oklch',
+		tokens: 'core',
+		skin: {
+			surface: { light: 'kami', dark: 'sumi' },
+			ink: { light: 'kami', dark: 'sumi' },
+			primary: 'shu',
+			accent: 'shu',
+			success: 'hisui',
+			warning: 'kohaku',
+			danger: 'shu',
+			error: 'shu',
+			info: 'kohaku'
+		},
+		shape: { radius: 'soft' },
+		typography: {
+			display: "'Fraunces', 'Iowan Old Style', Georgia, serif",
+			sans: "'Inter', system-ui, -apple-system, sans-serif",
+			mono: "'JetBrains Mono', 'SF Mono', Menlo, monospace"
+		},
+		themes: themes && themes.length ? themes : ['rokkit', 'zen-sumi'],
+		defaultTheme: defaultTheme || 'zen-sumi',
+		switcher: switcher || 'full',
+		storageKey: 'rokkit-theme'
+	}
+	if (includeChart) config.chart = generateChartConfig({ chartColors, chartShades })
+	return config
+}
+
+/**
+ * Build a Rokkit config object from the user's init choices.
+ * Emits the named-token `skin` shape (skin + colorSpace + tokens), plus
+ * optional `icons` and `chart` sections.
+ * @param {{ palette: string, customColors?: Record<string, string>, icons?: string,
+ *   iconPath?: string, iconStyle?: string, themes: string[], defaultTheme?: string,
+ *   switcher: string, includeChart?: boolean, chartColors?: string, chartShades?: string }} opts
+ * @returns {Record<string, unknown>}
+ */
 export function generateConfig({
 	palette,
 	customColors,
@@ -124,8 +258,14 @@ export function generateConfig({
 	chartColors,
 	chartShades
 }) {
+	if (palette === 'zen-sumi') {
+		return generateZenSumiConfig({ themes, defaultTheme, switcher, includeChart, chartColors, chartShades })
+	}
+
 	const config = {
-		colors: resolveColors(palette, customColors),
+		skin: resolveSkin(palette, customColors),
+		colorSpace: 'rgb',
+		tokens: 'core',
 		themes,
 		defaultTheme: defaultTheme || themes[0],
 		switcher,
@@ -205,6 +345,7 @@ const PROMPTS_CONFIG = [
 			{ title: 'Default (orange/pink/sky)', value: 'default' },
 			{ title: 'Vibrant (blue/purple/sky)', value: 'vibrant' },
 			{ title: 'Seaweed (sky/green/blue)', value: 'seaweed' },
+			{ title: 'Zen-Sumi (OKLCH ink-on-paper)', value: 'zen-sumi' },
 			{ title: 'Custom', value: 'custom' }
 		]
 	},
@@ -327,7 +468,7 @@ function writeRokkitConfig(cwd, config) {
 		console.warn('  rokkit.config.js already exists — skipping')
 		return
 	}
-	writeFileSync(configPath, `export default ${JSON.stringify(config, null, 2)}\n`)
+	writeFileSync(configPath, serializeRokkitConfig(config))
 	console.info('  Created rokkit.config.js')
 }