sellmate-design-system-react 2.2.0 → 3.1.0

package/dist/theme.css

@@ -1344,6 +1344,8 @@
   --cmp-gnb-rail-item-radius: 8px;
   --cmp-gnb-rail-item-icon: 24px;
   --cmp-gnb-rail-item-width: 44px;
+  --cmp-list-group-gap: 8px;
+  --cmp-list-group-padding: 16px;
   --cmp-listItem-paddingX: 16px;
   --cmp-listItem-paddingY-normal: 8px;
   --cmp-listItem-paddingY-dense: 4px;
@@ -1417,6 +1419,18 @@
   --cmp-sectionHeaderCard-required-icon: 16px;
   --cmp-sectionHeaderCard-subtitle-color: #555555;
   --cmp-sectionHeaderCard-body-bg: #FFFFFF;
+  --cmp-tree-item-bg-default: #FFFFFF;
+  --cmp-tree-item-bg-hover: #F9F9F9;
+  --cmp-tree-item-border-default: #E1E1E1;
+  --cmp-tree-item-border-width-default: 1px;
+  --cmp-tree-item-paddingX: 16px;
+  --cmp-tree-item-paddingY: 4px;
+  --cmp-tree-item-rowGap: 8px;
+  --cmp-tree-item-contentGap: 12px;
+  --cmp-tree-item-text-default: #222222;
+  --cmp-tree-item-text-selected: #0075FF;
+  --cmp-tree-item-arrow-icon: 12px;
+  --cmp-tree-connector-line-color: #AAAAAA;
 }
 
 /* 전역 스크롤바 — overflow(auto/scroll)로 스크롤이 생기는 모든 요소에 SScrollArea 기본 스크롤바를 자동 적용.
@@ -1425,6 +1439,14 @@
    Chrome 121+/WebKit 는 scrollbar-width·scrollbar-color 계산값이 auto 가 아니면 ::-webkit-scrollbar-* 를 통째로
    무시하므로, 표준 속성은 webkit 유사요소가 없는 브라우저(Firefox)에서만 켠다. */
 @layer base {
+  /* 전역 기본 텍스트 색 — 본문은 grey_95(= fg.primary). 요소마다 색을 지정하지 않아도
+     브라우저 기본 검정(#000)이 아니라 디자인 시스템 색으로 렌더된다.
+     보조·비활성 텍스트만 text-fg-tertiary(grey_65)로 내려 쓴다.
+     base 레이어라 소비 앱의 text-* 유틸리티(utilities)가 언제든 덮어쓴다. */
+  body {
+    color: var(--color-fg-primary);
+  }
+
   *::-webkit-scrollbar {
     width: 12px;
     height: 12px;

package/eslint/index.mjs

@@ -0,0 +1,66 @@
+/**
+ * sellmate-design-system-react — 소비 앱용 ESLint 플러그인.
+ *
+ * AGENTS.md 의 규칙 중 정적으로 검출 가능한 것을 린트로 강제한다.
+ * 사용법은 README 의 "ESLint 설정" 절 참조.
+ */
+import noRawHtmlControl from "./rules/no-raw-html-control.mjs";
+import noArbitraryClass from "./rules/no-arbitrary-class.mjs";
+import noOffScaleSpacing from "./rules/no-off-scale-spacing.mjs";
+import preferTypoPreset from "./rules/prefer-typo-preset.mjs";
+import tableNumericAlign from "./rules/table-numeric-align.mjs";
+import requireLocaleNumber from "./rules/require-locale-number.mjs";
+
+const PLUGIN_NAME = "sellmate";
+
+const plugin = {
+  meta: { name: "eslint-plugin-sellmate" },
+  rules: {
+    "no-raw-html-control": noRawHtmlControl,
+    "no-arbitrary-class": noArbitraryClass,
+    "no-off-scale-spacing": noOffScaleSpacing,
+    "prefer-typo-preset": preferTypoPreset,
+    "table-numeric-align": tableNumericAlign,
+    "require-locale-number": requireLocaleNumber,
+  },
+};
+
+/** 기본 프리셋 — JSX/TSX 파일에 적용 */
+const recommended = [
+  {
+    // 컬럼 정의를 .ts 파일로 분리하는 경우가 있어 tsx 뿐 아니라 ts 도 포함한다
+    files: ["**/*.{js,jsx,ts,tsx}"],
+    plugins: { [PLUGIN_NAME]: plugin },
+    rules: {
+      // 스타일이 조용히 사라지거나 디자인 시스템을 우회하는 경우 → error
+      [`${PLUGIN_NAME}/no-raw-html-control`]: "error",
+      [`${PLUGIN_NAME}/no-arbitrary-class`]: "error",
+      [`${PLUGIN_NAME}/no-off-scale-spacing`]: "error",
+      [`${PLUGIN_NAME}/table-numeric-align`]: "error",
+      [`${PLUGIN_NAME}/require-locale-number`]: "error",
+      // 대체 프리셋 판단에 여지가 있어 warn
+      [`${PLUGIN_NAME}/prefer-typo-preset`]: "warn",
+    },
+  },
+];
+
+/**
+ * 전 규칙 error + ul·ol·li·svg·label 까지 검사.
+ * 정당한 사용처(로고 SVG, 시맨틱 목록 등)가 있는 요소도 잡히므로
+ * 예외는 `allow` 로 열어 쓰는 것을 전제로 한다. 신규 프로젝트용.
+ */
+const strict = [
+  {
+    ...recommended[0],
+    rules: {
+      ...recommended[0].rules,
+      [`${PLUGIN_NAME}/no-raw-html-control`]: ["error", { strict: true }],
+      [`${PLUGIN_NAME}/prefer-typo-preset`]: "error",
+    },
+  },
+];
+
+plugin.configs = { recommended, strict };
+
+export default plugin;
+export const { rules, configs } = plugin;

package/eslint/lib/class-names.mjs

@@ -0,0 +1,119 @@
+/**
+ * className / class 속성에서 클래스 토큰을 추출하는 공용 헬퍼.
+ *
+ * 지원 형태:
+ *   className="a b"                     → Literal
+ *   className={`a ${x} b`}              → TemplateLiteral (정적 quasi 부분만)
+ *   className={cn('a', cond && 'b')}    → clsx/cn/classnames 호출의 문자열 인자
+ *   className={'a b'}                   → JSXExpressionContainer > Literal
+ *
+ * 동적으로 조립되는 부분(변수·삼항의 식별자 등)은 정적 분석 대상이 아니므로 건너뛴다.
+ */
+
+const CLASS_ATTRS = new Set(["className", "class"]);
+const CLASS_HELPERS = new Set(["cn", "clsx", "classNames", "classnames", "cva", "twMerge"]);
+
+/** 문자열을 공백 기준 클래스 토큰으로 나눈다 (variant 접두어는 유지) */
+export function tokenize(value) {
+  return String(value)
+    .split(/\s+/)
+    .filter(Boolean);
+}
+
+/**
+ * `hover:md:gap-12` → `gap-12` — variant 접두어를 벗겨 유틸리티 본체만 남긴다.
+ * 임의 값 안의 `:`(예: `[length:var(--x)]`)는 벗기지 않는다.
+ */
+export function stripVariants(token) {
+  let rest = token;
+  for (;;) {
+    const idx = indexOfTopLevelColon(rest);
+    if (idx === -1) return rest;
+    rest = rest.slice(idx + 1);
+  }
+}
+
+/** 대괄호 밖에 있는 첫 `:` 위치 (없으면 -1) */
+function indexOfTopLevelColon(s) {
+  let depth = 0;
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    if (c === "[") depth++;
+    else if (c === "]") depth--;
+    else if (c === ":" && depth === 0) return i;
+  }
+  return -1;
+}
+
+/** `!gap-12` / `-mt-8` 같은 접두 기호 제거 */
+export function stripModifiers(token) {
+  return token.replace(/^!/, "").replace(/^-/, "");
+}
+
+/**
+ * JSXAttribute 노드에서 정적으로 알 수 있는 클래스 토큰을 모두 수집한다.
+ * @returns {Array<{ token: string, node: import('estree').Node }>}
+ */
+export function collectClassTokens(attrNode) {
+  if (attrNode.type !== "JSXAttribute") return [];
+  const name = attrNode.name?.name;
+  if (!CLASS_ATTRS.has(name)) return [];
+
+  const out = [];
+  const push = (raw, node) => {
+    for (const token of tokenize(raw)) out.push({ token, node });
+  };
+
+  const visit = (node) => {
+    if (!node) return;
+    switch (node.type) {
+      case "Literal":
+        if (typeof node.value === "string") push(node.value, node);
+        break;
+      case "TemplateLiteral":
+        // 정적 부분만 본다. 보간(${}) 안쪽은 아래 표현식 방문으로 따로 처리.
+        for (const q of node.quasis) push(q.value.cooked ?? "", node);
+        for (const e of node.expressions) visit(e);
+        break;
+      case "JSXExpressionContainer":
+        visit(node.expression);
+        break;
+      case "CallExpression": {
+        const callee = node.callee;
+        const fnName = callee?.type === "Identifier" ? callee.name : callee?.property?.name;
+        if (fnName && CLASS_HELPERS.has(fnName)) {
+          for (const arg of node.arguments) visit(arg);
+        }
+        break;
+      }
+      case "ConditionalExpression":
+        visit(node.consequent);
+        visit(node.alternate);
+        break;
+      case "LogicalExpression":
+        visit(node.left);
+        visit(node.right);
+        break;
+      case "ArrayExpression":
+        for (const el of node.elements) visit(el);
+        break;
+      case "ObjectExpression":
+        // clsx({ 'gap-12': cond }) 형태 — 키가 클래스다
+        for (const prop of node.properties) {
+          if (prop.type === "Property" && prop.key) {
+            if (prop.key.type === "Literal" && typeof prop.key.value === "string") {
+              push(prop.key.value, prop.key);
+            } else if (prop.key.type === "Identifier" && !prop.computed) {
+              push(prop.key.name, prop.key);
+            }
+          }
+        }
+        break;
+      default:
+        break;
+    }
+  };
+
+  visit(attrNode.value);
+  return out;
+}

package/eslint/lib/table-column.mjs

@@ -0,0 +1,53 @@
+/**
+ * STableColumn 형태 판별과 "숫자 컬럼" 판정을 공유하는 헬퍼.
+ * table-numeric-align · require-locale-number 두 규칙이 함께 쓴다.
+ */
+
+/**
+ * 오른쪽 정렬 대상 — 숫자가 들어가는 모든 컬럼.
+ * 식별자(주문번호·상품코드)도 숫자라 자릿수를 맞춰야 하므로 포함한다.
+ */
+export const NUMERIC_LABEL =
+  /금액|가격|단가|판매가|원가|비용|수수료|배송비|할인|합계|총액|잔액|포인트|적립|수량|재고|개수|건수|횟수|비율|퍼센트|평점|점수|무게|용량|길이|면적|번호|코드|순번|순위|나이|연차/;
+
+/**
+ * 하이픈 등 서식이 들어간 문자열 — 숫자가 아니므로 정렬·서식 규칙 모두 대상이 아니다.
+ * (전화번호 010-1234-5678, 사업자번호 123-45-67890)
+ */
+export const IDENTIFIER_ONLY = /전화|휴대폰|연락처|사업자|주민|계좌|우편/;
+
+/** format 본문에 숫자 서식이 있으면 숫자 컬럼으로 본다 */
+export const NUMERIC_FORMAT = /toLocaleString|toFixed|Number\s*\(|parseInt|parseFloat/;
+
+/** 객체 리터럴에서 프로퍼티 노드를 이름으로 찾는다 */
+export function prop(objectNode, name) {
+  return objectNode.properties.find(
+    (p) =>
+      p.type === "Property" &&
+      !p.computed &&
+      ((p.key.type === "Identifier" && p.key.name === name) ||
+        (p.key.type === "Literal" && p.key.value === name)),
+  );
+}
+
+/** 문자열 리터럴 값 (아니면 undefined) */
+export function literalString(node) {
+  return node?.value?.type === "Literal" && typeof node.value.value === "string"
+    ? node.value.value
+    : undefined;
+}
+
+/**
+ * STableColumn 형태인지 — name·label·field 셋을 모두 가진 객체만 컬럼으로 본다.
+ * @returns {{ nameProp, labelProp, label: string } | null}
+ */
+export function asColumn(node) {
+  const nameProp = prop(node, "name");
+  const labelProp = prop(node, "label");
+  if (!nameProp || !labelProp || !prop(node, "field")) return null;
+
+  const label = literalString(labelProp);
+  if (label === undefined) return null; // 동적 label 은 판단하지 않는다
+
+  return { nameProp, labelProp, label, columnName: literalString(nameProp) };
+}

package/eslint/rules/no-arbitrary-class.mjs

@@ -0,0 +1,91 @@
+/**
+ * **디자인 토큰이 있는 속성**에 임의 값을 쓰는 것을 막는다 — `text-[14px]`, `bg-[#eee]` 등.
+ *
+ * 반대로, 디자인 시스템이 토큰화하지 않는 **앱 고유 레이아웃 치수**(`w-[280px]`,
+ * `max-w-[1200px]`, `grid-cols-[200px_1fr]`)는 정당한 사용이므로 막지 않는다.
+ * 토큰을 var() 로 참조하는 형태(`h-[var(--sys-size-...)]`)도 허용한다.
+ *
+ * AGENTS.md §1-2.
+ */
+import { collectClassTokens, stripVariants, stripModifiers } from "../lib/class-names.mjs";
+
+/**
+ * 토큰이 존재하는 속성 접두어 — 여기에 임의 값을 쓰면 디자인 시스템을 우회하는 것이다.
+ * 색·타이포·간격·모서리 4계열.
+ */
+const TOKEN_BACKED = [
+  // 색 (text- 는 색·폰트크기 양쪽 모두 토큰이 있어 어느 쪽이든 대상)
+  "text", "bg", "border", "outline", "ring", "shadow", "fill", "stroke",
+  "divide", "accent", "caret", "decoration", "from", "via", "to",
+  // 타이포
+  "font", "leading", "tracking",
+  // 간격
+  "gap", "gap-x", "gap-y", "space-x", "space-y",
+  "p", "px", "py", "pt", "pr", "pb", "pl", "ps", "pe",
+  "m", "mx", "my", "mt", "mr", "mb", "ml", "ms", "me",
+  // 모서리
+  "rounded", "rounded-t", "rounded-r", "rounded-b", "rounded-l",
+  "rounded-tl", "rounded-tr", "rounded-br", "rounded-bl",
+];
+
+/** 대괄호 안이 토큰 참조인지 — `var(--x)` 또는 `length:var(--x)` 같은 데이터타입 접두어 허용 */
+function isTokenReference(inner) {
+  const body = inner.includes(":") ? inner.slice(inner.indexOf(":") + 1) : inner;
+  return /^var\(--[\w-]+\)$/.test(body.trim());
+}
+
+/** `bg-[#eee]` → `bg` 처럼 임의 값 앞의 유틸리티 접두어를 뽑는다 */
+function prefixOf(util) {
+  const idx = util.indexOf("[");
+  return idx <= 0 ? "" : util.slice(0, idx - 1); // 대괄호 바로 앞의 `-` 제외
+}
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "색·타이포·간격·모서리에 임의 값 금지 — 토큰 유틸리티 또는 var(--token) 참조 사용",
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          /** 예외로 허용할 클래스 (완전 일치) */
+          allow: { type: "array", items: { type: "string" }, uniqueItems: true },
+          /** 검사 대상에서 뺄 유틸리티 접두어 (예: ["shadow"]) */
+          ignorePrefixes: { type: "array", items: { type: "string" }, uniqueItems: true },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      arbitrary:
+        "`{{token}}` — {{prefix}} 는 디자인 토큰이 있는 속성이라 임의 값을 쓸 수 없습니다. 토큰 유틸리티를 쓰거나 var(--token) 으로 참조하세요. (AGENTS.md §1-2)",
+    },
+  },
+
+  create(context) {
+    const allow = new Set(context.options[0]?.allow ?? []);
+    const ignored = new Set(context.options[0]?.ignorePrefixes ?? []);
+    const targets = TOKEN_BACKED.filter((p) => !ignored.has(p));
+
+    return {
+      JSXAttribute(node) {
+        for (const { token, node: valueNode } of collectClassTokens(node)) {
+          if (allow.has(token)) continue;
+
+          const util = stripModifiers(stripVariants(token));
+          const match = util.match(/\[([^\]]*)\]/);
+          if (!match) continue;
+          if (isTokenReference(match[1])) continue;
+
+          // 토큰이 없는 속성(w·max-w·grid-cols·top …)의 임의 값은 앱 고유 치수이므로 허용
+          const prefix = prefixOf(util);
+          if (!targets.includes(prefix)) continue;
+
+          context.report({ node: valueNode, messageId: "arbitrary", data: { token, prefix } });
+        }
+      },
+    };
+  },
+};

package/eslint/rules/no-off-scale-spacing.mjs

@@ -0,0 +1,67 @@
+/**
+ * 간격 유틸리티가 토큰 스케일 밖의 값을 쓰는 것을 막는다 — `gap-13`, `p-15` 등.
+ *
+ * Tailwind v4 는 `--spacing-*` 테마 키에 있는 값만 유틸리티로 생성하므로,
+ * 스케일 밖 숫자는 **에러 없이 조용히 아무 스타일도 적용되지 않는다.**
+ * 눈으로는 "간격이 왜 안 먹지" 로만 보이기 때문에 린트로 잡는다.
+ *
+ * AGENTS.md §2-2.
+ */
+import { collectClassTokens, stripVariants, stripModifiers } from "../lib/class-names.mjs";
+import { SPACING } from "../scale.gen.mjs";
+
+/** 값이 순수하게 간격 스케일에서 오는 유틸리티 접두어만 대상으로 한다 */
+const SPACING_PREFIXES = [
+  "gap-x", "gap-y", "gap",
+  "space-x", "space-y",
+  "px", "py", "pt", "pr", "pb", "pl", "ps", "pe", "p",
+  "mx", "my", "mt", "mr", "mb", "ml", "ms", "me", "m",
+];
+
+const ALLOWED = new Set([0, ...SPACING]);
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "간격 유틸리티는 토큰 스케일 값만 사용",
+    },
+    schema: [],
+    messages: {
+      offScale:
+        "`{{token}}` 의 {{value}} 는 간격 스케일에 없어 스타일이 적용되지 않습니다. 가까운 값: {{nearest}}. (AGENTS.md §2-2)",
+    },
+  },
+
+  create(context) {
+    return {
+      JSXAttribute(node) {
+        for (const { token, node: valueNode } of collectClassTokens(node)) {
+          const util = stripModifiers(stripVariants(token));
+
+          const prefix = SPACING_PREFIXES.find((p) => util.startsWith(`${p}-`));
+          if (!prefix) continue;
+
+          const raw = util.slice(prefix.length + 1);
+          // 숫자가 아닌 값(auto, px, full, [var(--x)] 등)은 이 규칙 대상이 아니다
+          if (!/^\d+$/.test(raw)) continue;
+
+          const value = Number(raw);
+          if (ALLOWED.has(value)) continue;
+
+          const nearest = [...ALLOWED]
+            .sort((a, b) => Math.abs(a - value) - Math.abs(b - value))
+            .slice(0, 2)
+            .sort((a, b) => a - b)
+            .join(" / ");
+
+          context.report({
+            node: valueNode,
+            messageId: "offScale",
+            data: { token, value: String(value), nearest },
+          });
+        }
+      },
+    };
+  },
+};

package/eslint/rules/no-raw-html-control.mjs

@@ -0,0 +1,117 @@
+/**
+ * 디자인 시스템에 대응 컴포넌트가 있는 생 HTML 요소 사용을 막는다.
+ * AGENTS.md §1-1 과 같은 목록을 강제한다.
+ */
+
+/**
+ * 기본 대상 — 대응 컴포넌트가 명확해 오탐 여지가 거의 없는 요소.
+ */
+const REPLACEMENTS = {
+  button: "SButton / SGhostButton / SDropdownButton / STextLink",
+  input: "SInput / SNumberInput / SCheckbox / SRadio / SFilePicker",
+  select: "SSelect",
+  textarea: "STextarea",
+  table: "STable / SKeyValueTable",
+  form: "SForm",
+  dialog: "SModal.create(...) / SModal.confirm(...) / SPopup",
+  hr: "SDivider",
+  details: "SExpansionItem",
+  summary: "SExpansionItem",
+  progress: "SLinearProgress / SCircleProgress",
+};
+
+/**
+ * strict 옵션에서만 검사하는 요소 — 정당한 사용처가 함께 있어 기본에서는 뺀다.
+ *  - svg   : 로고·일러스트·차트
+ *  - ul/li : 본문 안의 시맨틱 목록, 브레드크럼
+ *  - label : DS 밖 컨트롤의 접근성 레이블
+ */
+const STRICT_REPLACEMENTS = {
+  ul: "SList + SListItem",
+  ol: "SList + SListItem",
+  li: "SListItem",
+  svg: "SIcon",
+  label: "SField 의 label prop",
+};
+
+/** 시각 요소가 없어 대체 컴포넌트가 없는 input 타입 */
+const EXEMPT_INPUT_TYPES = new Set(["hidden"]);
+
+/** JSX 속성에서 리터럴 문자열 값을 읽는다 (동적 값이면 undefined) */
+function literalAttr(node, name) {
+  const attr = node.attributes.find(
+    (a) => a.type === "JSXAttribute" && a.name?.name === name,
+  );
+  const v = attr?.value;
+  if (v?.type === "Literal" && typeof v.value === "string") return v.value;
+  return undefined;
+}
+
+/** 전역 함수 → 권장 대체 */
+const GLOBAL_CALLS = {
+  alert: "SToast / SModal.confirm(...)",
+  confirm: "SModal.confirm(...)",
+};
+
+export default {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "디자인 시스템 컴포넌트가 있는 생 HTML 컨트롤 사용 금지",
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          /** 예외로 허용할 요소명 (예: 로고용 svg) */
+          allow: { type: "array", items: { type: "string" }, uniqueItems: true },
+          /** ul·ol·li·svg·label 까지 검사 (정당한 사용처가 있어 기본은 off) */
+          strict: { type: "boolean" },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      rawElement: "<{{name}}> 대신 {{replacement}} 를 사용하세요. (AGENTS.md §1-1)",
+      rawCall: "{{name}}() 대신 {{replacement}} 를 사용하세요. (AGENTS.md §1-1)",
+    },
+  },
+
+  create(context) {
+    const options = context.options[0] ?? {};
+    const allow = new Set(options.allow ?? []);
+    const replacements = options.strict
+      ? { ...REPLACEMENTS, ...STRICT_REPLACEMENTS }
+      : REPLACEMENTS;
+
+    return {
+      JSXOpeningElement(node) {
+        if (node.name.type !== "JSXIdentifier") return;
+        const name = node.name.name;
+        // 컴포넌트(대문자 시작)는 대상이 아니다
+        if (name[0] !== name[0].toLowerCase()) return;
+        if (allow.has(name)) return;
+
+        const replacement = replacements[name];
+        if (!replacement) return;
+
+        // <input type="hidden"> 처럼 시각 요소가 없는 경우는 대체 컴포넌트가 없다
+        if (name === "input" && EXEMPT_INPUT_TYPES.has(literalAttr(node, "type"))) return;
+
+        context.report({ node: node.name, messageId: "rawElement", data: { name, replacement } });
+      },
+
+      CallExpression(node) {
+        if (node.callee.type !== "Identifier") return;
+        const name = node.callee.name;
+        const replacement = GLOBAL_CALLS[name];
+        if (!replacement) return;
+        // 지역 선언(사용자가 만든 confirm 등)은 제외
+        if (context.sourceCode.getScope(node).references.some((r) => r.identifier === node.callee && r.resolved)) {
+          return;
+        }
+        context.report({ node, messageId: "rawCall", data: { name, replacement } });
+      },
+    };
+  },
+};

package/eslint/rules/prefer-typo-preset.mjs

@@ -0,0 +1,73 @@
+/**
+ * 폰트 크기·굵기를 낱개 유틸리티로 조립하는 것을 막고 `typo-*` 프리셋 사용을 유도한다.
+ * `text-14 font-bold` 대신 `typo-body-md-bold`.
+ *
+ * AGENTS.md §1-3 / §2-1.
+ */
+import { collectClassTokens, stripVariants, stripModifiers } from "../lib/class-names.mjs";
+import { TEXT_SIZES, TYPO_PRESETS } from "../scale.gen.mjs";
+
+const FONT_WEIGHTS = new Set([
+  "font-thin", "font-extralight", "font-light", "font-normal", "font-medium",
+  "font-semibold", "font-bold", "font-extrabold", "font-black",
+]);
+
+const TEXT_SIZE_SET = new Set(TEXT_SIZES.map(String));
+
+/** 자주 쓰는 조합에 대한 추천 프리셋 (없으면 일반 안내) */
+function suggest(size) {
+  const byRole = {
+    12: "typo-body-sm-*",
+    14: "typo-body-md-* / typo-heading-sm",
+    16: "typo-body-lg-* / typo-heading-md",
+    18: "typo-heading-lg",
+    11: "typo-body-xs-default",
+  };
+  return byRole[size] ?? "typo-*";
+}
+
+export default {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "폰트 크기·굵기 낱개 조합 대신 typo-* 프리셋 사용",
+    },
+    schema: [],
+    messages: {
+      fontSize:
+        "`{{token}}` 대신 타이포그래피 프리셋을 쓰세요 — {{suggestion}}. (AGENTS.md §2-1)",
+      fontWeight:
+        "`{{token}}` 을 단독으로 쓰지 말고 굵기가 포함된 typo-* 프리셋을 쓰세요. (AGENTS.md §2-1)",
+    },
+  },
+
+  create(context) {
+    return {
+      JSXAttribute(node) {
+        const tokens = collectClassTokens(node);
+        // 이미 프리셋을 쓰고 있으면 굵기 보조 유틸리티는 문제 삼지 않는다
+        const hasPreset = tokens.some(({ token }) =>
+          TYPO_PRESETS.includes(stripModifiers(stripVariants(token))),
+        );
+
+        for (const { token, node: valueNode } of tokens) {
+          const util = stripModifiers(stripVariants(token));
+
+          const sizeMatch = util.match(/^text-(\d+)$/);
+          if (sizeMatch && TEXT_SIZE_SET.has(sizeMatch[1])) {
+            context.report({
+              node: valueNode,
+              messageId: "fontSize",
+              data: { token, suggestion: suggest(Number(sizeMatch[1])) },
+            });
+            continue;
+          }
+
+          if (!hasPreset && FONT_WEIGHTS.has(util)) {
+            context.report({ node: valueNode, messageId: "fontWeight", data: { token } });
+          }
+        }
+      },
+    };
+  },
+};