create-shopify-scss-autofill 0.2.0 → 0.3.0

package/bin/create-scss-kit.mjs

@@ -79,18 +79,7 @@ function parseArgs(argv) {
   return out
 }
 
-function makeLowRangeCoefficients() {
-  const out = {}
-  for (let i = 0; i <= 50; i += 5) {
-    const key = `scale-${String(i).padStart(2, '0')}`
-    out[key] = Number((i / 100).toFixed(2))
-  }
-  return out
-}
-
 function makeDefaultConfig() {
-  const lowRange = makeLowRangeCoefficients()
-
   return {
     $schema: './tools/scss-kit/schema.json',
     design: {
@@ -104,6 +93,7 @@ function makeDefaultConfig() {
     },
     autofill: {
       function: 'r.resp',
+      vwFunction: 'r.vw',
       mobileMax: 850,
       scanDirs: ['src/styles'],
       output: 'src/styles/_responsive-autofill.generated.scss',
@@ -126,30 +116,82 @@ function makeDefaultConfig() {
     },
     coefficients: {
       mobile: {
-        ...lowRange,
-        h1: 0.5,
-        h2: 0.625,
-        h3: 0.75,
-        body: 0.857,
-        small: 1,
-        'section-gap': 0.5,
-        'card-gap': 0.6,
-        'element-gap': 0.75,
-        'button-text': 1,
-        icon: 0.67,
+        h1: 0.52,
+        h2: 0.55,
+        h3: 0.55,
+        h4: 0.6,
+        h5: 0.6,
+        h6: 0.6,
+        body: 0.6,
+        small: 0.65,
+        quote: 0.55,
+        'button-text': 0.6,
+        'nav-link': 0.6,
+        'form-label': 0.6,
+        'form-input': 0.6,
+        'price-large': 0.5,
+        'price-small': 0.6,
+        badge: 0.65,
+        breadcrumb: 0.65,
+      },
+      desktop: {
+        h1: 0.58,
+        h2: 0.6,
+        h3: 0.6,
+        h4: 0.6,
+        h5: 0.65,
+        h6: 0.65,
+        body: 0.65,
+        small: 0.65,
+        quote: 0.6,
+        'button-text': 0.65,
+        'nav-link': 0.65,
+        'form-label': 0.65,
+        'form-input': 0.65,
+        'price-large': 0.55,
+        'price-small': 0.65,
+        badge: 0.7,
+        breadcrumb: 0.7,
+      },
+    },
+    floors: {
+      mobile: {
+        h1: '24px',
+        h2: '20px',
+        h3: '18px',
+        h4: '16px',
+        h5: '14px',
+        h6: '14px',
+        body: '14px',
+        small: '12px',
+        quote: '14px',
+        'button-text': '14px',
+        'nav-link': '14px',
+        'form-label': '14px',
+        'form-input': '16px',
+        'price-large': '22px',
+        'price-small': '14px',
+        badge: '11px',
+        breadcrumb: '11px',
       },
       desktop: {
-        ...lowRange,
-        h1: 0.625,
-        h2: 0.67,
-        h3: 0.75,
-        body: 0.875,
-        small: 1,
-        'section-gap': 0.5,
-        'card-gap': 0.6,
-        'element-gap': 0.67,
-        'button-text': 1,
-        icon: 0.625,
+        h1: '28px',
+        h2: '22px',
+        h3: '18px',
+        h4: '16px',
+        h5: '14px',
+        h6: '14px',
+        body: '14px',
+        small: '12px',
+        quote: '16px',
+        'button-text': '14px',
+        'nav-link': '14px',
+        'form-label': '14px',
+        'form-input': '14px',
+        'price-large': '24px',
+        'price-small': '14px',
+        badge: '12px',
+        breadcrumb: '12px',
       },
     },
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-shopify-scss-autofill",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Scaffold scss-kit (SCSS workflow + responsive autofill) for Shopify theme development.",
   "keywords": [
     "shopify",

package/template/tools/scss-kit/README.md

@@ -1,6 +1,6 @@
 # scss-kit（本仓库内置工具）
 
-目的：在 Shopify ThemeKit 开发里实现“写 SCSS（src/styles）→ 编译 CSS（assets）→ theme watch 上传”，并提供一套基于 `r.resp(pc, mobile, desktopType[, mobileType])` 的移动端覆盖自动生成能力。
+目的：在 Shopify ThemeKit 开发里实现“写 SCSS（src/styles）→ 编译 CSS（assets）→ theme watch 上传”，并提供一套基于 `r.resp(pc, mobile, desktopType[, mobileType])` 与 `r.vw(pc, mobile)` 的移动端覆盖自动生成能力。
 
 ## 拷贝接入（新项目）
 
@@ -57,6 +57,72 @@
 - 顶部 `@use "./_responsive-autofill.<page>.generated" as auto;`
 - 底部 `@include auto.responsive_autofill_overrides();`（确保覆盖顺序）
 
+推荐约定：
+
+- 字体/需要下限兜底的值：使用 `r.resp(pc, mobile, desktopType[, mobileType])`
+- 大多数间距（padding/margin/gap）：使用 `r.vw(pc, mobile)`
+- 少量间距若确实需要最小值：改用 `r.resp(...)`（不要给 `r.vw` 追加参数）
+
+`r.vw(pc, mobile)` 的行为：
+
+- PC 输出 `min(vw, px)`，例如 `r.vw(40px, 24px)` → `min(2.0833vw, 40px)`
+- 自动生成的移动端覆盖直接输出 `vw`，例如 `3.2vw`
+
+## Responsive 函数目录（完整）
+
+以下函数都定义在 `src/styles/_responsive.scss`（由 `scss-kit` 生成）：
+
+### 业务侧常用（推荐直接调用）
+
+- `r.resp($pc, $mobile, $type, $mobile-type: null)`
+  - 用途：用于“字体/需要下限兜底”的场景。
+  - PC 输出：`clamp_pc($pc, min_px($pc, $type, desktop))`。
+  - Mobile 输出：由自动生成器扫描 `r.resp(...)` 后，在 `@media` 中生成 `clamp_mb(...)` 覆盖。
+  - 第 3/4 参数：第 3 个是 PC type；第 4 个是 mobile type（可省略，省略时沿用第 3 个）。
+  - 示例：`font-size: r.resp(40px, 24px, h1, h2);`
+
+- `r.vw($pc, $mobile)`
+  - 用途：用于“间距/尺寸优先流式”的场景（如 padding/margin/gap/宽高）。
+  - PC 输出：`min(vw, px)`（防止超大屏继续放大）。
+  - Mobile 输出：由自动生成器扫描 `r.vw(...)` 后，在 `@media` 中生成纯 `vw` 覆盖。
+  - 说明：`r.vw` 仅保留两个参数；若你需要最小值下限，请使用 `r.resp(...)`。
+  - 示例：`margin-top: r.vw(40px, 24px);`
+
+### 由 `r.resp` / `r.vw` 间接使用（一般不直接写）
+
+- `r.min_px($value, $type, $range: mobile, $override-coef: null, $override-floor: null)`
+  - 用途：计算 clamp 最小值。
+  - 规则：
+    - 命名 type：按 `max(designPx * coef(type), floor(type))` 计算（floor 来自 `floors.mobile/desktop`）。
+    - 数字 type：可直接传系数（例如 `0.6`），此时跳过 type 表查询；可选叠加 `override-floor`。
+
+- `r.coef($type, $range: mobile)`
+  - 用途：读取 `coefficients.mobile/desktop` 中对应 type 的系数。
+
+- `r._floor($type, $range: mobile)`
+  - 用途：读取 `floors.mobile/desktop` 中对应 type 的绝对兜底值。
+
+- `r.clamp_pc($pc, $min)`
+  - 用途：生成 PC clamp。
+  - 结构：`clamp($min, calc($pc * var(--px-to-vw)), $pc)`。
+
+- `r.clamp_mb($mobile, $min)`
+  - 用途：生成移动端 clamp。
+  - 结构：`clamp($min, calc($mobile * var(--px-to-vw-mb)), $mobile)`。
+
+- `r.vw_pc($pc)`
+  - 用途：生成 PC 端 `vw` 并带上限。
+  - 结构：`min(calc($pc * var(--px-to-vw)), $pc)`。
+
+- `r.vw_mb($mobile)`
+  - 用途：生成移动端纯 `vw`。
+  - 结构：`calc($mobile * var(--px-to-vw-mb))`。
+
+### 内部工具函数（不建议业务直接使用）
+
+- `_to-px($value)`：把无单位数字转为 `px`。
+- `_to-num($value)`：把 `px` 或无单位数字转为纯数字（其他单位会报错）。
+
 ## CSS 编译（safe mode）
 
 `npm run css:watch` 默认走 safe mode：

package/template/tools/scss-kit/cli.mjs

@@ -67,6 +67,7 @@ function getMobileMax(cfg) {
 
 function getAutofill(cfg) {
   const fn = cfg?.autofill?.function ?? 'r.resp'
+  const vwFn = cfg?.autofill?.vwFunction
   const mobileMax = getMobileMax(cfg)
   const scanDirs = cfg?.autofill?.scanDirs ?? [
     cfg?.paths?.scssSrcDir ?? 'src/styles',
@@ -82,9 +83,27 @@ function getAutofill(cfg) {
   }
   const ns = parts[0]
   const name = parts[1]
+
+  const defaultVwFn = `${ns}.vw`
+  const vwParts = String(vwFn ?? defaultVwFn).split('.')
+  if (vwParts.length !== 2 || !vwParts[0] || !vwParts[1]) {
+    throw new Error(
+      `Invalid autofill.vwFunction: ${String(
+        vwFn
+      )}. Expected format: <ns>.<name> (e.g. ${defaultVwFn})`
+    )
+  }
+  if (vwParts[0] !== ns) {
+    throw new Error(
+      `autofill.vwFunction namespace must match autofill.function namespace (${ns})`
+    )
+  }
+  const vwName = vwParts[1]
+
   return {
     ns,
     name,
+    vwName,
     mobileMax,
     scanDirs,
     outputAbs: path.join(ROOT, output),
@@ -139,8 +158,7 @@ function splitTopLevelArgs(argsStr) {
   return args
 }
 
-function replaceRespCalls(value, { ns, name }) {
-  const token = `${ns}.${name}(`
+function replaceFunctionCalls(value, token, mapArgsToReplacement) {
   let out = ''
   let idx = 0
   let changed = false
@@ -183,11 +201,9 @@ function replaceRespCalls(value, { ns, name }) {
 
     const argsStr = value.slice(argsStart, i)
     const args = splitTopLevelArgs(argsStr)
-    if (args.length >= 3) {
-      const mobile = args[1]
-      const desktopType = args[2]
-      const mobileType = args.length >= 4 ? args[3] : desktopType
-      out += `${ns}.clamp_mb(${mobile}, ${ns}.min_px(${mobile}, ${mobileType}, mobile))`
+    const replacement = mapArgsToReplacement(args)
+    if (replacement != null) {
+      out += replacement
       changed = true
     } else {
       // Not enough args: keep original call.
@@ -200,6 +216,33 @@ function replaceRespCalls(value, { ns, name }) {
   return { value: out.trim(), changed }
 }
 
+function replaceAutofillCalls(value, { ns, name, vwName }) {
+  const respToken = `${ns}.${name}(`
+  const replacedResp = replaceFunctionCalls(value, respToken, (args) => {
+    if (args.length < 3) return null
+    const mobile = args[1]
+    const desktopType = args[2]
+    const mobileType = args.length >= 4 ? args[3] : desktopType
+    return `${ns}.clamp_mb(${mobile}, ${ns}.min_px(${mobile}, ${mobileType}, mobile))`
+  })
+
+  const vwToken = `${ns}.${vwName}(`
+  const replacedVw = replaceFunctionCalls(
+    replacedResp.value,
+    vwToken,
+    (args) => {
+      if (args.length < 2) return null
+      const mobile = args[1]
+      return `${ns}.vw_mb(${mobile})`
+    }
+  )
+
+  return {
+    value: replacedVw.value.trim(),
+    changed: replacedResp.changed || replacedVw.changed,
+  }
+}
+
 function combineSelectors(parents, children) {
   const out = []
   for (const p of parents) {
@@ -216,7 +259,7 @@ function combineSelectors(parents, children) {
   return out
 }
 
-function scanScssForAutofill_legacy(absFilePath, { ns, name }) {
+function scanScssForAutofill_legacy(absFilePath, { ns, name, vwName }) {
   const raw = fs.readFileSync(absFilePath, 'utf8')
   const lines = raw.split(/\r?\n/)
 
@@ -275,7 +318,7 @@ function scanScssForAutofill_legacy(absFilePath, { ns, name }) {
       value = value.replace(/\s!important\s*$/i, '').trim()
     }
 
-    const replaced = replaceRespCalls(value, { ns, name })
+    const replaced = replaceAutofillCalls(value, { ns, name, vwName })
     if (!replaced.changed) continue
 
     const finalValue = important
@@ -290,7 +333,7 @@ function scanScssForAutofill_legacy(absFilePath, { ns, name }) {
   return rules
 }
 
-function scanScssForAutofill_ast(absFilePath, { ns, name }) {
+function scanScssForAutofill_ast(absFilePath, { ns, name, vwName }) {
   // Lazy-load optional deps so `init` can run before `npm install`.
   /** @type {typeof import('postcss')} */
   let postcss
@@ -332,7 +375,7 @@ function scanScssForAutofill_ast(absFilePath, { ns, name }) {
           const property = String(child.prop)
           let value = String(child.value ?? '').trim()
 
-          const replaced = replaceRespCalls(value, { ns, name })
+          const replaced = replaceAutofillCalls(value, { ns, name, vwName })
           if (!replaced.changed) continue
 
           const finalValue = child.important
@@ -362,12 +405,12 @@ function scanScssForAutofill_ast(absFilePath, { ns, name }) {
   return rules
 }
 
-function scanScssForAutofill(absFilePath, { ns, name }) {
+function scanScssForAutofill(absFilePath, { ns, name, vwName }) {
   try {
-    return scanScssForAutofill_ast(absFilePath, { ns, name })
+    return scanScssForAutofill_ast(absFilePath, { ns, name, vwName })
   } catch (e) {
     // Fallback for edge cases where parser can't handle a file.
-    return scanScssForAutofill_legacy(absFilePath, { ns, name })
+    return scanScssForAutofill_legacy(absFilePath, { ns, name, vwName })
   }
 }
 
@@ -388,7 +431,7 @@ function generateAutofillScss(cfg, collectedRules) {
   const header = `@use "./responsive" as ${ns};
 
 // Generated by scss-kit from ${CONFIG_NAME}
-// Source: scanned ${ns}.resp(pc, mobile, type) markers in scss.
+// Source: scanned ${ns}.resp(pc, mobile, desktopType[, mobileType]) and ${ns}.vw(pc, mobile) markers in scss.
 // Do not edit this file directly; re-run: npm run scss-kit:responsive:generate
 \n`
 
@@ -529,10 +572,11 @@ function toScssMap(obj) {
 function generateResponsiveScss(cfg) {
   const mobileMap = toScssMap(cfg.coefficients.mobile)
   const desktopMap = toScssMap(cfg.coefficients.desktop)
+  const mobileFloorMap = toScssMap(cfg.floors?.mobile ?? {})
+  const desktopFloorMap = toScssMap(cfg.floors?.desktop ?? {})
 
   return `@use "sass:map";
 @use "sass:math";
-@use "sass:list";
 @use "sass:meta";
 
 // Generated by scss-kit from ${CONFIG_NAME}
@@ -546,6 +590,10 @@ $coef-mobile: ${mobileMap};
 
 $coef-desktop: ${desktopMap};
 
+$floor-mobile: ${mobileFloorMap};
+
+$floor-desktop: ${desktopFloorMap};
+
 @function _to-px($value) {
   @return if(math.is-unitless($value), $value * 1px, $value);
 }
@@ -571,25 +619,36 @@ $coef-desktop: ${desktopMap};
   @error "Unknown coef type: #{$type}";
 }
 
-// 根据 ${cfg.design.mobileWidth} 稿数值 + 系数，推导 clamp() 的最小值。
-@function min_px($mobile, $type, $range: mobile, $override-coef: null) {
-  $v: _to-px($mobile);
+@function _floor($type, $range: mobile) {
+  $table: if($range == desktop, $floor-desktop, $floor-mobile);
+  @if map.has-key($table, $type) {
+    @return map.get($table, $type);
+  }
+  @return null;
+}
 
-  // Mobile typography rule:
-  // - Scale ${cfg.design.mobileWidth}px design to 375px proportion
-  // - Apply readable floors: h1>=16px, h2>=14px, other text>=12px
-  // - Ensure min <= max (design value)
-  @if $range == mobile and $override-coef == null {
-    $typography-types: (h1, h2, h3, body, small, button-text);
-    @if list.index($typography-types, $type) {
-      $scaled-375: $v * math.div(375, ${cfg.design.mobileWidth});
-      $floor: if($type == h1, 16px, if($type == h2, 14px, 12px));
-      @return math.min($v, math.max($scaled-375, $floor));
+// 根据设计稿 px + 系数推导 clamp() 最小值：max(design * coef, floor)。
+// $type 可传命名类型（字符串）或直接传数字系数（跳过系数表查询，不使用 floor）。
+@function min_px($value, $type, $range: mobile, $override-coef: null, $override-floor: null) {
+  $v: _to-px($value);
+
+  // 直接传数字系数：跳过类型表，直接以系数计算
+  @if meta.type-of($type) == number {
+    $min: $v * $type;
+    @if $override-floor != null {
+      @return math.max($min, _to-px($override-floor));
     }
+    @return $min;
   }
 
   $c: if($override-coef == null, coef($type, $range), $override-coef);
-  @return $v * $c;
+  $min: $v * $c;
+
+  $f: if($override-floor != null, _to-px($override-floor), _floor($type, $range));
+  @if $f {
+    @return math.max($min, $f);
+  }
+  @return $min;
 }
 
 // 生成桌面段 clamp：min + calc(pc * var(--px-to-vw)) + pc
@@ -606,6 +665,29 @@ $coef-desktop: ${desktopMap};
   @return clamp(#{$min}, calc(#{$n} * var(--px-to-vw-mb)), #{$v});
 }
 
+// 直接输出 PC 段 vw，并用设计稿 px 做上限兜底。
+@function vw_pc($pc) {
+  $v: _to-px($pc);
+  $n: _to-num($pc);
+  @return min(calc(#{$n} * var(--px-to-vw)), #{$v});
+}
+
+// 直接输出移动段 vw（无 clamp）。
+@function vw_mb($mobile) {
+  $n: _to-num($mobile);
+  @return calc(#{$n} * var(--px-to-vw-mb));
+}
+
+// vw(): spacing-first helper（间距优先，默认不设最小值）
+// - PC: min(vw, px)
+// - Mobile: 纯 vw（通过 autofill 覆盖生成）
+@function vw($pc, $mobile) {
+  @if meta.type-of($pc) != number or meta.type-of($mobile) != number {
+    @error "vw() expects numeric px values for both pc and mobile";
+  }
+  @return vw_pc($pc);
+}
+
 // resp():
 // - arg3: desktop type
 // - arg4 (optional): mobile type, defaults to desktop type

package/template/tools/scss-kit/schema.json

@@ -25,6 +25,7 @@
       "type": "object",
       "properties": {
         "function": {"type": "string"},
+        "vwFunction": {"type": "string"},
         "mobileMax": {"type": "integer", "minimum": 1},
         "scanDirs": {"type": "array", "items": {"type": "string"}},
         "output": {"type": "string"},
@@ -47,6 +48,13 @@
         "mobile": {"type": "object", "additionalProperties": {"type": "number"}},
         "desktop": {"type": "object", "additionalProperties": {"type": "number"}}
       }
+    },
+    "floors": {
+      "type": "object",
+      "properties": {
+        "mobile": {"type": "object", "additionalProperties": {"type": "string"}},
+        "desktop": {"type": "object", "additionalProperties": {"type": "string"}}
+      }
     }
   }
 }