@sparknest/theme-contract-vue 0.0.0-stage → 1.1.1

package/README.md

@@ -1,3 +1,28 @@
-# Temporary Holding Version
+# @sparknest/theme-contract-vue
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Cedar 与 Maple 的主题公共契约。`tokens.components` 是两端必须同时实现的公共 Token；`platformExtensions` 只登记确有不同 DOM/交互职责的组件，未登记组件不得增加单端公开 Token。
+
+`pnpm check` 会验证系统 Token、受管 system 颜色与组件 Token 的标准值、公共组件 Token、平台扩展边界、主题覆盖引用、旧 Token denylist 与文档中的 Token 名称。新增主题变量时应先决定它属于公共语义还是平台结构，不得用未消费的兼容别名制造表面对齐。
+
+Cedar 与 Maple 的中立主题契约事实来源。
+
+- `contracts/theme-contract.json` 管理两端必须共同遵守的组件和规则。
+- `systemTokenValues` 使用 `--PREFIX-` 作为中立占位符，登记跨端同义同值的颜色、间距、圆角、文字、动效与层级角色；其余显式平台默认共同覆盖所有 system 名称。
+- `componentTokenValues` 分批登记完成治理的公开组件 Token 默认值；未登记不表示允许漂移，而是尚待迁移。
+- `platformSystemTokenValues` 登记控件密度、浮层层级等有依据的平台差异；每个 system 名称必须在共享值或该端平台值中且只出现一次。
+- `platformComponentTokenValues` 按 cedar/maple 登记几何、密度及明确的平台语义默认差异；与共享 componentTokenValues 不得重叠。它不豁免名称、消费路径或主题检查。Checkbox 的 `mark-color` 是共享公开名称，但保留现有默认语义：Cedar 为 `surface-default`，Maple 为 `content-on-bright`，不通过统一登记来改变任一主题的实际配色。
+- `schema/theme-contract.schema.json` 约束契约文件结构。
+- 两端检查器必须从本包读取契约，禁止各自维护组件白名单。
+- 公共组件 token 使用相同逻辑名；`c` 与 `mp` 只作为平台前缀。
+- Switch 的 `checked-text-color` 是公开选中态前景：Cedar 默认跟随 `switch-text-color`，Maple 默认使用 `content-on-bright`。主题通过公开 token 覆盖，不能直接覆盖 `internal` token；Maple 浅色主题迁移后仍使用原有 `content-on-dark`。
+- 不允许兼容别名，品牌主题不得覆盖 `internal` token。
+
+新增或修改公共主题能力时，先修改本包契约，再同时修改 Cedar 与 Maple。
+
+CSS 变量的分层、公开边界和选用规则见 [Design Token 规范](../../standards/design-tokens.md)。
+
+`pnpm sync` 仅用于经过评审的契约变更；日常开发和 CI 使用 `pnpm check`，源码与已登记 token 不一致时直接失败。
+
+检查同时覆盖主题覆盖合法性、`internal` 隔离、旧变量 denylist，以及受管组件文档中的变量引用。
+
+`node ../../bin/token-inventory.mjs --check-consumers --summary` 审计全部组件声明消费；`node ../../bin/token-catalog.mjs --check` 校验两端菜单参考页。二者与名称／值契约是独立门禁，不代替真实浏览器状态验收。默认值规范化仅消除前缀、Less var 引号和等价 rgb alpha 写法，不把不同的语义变量或单位归并成“同值”。

package/bin/theme-contract.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+import { readFileSync, writeFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { checkThemeContract, collectThemeContract } from '../src/checker.mjs'
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const workspace = resolve(packageRoot, '../../..')
+const sources = {
+  cedarSource: resolve(workspace, 'cedar-design-web/packages/ui/src'),
+  mapleSource: resolve(workspace, 'maple-design-mobile/packages/ui/src'),
+}
+const command = process.argv[2] ?? 'check'
+
+if (command === 'sync') {
+  const path = resolve(packageRoot, 'contracts/theme-contract.json')
+  const contract = JSON.parse(readFileSync(path, 'utf8'))
+  contract.tokens = collectThemeContract(sources)
+  writeFileSync(path, `${JSON.stringify(contract, null, 2)}\n`)
+  console.log(`Theme contract synchronized: ${contract.tokens.system.length} system tokens, ${contract.components.length} components.`)
+} else if (command === 'check') {
+  const result = checkThemeContract(sources)
+  console.log(
+    `Theme contract passed: ${result.systemCount} system tokens, ` +
+      `${result.systemValueCount} governed system values, ${result.componentValueCount} governed component values, ` +
+      `${result.platformSystemValueCount} platform system values, ${result.platformComponentValueCount} platform component values, and ${result.componentCount} components.`,
+  )
+} else {
+  throw new Error(`Unknown command: ${command}`)
+}

package/contracts/legacy-denylist.json

@@ -0,0 +1,184 @@
+{
+  "cedar": [
+    "verification-code-column-gap",
+    "rate-gap-size",
+    "rate-font-size",
+    "rate-scale-active",
+    "rate-bg-active",
+    "rate-bg",
+    "rate-transition-duration-scale",
+    "checkbox-mask-bg-checked",
+    "checkbox-mask-border-color",
+    "checkbox-text-color",
+    "radio-bg-checked",
+    "radio-border-color",
+    "radio-text-color",
+    "textarea-color-tip-text",
+    "textarea-font-tip-size",
+    "textarea-layout-tip-right",
+    "textarea-padding-x",
+    "textarea-padding-y",
+    "textarea-size-min-height",
+    "upload-trigger-gap",
+    "upload-trigger-border-radius",
+    "upload-icon-font-size",
+    "upload-list-gap",
+    "upload-picture-grid-gap",
+    "upload-item-gap",
+    "upload-item-border-radius",
+    "upload-item-padding-vertical",
+    "upload-item-padding-horizontal",
+    "upload-item-picture-min-height",
+    "upload-item-picture-padding",
+    "upload-thumb-border-radius",
+    "upload-meta-gap",
+    "upload-meta-picture-card-padding-vertical",
+    "upload-meta-picture-card-padding-horizontal",
+    "upload-meta-picture-card-color",
+    "upload-size-font-size",
+    "upload-status-icon-font-size",
+    "upload-actions-gap",
+    "upload-action-border-radius",
+    "upload-action-picture-card-color",
+    "upload-progress-border-radius",
+    "upload-picture-overlay-bg",
+    "upload-picture-card-overlay-bg",
+    "upload-picture-action-bg"
+  ],
+  "maple": [
+    "rate-color",
+    "rate-primary-color",
+    "alert-action-margin",
+    "alert-close-icon-margin",
+    "alert-close-icon-size",
+    "alert-danger-background",
+    "alert-default-background",
+    "alert-default-border-color",
+    "alert-default-text-color",
+    "alert-icon-margin",
+    "alert-info-background",
+    "alert-message-font-size",
+    "alert-message-line-height",
+    "alert-message-margin-top",
+    "alert-padding",
+    "alert-standard-danger-text-color",
+    "alert-standard-info-text-color",
+    "alert-standard-success-text-color",
+    "alert-standard-warning-text-color",
+    "alert-success-background",
+    "alert-title-font-size",
+    "alert-title-font-weight",
+    "alert-tonal-danger-background",
+    "alert-tonal-danger-text-color",
+    "alert-tonal-info-background",
+    "alert-tonal-info-text-color",
+    "alert-tonal-success-background",
+    "alert-tonal-success-text-color",
+    "alert-tonal-warning-background",
+    "alert-tonal-warning-text-color",
+    "alert-warning-background",
+    "checkbox-checked-color",
+    "checkbox-disabled-color",
+    "checkbox-error-color",
+    "checkbox-icon-size",
+    "checkbox-text-color",
+    "checkbox-unchecked-color",
+    "radio-checked-color",
+    "radio-disabled-color",
+    "radio-error-color",
+    "radio-icon-size",
+    "radio-text-color",
+    "radio-unchecked-color",
+    "tag-font-weight",
+    "tag-icon-margin",
+    "tag-padding",
+    "tag-size-lg-height",
+    "tag-size-lg-icon-margin",
+    "tag-size-lg-padding",
+    "tag-size-md-height",
+    "tag-size-md-icon-margin",
+    "tag-size-md-padding",
+    "tag-size-sm-height",
+    "tag-size-sm-icon-margin",
+    "tag-size-sm-padding",
+    "tag-size-xl-height",
+    "tag-size-xl-icon-margin",
+    "tag-size-xl-padding",
+    "tag-size-xs-height",
+    "tag-size-xs-icon-margin",
+    "tag-size-xs-padding",
+    "tag-status-danger-border-color",
+    "tag-status-danger-color",
+    "tag-status-default-border-color",
+    "tag-status-default-color",
+    "tag-status-default-text-color",
+    "tag-status-info-border-color",
+    "tag-status-info-color",
+    "tag-status-primary-border-color",
+    "tag-status-primary-color",
+    "tag-status-secondary-border-color",
+    "tag-status-secondary-color",
+    "tag-status-success-border-color",
+    "tag-status-success-color",
+    "tag-status-tertiary-border-color",
+    "tag-status-tertiary-color",
+    "tag-status-warning-border-color",
+    "tag-status-warning-color",
+    "search-height",
+    "search-padding",
+    "search-background",
+    "search-field-height",
+    "search-field-padding",
+    "search-field-background",
+    "search-label-color",
+    "search-label-margin-right",
+    "search-action-color",
+    "search-action-margin-left",
+    "search-icon-color",
+    "search-history-padding",
+    "search-history-item-height",
+    "search-history-item-color",
+    "search-history-item-border-color",
+    "upload-action-background",
+    "upload-action-icon-color",
+    "upload-file-name-background",
+    "upload-file-name-color",
+    "upload-file-cover-background",
+    "upload-action-icon-size",
+    "upload-action-margin",
+    "upload-file-size",
+    "upload-file-margin",
+    "upload-file-name-font-size",
+    "upload-file-name-padding",
+    "upload-file-text-align",
+    "upload-file-border-radius",
+    "upload-file-close-background",
+    "upload-file-close-size",
+    "upload-file-close-icon-font-size",
+    "upload-file-close-icon-color",
+    "upload-file-cover-fit",
+    "upload-preview-video-width",
+    "upload-preview-video-height",
+    "upload-file-indicator-height",
+    "upload-file-indicator-normal-color",
+    "upload-file-indicator-success-color",
+    "upload-file-indicator-error-color",
+    "upload-file-progress-color",
+    "upload-disabled-color",
+    "upload-disabled-text-color",
+    "upload-loading-background",
+    "carousel-indicator-color",
+    "carousel-indicators-offset",
+    "carousel-indicator-offset",
+    "carousel-navigation-button-width",
+    "carousel-navigation-button-height",
+    "carousel-navigation-button-border-radius",
+    "carousel-navigation-button-background",
+    "carousel-navigation-button-color",
+    "carousel-navigation-icon-size",
+    "carousel-navigation-prev-left",
+    "carousel-navigation-next-right",
+    "carousel-navigation-prev-top",
+    "carousel-navigation-next-bottom"
+  ]
+}