Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

12.4 KB
Raw Blame
import type { SnapshotColor } from './snapshot.ts';
import { SEMANTIC_ROLE_IDS } from './semantic-roles.ts';

export const CLASSIFICATION_CATEGORIES = [
  'literal',
  'alias',
  'hsl-triplet',
  'runtime-derived-or-protected',
] as const;

export type ClassificationCategory = (typeof CLASSIFICATION_CATEGORIES)[number];

export type ClassificationDestination =
  | 'reference-candidate'
  | 'semantic-or-component-candidate'
  | 'hsl-pair'
  | 'register-only';

export interface ProtectedRule {
  family: 'cindy-skin-family' | 'u2-secondary-info' | 'annotation-accent';
  owner: string;
  rule: string;
  /**
   * semantic-modeled:Tier-1 semantic slot(治理合同 §3.2「名称与用途延续」)
   * ——照常 semantic 建模 + 保留 protected 元数据;保护限制的是改值须经
   * 裁决,不是禁止迁移(review P2 实锤:U2 的 text-secondary 被统一
   * register-only 分支移出 semantic,DS-8 将无法从新真相源生成它)。
   * register-only:Tier-3 singleton(治理合同 §3.2「protected 角色或保留
   * 原位,逐项裁决,默认不动」)——本 PR 未裁决进 semantic,只登记。
   */
  mode: 'semantic-modeled' | 'register-only';
}

export interface ExemptionRule {
  family: 'semantic-exemption';
  owner: string;
  rule: string;
}

export interface ClassificationEntry {
  id: string;
  category: ClassificationCategory;
  destination: ClassificationDestination;
  lightKind: ValueKind;
  darkKind: ValueKind;
  aliasOf?: { light: string | null; dark: string | null };
  hslPairOf?: string;
  protected?: ProtectedRule;
  /** 语义豁免色(DESIGN.md §10 theme-invariant 族):照常 semantic 建模,但带豁免元数据——外部主题不可覆盖,DS-8 生成主题入口时据此与可覆写 semantic 区分。 */
  exemption?: ExemptionRule;
  modeledAsSemantic: boolean;
}

export interface ClassificationDocument {
  source: string;
  generatedBy: 'packages/design-tokens/src/classify.ts';
  snapshotCount: number;
  categories: Record<ClassificationCategory, number>;
  entries: ClassificationEntry[];
}

export type ValueKind =
  | 'null'
  | 'alias'
  | 'hex'
  | 'rgb'
  | 'hsl-function'
  | 'hsl-triplet'
  | 'transparent'
  | 'css-keyword'
  | 'color-mix'
  | 'shadow'
  | 'non-color'
  | 'mixed';

const VAR_RE = /^(?:hsl\()?var\(--([a-z0-9-]+)\)\)?$/;
const HEX_RE = /^#([0-9a-fA-F]{3,8})$/;
const RGB_RE = /^rgba?\(/;
const HSL_FN_RE = /^hsla?\(/;
const TRIPLET_RE = /^-?\d+(?:\.\d+)?\s+\d+(?:\.\d+)?%\s+\d+(?:\.\d+)?%$/;
const LENGTH_RE = /^\d+(?:\.\d+)?(?:px|rem|ms|em)$/;
const NUMBER_RE = /^\d+(?:\.\d+)?$/;

/**
 * 加严保护值:治理合同 §1.1 / DESIGN.md §15。
 * 两种 mode(治理合同 §3.2 的 Tier-1/Tier-3 分野):
 *  - semantic-modeled——Tier-1 slot(text-secondary / text-secondary-cross):
 *    照常 semantic 建模 + protected 元数据。保护(原 U2,2026-10-22 起为墨水文字
 *    阶梯,family id 沿用 u2-secondary-info)限制的是改值须裁决,
 *    不是禁止迁移;「名称与用途延续」要求 DS-8 能从新真相源生成它们。
 *  - register-only——Tier-3 singleton(annotation-accent / login-brand-*):
 *    只登记、不建模(治理合同「保留原位,逐项裁决,默认不动」)。
 * CINDY 皮肤族在默认 ColorRegistry 里只有登录品牌红两项(其余皮肤值在
 * cindy-light/dark 主题 override,不在本快照)。
 */
export const PROTECTED_IDS: Readonly<Record<string, ProtectedRule>> = {
  'annotation-accent': {
    family: 'annotation-accent',
    owner: 'DESIGN.md §15.4',
    rule: '图片标注烧录墨色,exempt, do not change',
    mode: 'register-only',
  },
  'text-secondary': {
    family: 'u2-secondary-info',
    owner: 'DESIGN.md §15.16',
    rule: '文字次要档:改值须用户裁决(2026-10-22 起墨水文字阶梯取代 U2,保护延续到整条阶梯)',
    mode: 'semantic-modeled',
  },
  'text-secondary-cross': {
    family: 'u2-secondary-info',
    owner: 'DESIGN.md §15.16',
    rule: '文字次要档:改值须用户裁决(2026-10-22 起墨水文字阶梯取代 U2,保护延续到整条阶梯)',
    mode: 'semantic-modeled',
  },
  'login-brand-accent': {
    family: 'cindy-skin-family',
    owner: 'DESIGN.md §15.1',
    rule: 'CINDY 皮肤族品牌红,实现期零裁量',
    mode: 'register-only',
  },
  'login-brand-accent-pressed': {
    family: 'cindy-skin-family',
    owner: 'DESIGN.md §15.1',
    rule: 'CINDY 皮肤族品牌红(pressed),实现期零裁量',
    mode: 'register-only',
  },
};

/**
 * 语义豁免色(DESIGN.md §10 Semantic Exemption Colors,theme-invariant):
 * 与 PROTECTED_IDS 的区别——豁免色**照常进 semantic 建模**(消费方按语义
 * 角色引用),但外部主题不可覆盖、跨主题恒定。治理合同 §3.2 要求 Tier-3
 * 豁免色作为 semantic 中的 protected 角色迁移;这里用独立的 exemption
 * 标记承载(不塞 PROTECTED_IDS——那个的语义是「只登记不建模」,会被
 * assertProtectedNotSemantic 拒进 semantic)。DS-8 生成主题入口时据此
 * 区分「可覆写 semantic」与「必须保留原值的豁免族」。
 * 只登记已进首批 semantic 角色(SEMANTIC_ROLES)的豁免色;DESIGN.md §10
 * 豁免表其余未建模项(diff-*、login-error-fg 等)进 shadow 层时再登记。
 */
export const SEMANTIC_EXEMPTION_IDS: Readonly<Record<string, ExemptionRule>> = {
  destructive: {
    family: 'semantic-exemption',
    owner: 'DESIGN.md §10',
    rule: 'theme-invariant 语义豁免色(Tier-3 singleton),外部主题不覆盖',
  },
  'error-flat': {
    family: 'semantic-exemption',
    owner: 'DESIGN.md §10',
    rule: 'theme-invariant 语义豁免色(Tier-3 singleton),外部主题不覆盖',
  },
  'error-bg': {
    family: 'semantic-exemption',
    owner: 'DESIGN.md §10',
    rule: 'theme-invariant 语义豁免色(Tier-3 singleton),外部主题不覆盖',
  },
  'error-border': {
    family: 'semantic-exemption',
    owner: 'DESIGN.md §10',
    rule: 'theme-invariant 语义豁免色(Tier-3 singleton),外部主题不覆盖',
  },
  'error-fg': {
    family: 'semantic-exemption',
    owner: 'DESIGN.md §10',
    rule: 'theme-invariant 语义豁免色(Tier-3 singleton),外部主题不覆盖',
  },
  'error-fg-strong': {
    family: 'semantic-exemption',
    owner: 'DESIGN.md §10',
    rule: 'theme-invariant 语义豁免色(Tier-3 singleton),外部主题不覆盖',
  },
  'warning-accent': {
    family: 'semantic-exemption',
    owner: 'DESIGN.md §10',
    rule: 'theme-invariant 语义豁免色(Tier-3 singleton),外部主题不覆盖',
  },
  'warning-fg': {
    family: 'semantic-exemption',
    owner: 'DESIGN.md §10',
    rule: 'theme-invariant 语义豁免色(Tier-3 singleton),外部主题不覆盖',
  },
  'warning-bg-soft': {
    family: 'semantic-exemption',
    owner: 'DESIGN.md §10',
    rule: 'theme-invariant 语义豁免色(Tier-3 singleton),外部主题不覆盖',
  },
  'focus-ring': {
    family: 'semantic-exemption',
    owner: 'DESIGN.md §10',
    rule: 'theme-invariant 语义豁免色(Tier-3 singleton),外部主题不覆盖',
  },
  'focus-ring-soft': {
    family: 'semantic-exemption',
    owner: 'DESIGN.md §10',
    rule: 'theme-invariant 语义豁免色(Tier-3 singleton),外部主题不覆盖',
  },
};

export function parseAliasTarget(value: string | null): string | null {
  if (value == null) return null;
  const match = VAR_RE.exec(value.trim());
  return match ? match[1] : null;
}

export function classifyValue(value: string | null): ValueKind {
  if (value == null) return 'null';
  const text = value.trim();
  if (text.startsWith('color-mix(')) return 'color-mix';
  if (parseAliasTarget(text)) return 'alias';
  if (text === 'transparent') return 'transparent';
  if (text === 'inherit' || text === 'none' || text === 'currentColor') {
    return 'css-keyword';
  }
  if (HEX_RE.test(text)) return 'hex';
  if (RGB_RE.test(text)) return 'rgb';
  if (HSL_FN_RE.test(text)) return 'hsl-function';
  if (TRIPLET_RE.test(text)) return 'hsl-triplet';
  if (LENGTH_RE.test(text) || NUMBER_RE.test(text) || text.startsWith('cubic-bezier')) {
    return 'non-color';
  }
  if (/\brgba?\(/.test(text)) return 'shadow';
  return 'mixed';
}

export function isLiteralKind(kind: ValueKind): boolean {
  return (
    kind === 'hex' ||
    kind === 'rgb' ||
    kind === 'hsl-function' ||
    kind === 'hsl-triplet' ||
    kind === 'transparent'
  );
}

export function classifyColor(entry: SnapshotColor): ClassificationEntry {
  const lightKind = classifyValue(entry.light);
  const darkKind = classifyValue(entry.dark);
  const protectedRule = PROTECTED_IDS[entry.id];
  // 豁免色照常建模(category / destination 走正常分支),只附加豁免元数据。
  const exemptionRule = SEMANTIC_EXEMPTION_IDS[entry.id];

  if (protectedRule) {
    // register-only(Tier-3 singleton):只登记、不建模,维持既有行为。
    if (protectedRule.mode === 'register-only') {
      return {
        id: entry.id,
        category: 'runtime-derived-or-protected',
        destination: 'register-only',
        lightKind,
        darkKind,
        protected: protectedRule,
        modeledAsSemantic: false,
      };
    }
    // semantic-modeled(Tier-1 slot):照常走值形态分类(命名与用途延续),
    // 保留 protected 元数据、强制进 semantic——保护限制改值,不禁止迁移。
    return {
      id: entry.id,
      category: isLiteralKind(lightKind) && isLiteralKind(darkKind)
        ? 'literal'
        : lightKind === 'alias' && darkKind === 'alias'
          ? 'alias'
          : 'runtime-derived-or-protected',
      destination: isLiteralKind(lightKind) && isLiteralKind(darkKind)
        ? 'reference-candidate'
        : lightKind === 'alias' && darkKind === 'alias'
          ? 'semantic-or-component-candidate'
          : 'register-only',
      lightKind,
      darkKind,
      aliasOf: lightKind === 'alias' && darkKind === 'alias'
        ? { light: parseAliasTarget(entry.light), dark: parseAliasTarget(entry.dark) }
        : undefined,
      protected: protectedRule,
      modeledAsSemantic: true,
    };
  }

  // -hsl 后缀只是命名约定,不能单独作为判据:双模式必须真的都是 hsl-triplet
  // 值(形如 `60 12.5% 97%`)。后缀命中但值不是 triplet 的条目按实际值形态
  // 落入 alias / literal / runtime-derived 分支,不许冒充 hsl-pair。
  if (
    entry.id.endsWith('-hsl') &&
    lightKind === 'hsl-triplet' &&
    darkKind === 'hsl-triplet'
  ) {
    return {
      id: entry.id,
      category: 'hsl-triplet',
      destination: 'hsl-pair',
      lightKind,
      darkKind,
      hslPairOf: entry.id.slice(0, -'-hsl'.length),
      ...(exemptionRule ? { exemption: exemptionRule } : {}),
      modeledAsSemantic: SEMANTIC_ROLE_IDS.has(entry.id),
    };
  }

  if (lightKind === 'alias' && darkKind === 'alias') {
    return {
      id: entry.id,
      category: 'alias',
      destination: 'semantic-or-component-candidate',
      lightKind,
      darkKind,
      aliasOf: {
        light: parseAliasTarget(entry.light),
        dark: parseAliasTarget(entry.dark),
      },
      ...(exemptionRule ? { exemption: exemptionRule } : {}),
      modeledAsSemantic: SEMANTIC_ROLE_IDS.has(entry.id),
    };
  }

  if (isLiteralKind(lightKind) && isLiteralKind(darkKind)) {
    return {
      id: entry.id,
      category: 'literal',
      destination: 'reference-candidate',
      lightKind,
      darkKind,
      ...(exemptionRule ? { exemption: exemptionRule } : {}),
      modeledAsSemantic: SEMANTIC_ROLE_IDS.has(entry.id),
    };
  }

  return {
    id: entry.id,
    category: 'runtime-derived-or-protected',
    destination: 'register-only',
    lightKind,
    darkKind,
    modeledAsSemantic: false,
  };
}

export function classifySnapshot(
  colors: readonly SnapshotColor[],
  source: string,
): ClassificationDocument {
  const entries = colors.map(classifyColor);
  const categories = {
    literal: 0,
    alias: 0,
    'hsl-triplet': 0,
    'runtime-derived-or-protected': 0,
  } satisfies Record<ClassificationCategory, number>;
  for (const entry of entries) {
    categories[entry.category] += 1;
  }
  return {
    source,
    generatedBy: 'packages/design-tokens/src/classify.ts',
    snapshotCount: colors.length,
    categories,
    entries,
  };
}

export function stableStringify(value: unknown): string {
  return `${JSON.stringify(value, null, 2)}\n`;
}