@hia/theme-core 0.6.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,7 @@
1
1
  import { bestOnColor } from '../color/contrast.js';
2
2
  import { tonalScaleAt } from '../color/scale.js';
3
3
  import { typographySpacingVars } from '../token/typography.js';
4
+ import { radiusSequence, shadowCss } from '../token/radius.js';
4
5
  import { clamp } from '../color/convert.js';
5
6
  import { GRADIENT_DEFS } from '../data/gradients.js';
6
7
  // 占比合法性:^(front|end)\d{1,3}$ 且数值 0-100(ADR-004 数值化)。
@@ -31,7 +32,8 @@ export function swapGradientBias(bias) {
31
32
  // 解析任意色阶引用为实际色值(ADR-004):标准 10 档查 scale 表;自定义值 tonalScaleAt 插值。
32
33
  // <lang zh-CN>theme[family].value 为基色 HEX;非法数字回退 500 档(基色本色)。</lang>
33
34
  // <lang en>theme[family].value is the base HEX; invalid numbers fall back to step 500 (the base).</lang>
34
- function resolveScaleColor(theme, family, shade) {
35
+ /** @lang zh-CN 解析任意色阶引用为实际色值(`W-tb-P38` 导出为 DTCG 渐变 stops 所需,改公开)。 @lang en Resolves an arbitrary shade reference to its colour (exported for `W-tb-P38` DTCG gradient stops). */
36
+ export function resolveScaleColor(theme, family, shade) {
35
37
  // 色族解析:主/副走角色表;third 走第三角色;aux<N> 走对应辅助槽位(ADR-007 v2)。
36
38
  // <lang zh-CN>third/aux 槽位缺失(模式不匹配/槽位未加)时回退主色 500,保证渲染不断。</lang>
37
39
  // <lang en>Missing third/aux slots fall back to primary 500 so rendering never breaks.</lang>
@@ -68,14 +70,29 @@ function tokenFor(config, shade, mode, theme) {
68
70
  return resolveScaleColor(theme, config.family, shade);
69
71
  }
70
72
  // 生成单条渐变的 CSS:禁用时退化为纯色(起始色),否则输出 linear-gradient。
71
- // <lang zh-CN>默认 runtime 模式;mode/literal 决定是否内联色值。</lang>
72
- // <lang en>Defaults to runtime; mode/literal decide whether colors are inlined.</lang>
73
- export function gradientCss(config, mode = 'runtime', theme) {
73
+ // <lang zh-CN>默认 runtime 模式;mode/literal 决定是否内联色值。
74
+ // **降级链(`W-tb-P37`)**:启用态在渐变层下追加起始色纯色垫底(多层背景,渐变在上)——
75
+ // 渐变含半透明色标时不会露出容器底色;消费方需完全的解析级降级时应另行双声明
76
+ // (background-color 先行,background-image 后行,见 inject-template)。
77
+ // underlay=false 供不容许多层背景的消费方(WordPress 渐变预设解析器)关闭。
78
+ // </lang>
79
+ // <lang en>Defaults to runtime; mode/literal decide whether colors are inlined.
80
+ // **Degradation chain (`W-tb-P37`)**: when enabled, a solid start-colour underlay is appended beneath the
81
+ // gradient layer (multi-layer background, gradient on top) so translucent stops never expose the container.
82
+ // Consumers needing parse-level fallback should emit two declarations (background-color first, then
83
+ // background-image — see inject-template). underlay=false for consumers that cannot take multi-layer
84
+ // backgrounds (the WordPress gradient preset parser).</lang>
85
+ export function gradientCss(config, mode = 'runtime', theme, underlay = true) {
74
86
  const start = tokenFor(config, config.start, mode, theme), end = tokenFor(config, config.end, mode, theme);
75
87
  // 禁用则直接返回起始色,等效纯背景。
76
88
  // <lang zh-CN>让调用方无需区分“未启用”与“启用”。</lang>
77
89
  // <lang en>Lets callers treat disabled uniformly as a solid background.</lang>
78
- return config.enabled === false ? start : `linear-gradient(${config.direction}, ${gradientStops(start, end, config.bias)})`;
90
+ if (config.enabled === false)
91
+ return start;
92
+ const gradient = `linear-gradient(${config.direction}, ${gradientStops(start, end, config.bias)})`;
93
+ // 纯色垫底与起始色同源:降级时呈现"起始色平铺"的合理近似。
94
+ // <lang en>The underlay mirrors the start colour: degradation degrades to a sensible flat start colour.</lang>
95
+ return underlay ? `${gradient}, ${start}` : gradient;
79
96
  }
80
97
  // 取渐变“主色”用于决定前景色:end 占比时取结束色阶,否则取起始色阶。
81
98
  // <lang zh-CN>主色阶决定该卡片上文字该用白还是深,影响可读性;任意色阶经 resolveScaleColor 插值。</lang>
@@ -151,6 +168,28 @@ export function createRuntimeCssVariables(theme) {
151
168
  // <lang zh-CN>追加入 :root 内联变量集合。</lang>
152
169
  // <lang en>Merged into the :root inline var set.</lang>
153
170
  Object.assign(vars, typographySpacingVars(theme));
171
+ // 语义状态色变量(`W-tb-P37`/ADR-012):主题携带时写入 --success/-info/-warning/-danger 及 500/700 阶,
172
+ // 供预览(状态卡/按钮)消费;未携带的主题不写入(旧形态不变)。
173
+ // <lang en>Semantic status vars (`W-tb-P37`/ADR-012): emitted when carried for preview consumption; absent
174
+ // groups keep the legacy shape.</lang>
175
+ if (theme.semantic) {
176
+ for (const [k, role] of Object.entries(theme.semantic)) {
177
+ vars[`--${k}`] = role.value;
178
+ vars[`--on-${k}`] = role.on;
179
+ vars[`--${k}-500`] = role.scale['500'] ?? role.value;
180
+ vars[`--${k}-100`] = role.scale['100'] ?? role.value;
181
+ }
182
+ }
183
+ // 圆角/阴影变量(`W-tb-P37`):--radius-* / --shadow-*,供预览与导出统一消费。
184
+ // <lang en>Radius/shadow vars (`W-tb-P37`): --radius-* / --shadow-* consumed by preview and exports.</lang>
185
+ const radius = radiusSequence(theme.radius);
186
+ for (const [k, v] of Object.entries(radius))
187
+ vars[`--radius-${k}`] = `${v}px`;
188
+ // 阴影固定三档:sm/md/lg 键集稳定,避免 Object.entries 的隐式 any。
189
+ // <lang en>Shadow levels are the stable sm/md/lg set, avoiding implicit-any from Object.entries.</lang>
190
+ const shadows = shadowCss(theme.shadow, theme.primary.value);
191
+ for (const k of ['sm', 'md', 'lg'])
192
+ vars[`--shadow-${k}`] = shadows[k];
154
193
  // 自定义色阶变量:按渐变引用去重生成 --p650 / --s650 等附加变量(ADR-004)。
155
194
  // <lang zh-CN>与标准 10 档同名规则,tokenFor 的 var() 引用无需区分。</lang>
156
195
  // <lang en>Same naming as the standard steps, so tokenFor's var() references need no branching.</lang>
package/dist/index.d.ts CHANGED
@@ -14,13 +14,23 @@ export { SERIES_RELATION_DEFS, getSeriesRelationDef, deriveSecondaryByRelation,
14
14
  export { nameColor, modifierFor, hueNameFor, MODIFIER_NAMES, HUE_NAMES } from './color/color-name.js';
15
15
  export type { ColorModifier, HueName } from './color/color-name.js';
16
16
  export type { SeriesRelationDef } from './color/harmony.js';
17
- export { luminance, contrast, bestOnColor } from './color/contrast.js';
17
+ export { luminance, contrast, bestOnColor, contrastMatrix, stepForContrast } from './color/contrast.js';
18
+ export type { MatrixEntry, ContrastMatrixResult, StepForContrastResult } from './color/contrast.js';
19
+ export { apcaLc, apcaY } from './color/apca.js';
20
+ export { simulateCvd, MACHADO_2009_SEV1, CVD_LABELS } from './color/vision.js';
21
+ export type { CvdType } from './color/vision.js';
18
22
  export { primaryCandidates } from './data/primaryCandidates.js';
19
23
  export { builtinPresets } from './data/presets.js';
20
24
  export { GRADIENT_DEFS, GRADIENT_DEFAULTS, cloneGradientSettings } from './data/gradients.js';
21
25
  export { BAODIAN_PALETTE, FORM_PACKS, BAODIAN_FORM_NAMES } from './data/palette-packs.js';
22
26
  export type { BaodianCombo } from './data/palette-packs.js';
23
27
  export { tonePresets, buildTonePreset, TONE_MOODS, TONE_FORM_PRIORITY, TONE_DEFAULT_PRIORITY, TONE_AUX_SLOTS } from './data/tone-presets.js';
28
+ export { deriveSemanticTokens, cloneSemanticTokens, isSemanticDerived, SEMANTIC_HUES, SEMANTIC_NAMES } from './color/semantic.js';
29
+ export type { SemanticStatusKey } from './types.js';
30
+ export { extractImagePalette, downsamplePixels, suggestGradientDirection, IMAGE_EXTRACT_MAX_DIM, IMAGE_EXTRACT_CLUSTERS } from './color/image-extract.js';
31
+ export type { ImagePixels, ImageCandidate, ImageExtractResult, ImageExtractMode } from './color/image-extract.js';
32
+ export { radiusSequence, shadowCss, cloneRadiusTokens, cloneShadowTokens, RADIUS_DEFAULTS, SHADOW_DEFAULTS } from './token/radius.js';
33
+ export type { RadiusStep, ShadowLevel } from './token/radius.js';
24
34
  export { MOOD_PRIMARY_COLORS, moodPrimaryColorFor } from './data/mood-primary-colors.js';
25
35
  export type { MoodPrimaryColor } from './data/mood-primary-colors.js';
26
36
  export { TRADITIONAL_COLORS } from './data/traditional-colors.js';
@@ -48,6 +58,9 @@ export type { VirtualFile, ExportTarget, ExportAdapterOptions } from './export/t
48
58
  export { EXPORT_TARGETS, getExportTarget, listExportTargets } from './export/registry.js';
49
59
  export { wordpressChildTarget } from './export/wordpress.js';
50
60
  export { tailwindConfigTarget } from './export/tailwind.js';
61
+ export { tailwindV4Target } from './export/tailwind4.js';
62
+ export { dtcgExportTarget, exportDtcgTokens, parseDtcgTokens } from './export/dtcg.js';
63
+ export type { DtcgIssue, DtcgIssueCode, DtcgParseResult } from './export/dtcg.js';
51
64
  export { injectTemplateTarget } from './export/inject-template.js';
52
65
  export { analyzeTheme } from './analyze/analyze.js';
53
66
  export type { ExtractSignals, ScoredColor, ExtractResult, CssVarSignal, DomColorSignal, ScreenshotColorSignal } from './analyze/types.js';
package/dist/index.js CHANGED
@@ -22,10 +22,20 @@ export { HARMONY_DEFS, harmonyCandidate, generateSecondarySet } from './color/ha
22
22
  // <lang en>Pure generator shared by Theme assembly and UI regeneration.</lang>
23
23
  export { SERIES_RELATION_DEFS, getSeriesRelationDef, deriveSecondaryByRelation, deriveThirdByRelation, generateAuxiliaryCandidates, shiftHueTo, anchorComboMembers } from './color/harmony.js';
24
24
  export { nameColor, modifierFor, hueNameFor, MODIFIER_NAMES, HUE_NAMES } from './color/color-name.js';
25
- // 对比度与最佳前景色选择(WCAG 相对亮度)。
26
- // <lang zh-CN>用于自动决定角色色上的文字用白还是深色。</lang>
27
- // <lang en>Decides white vs dark foreground on a role color via WCAG relative luminance.</lang>
28
- export { luminance, contrast, bestOnColor } from './color/contrast.js';
25
+ // 对比度与最佳前景色选择(WCAG 相对亮度);`W-tb-P36` 增补矩阵与目标生成。
26
+ // <lang zh-CN>用于自动决定角色色上的文字用白还是深色;contrastMatrix 供全调色板逐对校验,
27
+ // stepForContrast 以目标比值反推色值(Leonardo 式),与锚定推导互补。</lang>
28
+ // <lang en>Decides white vs dark foreground on a role color via WCAG relative luminance; `W-tb-P36` adds the
29
+ // matrix and target-driven synthesis. contrastMatrix serves palette-wide pairwise checks; stepForContrast
30
+ // synthesizes a colour for a target ratio (Leonardo-style), complementing anchored derivation.</lang>
31
+ export { luminance, contrast, bestOnColor, contrastMatrix, stepForContrast } from './color/contrast.js';
32
+ // APCA Lc 副指标(`W-tb-P36`):仅作参考值展示,非合规判定——WCAG 3 尚未定案。
33
+ // <lang en>APCA Lc secondary metric (`W-tb-P36`): reference readout only, never a compliance verdict — WCAG 3
34
+ // is still undecided.</lang>
35
+ export { apcaLc, apcaY } from './color/apca.js';
36
+ // 色觉缺陷模拟(`W-tb-P36`):Machado 2009 三主型,线性空间应用矩阵。
37
+ // <lang en>CVD simulation (`W-tb-P36`): Machado 2009 three main types, matrices applied in linear space.</lang>
38
+ export { simulateCvd, MACHADO_2009_SEV1, CVD_LABELS } from './color/vision.js';
29
39
  // 数据:主色候选库、内置预设、渐变定义与默认配置。
30
40
  // <lang zh-CN>候选库与预设为静态数据;GRADIENT_* 为渐变角色契约与默认值。</lang>
31
41
  // <lang en>Static data: primary candidates and built-in presets; GRADIENT_* are gradient role contracts and defaults.</lang>
@@ -37,6 +47,18 @@ export { GRADIENT_DEFS, GRADIENT_DEFAULTS, cloneGradientSettings } from './data/
37
47
  // <lang en>Auto-extracted from the Peise Baodian CHM source; backs the relation-rule preset dropdown.</lang>
38
48
  export { BAODIAN_PALETTE, FORM_PACKS, BAODIAN_FORM_NAMES } from './data/palette-packs.js';
39
49
  export { tonePresets, buildTonePreset, TONE_MOODS, TONE_FORM_PRIORITY, TONE_DEFAULT_PRIORITY, TONE_AUX_SLOTS } from './data/tone-presets.js';
50
+ // 语义状态色派生(`W-tb-P37`,ADR-012):success/info/warning/danger 四组完整 RoleColor。
51
+ // 色相按语义固定,明暗/彩度特征随主色;派生是预填值,用户可覆盖(isSemanticDerived)。
52
+ // <lang en>Semantic status derivation (`W-tb-P37`, ADR-012): four full RoleColors with fixed semantic hues and
53
+ // primary-inherited lightness/chroma; derived values are prefills users may override.</lang>
54
+ export { deriveSemanticTokens, cloneSemanticTokens, isSemanticDerived, SEMANTIC_HUES, SEMANTIC_NAMES } from './color/semantic.js';
55
+ // 图片提色(`W-tb-P39`,ADR-014):确定性中位切分提取主/副/渐变候选——纯计算无 IO。
56
+ // <lang en>Image colour extraction (`W-tb-P39`, ADR-014): deterministic median-cut extraction of primary,
57
+ // secondary and gradient candidates — pure computation, no IO.</lang>
58
+ export { extractImagePalette, downsamplePixels, suggestGradientDirection, IMAGE_EXTRACT_MAX_DIM, IMAGE_EXTRACT_CLUSTERS } from './color/image-extract.js';
59
+ // 圆角/阴影令牌(`W-tb-P37`,ADR-006 契约位落地):档位派生纯函数。
60
+ // <lang en>Radius/shadow tokens (`W-tb-P37`, ADR-006 slot landed): pure derivation functions.</lang>
61
+ export { radiusSequence, shadowCss, cloneRadiusTokens, cloneShadowTokens, RADIUS_DEFAULTS, SHADOW_DEFAULTS } from './token/radius.js';
40
62
  // 情感主色:**独立数据集**(维护者校正后重做),自带色值,不与主色候选库关联。
41
63
  // 早前版本曾把情感映射到 44 主色候选(首色频次 + OKLab 最近邻),结果语义错乱,
42
64
  // 根因是串了数据源——候选库讲"网站/流行色",与情感语义无关。此表已与候选库完全解耦。
@@ -70,6 +92,8 @@ export { exportThemeJson } from './token/json.js';
70
92
  export { EXPORT_TARGETS, getExportTarget, listExportTargets } from './export/registry.js';
71
93
  export { wordpressChildTarget } from './export/wordpress.js';
72
94
  export { tailwindConfigTarget } from './export/tailwind.js';
95
+ export { tailwindV4Target } from './export/tailwind4.js';
96
+ export { dtcgExportTarget, exportDtcgTokens, parseDtcgTokens } from './export/dtcg.js';
73
97
  export { injectTemplateTarget } from './export/inject-template.js';
74
98
  export { analyzeTheme } from './analyze/analyze.js';
75
99
  export { toV2Signals } from './analyze/v1-compat.js';
package/dist/studio.js CHANGED
@@ -57,19 +57,19 @@ export function createThemeDraft(value = {}) {
57
57
  // <lang zh-CN>载入操作台时使用,gradients 缺失则回落默认。</lang>
58
58
  // <lang en>Used when loading into the studio; falls back to defaults when gradients are absent.</lang>
59
59
  export function draftFromPreset(preset) {
60
- return createThemeDraft({ id: preset.id, name: preset.name, category: preset.category, industry: preset.industry, primary: preset.primary, secondary: preset.secondary, primaryName: preset.primaryName, secondaryName: preset.secondaryName, note: preset.note, gradients: preset.gradients, seriesMode: preset.seriesMode, seriesRelation: preset.seriesRelation, thirdColor: preset.thirdColor, auxiliary: preset.auxiliary });
60
+ return createThemeDraft({ id: preset.id, name: preset.name, category: preset.category, industry: preset.industry, primary: preset.primary, secondary: preset.secondary, primaryName: preset.primaryName, secondaryName: preset.secondaryName, note: preset.note, gradients: preset.gradients, seriesMode: preset.seriesMode, seriesRelation: preset.seriesRelation, thirdColor: preset.thirdColor, auxiliary: preset.auxiliary, radius: preset.radius, shadow: preset.shadow, semantic: preset.semantic, semanticDerived: preset.semanticDerived });
61
61
  }
62
62
  // 将草稿构建为完整主题,名称缺省时按主副色名自动生成。
63
63
  // <lang zh-CN>草稿到渲染/导出的桥梁,所有色阶在此计算;typography/spacing 随草稿透传(ADR-006)。</lang>
64
64
  // <lang en>Bridge from draft to render/export; all scales are computed here; typography/spacing pass through (ADR-006).</lang>
65
65
  export function buildThemeFromDraft(draft) {
66
- return buildTheme({ name: draft.name || autoThemeName(draft.primaryName, draft.secondaryName), category: draft.category, industry: draft.industry, primary: draft.primary, secondary: draft.secondary, primaryName: draft.primaryName, secondaryName: draft.secondaryName, note: draft.note, gradients: draft.gradients, typography: draft.typography, spacing: draft.spacing, seriesMode: draft.seriesMode, seriesRelation: draft.seriesRelation, thirdColor: draft.thirdColor, auxiliary: draft.auxiliary, auxiliaryModifiers: draft.auxiliaryModifiers });
66
+ return buildTheme({ name: draft.name || autoThemeName(draft.primaryName, draft.secondaryName), category: draft.category, industry: draft.industry, primary: draft.primary, secondary: draft.secondary, primaryName: draft.primaryName, secondaryName: draft.secondaryName, note: draft.note, gradients: draft.gradients, typography: draft.typography, spacing: draft.spacing, seriesMode: draft.seriesMode, seriesRelation: draft.seriesRelation, thirdColor: draft.thirdColor, auxiliary: draft.auxiliary, auxiliaryModifiers: draft.auxiliaryModifiers, radius: draft.radius, shadow: draft.shadow, semantic: draft.semantic });
67
67
  }
68
68
  // 由草稿导出为可保存预设,id 缺失时以时间戳生成自定义 id。
69
69
  // <lang zh-CN>保存/导出时使用,基色再次规范化确保持久化一致。</lang>
70
70
  // <lang en>Used for save/export; base colors are re-normalized for consistent persistence.</lang>
71
71
  export function presetFromDraft(draft, id = `custom-${Date.now()}`) {
72
- return { id, name: draft.name || autoThemeName(draft.primaryName, draft.secondaryName), category: draft.category || 'custom', industry: draft.industry || '', primary: normalizeHex(draft.primary), secondary: normalizeHex(draft.secondary), primaryName: draft.primaryName || nameColor(draft.primary).zh, secondaryName: draft.secondaryName || nameColor(draft.secondary).zh, note: draft.note || '由主副色操作台生成导入。', gradients: cloneGradientSettings(draft.gradients), ...(draft.seriesMode && draft.seriesMode !== 'dual' ? { seriesMode: draft.seriesMode } : {}), ...(draft.seriesRelation && draft.seriesRelation !== 'manual' ? { seriesRelation: draft.seriesRelation } : {}), ...(draft.thirdColor ? { thirdColor: { ...draft.thirdColor, scale: { ...draft.thirdColor.scale } } } : {}), ...(draft.auxiliary?.length ? { auxiliary: draft.auxiliary.map(a => ({ ...a, scale: { ...a.scale } })) } : {}) };
72
+ return { id, name: draft.name || autoThemeName(draft.primaryName, draft.secondaryName), category: draft.category || 'custom', industry: draft.industry || '', primary: normalizeHex(draft.primary), secondary: normalizeHex(draft.secondary), primaryName: draft.primaryName || nameColor(draft.primary).zh, secondaryName: draft.secondaryName || nameColor(draft.secondary).zh, note: draft.note || '由主副色操作台生成导入。', gradients: cloneGradientSettings(draft.gradients), ...(draft.seriesMode && draft.seriesMode !== 'dual' ? { seriesMode: draft.seriesMode } : {}), ...(draft.seriesRelation && draft.seriesRelation !== 'manual' ? { seriesRelation: draft.seriesRelation } : {}), ...(draft.thirdColor ? { thirdColor: { ...draft.thirdColor, scale: { ...draft.thirdColor.scale } } } : {}), ...(draft.auxiliary?.length ? { auxiliary: draft.auxiliary.map(a => ({ ...a, scale: { ...a.scale } })) } : {}), ...(draft.radius ? { radius: draft.radius } : {}), ...(draft.shadow ? { shadow: draft.shadow } : {}), ...(draft.semantic ? { semantic: draft.semantic } : {}), ...(draft.semanticDerived ? { semanticDerived: draft.semanticDerived } : {}) };
73
73
  }
74
74
  // 在候选库中按主副色同时匹配出对应候选(用于回显“当前主色”来源)。
75
75
  // <lang zh-CN>仅当主色与推荐副色都一致才命中,避免近似色误判。</lang>
package/dist/theme.js CHANGED
@@ -13,6 +13,8 @@ export function cloneTypography(t) { const r = { fontFamily: { ...t.fontFamily }
13
13
  export function cloneSpacing(s) { const r = { ...s }; if (s.overrides)
14
14
  r.overrides = { ...s.overrides }; return r; }
15
15
  import { bestOnColor } from './color/contrast.js';
16
+ import { cloneRadiusTokens, cloneShadowTokens } from './token/radius.js';
17
+ import { cloneSemanticTokens } from './color/semantic.js';
16
18
  import { normalizeHex } from './color/convert.js';
17
19
  import { tonalScale } from './color/scale.js';
18
20
  import { cloneGradientSettings } from './data/gradients.js';
@@ -104,7 +106,16 @@ export function buildTheme(input) {
104
106
  seriesMode,
105
107
  seriesRelation,
106
108
  ...(thirdColor ? { thirdColor } : {}),
107
- auxiliary
109
+ auxiliary,
110
+ // 圆角/阴影(`W-tb-P37`,ADR-006 契约位落地):可选入参,缺省回退默认档——旧调用点不受影响。
111
+ // <lang en>Radius/shadow (`W-tb-P37`, ADR-006 slot landed): optional inputs defaulting back — legacy call
112
+ // sites unaffected.</lang>
113
+ radius: cloneRadiusTokens(input.radius),
114
+ shadow: cloneShadowTokens(input.shadow),
115
+ // 语义状态色(ADR-012):仅透传显式提供的组;**不静默派生**——旧主题观感不因升级改变(决策 6)。
116
+ // <lang en>Semantic tokens (ADR-012): only pass through explicit groups; **no silent derivation** — old
117
+ // themes must not change appearance on upgrade (decision 6).</lang>
118
+ ...(input.semantic ? { semantic: cloneSemanticTokens(input.semantic) } : {})
108
119
  };
109
120
  }
110
121
  //# sourceMappingURL=theme.js.map
package/dist/token/css.js CHANGED
@@ -1,9 +1,12 @@
1
1
  import { collectCustomShades, exportGradientVariableLines } from '../gradient/render.js';
2
+ import { radiusSequence, shadowCss } from './radius.js';
2
3
  // 将完整主题导出为 :root CSS 自定义属性文本(设计系统/小程序消费入口)。
3
4
  // <lang zh-CN>包含角色基色、前景色、主副色各 10 级色阶、渐变引用的自定义色阶(ADR-004 附加式)、
4
- // 第三角色(ADR-007 v2,仅三色模式)、辅助色槽位与全部渐变变量;缩进贴近手写样式表。</lang>
5
+ // 第三角色(ADR-007 v2,仅三色模式)、辅助色槽位与全部渐变变量;`W-tb-P37` 追加语义状态色、
6
+ // 圆角与阴影令牌;缩进贴近手写样式表。</lang>
5
7
  // <lang en>Emits role base colors, foregrounds, 10-step scales, gradient-referenced custom shades
6
- // (ADR-004 additive), the third role (ADR-007 v2, triad only), auxiliary slots and all gradient vars.</lang>
8
+ // (ADR-004 additive), the third role (ADR-007 v2, triad only), auxiliary slots and all gradient vars;
9
+ // `W-tb-P37` adds semantic status tokens, radius and shadow tokens.</lang>
7
10
  export function exportThemeCss(theme) {
8
11
  // 自定义色阶:与运行时变量同源(collectCustomShades 去重插值),保证导出即可用。
9
12
  // <lang zh-CN>键名与 --hia-primary-{shade} 规则一致,消费方 var() 引用无需区分。</lang>
@@ -29,14 +32,31 @@ export function exportThemeCss(theme) {
29
32
  ` --hia-on-aux${i}: ${aux.on};`,
30
33
  ...Object.entries(aux.scale).map(([k, v]) => `--hia-aux${i}-${k}: ${v};`)
31
34
  ].join('\n ')).join(theme.auxiliary.length ? '\n' : '');
35
+ // 语义状态色(ADR-012):仅当主题携带该组时输出;键名 --hia-<status>[-<shade>]/--hia-on-<status>。
36
+ // <lang zh-CN>未派生的旧主题不出现该段(产物与旧版一致)。</lang>
37
+ // <lang en>Emitted only when the theme carries the group; old themes without it keep identical output.</lang>
38
+ const semanticLines = theme.semantic ? Object.entries(theme.semantic).map(([k, role]) => [
39
+ ` --hia-${k}: ${role.value};`,
40
+ ` --hia-on-${k}: ${role.on};`,
41
+ ...Object.entries(role.scale).map(([shade, v]) => `--hia-${k}-${shade}: ${v};`)
42
+ ].join('\n ')).join('\n') : '';
43
+ // 圆角/阴影(`W-tb-P37`):五档圆角 px + 三档阴影字符串;阴影可随主色染色。
44
+ // <lang en>Radius/shadow (`W-tb-P37`): five radius steps (px) + three shadow strings; shadows may tint with
45
+ // the primary.</lang>
46
+ const radius = radiusSequence(theme.radius);
47
+ const shadows = shadowCss(theme.shadow, theme.primary.value);
48
+ const radiusLines = Object.entries(radius).map(([k, v]) => ` --hia-radius-${k}: ${v}px;`).join('\n');
49
+ const shadowLines = Object.entries(shadows).map(([k, v]) => ` --hia-shadow-${k}: ${v};`).join('\n');
32
50
  return `:root {
33
51
  --hia-primary: ${theme.primary.value};
34
52
  --hia-on-primary: ${theme.primary.on};
35
53
  --hia-secondary: ${theme.secondary.value};
36
54
  --hia-on-secondary: ${theme.secondary.on};
37
55
  ${Object.entries(theme.primary.scale).map(([k, v]) => `--hia-primary-${k}: ${v};`).join('\n ')}${primaryCustom ? `\n ${primaryCustom}` : ''}
38
- ${Object.entries(theme.secondary.scale).map(([k, v]) => `--hia-secondary-${k}: ${v};`).join('\n ')}${secondaryCustom ? `\n ${secondaryCustom}` : ''}${thirdLines ? `\n ${thirdLines}` : ''}${auxLines ? `\n ${auxLines}` : ''}
56
+ ${Object.entries(theme.secondary.scale).map(([k, v]) => `--hia-secondary-${k}: ${v};`).join('\n ')}${secondaryCustom ? `\n ${secondaryCustom}` : ''}${thirdLines ? `\n ${thirdLines}` : ''}${auxLines ? `\n ${auxLines}` : ''}${semanticLines ? `\n ${semanticLines}` : ''}
39
57
  ${exportGradientVariableLines(theme.gradients)}
58
+ ${radiusLines}
59
+ ${shadowLines}
40
60
  }`;
41
61
  }
42
62
  //# sourceMappingURL=css.js.map
@@ -28,6 +28,12 @@ export function exportThemeJson(theme) {
28
28
  auxiliary: theme.auxiliary.map(a => ({ name: a.name, value: a.value, scale: a.scale, on: a.on })),
29
29
  typography: theme.typography,
30
30
  spacing: theme.spacing,
31
+ // 语义状态色 + 圆角/阴影(`W-tb-P37`,ADR-012):可选组,携带时全量输出(消费方免重建)。
32
+ // <lang en>Semantic statuses + radius/shadow (`W-tb-P37`, ADR-012): optional groups emitted in full when
33
+ // present, so consumers need no rebuild.</lang>
34
+ ...(theme.semantic ? { semantic: theme.semantic } : {}),
35
+ ...(theme.radius ? { radius: theme.radius } : {}),
36
+ ...(theme.shadow ? { shadow: theme.shadow } : {}),
31
37
  gradients: theme.gradients
32
38
  }, null, 2);
33
39
  }
@@ -0,0 +1,38 @@
1
+ /**
2
+ * @lang zh-CN 圆角与阴影令牌(`W-tb-P37`,ADR-006 契约位落地):档位派生纯函数。
3
+ * 圆角五档由基准值派生;阴影三档由强度派生(可混入主色低透明度做品牌化阴影)。
4
+ * 全部纯函数、无 IO——与色阶/间距同一套生成式令牌管线(ADR-006 决策 2)。
5
+ *
6
+ * @lang en Radius & shadow tokens (`W-tb-P37`, ADR-006 contract slot landed): pure derivation functions.
7
+ * Five radius steps derive from one base; three shadow levels derive from strength (optionally tinted with
8
+ * the primary colour). Pure and IO-free — the same generative pipeline as scales/spacing (ADR-006 decision 2).
9
+ */
10
+ import type { RadiusTokens, ShadowTokens } from '../types.js';
11
+ /** @lang zh-CN 圆角档位键。 @lang en Radius step keys. */
12
+ export type RadiusStep = 'sm' | 'md' | 'lg' | 'xl' | 'pill';
13
+ /** @lang zh-CN 圆角令牌默认值(8px 基准——主流设计系统最常见档)。 @lang en Radius defaults (8px base — the most common design-system step). */
14
+ export declare const RADIUS_DEFAULTS: RadiusTokens;
15
+ /** @lang zh-CN 阴影令牌默认值(soft 档——适合浅色后台)。 @lang en Shadow defaults (soft — suits light consoles). */
16
+ export declare const SHADOW_DEFAULTS: ShadowTokens;
17
+ export declare function cloneRadiusTokens(tokens?: Partial<RadiusTokens> | null): RadiusTokens;
18
+ export declare function cloneShadowTokens(tokens?: Partial<ShadowTokens> | null): ShadowTokens;
19
+ /**
20
+ * @lang zh-CN 圆角档位序列(px):sm=base/2、md=base、lg=×1.5、xl=×2、pill=胶囊(999 保证全圆)。
21
+ * overrides 按 `radius-sm` 等键覆写单档。纯函数。
22
+ * @lang en Radius sequence (px): sm=base/2, md=base, lg=×1.5, xl=×2, pill=999 (guaranteed full round).
23
+ * Overrides apply per step via keys like `radius-sm`. Pure.
24
+ */
25
+ export declare function radiusSequence(tokens?: Partial<RadiusTokens> | null): Record<RadiusStep, number>;
26
+ /** @lang zh-CN 阴影档位键(sm/md/lg)。 @lang en Shadow level keys (sm/md/lg). */
27
+ export type ShadowLevel = 'sm' | 'md' | 'lg';
28
+ /**
29
+ * @lang zh-CN 阴影三档 CSS box-shadow 字符串:`x y blur spread color` 双层(环境层 + 贴近层)。
30
+ * tintFromPrimary 时阴影色向主色色相偏移(低饱和、低透明度)——品牌化但不脏版面。
31
+ * strength='none' 时全部为 'none'(可读性兜底:调用方不必分支)。overrides 按键 `shadow-sm` 等覆写。
32
+ * @lang en Shadow CSS box-shadow strings for three levels: two-layer `x y blur spread color` (ambient + key).
33
+ * tintFromPrimary shifts shadow hue toward the primary (low sat/alpha — branded but not muddy);
34
+ * strength='none' yields 'none' for all levels so callers need no branching. Overrides via keys like
35
+ * `shadow-sm`.
36
+ */
37
+ export declare function shadowCss(tokens: Partial<ShadowTokens> | null | undefined, primaryHex: string): Record<ShadowLevel, string>;
38
+ //# sourceMappingURL=radius.d.ts.map
@@ -0,0 +1,94 @@
1
+ import { hexToRgb } from '../color/convert.js';
2
+ /** @lang zh-CN 圆角令牌默认值(8px 基准——主流设计系统最常见档)。 @lang en Radius defaults (8px base — the most common design-system step). */
3
+ export const RADIUS_DEFAULTS = { base: 8 };
4
+ /** @lang zh-CN 阴影令牌默认值(soft 档——适合浅色后台)。 @lang en Shadow defaults (soft — suits light consoles). */
5
+ export const SHADOW_DEFAULTS = { strength: 'soft' };
6
+ // 补齐圆角配置:缺省/非法回退默认值(clone 语义,向后兼容 ADR-006 决策 4)。
7
+ // <lang en>Normalise radius config: missing/invalid falls back to defaults (clone semantics, ADR-006 decision 4).</lang>
8
+ export function cloneRadiusTokens(tokens) {
9
+ const base = tokens && Number.isFinite(tokens.base) && tokens.base >= 0 ? tokens.base : RADIUS_DEFAULTS.base;
10
+ return { base, overrides: tokens?.overrides ? { ...tokens.overrides } : undefined };
11
+ }
12
+ // 补齐阴影配置:非法强度回退 soft。
13
+ // <lang en>Normalise shadow config: invalid strength falls back to soft.</lang>
14
+ export function cloneShadowTokens(tokens) {
15
+ const strength = tokens && ['none', 'soft', 'medium', 'strong'].includes(tokens.strength) ? tokens.strength : SHADOW_DEFAULTS.strength;
16
+ return { strength, tintFromPrimary: tokens?.tintFromPrimary ?? false, overrides: tokens?.overrides ? { ...tokens.overrides } : undefined };
17
+ }
18
+ /**
19
+ * @lang zh-CN 圆角档位序列(px):sm=base/2、md=base、lg=×1.5、xl=×2、pill=胶囊(999 保证全圆)。
20
+ * overrides 按 `radius-sm` 等键覆写单档。纯函数。
21
+ * @lang en Radius sequence (px): sm=base/2, md=base, lg=×1.5, xl=×2, pill=999 (guaranteed full round).
22
+ * Overrides apply per step via keys like `radius-sm`. Pure.
23
+ */
24
+ export function radiusSequence(tokens) {
25
+ const t = cloneRadiusTokens(tokens);
26
+ const pill = 999;
27
+ const seq = {
28
+ sm: Math.round(t.base / 2),
29
+ md: Math.round(t.base),
30
+ lg: Math.round(t.base * 1.5),
31
+ xl: Math.round(t.base * 2),
32
+ pill
33
+ };
34
+ // 覆写:显式指定某档则用覆写值(pill 覆写同样尊重)。
35
+ // <lang en>Overrides: an explicit step wins (pill overrides respected too).</lang>
36
+ for (const step of Object.keys(seq)) {
37
+ const key = `radius-${step}`;
38
+ const v = t.overrides?.[key];
39
+ if (Number.isFinite(v))
40
+ seq[step] = v;
41
+ }
42
+ return seq;
43
+ }
44
+ // 各强度的阴影基参数:偏移/模糊/透明度随强度递增。
45
+ // <lang en>Shadow base params per strength: offset/blur/alpha grow with strength.</lang>
46
+ const SHADOW_PARAMS = {
47
+ none: null,
48
+ soft: { y: 1, blur: 3, spread: 0, alpha: 0.10 },
49
+ medium: { y: 2, blur: 8, spread: 0, alpha: 0.14 },
50
+ strong: { y: 4, blur: 16, spread: 0, alpha: 0.20 }
51
+ };
52
+ /**
53
+ * @lang zh-CN 阴影三档 CSS box-shadow 字符串:`x y blur spread color` 双层(环境层 + 贴近层)。
54
+ * tintFromPrimary 时阴影色向主色色相偏移(低饱和、低透明度)——品牌化但不脏版面。
55
+ * strength='none' 时全部为 'none'(可读性兜底:调用方不必分支)。overrides 按键 `shadow-sm` 等覆写。
56
+ * @lang en Shadow CSS box-shadow strings for three levels: two-layer `x y blur spread color` (ambient + key).
57
+ * tintFromPrimary shifts shadow hue toward the primary (low sat/alpha — branded but not muddy);
58
+ * strength='none' yields 'none' for all levels so callers need no branching. Overrides via keys like
59
+ * `shadow-sm`.
60
+ */
61
+ export function shadowCss(tokens, primaryHex) {
62
+ const t = cloneShadowTokens(tokens);
63
+ const out = {};
64
+ for (const level of ['sm', 'md', 'lg']) {
65
+ const key = `shadow-${level}`;
66
+ const override = t.overrides?.[key];
67
+ if (override) {
68
+ out[level] = override;
69
+ continue;
70
+ }
71
+ const params = SHADOW_PARAMS[t.strength];
72
+ if (!params) {
73
+ out[level] = 'none';
74
+ continue;
75
+ }
76
+ // 双层阴影:外层环境阴影(大模糊低透明)+ 内层贴近阴影(小偏移)。
77
+ // <lang en>Two layers: outer ambient (large blur, low alpha) + inner key shadow (small offset).</lang>
78
+ const scale = level === 'sm' ? 1 : level === 'md' ? 1.8 : 3.2;
79
+ const alpha = params.alpha * (level === 'sm' ? 1 : level === 'md' ? 1.05 : 1.15);
80
+ if (t.tintFromPrimary) {
81
+ // 染色阴影:主色线性 RGB 与中性暗色按 alpha 混出阴影基色。
82
+ // <lang en>Tinted shadow: mix the primary's linear RGB with a neutral dark at alpha.</lang>
83
+ const [r, g, b] = hexToRgb(primaryHex);
84
+ const mix = (c) => Math.round((c * 0.35 + 0.08 * 0.65) * 255);
85
+ const shade = `rgb(${mix(r)} ${mix(g)} ${mix(b)} / ${alpha.toFixed(3)})`;
86
+ out[level] = `0 ${params.y * scale}px ${params.blur * scale}px ${params.spread}px ${shade}, 0 ${params.y}px ${params.blur}px 0 ${shade}`;
87
+ }
88
+ else {
89
+ out[level] = `0 ${params.y * scale}px ${params.blur * scale}px ${params.spread}px rgb(15 23 42 / ${alpha.toFixed(3)}), 0 ${params.y}px ${params.blur}px 0 rgb(15 23 42 / ${alpha.toFixed(3)})`;
90
+ }
91
+ }
92
+ return out;
93
+ }
94
+ //# sourceMappingURL=radius.js.map
package/dist/types.d.ts CHANGED
@@ -46,6 +46,22 @@ export interface SpacingTokens {
46
46
  levels: number;
47
47
  overrides?: Record<string, number>;
48
48
  }
49
+ export interface RadiusTokens {
50
+ base: number;
51
+ overrides?: Record<string, number>;
52
+ }
53
+ export interface ShadowTokens {
54
+ strength: 'none' | 'soft' | 'medium' | 'strong';
55
+ tintFromPrimary?: boolean;
56
+ overrides?: Record<string, string>;
57
+ }
58
+ export type SemanticStatusKey = 'success' | 'info' | 'warning' | 'danger';
59
+ export interface SemanticTokens {
60
+ success: RoleColor;
61
+ info: RoleColor;
62
+ warning: RoleColor;
63
+ danger: RoleColor;
64
+ }
49
65
  export interface Theme {
50
66
  name: string;
51
67
  category: string;
@@ -60,6 +76,9 @@ export interface Theme {
60
76
  seriesRelation: SeriesRelationId;
61
77
  thirdColor?: RoleColor;
62
78
  auxiliary: RoleColor[];
79
+ radius?: RadiusTokens;
80
+ shadow?: ShadowTokens;
81
+ semantic?: SemanticTokens;
63
82
  }
64
83
  export interface ThemeInput {
65
84
  name?: string;
@@ -78,6 +97,9 @@ export interface ThemeInput {
78
97
  thirdColor?: RoleColor;
79
98
  auxiliary?: RoleColor[];
80
99
  auxiliaryModifiers?: AuxiliaryModifier[];
100
+ radius?: RadiusTokens;
101
+ shadow?: ShadowTokens;
102
+ semantic?: SemanticTokens;
81
103
  }
82
104
  export interface PrimaryCandidate {
83
105
  id: string;
@@ -107,6 +129,10 @@ export interface Preset {
107
129
  seriesRelation?: SeriesRelationId;
108
130
  thirdColor?: RoleColor;
109
131
  auxiliary?: RoleColor[];
132
+ radius?: RadiusTokens;
133
+ shadow?: ShadowTokens;
134
+ semantic?: SemanticTokens;
135
+ semanticDerived?: Record<string, boolean>;
110
136
  }
111
137
  export interface HarmonyDef {
112
138
  id: string;
@@ -136,6 +162,11 @@ export interface ThemeDraft {
136
162
  thirdColor?: RoleColor;
137
163
  auxiliary?: RoleColor[];
138
164
  auxiliaryModifiers?: AuxiliaryModifier[];
165
+ radius?: RadiusTokens;
166
+ shadow?: ShadowTokens;
167
+ semantic?: SemanticTokens;
168
+ /** @lang zh-CN 语义色派生标记(ADR-012):true=仍随主色派生;缺省 false=用户值不跟随。 @lang en Semantic derivation flags (ADR-012): true = still derived from primary; absent/false = user-managed. */
169
+ semanticDerived?: Record<string, boolean>;
139
170
  }
140
171
  export type SeriesMode = 'single' | 'dual' | 'triad';
141
172
  export type SeriesRelationId = 'manual' | 'complement' | 'clash' | 'neutral' | 'analogous' | 'split-complement' | 'tertiary' | 'primary-combo' | 'secondary-combo' | 'pure';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hia/theme-core",
3
- "version": "0.6.0",
3
+ "version": "0.7.0",
4
4
  "description": "HIA cross-platform theme domain core: models, OKLCH algorithms, theme studio state, gradient rendering, token export and website-color analysis.",
5
5
  "license": "MIT",
6
6
  "author": "HIA Theme Builder contributors",