Skip to content

xinetzone/SpecWeave / .agents/skills/design-library-creator

design-library-creator

Flagged

Create, expand, and refine professional Design Libraries / Design Systems with structured token architecture. ONLY invoke when user EXPLICITLY mentions design-system terminology: 'Design Library', 'Design System', '设计系统', '设计库', 'token system', 'design tokens', '组件库规范', or provides a parsed design-spec bundle (ZIP/Figma export). Also covers creating a new theme / color theme as a design-system deliverable (创建主题/新建暖色主题/深色主题等 — tokens + palette + component styling). Do NOT route here for: '素材库', '全套素材', '素材合集', '物料库', '生成素材', '做一套设计', '做几张图', '设计一套页面', '帮我出图', page/poster/landing-page creation, or any visual-asset generation intent where the user does not demonstrate knowledge of design-system concepts. Those belong to solo-design.

FileKindSize
SKILL.mdskill md19.3 KB
aesthetics/dark-mode.mdmarkdown1.8 KB
aesthetics/index.mdmarkdown33.8 KB
aesthetics/navigation-footer.mdmarkdown2.2 KB
aesthetics/screen-craft.mdmarkdown9.2 KB
aesthetics/self-check.mdmarkdown24.9 KB
examples/templates/component-dispatch-rules.mdmarkdown9.1 KB
examples/templates/figma-token-gen.mdmarkdown50.3 KB
examples/templates/incremental.mdmarkdown5.7 KB
examples/templates/phase-2-analysts.mdmarkdown6.8 KB
examples/templates/phase-2-structured-spec.mdmarkdown8.8 KB
examples/templates/phase-2.5-intent-synthesis.mdmarkdown31.0 KB
examples/templates/phase-3-4-component.mdmarkdown9.0 KB
examples/templates/phase-4-ui-kit.mdmarkdown39.3 KB
examples/templates/phase-5-docs.mdmarkdown12.5 KB
examples/templates/scratch-token-gen.mdmarkdown14.4 KB
examples/templates/specimen-reference.htmlother6.0 KB
file-specs/css-json.mdmarkdown9.5 KB
file-specs/css-tokens.mdmarkdown33.6 KB
file-specs/design-library-output.mdmarkdown10.3 KB
file-specs/design-spec-bundle.mdmarkdown5.9 KB
file-specs/documentation.mdmarkdown12.3 KB
file-specs/preview-pages.mdmarkdown28.0 KB
file-specs/ui-kit.mdmarkdown28.5 KB
operation-policies/agent-orchestration.mdmarkdown20.2 KB
operation-policies/bundle-exploration.mdmarkdown9.0 KB
operation-policies/decision-rules.mdmarkdown10.7 KB
operation-policies/quality-gates.mdmarkdown10.5 KB
operation-policies/user-output-policy.mdmarkdown7.8 KB
scripts/check-design-library-phase.mjsscript85.1 KB
scripts/copy-bundle-assets.mjsscript12.3 KB
scripts/css-to-json.mjsscript53.1 KB
scripts/css-utils.mjsscript748 B
scripts/extract-components-css.mjsscript10.3 KB
scripts/generate-uikit-plan.mjsscript27.5 KB
scripts/jsonl-utils.mjsscript7.3 KB
scripts/validate-design-library-output.mjsscript3.1 KB
scripts/validate-intent.mjsscript7.3 KB
scripts/validate-token-input.mjsscript4.0 KB
scripts/validate-uikit-plan.mjsscript13.6 KB
skill-release-manifest.jsonconfig202 B
workflows/create-from-scratch.mdmarkdown22.5 KB
workflows/create-from-structured-spec.mdmarkdown17.5 KB
workflows/create-library.mdmarkdown53.0 KB
workflows/expand-components.mdmarkdown9.0 KB
workflows/generate-additional-kit.mdmarkdown4.9 KB
workflows/refine-library.mdmarkdown9.7 KB

scripts/validate-uikit-plan.mjs

View on GitHub
#!/usr/bin/env node

import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';

const REQUIRED_TOP_LEVEL_FIELDS = [
  'corePreviewComponents',
  'supportEvidenceComponents',
  'allowedComponents',
  'screenBlueprints',
  'forbiddenInventedComponents',
  'lowConfidence',
  'warnings',
];

const FORBIDDEN_TOP_LEVEL_FIELDS = [
  'strategy',
  'families',
  'decisions',
  'coverageSummary',
  'plan',
  'selectedComponents',
  'componentsOnly',
];

function readJson(filePath) {
  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
}

function unique(items) {
  return [...new Set(items.filter(Boolean))];
}

function normalizeComponentEntry(entry, index, failures, fieldName) {
  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
    failures.push(`${fieldName}[${index}] must be an object`);
    return undefined;
  }

  const slug = typeof entry.slug === 'string' ? entry.slug.trim() : '';
  if (!slug) {
    failures.push(`${fieldName}[${index}].slug is required`);
    return undefined;
  }

  const evidenceFile = typeof entry.evidenceFile === 'string'
    ? entry.evidenceFile
    : typeof entry.evidence === 'string'
      ? entry.evidence
      : `components/_evidence/${slug}.json`;

  const reason = typeof entry.reason === 'string'
    ? entry.reason
    : typeof entry.basis === 'string'
      ? entry.basis
      : typeof entry.role === 'string'
        ? entry.role
        : '';
  if (!reason) {
    failures.push(`${fieldName}[${index}].reason is required`);
  }

  const normalized = { slug, reason, evidenceFile };
  if (Number.isFinite(entry.priority)) {
    normalized.priority = entry.priority;
  }
  if (typeof entry.slot === 'string' && entry.slot) {
    normalized.slot = entry.slot;
  }
  return normalized;
}

function normalizeScreenBlueprint(entry, index, failures) {
  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
    failures.push(`screenBlueprints[${index}] must be an object`);
    return undefined;
  }

  const name = typeof entry.name === 'string'
    ? entry.name
    : typeof entry.slug === 'string'
      ? entry.slug
      : null;
  const purpose = typeof entry.purpose === 'string' ? entry.purpose : '';
  const role = typeof entry.role === 'string' ? entry.role : '';
  const componentSlugs = Array.isArray(entry.componentSlugs)
    ? entry.componentSlugs
    : Array.isArray(entry.components)
      ? entry.components
      : [];
  const layoutIntent = typeof entry.layoutIntent === 'string' ? entry.layoutIntent : purpose;

  // componentSlugs is optional — LLM assigns components to screens at runtime
  // using the allowedComponents whitelist. Generator intentionally leaves this empty.

  const normalized = {
    name,
    componentSlugs: unique(componentSlugs.map((slug) => typeof slug === 'string' ? slug.trim() : '')),
  };
  if (purpose) normalized.purpose = purpose;
  if (layoutIntent && layoutIntent !== purpose) normalized.layoutIntent = layoutIntent;
  if (role) normalized.role = role;
  if (typeof entry.primaryAction === 'string' && entry.primaryAction) normalized.primaryAction = entry.primaryAction;
  return normalized;
}

function loadEvidenceSlugs(evidenceIndexPath, failures) {
  if (!evidenceIndexPath) {
    return undefined;
  }
  if (!fs.existsSync(evidenceIndexPath)) {
    failures.push(`evidence index missing: ${evidenceIndexPath}`);
    return undefined;
  }

  try {
    const evidenceIndex = readJson(evidenceIndexPath);
    return new Set(
      (Array.isArray(evidenceIndex.components) ? evidenceIndex.components : [])
        .map((component) => component?.slug)
        .filter(Boolean),
    );
  } catch (error) {
    failures.push(`failed to parse evidence index: ${error.message}`);
    return undefined;
  }
}

function loadComponentContractSlugs(componentIndexPath, componentsDirPath, failures) {
  if (!componentIndexPath && !componentsDirPath) {
    return undefined;
  }
  if (!componentIndexPath) {
    failures.push('--component-index is required when --components-dir is provided');
    return undefined;
  }
  if (!componentsDirPath) {
    failures.push('--components-dir is required when --component-index is provided');
    return undefined;
  }
  if (!fs.existsSync(componentIndexPath)) {
    failures.push(`component index missing: ${componentIndexPath}`);
    return undefined;
  }

  try {
    const componentIndex = readJson(componentIndexPath);
    const entries = Array.isArray(componentIndex?.components)
      ? componentIndex.components
      : Array.isArray(componentIndex)
        ? componentIndex
        : [];
    const slugs = entries
      .map((component) => typeof component?.slug === 'string' ? component.slug.trim() : '')
      .filter(Boolean);
    const existing = new Set();
    for (const slug of slugs) {
      const componentPath = path.join(componentsDirPath, `${slug}.json`);
      if (!fs.existsSync(componentPath)) {
        failures.push(`component contract missing: ${componentPath}`);
      } else {
        existing.add(slug);
      }
    }
    return existing;
  } catch (error) {
    failures.push(`failed to parse component index: ${error.message}`);
    return undefined;
  }
}

export function normalizeUiKitPlan(plan, options = {}) {
  const failures = [];
  const warnings = [];

  if (!plan || typeof plan !== 'object' || Array.isArray(plan)) {
    return { ok: false, failures: ['uikit plan must be a JSON object'], warnings };
  }

  for (const field of FORBIDDEN_TOP_LEVEL_FIELDS) {
    if (Object.prototype.hasOwnProperty.call(plan, field)) {
      failures.push(`forbidden top-level field "${field}" indicates planner intermediate schema`);
    }
  }

  for (const field of REQUIRED_TOP_LEVEL_FIELDS) {
    if (!Object.prototype.hasOwnProperty.call(plan, field)) {
      failures.push(`missing top-level field "${field}"`);
    }
  }

  const corePreviewComponents = (Array.isArray(plan.corePreviewComponents) ? plan.corePreviewComponents : [])
    .map((entry, index) => normalizeComponentEntry(entry, index, failures, 'corePreviewComponents'))
    .filter(Boolean);
  const supportEvidenceComponents = (Array.isArray(plan.supportEvidenceComponents) ? plan.supportEvidenceComponents : [])
    .map((entry, index) => normalizeComponentEntry(entry, index, failures, 'supportEvidenceComponents'))
    .filter(Boolean);
  const screenBlueprints = (Array.isArray(plan.screenBlueprints) ? plan.screenBlueprints : [])
    .map((entry, index) => normalizeScreenBlueprint(entry, index, failures))
    .filter(Boolean);

  if (corePreviewComponents.length === 0) {
    failures.push('corePreviewComponents must not be empty');
  }
  // No upper-bound validation — count is controlled by generate-uikit-plan.mjs LIMITS config.

  const computedAllowed = unique([
    ...corePreviewComponents.map((entry) => entry.slug),
    ...supportEvidenceComponents.map((entry) => entry.slug),
    ...screenBlueprints.flatMap((entry) => entry.componentSlugs),
  ]);
  const allowedComponents = unique(Array.isArray(plan.allowedComponents)
    ? plan.allowedComponents.map((slug) => typeof slug === 'string' ? slug.trim() : '')
    : []);

  if (allowedComponents.length === 0) {
    failures.push('allowedComponents must not be empty');
  }

  const missingFromAllowed = computedAllowed.filter((slug) => !allowedComponents.includes(slug));
  const extraAllowed = allowedComponents.filter((slug) => !computedAllowed.includes(slug));
  if (missingFromAllowed.length > 0 || extraAllowed.length > 0) {
    failures.push(
      `allowedComponents must equal selected component union; missing=[${missingFromAllowed.join(', ')}], extra=[${extraAllowed.join(', ')}]`,
    );
  }

  const evidenceSlugs = loadEvidenceSlugs(options.evidenceIndexPath, failures);
  if (evidenceSlugs) {
    const unknownAllowed = allowedComponents.filter((slug) => !evidenceSlugs.has(slug));
    if (unknownAllowed.length > 0) {
      failures.push(`allowedComponents not found in evidence index: ${unknownAllowed.join(', ')}`);
    }
  }
  const componentSlugs = loadComponentContractSlugs(options.componentIndexPath, options.componentsDirPath, failures);
  if (componentSlugs) {
    const unknownAllowed = allowedComponents.filter((slug) => !componentSlugs.has(slug));
    if (unknownAllowed.length > 0) {
      failures.push(`allowedComponents not found in component index: ${unknownAllowed.join(', ')}`);
    }
  }

  const forbiddenInventedComponents = Array.isArray(plan.forbiddenInventedComponents)
    ? unique(plan.forbiddenInventedComponents.map((slug) => typeof slug === 'string' ? slug.trim() : ''))
    : [];
  const normalizedWarnings = Array.isArray(plan.warnings)
    ? plan.warnings.filter((item) => typeof item === 'string')
    : [];

  const headBoilerplate = typeof plan.headBoilerplate === 'string'
    ? plan.headBoilerplate
    : '<link rel="stylesheet" href="../../colors_and_type.css">';
  if (typeof plan.headBoilerplate !== 'string') {
    warnings.push('defaulted-headBoilerplate');
  } else if (!plan.headBoilerplate.includes('colors_and_type.css')) {
    failures.push('uikit-plan missing or invalid headBoilerplate field');
  }

  if (typeof plan.lowConfidence !== 'boolean') {
    failures.push('lowConfidence must be a boolean');
  }

  // 透传已知附加字段(layout/selectionPolicy/slotAssignments 等),
  // 这些字段被 phase-4 模板(sidebarColumnWidth/fixed-slots 诊断)和场景化链路消费,剥离会使下游契约失效
  const passthrough = {};
  if (plan.layout && typeof plan.layout === 'object' && !Array.isArray(plan.layout)) {
    passthrough.layout = plan.layout;
  }
  if (typeof plan.selectionPolicy === 'string' && plan.selectionPolicy) {
    passthrough.selectionPolicy = plan.selectionPolicy;
  }
  if (Array.isArray(plan.slotAssignments)) {
    passthrough.slotAssignments = plan.slotAssignments;
  }
  if (Array.isArray(plan.missingFixedSlots)) {
    passthrough.missingFixedSlots = plan.missingFixedSlots;
  }
  if (Array.isArray(plan.fallbackComponents)) {
    passthrough.fallbackComponents = plan.fallbackComponents;
  }
  if (typeof plan.needsNarrative === 'boolean') {
    passthrough.needsNarrative = plan.needsNarrative;
  }
  if (plan.productNarrative && typeof plan.productNarrative === 'object' && !Array.isArray(plan.productNarrative)) {
    passthrough.productNarrative = plan.productNarrative;
  }

  const normalized = {
    schemaVersion: Number.isFinite(plan.schemaVersion) ? plan.schemaVersion : 1,
    headBoilerplate,
    corePreviewComponents,
    supportEvidenceComponents,
    allowedComponents,
    screenBlueprints,
    ...(plan.productContext && typeof plan.productContext === 'object' && !Array.isArray(plan.productContext)
      ? { productContext: plan.productContext }
      : {}),
    ...passthrough,
    forbiddenInventedComponents,
    lowConfidence: Boolean(plan.lowConfidence),
    warnings: normalizedWarnings,
  };

  return {
    ok: failures.length === 0,
    failures,
    warnings,
    plan: normalized,
  };
}

export function validateUiKitPlanFile(planPath, options = {}) {
  const failures = [];
  let rawPlan;
  try {
    rawPlan = readJson(planPath);
  } catch (error) {
    return {
      ok: false,
      failures: [`failed to parse uikit plan: ${error.message}`],
      warnings: [],
    };
  }

  const result = normalizeUiKitPlan(rawPlan, options);
  failures.push(...result.failures);

  if (failures.length === 0 && options.outPaths?.length) {
    const content = `${JSON.stringify(result.plan, null, 2)}\n`;
    for (const outPath of options.outPaths) {
      fs.mkdirSync(path.dirname(outPath), { recursive: true });
      fs.writeFileSync(outPath, content);
    }
  }

  return {
    ok: failures.length === 0,
    failures,
    warnings: result.warnings,
    plan: result.plan,
  };
}

function parseArgs(argv) {
  const args = {
    outPaths: [],
  };
  for (let index = 0; index < argv.length; index += 1) {
    const arg = argv[index];
    if (arg === '--plan') {
      args.planPath = argv[++index];
    } else if (arg === '--evidence-index') {
      args.evidenceIndexPath = argv[++index];
    } else if (arg === '--component-index') {
      args.componentIndexPath = argv[++index];
    } else if (arg === '--components-dir') {
      args.componentsDirPath = argv[++index];
    } else if (arg === '--out') {
      args.outPaths.push(argv[++index]);
    } else {
      throw new Error(`unknown argument: ${arg}`);
    }
  }
  return args;
}

const currentFile = fileURLToPath(import.meta.url);
if (process.argv[1] === currentFile) {
  try {
    const args = parseArgs(process.argv.slice(2));
    if (!args.planPath) {
      throw new Error('--plan is required');
    }
    if (args.evidenceIndexPath && (args.componentIndexPath || args.componentsDirPath)) {
      throw new Error('choose either --evidence-index or --component-index/--components-dir, not both');
    }
    const result = validateUiKitPlanFile(path.resolve(args.planPath), {
      evidenceIndexPath: args.evidenceIndexPath ? path.resolve(args.evidenceIndexPath) : undefined,
      componentIndexPath: args.componentIndexPath ? path.resolve(args.componentIndexPath) : undefined,
      componentsDirPath: args.componentsDirPath ? path.resolve(args.componentsDirPath) : undefined,
      outPaths: args.outPaths.map((outPath) => path.resolve(outPath)),
    });
    const summary = {
      ok: result.ok,
      failures: result.failures,
      warnings: result.warnings,
      allowedComponents: result.plan?.allowedComponents || [],
      coreCount: result.plan?.corePreviewComponents?.length || 0,
      supportCount: result.plan?.supportEvidenceComponents?.length || 0,
    };
    if (!result.ok) {
      console.error(JSON.stringify(summary, null, 2));
      process.exit(1);
    }
    console.log(JSON.stringify(summary, null, 2));
  } catch (error) {
    console.error(JSON.stringify({ ok: false, failures: [error.message], warnings: [] }, null, 2));
    process.exit(1);
  }
}
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 197kUpdated Claude CodeCodexVerifiedInstall