@q1travel/design-system 0.1.0 → 0.3.0

package/bin/q1-design.mjs

@@ -0,0 +1,464 @@
+#!/usr/bin/env node
+// Consumer-side CLI for the design-authority npm seam (decision 0001):
+// `sync` materializes the package's canonical skill + contracts into a
+// read-only cache under the consumer repo; `verify` proves that cache was
+// never hand-edited and still matches the installed package version.
+
+import { createRequire } from 'node:module';
+import {
+  cpSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { createHash } from 'node:crypto';
+import { dirname, extname, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PACKAGE_NAME = '@q1travel/design-system';
+const SKILL_RELATIVE_DIR = '.claude/skills/product-design';
+const MANIFEST_FILE_NAME = '.q1-design-manifest.json';
+const SKILL_SOURCE_SUBPATH = '.agents/skills/product-design';
+const CONTRACTS_SOURCE_SUBPATH = 'contracts';
+
+const LINT_EXTENSIONS = new Set(['.css', '.js', '.jsx', '.ts', '.tsx', '.mjs']);
+const DASH_DS_PATTERN = /--ds-/;
+const TRANSITION_ALL_PATTERN = /transition(?:-property)?\s*:\s*all\b/;
+const HEX_COLOR_PATTERN = /#[0-9a-fA-F]{3,8}\b/;
+const COLOR_FUNCTION_PATTERN = /\b(?:rgb|rgba|hsl)\s*\(/i;
+
+function resolveInstalledPackageRoot(consumerRootDir) {
+  const require = createRequire(join(consumerRootDir, 'package.json'));
+  let packageJsonPath;
+  try {
+    packageJsonPath = require.resolve(`${PACKAGE_NAME}/package.json`);
+  } catch {
+    return null;
+  }
+  return dirname(packageJsonPath);
+}
+
+function readInstalledPackageVersion(packageRootDir) {
+  const packageJson = JSON.parse(
+    readFileSync(join(packageRootDir, 'package.json'), 'utf8'),
+  );
+  return packageJson.version;
+}
+
+function toPosixPath(pathValue) {
+  return pathValue.split(sep).join('/');
+}
+
+function listFilesRecursively(rootDir) {
+  const relativeFilePaths = [];
+
+  function walk(currentDir) {
+    for (const entryName of readdirSync(currentDir).sort()) {
+      const entryPath = join(currentDir, entryName);
+      if (statSync(entryPath).isDirectory()) {
+        walk(entryPath);
+      } else {
+        relativeFilePaths.push(toPosixPath(relative(rootDir, entryPath)));
+      }
+    }
+  }
+
+  if (existsSync(rootDir)) {
+    walk(rootDir);
+  }
+  return relativeFilePaths;
+}
+
+function computeFileHash(filePath) {
+  return createHash('sha256').update(readFileSync(filePath)).digest('hex');
+}
+
+function assertNotSymlink(pathValue) {
+  let stats;
+  try {
+    stats = lstatSync(pathValue);
+  } catch {
+    return; // 不存在,无需检查
+  }
+  if (stats.isSymbolicLink()) {
+    console.error(
+      `[q1-design] ${pathValue} 是符号链接,拒绝在其上删除/写入;请先手工处理该链接再重试。`,
+    );
+    process.exit(1);
+  }
+}
+
+function runSync(consumerRootDir) {
+  // 防误删:必须在项目根(有 package.json)运行,否则会把任意 cwd 下的
+  // .claude/skills/product-design 当缓存删掉。
+  if (!existsSync(join(consumerRootDir, 'package.json'))) {
+    console.error(
+      `[q1-design] 当前目录不在项目根(缺 package.json): ${consumerRootDir}`,
+    );
+    process.exit(1);
+  }
+
+  const packageRootDir = resolveInstalledPackageRoot(consumerRootDir);
+  if (!packageRootDir) {
+    console.error(
+      `[q1-design] 未安装 ${PACKAGE_NAME},请先 npm install ${PACKAGE_NAME}`,
+    );
+    process.exit(1);
+  }
+
+  const skillCacheDir = join(consumerRootDir, SKILL_RELATIVE_DIR);
+  const skillsParentDir = dirname(skillCacheDir);
+
+  // 防误删:.claude、.claude/skills、目标目录任一是 symlink 都拒绝——
+  // 否则 rmSync/rename 可能穿透链接抹掉链接指向的真实目录。
+  assertNotSymlink(join(consumerRootDir, '.claude'));
+  assertNotSymlink(skillsParentDir);
+  assertNotSymlink(skillCacheDir);
+
+  // 防误删:目标已存在但不含 manifest ⇒ 不是本工具生成的目录,拒绝覆盖。
+  if (
+    existsSync(skillCacheDir) &&
+    !existsSync(join(skillCacheDir, MANIFEST_FILE_NAME))
+  ) {
+    console.error(
+      `[q1-design] ${skillCacheDir} 已存在且缺少 ${MANIFEST_FILE_NAME},目录非本工具生成;如确认可覆盖,请先手动删除该目录再重试。`,
+    );
+    process.exit(1);
+  }
+
+  // 事务化:先在 .claude/skills/ 下建临时目录,完整复制 + 写 manifest 成功后,
+  // 才 rm 旧缓存 → rename 就位;中途任何失败都清理临时目录,旧缓存保留。
+  mkdirSync(skillsParentDir, { recursive: true });
+  const tempDir = join(skillsParentDir, `product-design.tmp-${process.pid}`);
+
+  let fileHashes;
+  let packageVersion;
+  try {
+    rmSync(tempDir, { recursive: true, force: true });
+    mkdirSync(tempDir, { recursive: true });
+
+    cpSync(join(packageRootDir, SKILL_SOURCE_SUBPATH), tempDir, {
+      recursive: true,
+    });
+    cpSync(
+      join(packageRootDir, CONTRACTS_SOURCE_SUBPATH),
+      join(tempDir, 'contracts'),
+      { recursive: true },
+    );
+
+    packageVersion = readInstalledPackageVersion(packageRootDir);
+    fileHashes = {};
+    for (const relativeFilePath of listFilesRecursively(tempDir)) {
+      fileHashes[relativeFilePath] = computeFileHash(
+        join(tempDir, relativeFilePath),
+      );
+    }
+
+    const manifest = {
+      package: PACKAGE_NAME,
+      version: packageVersion,
+      generatedAt: new Date().toISOString(),
+      files: fileHashes,
+    };
+    writeFileSync(
+      join(tempDir, MANIFEST_FILE_NAME),
+      `${JSON.stringify(manifest, null, 2)}\n`,
+    );
+
+    rmSync(skillCacheDir, { recursive: true, force: true });
+    renameSync(tempDir, skillCacheDir);
+  } catch (error) {
+    rmSync(tempDir, { recursive: true, force: true });
+    console.error(`[q1-design] sync 失败,旧缓存保留: ${error.message}`);
+    process.exit(1);
+  }
+
+  const syncedFileCount = Object.keys(fileHashes).length;
+  console.log(`[q1-design] synced ${syncedFileCount} files`);
+  console.log(`[q1-design] version: ${packageVersion}`);
+  console.log(`[q1-design] target: ${skillCacheDir}`);
+  console.log(
+    '[q1-design] 该目录是只读缓存,勿手改;建议加入 .gitignore,变更请改包版本后重新 sync。',
+  );
+}
+
+// verify 的信任根:从已安装包重算期望文件集(skill 源 + contracts)与 sha256。
+// 缓存里的 manifest 可被篡改者同步重签,不能作为判定依据。
+function computeExpectedFileHashes(packageRootDir) {
+  const expectedFileHashes = {};
+  const skillSourceDir = join(packageRootDir, SKILL_SOURCE_SUBPATH);
+  for (const relativeFilePath of listFilesRecursively(skillSourceDir)) {
+    expectedFileHashes[relativeFilePath] = computeFileHash(
+      join(skillSourceDir, relativeFilePath),
+    );
+  }
+  const contractsSourceDir = join(packageRootDir, CONTRACTS_SOURCE_SUBPATH);
+  for (const relativeFilePath of listFilesRecursively(contractsSourceDir)) {
+    expectedFileHashes[`contracts/${relativeFilePath}`] = computeFileHash(
+      join(contractsSourceDir, relativeFilePath),
+    );
+  }
+  return expectedFileHashes;
+}
+
+function runVerify(consumerRootDir) {
+  const skillCacheDir = join(consumerRootDir, SKILL_RELATIVE_DIR);
+  const manifestPath = join(skillCacheDir, MANIFEST_FILE_NAME);
+  if (!existsSync(manifestPath)) {
+    console.error(`[q1-design] 缺少 manifest: ${manifestPath}`);
+    process.exit(1);
+  }
+
+  // manifest 仍读:用于报「版本漂移」与快速定位;判定以安装包重算为准。
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  const problems = [];
+
+  for (const relativeFilePath of Object.keys(manifest.files)) {
+    if (relativeFilePath.split('/').includes('..')) {
+      problems.push(`manifest 相对路径非法(含 ..): ${relativeFilePath}`);
+    }
+  }
+
+  const packageRootDir = resolveInstalledPackageRoot(consumerRootDir);
+  if (!packageRootDir) {
+    console.error(
+      `[q1-design] 未安装 ${PACKAGE_NAME},verify 以安装包为信任根,无法校验;请先 npm install ${PACKAGE_NAME}`,
+    );
+    process.exit(1);
+  }
+
+  const expectedFileHashes = computeExpectedFileHashes(packageRootDir);
+  for (const [relativeFilePath, expectedHash] of Object.entries(
+    expectedFileHashes,
+  )) {
+    const filePath = join(skillCacheDir, relativeFilePath);
+    if (!existsSync(filePath)) {
+      problems.push(`缺文件: ${relativeFilePath}`);
+      continue;
+    }
+    const actualHash = computeFileHash(filePath);
+    if (actualHash !== expectedHash) {
+      problems.push(`与安装包不一致(疑似手改): ${relativeFilePath}`);
+    }
+  }
+
+  const expectedFileNames = new Set(Object.keys(expectedFileHashes));
+  for (const relativeFilePath of listFilesRecursively(skillCacheDir)) {
+    if (
+      relativeFilePath !== MANIFEST_FILE_NAME &&
+      !expectedFileNames.has(relativeFilePath)
+    ) {
+      problems.push(`多出未登记文件: ${relativeFilePath}`);
+    }
+  }
+
+  const installedVersion = readInstalledPackageVersion(packageRootDir);
+  if (installedVersion !== manifest.version) {
+    problems.push(
+      `版本漂移: manifest=${manifest.version} 已安装=${installedVersion}`,
+    );
+  }
+
+  if (problems.length > 0) {
+    console.error('[q1-design] verify ✗');
+    for (const problem of problems) {
+      console.error(`  - ${problem}`);
+    }
+    process.exit(1);
+  }
+
+  console.log('[q1-design] verify ✓');
+}
+
+function walkForLint(dirPath, targetFiles) {
+  for (const entryName of readdirSync(dirPath).sort()) {
+    const entryPath = join(dirPath, entryName);
+    if (statSync(entryPath).isDirectory()) {
+      walkForLint(entryPath, targetFiles);
+    } else if (LINT_EXTENSIONS.has(extname(entryPath))) {
+      targetFiles.push(entryPath);
+    }
+  }
+}
+
+function collectLintTargetFiles(inputPaths, baseDir) {
+  const targetFiles = [];
+  for (const inputPath of inputPaths) {
+    const absolutePath = resolve(baseDir, inputPath);
+    if (!existsSync(absolutePath)) {
+      console.error(`[q1-design] 路径不存在: ${inputPath}`);
+      process.exit(1);
+    }
+    if (statSync(absolutePath).isDirectory()) {
+      walkForLint(absolutePath, targetFiles);
+    } else if (LINT_EXTENSIONS.has(extname(absolutePath))) {
+      targetFiles.push(absolutePath);
+    }
+  }
+  return targetFiles;
+}
+
+function isTokensPath(absolutePath, baseDir) {
+  return toPosixPath(relative(baseDir, absolutePath)).includes('tokens');
+}
+
+function hasDisablePragma(fileContent, ruleId) {
+  return new RegExp(`q1-lint-disable\\s+${ruleId}\\b`).test(fileContent);
+}
+
+function truncateLine(lineContent, maxLength = 100) {
+  const trimmed = lineContent.trim();
+  return trimmed.length > maxLength
+    ? `${trimmed.slice(0, maxLength)}…`
+    : trimmed;
+}
+
+function collectLintHits(inputPaths, baseDir) {
+  const targetFiles = collectLintTargetFiles(inputPaths, baseDir);
+  const hits = [];
+
+  for (const absoluteFilePath of targetFiles) {
+    const fileContent = readFileSync(absoluteFilePath, 'utf8');
+    const relativeFilePath = toPosixPath(relative(baseDir, absoluteFilePath));
+    const isCssFile = extname(absoluteFilePath) === '.css';
+    const q1ds501Applicable =
+      isCssFile &&
+      !isTokensPath(absoluteFilePath, baseDir) &&
+      !hasDisablePragma(fileContent, 'Q1-DS-501');
+
+    fileContent.split('\n').forEach((lineContent, index) => {
+      const lineNumber = index + 1;
+      if (DASH_DS_PATTERN.test(lineContent)) {
+        hits.push({
+          ruleId: 'Q1-DS-001',
+          filePath: relativeFilePath,
+          lineNumber,
+          lineContent,
+        });
+      }
+      if (TRANSITION_ALL_PATTERN.test(lineContent)) {
+        hits.push({
+          ruleId: 'Q1-DS-401',
+          filePath: relativeFilePath,
+          lineNumber,
+          lineContent,
+        });
+      }
+      if (
+        q1ds501Applicable &&
+        (HEX_COLOR_PATTERN.test(lineContent) ||
+          COLOR_FUNCTION_PATTERN.test(lineContent))
+      ) {
+        hits.push({
+          ruleId: 'Q1-DS-501',
+          filePath: relativeFilePath,
+          lineNumber,
+          lineContent,
+        });
+      }
+    });
+  }
+
+  return hits;
+}
+
+function runLint(inputPaths, consumerRootDir) {
+  const hits = collectLintHits(inputPaths, consumerRootDir);
+
+  if (hits.length === 0) {
+    console.log('[q1-design] lint ✓');
+    return;
+  }
+
+  for (const hit of hits) {
+    console.log(
+      `${hit.ruleId} ${hit.filePath}:${hit.lineNumber} ${truncateLine(hit.lineContent)}`,
+    );
+  }
+  console.log(`[q1-design] 共 ${hits.length} 处命中`);
+  process.exit(1);
+}
+
+function resolvePackageRootDir() {
+  const scriptDir = dirname(fileURLToPath(import.meta.url));
+  return join(scriptDir, '..');
+}
+
+function runEval() {
+  const packageRootDir = resolvePackageRootDir();
+  const evalsDir = join(packageRootDir, 'tooling', 'scripts', 'evals');
+  const fixturesIndex = JSON.parse(
+    readFileSync(join(evalsDir, 'fixtures.json'), 'utf8'),
+  );
+
+  let hasFailure = false;
+  let passCount = 0;
+
+  for (const fixture of fixturesIndex.fixtures) {
+    const fixtureDir = join(evalsDir, fixture.dir);
+    const beforeHitCount = collectLintHits(
+      [join(fixtureDir, 'before')],
+      evalsDir,
+    ).filter((hit) => hit.ruleId === fixture.rule).length;
+    const afterHitCount = collectLintHits(
+      [join(fixtureDir, 'after')],
+      evalsDir,
+    ).filter((hit) => hit.ruleId === fixture.rule).length;
+
+    if (
+      beforeHitCount === fixture.expectedHits &&
+      afterHitCount === 0
+    ) {
+      console.log(`PASS ${fixture.id}`);
+      passCount += 1;
+    } else if (beforeHitCount !== fixture.expectedHits) {
+      console.log(
+        `FAIL ${fixture.id}: before 命中 ${fixture.rule} ${beforeHitCount} 处,期望 ${fixture.expectedHits} 处`,
+      );
+      hasFailure = true;
+    } else {
+      console.log(
+        `FAIL ${fixture.id}: after 仍命中 ${fixture.rule}(${afterHitCount} 处)`,
+      );
+      hasFailure = true;
+    }
+  }
+
+  console.log(
+    `[q1-design] eval ${passCount}/${fixturesIndex.fixtures.length} PASS`,
+  );
+  if (hasFailure) {
+    process.exit(1);
+  }
+}
+
+function printUsage() {
+  console.error('Usage: q1-design <sync|verify|lint|eval>');
+  console.error(
+    '  lint [路径...]  扫描 .css/.js/.jsx/.ts/.tsx/.mjs,默认 src,目录递归',
+  );
+  console.error('  eval            对 tooling/scripts/evals 的 fixtures 跑 before/after 断言');
+}
+
+const subcommand = process.argv[2];
+const consumerRootDir = process.cwd();
+
+if (subcommand === 'sync') {
+  runSync(consumerRootDir);
+} else if (subcommand === 'verify') {
+  runVerify(consumerRootDir);
+} else if (subcommand === 'lint') {
+  const inputPaths = process.argv.slice(3);
+  runLint(inputPaths.length > 0 ? inputPaths : ['src'], consumerRootDir);
+} else if (subcommand === 'eval') {
+  runEval();
+} else {
+  printUsage();
+  process.exit(1);
+}

package/contracts/design-engineering-principles.md

@@ -0,0 +1,39 @@
+# q1travel Design Engineering Principles
+
+These principles define how q1travel design-system work is evaluated. They are product and engineering standards, not decorative preferences.
+
+## Usefulness
+
+- Solve real user and team problems before polishing surface details.
+- Make frequent tasks feel direct, predictable, and low-friction.
+- Treat documentation as a product surface: every page should answer what the element is, when to use it, and what contract it carries.
+
+## Whole Experience
+
+- Own copy, layout, interaction, states, accessibility, performance, and implementation together.
+- Design empty, sparse, dense, loading, error, hover, active, focus, and disabled states before calling a component complete.
+- Keep the public standard neutral; do not bind the system to one internal workflow or one business line.
+
+## Constraints
+
+- Understand the user, route, device, theme, and implementation boundary before choosing a solution.
+- Prefer platform semantics and CSS layout before measurement scripts or screenshot-driven constants.
+- Use q1travel tokens and canonical components as the source of production behavior.
+
+## Inclusion
+
+- Build keyboard-operable, readable, and resilient interfaces by default.
+- Make complexity available without making it required.
+- Preserve visible focus, accessible names, usable hit targets, and non-color-only status cues.
+
+## Craft
+
+- Scope small enough to execute well.
+- Align every element deliberately to a grid, edge, baseline, or optical center.
+- Increase contrast on interaction states and avoid animation that does not clarify cause and effect.
+
+## Team Defaults
+
+- Convert repeated review feedback into contracts, shared components, or checks.
+- Keep changes reviewable, evidence-backed, and easy to roll forward.
+- If implementation and contract drift, fix the source contract or stop and ask for direction.