@qijenchen/design-system 0.1.0-beta.93 → 0.1.0-beta.96

package/src/tokens/utility-registry.json

@@ -1,13 +1,16 @@
 {
   "$schema": "./utility-registry.schema.json",
+  "schemaVersion": 1,
   "_meta": {
     "purpose": "Single SSOT for Tailwind utility allow/block — extracted from typography/radius/opacity/elevation/color spec.md 禁止 lists. Hook reads this(not grep spec.md)to enforce token-first discipline. New token additions or removals → update here first, spec.md cite registry.",
     "owner": "packages/design-system/src/tokens/utility-registry.json",
     "consumed_by": [
-      ".claude/hooks/check_opacity_token_usage.sh",
-      ".claude/skills/design-system-audit/references/audit-prompts.md Dim 5",
-      ".claude/hooks/lib/_token_hygiene.sh"
+      "packages/design-system/ds-canonical/hooks/check_opacity_token_usage.sh",
+      "packages/design-system/ds-canonical/skills/design-system-audit/references/audit-prompts.md#Dim-5",
+      "packages/design-system/ds-canonical/hooks/lib/_token_hygiene.sh",
+      "packages/design-system/ds-canonical/hooks/check_consumer_code_quality.sh"
     ],
+    "provider_view_policy": ".claude/.agents/.codex projections are generated discovery adapters only; they are never registry owners or edit targets.",
     "spec_sources": [
       "packages/design-system/src/tokens/typography/typography.spec.md L118-156",
       "packages/design-system/src/tokens/radius/radius.spec.md L57-71",
@@ -66,6 +69,116 @@
       }
     }
   },
+  "enforcement": {
+    "schemaVersion": 1,
+    "engine": "utility-registry-rules-v1",
+    "block": [
+      {
+        "id": "typography-size",
+        "label": "typography size",
+        "tokenListPointer": "/typography/block/size_raw"
+      },
+      {
+        "id": "typography-weight",
+        "label": "typography weight",
+        "tokenListPointer": "/typography/block/weight_raw"
+      },
+      {
+        "id": "typography-leading-numeric",
+        "label": "leading numeric",
+        "pattern": "(?<![A-Za-z0-9_-])leading-[0-9]+(?:\\.[0-9]+)?(?![A-Za-z0-9_-])"
+      },
+      {
+        "id": "typography-tracking",
+        "label": "tracking raw",
+        "tokenListPointer": "/typography/block/tracking_raw"
+      },
+      {
+        "id": "typography-inline-style",
+        "label": "typography inline style",
+        "pattern": "style\\s*=\\s*\\{\\{[^}]*\\b(?:fontSize|lineHeight)\\s*:"
+      },
+      {
+        "id": "radius-out-of-range",
+        "label": "radius out-of-range",
+        "tokenListPointer": "/radius/block/out_of_range"
+      },
+      {
+        "id": "radius-ambiguous-default",
+        "label": "radius ambiguous default",
+        "tokenListPointer": "/radius/block/ambiguous_default"
+      },
+      {
+        "id": "radius-arbitrary-examples",
+        "label": "radius arbitrary",
+        "tokenListPointer": "/radius/block/arbitrary_value"
+      },
+      {
+        "id": "radius-arbitrary",
+        "label": "radius arbitrary",
+        "pattern": "(?<![A-Za-z0-9_-])rounded(?:-(?:t|b|l|r|tl|tr|bl|br|s|e|ss|se|es|ee))?-\\[[^\\]\\r\\n]+\\](?![A-Za-z0-9_-])",
+        "excludeTokenListPointer": "/radius/allow"
+      },
+      {
+        "id": "radius-inline-style",
+        "label": "radius inline style",
+        "pattern": "style\\s*=\\s*\\{\\{[^}]*\\bborderRadius\\s*:"
+      },
+      {
+        "id": "opacity-numeric-tier",
+        "label": "opacity",
+        "tokenListPointer": "/opacity/block/numeric_tier"
+      },
+      {
+        "id": "opacity-numeric",
+        "label": "opacity",
+        "pattern": "(?<![A-Za-z0-9_-])opacity-[0-9]+(?![A-Za-z0-9_-])",
+        "excludeTokenListPointer": "/opacity/allow"
+      },
+      {
+        "id": "opacity-arbitrary",
+        "label": "opacity arbitrary",
+        "pattern": "(?<![A-Za-z0-9_-])opacity-\\[[^\\]\\r\\n]+\\](?![A-Za-z0-9_-])"
+      },
+      {
+        "id": "elevation-tailwind-size",
+        "label": "elevation size",
+        "tokenListPointer": "/elevation/block/tailwind_size"
+      },
+      {
+        "id": "shadcn-color-alias",
+        "label": "shadcn alias",
+        "tokenListPointer": "/shadcn_alias/block/color_alias"
+      },
+      {
+        "id": "primitive-color-examples",
+        "label": "primitive color as utility",
+        "tokenListPointer": "/primitive_color_as_utility/block/primitive_class"
+      },
+      {
+        "id": "primitive-color-family",
+        "label": "primitive color as utility",
+        "pattern": "(?<![A-Za-z0-9_-])(?:bg|text|border)-(?:neutral|blue|red|green|yellow|orange|purple|pink|cyan|teal|deep-orange|deep-purple|light-blue|light-green|lime|amber|indigo|brown|gray)-[0-9]+(?![A-Za-z0-9_-])"
+      },
+      {
+        "id": "phantom-state-suffix",
+        "label": "phantom state suffix(silent no-op)",
+        "pattern": "(?<![A-Za-z0-9_-])(?:(?:hover|active|focus):)?(?:bg|text|border|ring)-[a-z][a-z-]*-(?:hovered|actived|focussed|pressed)(?![A-Za-z0-9_-])"
+      }
+    ],
+    "warn": [
+      {
+        "id": "spacing-micro-gap",
+        "label": "micro gap <4px",
+        "tokenListPointer": "/spacing/warn/micro_gap"
+      },
+      {
+        "id": "sizing-fraction-width",
+        "label": "fraction width",
+        "tokenListPointer": "/sizing/warn/fraction"
+      }
+    ]
+  },
   "typography": {
     "allow": [
       "text-h1",
@@ -138,7 +251,9 @@
         "rounded-2xl",
         "rounded-3xl"
       ],
-      "ambiguous_default": "rounded(use rounded-md explicit)",
+      "ambiguous_default": [
+        "rounded"
+      ],
       "arbitrary_value": [
         "rounded-[6px]",
         "rounded-[var(--radius-md)]"

package/src/tokens/utility-registry.schema.json

@@ -0,0 +1,373 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://qijenchen.dev/schemas/design-system/utility-registry-v1.json",
+  "title": "Design-system utility policy registry",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "$schema",
+    "schemaVersion",
+    "_meta",
+    "enforcement",
+    "typography",
+    "radius",
+    "opacity",
+    "elevation",
+    "spacing",
+    "sizing",
+    "shadcn_alias",
+    "primitive_color_as_utility"
+  ],
+  "properties": {
+    "$schema": { "const": "./utility-registry.schema.json" },
+    "schemaVersion": { "const": 1 },
+    "_meta": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "purpose",
+        "owner",
+        "consumed_by",
+        "provider_view_policy",
+        "spec_sources",
+        "rationale",
+        "exceptions"
+      ],
+      "properties": {
+        "purpose": { "$ref": "#/$defs/nonEmptyString" },
+        "owner": {
+          "const": "packages/design-system/src/tokens/utility-registry.json"
+        },
+        "consumed_by": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/canonicalReference" }
+        },
+        "provider_view_policy": { "$ref": "#/$defs/nonEmptyString" },
+        "spec_sources": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/nonEmptyString" }
+        },
+        "rationale": { "$ref": "#/$defs/nonEmptyString" },
+        "exceptions": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "_added",
+            "anatomy_stories_inspector",
+            "token_stories_section_label",
+            "principles_stories_codepre",
+            "icon_as_text_and_numeric_in_circle"
+          ],
+          "properties": {
+            "_added": { "$ref": "#/$defs/nonEmptyString" },
+            "anatomy_stories_inspector": {
+              "allOf": [
+                { "$ref": "#/$defs/exceptionBase" },
+                {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["scope", "allowed_utilities", "rationale", "audit_dim_53_fix"],
+                  "properties": {
+                    "scope": { "$ref": "#/$defs/nonEmptyString" },
+                    "allowed_utilities": { "$ref": "#/$defs/tokenArray" },
+                    "rationale": { "$ref": "#/$defs/nonEmptyString" },
+                    "audit_dim_53_fix": { "$ref": "#/$defs/nonEmptyString" }
+                  }
+                }
+              ]
+            },
+            "token_stories_section_label": { "$ref": "#/$defs/standardException" },
+            "principles_stories_codepre": { "$ref": "#/$defs/standardException" },
+            "icon_as_text_and_numeric_in_circle": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "scope",
+                "allowed_utilities",
+                "rule_one_liner",
+                "rationale",
+                "current_consumers",
+                "non_goal"
+              ],
+              "properties": {
+                "scope": { "$ref": "#/$defs/nonEmptyString" },
+                "allowed_utilities": { "$ref": "#/$defs/tokenArray" },
+                "rule_one_liner": { "$ref": "#/$defs/nonEmptyString" },
+                "rationale": { "$ref": "#/$defs/nonEmptyString" },
+                "current_consumers": {
+                  "type": "array",
+                  "minItems": 1,
+                  "uniqueItems": true,
+                  "items": { "$ref": "#/$defs/nonEmptyString" }
+                },
+                "non_goal": { "$ref": "#/$defs/nonEmptyString" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "enforcement": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion", "engine", "block", "warn"],
+      "properties": {
+        "schemaVersion": { "const": 1 },
+        "engine": { "const": "utility-registry-rules-v1" },
+        "block": {
+          "type": "array",
+          "minItems": 18,
+          "maxItems": 18,
+          "items": { "$ref": "#/$defs/enforcementRule" }
+        },
+        "warn": {
+          "type": "array",
+          "minItems": 2,
+          "maxItems": 2,
+          "items": { "$ref": "#/$defs/enforcementRule" }
+        }
+      }
+    },
+    "typography": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["allow", "block"],
+      "properties": {
+        "allow": { "$ref": "#/$defs/tokenArray" },
+        "block": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "size_raw",
+            "weight_raw",
+            "leading_numeric",
+            "tracking_raw",
+            "tracking_raw_rationale",
+            "inline_style",
+            "rationale_path"
+          ],
+          "properties": {
+            "size_raw": { "$ref": "#/$defs/tokenArray" },
+            "weight_raw": { "$ref": "#/$defs/tokenArray" },
+            "leading_numeric": { "$ref": "#/$defs/nonEmptyString" },
+            "tracking_raw": { "$ref": "#/$defs/tokenArray" },
+            "tracking_raw_rationale": { "$ref": "#/$defs/nonEmptyString" },
+            "inline_style": { "$ref": "#/$defs/nonEmptyString" },
+            "rationale_path": { "$ref": "#/$defs/nonEmptyString" }
+          }
+        }
+      }
+    },
+    "radius": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["allow", "allow_note", "block"],
+      "properties": {
+        "allow": { "$ref": "#/$defs/tokenArray" },
+        "allow_note": { "$ref": "#/$defs/nonEmptyString" },
+        "block": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "out_of_range",
+            "ambiguous_default",
+            "arbitrary_value",
+            "inline_style",
+            "rationale_path"
+          ],
+          "properties": {
+            "out_of_range": { "$ref": "#/$defs/tokenArray" },
+            "ambiguous_default": { "$ref": "#/$defs/tokenArray" },
+            "arbitrary_value": { "$ref": "#/$defs/tokenArray" },
+            "inline_style": { "$ref": "#/$defs/nonEmptyString" },
+            "rationale_path": { "$ref": "#/$defs/nonEmptyString" }
+          }
+        }
+      }
+    },
+    "opacity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["allow", "block"],
+      "properties": {
+        "allow": { "$ref": "#/$defs/tokenArray" },
+        "block": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["numeric_tier", "arbitrary_value", "rationale_path", "philosophy"],
+          "properties": {
+            "numeric_tier": { "$ref": "#/$defs/tokenArray" },
+            "arbitrary_value": { "$ref": "#/$defs/nonEmptyString" },
+            "rationale_path": { "$ref": "#/$defs/nonEmptyString" },
+            "philosophy": { "$ref": "#/$defs/nonEmptyString" }
+          }
+        }
+      }
+    },
+    "elevation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["allow", "block"],
+      "properties": {
+        "allow": { "$ref": "#/$defs/tokenArray" },
+        "block": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["tailwind_size", "rationale_path", "philosophy"],
+          "properties": {
+            "tailwind_size": { "$ref": "#/$defs/tokenArray" },
+            "rationale_path": { "$ref": "#/$defs/nonEmptyString" },
+            "philosophy": { "$ref": "#/$defs/nonEmptyString" }
+          }
+        }
+      }
+    },
+    "spacing": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["allow_canonical", "warn"],
+      "properties": {
+        "allow_canonical": { "$ref": "#/$defs/nonEmptyString" },
+        "warn": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["micro_gap", "rationale"],
+          "properties": {
+            "micro_gap": { "$ref": "#/$defs/tokenArray" },
+            "rationale": { "$ref": "#/$defs/nonEmptyString" }
+          }
+        }
+      }
+    },
+    "sizing": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["warn"],
+      "properties": {
+        "warn": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["fraction", "rationale"],
+          "properties": {
+            "fraction": { "$ref": "#/$defs/tokenArray" },
+            "rationale": { "$ref": "#/$defs/nonEmptyString" }
+          }
+        }
+      }
+    },
+    "shadcn_alias": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["block"],
+      "properties": {
+        "block": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["color_alias", "rationale", "rationale_path"],
+          "properties": {
+            "color_alias": { "$ref": "#/$defs/tokenArray" },
+            "rationale": { "$ref": "#/$defs/nonEmptyString" },
+            "rationale_path": { "$ref": "#/$defs/nonEmptyString" }
+          }
+        }
+      }
+    },
+    "primitive_color_as_utility": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["block"],
+      "properties": {
+        "block": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["primitive_class", "rationale"],
+          "properties": {
+            "primitive_class": { "$ref": "#/$defs/tokenArray" },
+            "rationale": { "$ref": "#/$defs/nonEmptyString" }
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "nonEmptyString": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[^\\u0000-\\u001F\\u007F]+$"
+    },
+    "canonicalReference": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?!\\.claude(?:/|$)|\\.agents(?:/|$)|\\.codex(?:/|$))(?!/)(?!.*(?:^|/)\\.\\.?/)(?!.*\\\\)[A-Za-z0-9_.@/#-]+(?: [A-Za-z0-9_.@/#()-]+)*$"
+    },
+    "tokenArray": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "pattern": "^[^\\s\\u0000-\\u001F\\u007F]+$"
+      }
+    },
+    "exceptionBase": {
+      "type": "object"
+    },
+    "standardException": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["scope", "allowed_utilities", "rationale"],
+      "properties": {
+        "scope": { "$ref": "#/$defs/nonEmptyString" },
+        "allowed_utilities": { "$ref": "#/$defs/tokenArray" },
+        "rationale": { "$ref": "#/$defs/nonEmptyString" }
+      }
+    },
+    "enforcementRule": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id", "label", "tokenListPointer"],
+          "properties": {
+            "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+            "label": { "$ref": "#/$defs/nonEmptyString" },
+            "tokenListPointer": {
+              "enum": [
+                "/typography/block/size_raw",
+                "/typography/block/weight_raw",
+                "/typography/block/tracking_raw",
+                "/radius/block/out_of_range",
+                "/radius/block/ambiguous_default",
+                "/radius/block/arbitrary_value",
+                "/opacity/block/numeric_tier",
+                "/elevation/block/tailwind_size",
+                "/shadcn_alias/block/color_alias",
+                "/primitive_color_as_utility/block/primitive_class",
+                "/spacing/warn/micro_gap",
+                "/sizing/warn/fraction"
+              ]
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id", "label", "pattern"],
+          "properties": {
+            "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+            "label": { "$ref": "#/$defs/nonEmptyString" },
+            "pattern": { "$ref": "#/$defs/nonEmptyString" },
+            "excludeTokenListPointer": {
+              "enum": ["/radius/allow", "/opacity/allow"]
+            }
+          }
+        }
+      ]
+    }
+  }
+}

package/tools/README.md

@@ -0,0 +1,9 @@
+# Design-system migration tools
+
+This directory is shipped inside `@qijenchen/design-system`; it is the provider-neutral runtime for versioned API codemods and reviewed visual-baseline updates. Claude, Codex, hosted environments, and future models call the same package binaries and therefore do not own parallel migration logic.
+
+- `codemods/`: exact TypeScript AST binding, versioned migration plans, manual blockers, digest-bound check/apply, and rollback-safe pathname publication.
+- `visual-baseline/`: full PNG decode/CRC validation, content-addressed image statements, signed human or activated managed-broker review, and `apply-reviewed` without Git mutation.
+- `shared/`: no-link path validation and the common exclusive transaction/rollback primitive.
+
+The transaction claim is limited to cooperating writers that honor the same lock plus observed per-file pathname CAS. These tools do not claim parent-directory-swap resistance, storage power-loss durability, or protection from a non-cooperative writer that retains an old open file descriptor.

package/tools/codemods/cli.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { readFileSync, realpathSync } from 'node:fs'
+import { relative, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+  BETA_84_MIGRATION_ID,
+  applyCodemodProposal,
+  checkCodemodProposal,
+  planCodemod,
+} from './index.mjs'
+import { canonicalJson, writeAtomicFile } from '../shared/safe-filesystem.mjs'
+
+function fail(message) {
+  throw new Error(`design-system codemod CLI blocked:${message}`)
+}
+
+function parse(argv) {
+  const [migrationId, command, ...tokens] = argv
+  if (migrationId !== BETA_84_MIGRATION_ID) fail(`first argument must be ${BETA_84_MIGRATION_ID}`)
+  if (!['plan', 'check', 'apply'].includes(command)) fail('command must be plan, check, or apply')
+  const options = { migrationId, command, root: '.', sources: [], output: null, proposal: null, expectedDigest: null }
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index]
+    const next = () => {
+      const value = tokens[++index]
+      if (!value || value.startsWith('--')) fail(`${token} requires a value`)
+      return value
+    }
+    if (token === '--root') options.root = next()
+    else if (token === '--source') options.sources.push(next())
+    else if (token === '--output') options.output = next()
+    else if (token === '--proposal') options.proposal = next()
+    else if (token === '--expected-proposal-digest') options.expectedDigest = next()
+    else fail(`unknown option:${token}`)
+  }
+  return options
+}
+
+function relativeOutput(root, value) {
+  const absoluteRoot = resolve(root)
+  const absolute = resolve(absoluteRoot, value)
+  const path = relative(absoluteRoot, absolute)
+  if (!path || path === '..' || path.startsWith(`..${sep}`)) fail('output must be a file below --root')
+  return path.split(sep).join('/')
+}
+
+function readProposal(root, value) {
+  if (!value) fail('--proposal is required')
+  const absolute = resolve(root, value)
+  let proposal
+  try { proposal = JSON.parse(readFileSync(absolute, 'utf8')) } catch (error) { fail(`proposal is unavailable or invalid JSON:${error.message}`) }
+  return proposal
+}
+
+export function runCodemodCli(argv = process.argv.slice(2)) {
+  const options = parse(argv)
+  if (options.command === 'plan') {
+    if (options.proposal || options.expectedDigest) fail('plan does not accept apply/check evidence options')
+    const proposal = planCodemod({ repoRoot: options.root, sourceRoots: options.sources.length ? options.sources : ['.'] })
+    const body = Buffer.from(canonicalJson(proposal))
+    if (options.output) writeAtomicFile(resolve(options.root), relativeOutput(options.root, options.output), body, 'codemod proposal', fail)
+    else process.stdout.write(body)
+    if (proposal.blockers.length) {
+      process.stderr.write(`codemod blocked: ${proposal.blockers.length} manual blocker(s); proposal ${proposal.proposalDigest}\n`)
+      return 2
+    }
+    if (options.output) process.stdout.write(`${canonicalJson({ proposalDigest: proposal.proposalDigest, files: proposal.files.length, output: options.output })}`)
+    return 0
+  }
+  if (options.sources.length || options.output) fail(`${options.command} does not accept --source or --output`)
+  const proposal = readProposal(options.root, options.proposal)
+  const result = options.command === 'check'
+    ? checkCodemodProposal({ repoRoot: options.root, proposal })
+    : applyCodemodProposal({ repoRoot: options.root, proposal, expectedProposalDigest: options.expectedDigest })
+  process.stdout.write(canonicalJson(result))
+  return 0
+}
+
+function isMainModule(argvPath = process.argv[1]) {
+  if (!argvPath) return false
+  try {
+    return realpathSync(argvPath) === realpathSync(fileURLToPath(import.meta.url))
+  } catch {
+    return resolve(argvPath) === resolve(fileURLToPath(import.meta.url))
+  }
+}
+
+if (isMainModule()) {
+  try { process.exitCode = runCodemodCli() } catch (error) {
+    console.error(error.message)
+    process.exitCode = 1
+  }
+}