@tide-tds/foundation 0.1.0 → 0.2.0

package/dist/color-css.d.ts

@@ -0,0 +1,46 @@
+import { ColorSlot, SlotRule } from "./color-slot.js";
+import { SemanticColorName, SemanticNamespace, ThemeName } from "./semantic.js";
+/** Primitive 변수 이름. 예: `--tide-color-blue-600` */
+export declare function primitiveVar(name: string): string;
+/** 계열 변수 이름. 예: `--tide-blue-solid` */
+export declare function familyVar(family: string, slot: ColorSlot): string;
+/** accent 슬롯 변수 이름. 예: `--tide-accent-solid` */
+export declare function accentVar(slot: ColorSlot): string;
+/** Semantic Token 변수 이름. 예: `--tide-bg-primary-solid` */
+export declare function semanticVar(className: string): string;
+/**
+ * 계열 하나의 Theme 블록 선언(9줄).
+ * @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+ */
+export declare function familyThemeDeclarations(family: string, steps: Readonly<Record<ColorSlot, SlotRule>>, theme: ThemeName): string[];
+/**
+ * `[data-color="<색 이름>"]` 규칙 하나. Role은 Role Token을, 계열은 계열 변수를 꽂는다.
+ * @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+ */
+export declare function dataColorRule(name: string): string;
+/**
+ * Theme 블록의 accent 기본값(primary). data-color가 없는 요소도 그 Theme의 값을 읽는다.
+ * @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+ */
+export declare function accentDefaultDeclarations(): string[];
+/**
+ * Tide 색 계열 전체의 Theme 블록 선언.
+ * @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+ */
+export declare function tideFamilyThemeDeclarations(theme: ThemeName): string[];
+/**
+ * Role Token이 Theme에서 계열 변수의 별칭이면 그 변수 참조를 돌려준다. 덮어쓴 슬롯이거나 Role Token이 아니면 undefined다.
+ * @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+ */
+export declare function roleAliasCss(className: SemanticColorName, theme: ThemeName): string | undefined;
+/** accent Utility class 하나. key는 Utility class에서 접두사를 뺀 이름이다. */
+export interface AccentUtility {
+  readonly namespace: SemanticNamespace;
+  readonly key: string;
+  readonly slot: ColorSlot;
+}
+/**
+ * accent Utility class 목록. 예: `bg-accent-solid` → `--tide-accent-solid`, `text-accent` → `--tide-accent-text`
+ * @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+ */
+export declare const accentUtilities: readonly AccentUtility[];

package/dist/color-css.js

@@ -0,0 +1,105 @@
+import { colorFamilyNames, isRole, roleNames, roleSlotToken } from "./color-name.js";
+import { colorSlots, familySlotSteps, slotPrimitive } from "./color-slot.js";
+import { roleFamily, semanticEntries } from "./semantic.js";
+
+// src/color-css.ts
+/** Primitive 변수 이름. 예: `--tide-color-blue-600` */
+function primitiveVar(name) {
+	return `--tide-color-${name}`;
+}
+/** 계열 변수 이름. 예: `--tide-blue-solid` */
+function familyVar(family, slot) {
+	return `--tide-${family}-${slot}`;
+}
+/** accent 슬롯 변수 이름. 예: `--tide-accent-solid` */
+function accentVar(slot) {
+	return `--tide-accent-${slot}`;
+}
+/** Semantic Token 변수 이름. 예: `--tide-bg-primary-solid` */
+function semanticVar(className) {
+	return `--tide-${className}`;
+}
+/** 슬롯 값의 CSS 표현. 계열 단계는 Primitive 변수를, white·black은 Tide Primitive 변수를 가리킨다. */
+function slotCss(family, step) {
+	return `var(${primitiveVar(slotPrimitive(family, step))})`;
+}
+/**
+* 계열 하나의 Theme 블록 선언(9줄).
+* @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+*/
+function familyThemeDeclarations(family, steps, theme) {
+	return colorSlots.map((slot) => `  ${familyVar(family, slot)}: ${slotCss(family, steps[slot][theme])};`);
+}
+/** accent 슬롯에 변수를 꽂는 선언 */
+function accentDeclarations(source) {
+	return colorSlots.map((slot) => `  ${accentVar(slot)}: var(${source(slot)});`);
+}
+/**
+* `[data-color="<색 이름>"]` 규칙 하나. Role은 Role Token을, 계열은 계열 변수를 꽂는다.
+* @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+*/
+function dataColorRule(name) {
+	const source = isRole(name) ? (slot) => semanticVar(roleSlotToken(name, slot)) : (slot) => familyVar(name, slot);
+	return [
+		`[data-color="${name}"] {`,
+		...accentDeclarations(source),
+		"}"
+	].join("\n");
+}
+/**
+* Theme 블록의 accent 기본값(primary). data-color가 없는 요소도 그 Theme의 값을 읽는다.
+* @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+*/
+function accentDefaultDeclarations() {
+	return accentDeclarations((slot) => semanticVar(roleSlotToken("primary", slot)));
+}
+/**
+* Tide 색 계열 전체의 Theme 블록 선언.
+* @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+*/
+function tideFamilyThemeDeclarations(theme) {
+	return colorFamilyNames.flatMap((family) => familyThemeDeclarations(family, familySlotSteps(family), theme));
+}
+const roleAliases = new Map(roleNames.flatMap((role) => colorSlots.map((slot) => [roleSlotToken(role, slot), slot]).filter(([token]) => token.includes(`-${role}`)).map(([token, slot]) => [token, {
+	family: roleFamily[role],
+	slot
+}])));
+/**
+* Role Token이 Theme에서 계열 변수의 별칭이면 그 변수 참조를 돌려준다. 덮어쓴 슬롯이거나 Role Token이 아니면 undefined다.
+* @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+*/
+function roleAliasCss(className, theme) {
+	const alias = roleAliases.get(className);
+	if (!alias) return void 0;
+	const family = alias.family;
+	const familyValue = slotPrimitive(family, familySlotSteps(family)[alias.slot][theme]);
+	return semanticEntries().find((candidate) => candidate.className === className).value[theme] === familyValue ? `var(${familyVar(family, alias.slot)})` : void 0;
+}
+/**
+* accent Utility class 목록. 예: `bg-accent-solid` → `--tide-accent-solid`, `text-accent` → `--tide-accent-text`
+* @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+*/
+const accentUtilities = [
+	...colorSlots.filter((slot) => slot !== "text" && slot !== "border" && slot !== "on-solid").map((slot) => ({
+		namespace: "background",
+		key: `accent-${slot}`,
+		slot
+	})),
+	{
+		namespace: "text",
+		key: "accent",
+		slot: "text"
+	},
+	{
+		namespace: "text",
+		key: "accent-on-solid",
+		slot: "on-solid"
+	},
+	{
+		namespace: "border",
+		key: "accent",
+		slot: "border"
+	}
+];
+
+export { accentDefaultDeclarations, accentUtilities, accentVar, dataColorRule, familyThemeDeclarations, familyVar, primitiveVar, roleAliasCss, semanticVar, tideFamilyThemeDeclarations };

package/dist/color-family.d.ts

@@ -0,0 +1,54 @@
+/**
+ * `@tide-tds/foundation/color-family`: 앱이 자기 브랜드 색 계열을 더하는 API.
+ *
+ * 앱은 `defineColorFamily`로 11단계 스케일을 정의하고, `tide-color build <파일>`로 CSS를 만든다.
+ * CSS는 Tide 계열과 같은 매핑 규칙으로 light·dark 계열 변수와 `[data-color="<이름>"]` 규칙을 담는다.
+ * @packageDocumentation
+ */
+import { ColorStep } from "./color.js";
+import { ColorSlot, SlotOverrides, SlotRule, SlotStep } from "./color-slot.js";
+import { ColorContrastResult, ColorContrastRule } from "./contrast.js";
+import { ThemeName } from "./semantic.js";
+/** 50~950의 11단계 스케일. 값은 `#rrggbb` hex다. */
+export type ColorScale = Readonly<Record<ColorStep, string>>;
+/** `defineColorFamily`에 넘기는 값 */
+export interface ColorFamilyInput<Name extends string> {
+  /** 색 이름. `data-color`와 변수 이름(`--tide-<이름>-solid`)에 쓴다. 소문자, 숫자, `-`만 쓴다. */
+  readonly name: Name;
+  /** 11단계 스케일 전체 */
+  readonly scale: ColorScale;
+  /** 매핑 규칙에서 덮어쓸 슬롯 값. 예: 밝은 계열의 `on-solid`를 `{ light: 950, dark: 950 }`으로 */
+  readonly overrides?: SlotOverrides;
+}
+/** 검증을 마친 앱 색 계열 */
+export interface ColorFamilyDefinition<Name extends string = string> {
+  readonly name: Name;
+  readonly scale: ColorScale;
+  readonly overrides: SlotOverrides;
+}
+/**
+ * 앱 브랜드 색 계열을 정의한다. 이름, 스케일, 덮어쓸 값이 올바른지 확인하고 그대로 돌려준다.
+ *
+ * ```ts
+ * // brand.ts
+ * import { defineColorFamily } from "@tide-tds/foundation/color-family";
+ *
+ * export default defineColorFamily({
+ *   name: "brand",
+ *   scale: { 50: "#f5f3ff", 100: "#ede9fe", ... 950: "#2e1065" },
+ * });
+ * ```
+ *
+ * @throws 이름이 Tide 색 이름과 겹치거나, 스케일 단계가 빠졌거나, hex가 `#rrggbb`가 아니면
+ */
+export declare function defineColorFamily<const Name extends string>(input: ColorFamilyInput<Name>): ColorFamilyDefinition<Name>;
+/** 앱 계열의 Theme별 슬롯 hex */
+export declare function colorFamilySlotHex(family: ColorFamilyDefinition): Record<ThemeName, Record<ColorSlot, string>>;
+/** 앱 계열을 Tide와 같은 대비 쌍 규칙으로 light·dark에서 검사한다. 미달이면 `pass`가 false다. */
+export declare function checkColorFamily(family: ColorFamilyDefinition): ColorContrastResult[];
+/**
+ * 앱 계열의 CSS. Primitive 변수, light·dark 계열 변수, `[data-color]` 규칙을 담는다.
+ * Tide CSS(`@tide-tds/components/styles.css` 또는 foundation CSS) 다음에 불러온다.
+ */
+export declare function colorFamilyCss(families: readonly ColorFamilyDefinition[]): string;
+export type { ColorContrastResult, ColorContrastRule, ColorSlot, SlotOverrides, SlotRule, SlotStep };

package/dist/color-family.js

@@ -0,0 +1,112 @@
+import { color } from "./color.js";
+import { tideColorNames } from "./color-name.js";
+import { dataColorRule, familyThemeDeclarations, primitiveVar } from "./color-css.js";
+import { colorSlots, resolveSlotSteps, slotPrimitive } from "./color-slot.js";
+import { checkColorContrast } from "./contrast.js";
+
+// src/color-family.ts
+/**
+* `@tide-tds/foundation/color-family`: 앱이 자기 브랜드 색 계열을 더하는 API.
+*
+* 앱은 `defineColorFamily`로 11단계 스케일을 정의하고, `tide-color build <파일>`로 CSS를 만든다.
+* CSS는 Tide 계열과 같은 매핑 규칙으로 light·dark 계열 변수와 `[data-color="<이름>"]` 규칙을 담는다.
+* @packageDocumentation
+*/
+const steps = Object.keys(color.blue).map(Number);
+const reservedNames = /* @__PURE__ */ new Set([
+	...tideColorNames,
+	"accent",
+	"white",
+	"black",
+	"color",
+	"bg",
+	"text",
+	"border",
+	"outline",
+	"font",
+	"rounded",
+	"shadow",
+	"duration",
+	"ease",
+	"z",
+	"focus"
+]);
+function isSlotStep(value) {
+	return value === "white" || value === "black" || steps.includes(value);
+}
+/**
+* 앱 브랜드 색 계열을 정의한다. 이름, 스케일, 덮어쓸 값이 올바른지 확인하고 그대로 돌려준다.
+*
+* ```ts
+* // brand.ts
+* import { defineColorFamily } from "@tide-tds/foundation/color-family";
+*
+* export default defineColorFamily({
+*   name: "brand",
+*   scale: { 50: "#f5f3ff", 100: "#ede9fe", ... 950: "#2e1065" },
+* });
+* ```
+*
+* @throws 이름이 Tide 색 이름과 겹치거나, 스케일 단계가 빠졌거나, hex가 `#rrggbb`가 아니면
+*/
+function defineColorFamily(input) {
+	const { name, scale, overrides = {} } = input;
+	if (!/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/.test(name)) throw new Error(`색 이름은 소문자로 시작하는 kebab-case여야 한다: "${name}"`);
+	if (reservedNames.has(name)) throw new Error(`"${name}"은 Tide가 쓰는 이름이라 앱 색 계열 이름으로 쓸 수 없다.`);
+	for (const step of steps) {
+		const hex = scale[step];
+		if (typeof hex !== "string" || !/^#[0-9a-f]{6}$/i.test(hex)) throw new Error(`${name}-${step}: #rrggbb hex가 아니다(${String(hex)})`);
+	}
+	const extraSteps = Object.keys(scale).filter((step) => !steps.includes(Number(step)));
+	if (extraSteps.length > 0) throw new Error(`${name}: 스케일에 없는 단계가 있다(${extraSteps.join(", ")})`);
+	for (const [slot, rule] of Object.entries(overrides)) {
+		if (!colorSlots.includes(slot)) throw new Error(`${name}: 없는 슬롯을 덮어썼다(${slot})`);
+		for (const [theme, step] of Object.entries(rule ?? {})) if (theme !== "light" && theme !== "dark" || !isSlotStep(step)) throw new Error(`${name}: ${slot}.${theme} 값이 단계(50~950, white, black)가 아니다`);
+	}
+	return {
+		name,
+		scale: Object.fromEntries(steps.map((step) => [step, scale[step].toLowerCase()])),
+		overrides
+	};
+}
+/** 앱 계열의 슬롯별 단계(규칙 + 덮어쓸 값) */
+function slotSteps(family) {
+	return resolveSlotSteps(family.overrides);
+}
+/** 앱 계열의 Theme별 슬롯 hex */
+function colorFamilySlotHex(family) {
+	const resolved = slotSteps(family);
+	const hex = (step) => typeof step === "number" ? family.scale[step] : color[step];
+	return {
+		light: Object.fromEntries(colorSlots.map((slot) => [slot, hex(resolved[slot].light)])),
+		dark: Object.fromEntries(colorSlots.map((slot) => [slot, hex(resolved[slot].dark)]))
+	};
+}
+/** 앱 계열을 Tide와 같은 대비 쌍 규칙으로 light·dark에서 검사한다. 미달이면 `pass`가 false다. */
+function checkColorFamily(family) {
+	return checkColorContrast(colorFamilySlotHex(family));
+}
+/**
+* 앱 계열의 CSS. Primitive 변수, light·dark 계열 변수, `[data-color]` 규칙을 담는다.
+* Tide CSS(`@tide-tds/components/styles.css` 또는 foundation CSS) 다음에 불러온다.
+*/
+function colorFamilyCss(families) {
+	const themeBlock = (theme) => families.flatMap((family) => familyThemeDeclarations(family.name, slotSteps(family), theme));
+	return [
+		":root {",
+		...families.flatMap((family) => steps.map((step) => `  ${primitiveVar(slotPrimitive(family.name, step))}: ${family.scale[step]};`)),
+		"}",
+		"",
+		":root,\n[data-theme=\"light\"] {",
+		...themeBlock("light"),
+		"}",
+		"",
+		"[data-theme=\"dark\"] {",
+		...themeBlock("dark"),
+		"}",
+		"",
+		...families.flatMap((family) => [dataColorRule(family.name), ""])
+	].join("\n");
+}
+
+export { checkColorFamily, colorFamilyCss, colorFamilySlotHex, defineColorFamily };

package/dist/color-name.d.ts

@@ -0,0 +1,40 @@
+import { ColorFamily } from "./color.js";
+import { ColorSlot } from "./color-slot.js";
+import { SemanticColorName, ThemeName, ThemedColor, TideRole } from "./semantic.js";
+/** Tide에 들어 있는 색 이름. 앱이 augmentation으로 더한 이름은 들어 있지 않다. */
+export type TideColor = TideRole | ColorFamily;
+/**
+ * Role 이름 목록(neutral, primary, success, warning, danger, info 순서).
+ * @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+ */
+export declare const roleNames: readonly TideRole[];
+/**
+ * Tide 색 계열 목록(`color`의 11단계 계열 순서).
+ * @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+ */
+export declare const colorFamilyNames: readonly ColorFamily[];
+/**
+ * Tide 색 이름 목록. Role 다음에 색 계열이 온다.
+ * @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+ */
+export declare const tideColorNames: readonly TideColor[];
+/**
+ * Tide Role인지 확인한다. 앱 Role은 Role Token이 없어서 false다.
+ * @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+ */
+export declare function isRole(name: string): name is TideRole;
+/**
+ * Role 슬롯이 가리키는 Semantic Token. 예: (`primary`, `solid`) → `bg-primary-solid`, (`neutral`, `text`) → `text-default`
+ * @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+ */
+export declare function roleSlotToken(role: TideRole, slot: ColorSlot): SemanticColorName;
+/**
+ * Tide 색 이름 하나의 슬롯별 값(Theme별 Primitive).
+ * @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+ */
+export declare function colorSlotValues(name: TideColor): Record<ColorSlot, ThemedColor>;
+/**
+ * Tide 색 이름 하나의 슬롯별 hex(Theme 하나).
+ * @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+ */
+export declare function colorSlotHex(name: TideColor, theme: ThemeName): Record<ColorSlot, string>;

package/dist/color-name.js

@@ -0,0 +1,61 @@
+import { color } from "./color.js";
+import { colorSlots, familySlotSteps, slotPrimitive } from "./color-slot.js";
+import { colorValueHex, roleFamily, roleSharedSlots, semanticEntries } from "./semantic.js";
+
+// src/color-name.ts
+/**
+* Role 이름 목록(neutral, primary, success, warning, danger, info 순서).
+* @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+*/
+const roleNames = Object.keys(roleFamily);
+/**
+* Tide 색 계열 목록(`color`의 11단계 계열 순서).
+* @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+*/
+const colorFamilyNames = Object.keys(color).filter((name) => typeof color[name] !== "string");
+/**
+* Tide 색 이름 목록. Role 다음에 색 계열이 온다.
+* @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+*/
+const tideColorNames = [...roleNames, ...colorFamilyNames];
+/**
+* Tide Role인지 확인한다. 앱 Role은 Role Token이 없어서 false다.
+* @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+*/
+function isRole(name) {
+	return Object.hasOwn(roleFamily, name);
+}
+/**
+* Role 슬롯이 가리키는 Semantic Token. 예: (`primary`, `solid`) → `bg-primary-solid`, (`neutral`, `text`) → `text-default`
+* @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+*/
+function roleSlotToken(role, slot) {
+	if (slot === "on-solid") return "text-on-solid";
+	if (slot === "text" || slot === "border") return roleSharedSlots[role]?.[slot] ?? `${slot}-${role}`;
+	return `bg-${role}-${slot}`;
+}
+/**
+* Tide 색 이름 하나의 슬롯별 값(Theme별 Primitive).
+* @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+*/
+function colorSlotValues(name) {
+	if (isRole(name)) {
+		const entries = new Map(semanticEntries().map((entry) => [entry.className, entry.value]));
+		return Object.fromEntries(colorSlots.map((slot) => [slot, entries.get(roleSlotToken(name, slot))]));
+	}
+	const steps = familySlotSteps(name);
+	return Object.fromEntries(colorSlots.map((slot) => [slot, {
+		light: slotPrimitive(name, steps[slot].light),
+		dark: slotPrimitive(name, steps[slot].dark)
+	}]));
+}
+/**
+* Tide 색 이름 하나의 슬롯별 hex(Theme 하나).
+* @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+*/
+function colorSlotHex(name, theme) {
+	const values = colorSlotValues(name);
+	return Object.fromEntries(colorSlots.map((slot) => [slot, colorValueHex(values[slot][theme])]));
+}
+
+export { colorFamilyNames, colorSlotHex, colorSlotValues, isRole, roleNames, roleSlotToken, tideColorNames };

package/dist/color-slot.d.ts

@@ -0,0 +1,80 @@
+import { ColorFamily, ColorStep } from "./color.js";
+/**
+ * 색 계열 변수 묶음의 슬롯. CSS에서는 `--tide-<색 이름>-<슬롯>`과 `--tide-accent-<슬롯>`으로 나간다.
+ */
+export declare const colorSlots: readonly ["solid", "solid-hover", "solid-active", "subtle", "subtle-hover", "subtle-active", "text", "border", "on-solid"];
+/** 색 계열 변수 묶음의 슬롯 이름. 예: `solid`, `subtle-hover`, `on-solid` */
+export type ColorSlot = (typeof colorSlots)[number];
+/** 배경 슬롯(solid 3단계, subtle 3단계) */
+export type BackgroundSlot = Exclude<ColorSlot, "text" | "border" | "on-solid">;
+/** 슬롯이 가리키는 값: 그 계열 스케일의 단계, 또는 `white`·`black` */
+export type SlotStep = ColorStep | "white" | "black";
+/** Theme별 슬롯 값 */
+export interface SlotRule {
+  readonly light: SlotStep;
+  readonly dark: SlotStep;
+}
+/** 계열마다 덮어쓸 슬롯 값. Theme 하나만 덮어써도 된다. */
+export type SlotOverrides = { readonly [Slot in ColorSlot]?: Partial<SlotRule>; };
+/**
+ * 슬롯 매핑 규칙.
+ * @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+ */
+export declare const slotRule: {
+  readonly solid: {
+    readonly light: 600;
+    readonly dark: 600;
+  };
+  readonly "solid-hover": {
+    readonly light: 700;
+    readonly dark: 700;
+  };
+  readonly "solid-active": {
+    readonly light: 800;
+    readonly dark: 800;
+  };
+  readonly subtle: {
+    readonly light: 50;
+    readonly dark: 950;
+  };
+  readonly "subtle-hover": {
+    readonly light: 100;
+    readonly dark: 900;
+  };
+  readonly "subtle-active": {
+    readonly light: 200;
+    readonly dark: 800;
+  };
+  readonly text: {
+    readonly light: 800;
+    readonly dark: 200;
+  };
+  readonly border: {
+    readonly light: 600;
+    readonly dark: 400;
+  };
+  readonly "on-solid": {
+    readonly light: "white";
+    readonly dark: "white";
+  };
+};
+/**
+ * Tide 계열별 덮어쓸 값.
+ * @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+ */
+export declare const familyOverrides: {};
+/**
+ * 규칙에 덮어쓸 값을 얹은 슬롯별 단계.
+ * @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+ */
+export declare function resolveSlotSteps(...overrides: (SlotOverrides | undefined)[]): Record<ColorSlot, SlotRule>;
+/**
+ * 슬롯 값을 Primitive 이름으로 바꾼다. 예: (`blue`, 600) → `blue-600`, (`blue`, `white`) → `white`
+ * @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+ */
+export declare function slotPrimitive(family: string, step: SlotStep): string;
+/**
+ * Tide 계열 하나의 슬롯별 단계(규칙 + 그 계열의 덮어쓸 값).
+ * @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+ */
+export declare function familySlotSteps(family: ColorFamily): Record<ColorSlot, SlotRule>;

package/dist/color-slot.js

@@ -0,0 +1,90 @@
+// src/color-slot.ts
+/**
+* 색 계열 변수 묶음의 슬롯. CSS에서는 `--tide-<색 이름>-<슬롯>`과 `--tide-accent-<슬롯>`으로 나간다.
+*/
+const colorSlots = [
+	"solid",
+	"solid-hover",
+	"solid-active",
+	"subtle",
+	"subtle-hover",
+	"subtle-active",
+	"text",
+	"border",
+	"on-solid"
+];
+/**
+* 슬롯 매핑 규칙.
+* @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+*/
+const slotRule = {
+	solid: {
+		light: 600,
+		dark: 600
+	},
+	"solid-hover": {
+		light: 700,
+		dark: 700
+	},
+	"solid-active": {
+		light: 800,
+		dark: 800
+	},
+	subtle: {
+		light: 50,
+		dark: 950
+	},
+	"subtle-hover": {
+		light: 100,
+		dark: 900
+	},
+	"subtle-active": {
+		light: 200,
+		dark: 800
+	},
+	text: {
+		light: 800,
+		dark: 200
+	},
+	border: {
+		light: 600,
+		dark: 400
+	},
+	"on-solid": {
+		light: "white",
+		dark: "white"
+	}
+};
+/**
+* Tide 계열별 덮어쓸 값.
+* @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+*/
+const familyOverrides = {};
+/**
+* 규칙에 덮어쓸 값을 얹은 슬롯별 단계.
+* @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+*/
+function resolveSlotSteps(...overrides) {
+	return Object.fromEntries(colorSlots.map((slot) => {
+		return [slot, overrides.reduce((current, override) => ({
+			...current,
+			...override?.[slot]
+		}), slotRule[slot])];
+	}));
+}
+/**
+* 슬롯 값을 Primitive 이름으로 바꾼다. 예: (`blue`, 600) → `blue-600`, (`blue`, `white`) → `white`
+* @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+*/
+function slotPrimitive(family, step) {
+	return typeof step === "number" ? `${family}-${step}` : step;
+}
+/**
+* Tide 계열 하나의 슬롯별 단계(규칙 + 그 계열의 덮어쓸 값).
+* @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+*/
+function familySlotSteps(family) {
+	return resolveSlotSteps(familyOverrides[family]);
+}
+
+export { colorSlots, familyOverrides, familySlotSteps, resolveSlotSteps, slotPrimitive, slotRule };

package/dist/color.d.ts

@@ -80,13 +80,13 @@ export declare const color: {
     readonly 950: "#002f3d";
   };
 };
-type Color = typeof color;
+type ColorTable = typeof color;
 /** 11단계 스케일을 가진 계열 이름. 예: `blue` */
-export type ColorFamily = { [Key in keyof Color]: Color[Key] extends string ? never : Key; }[keyof Color];
+export type ColorFamily = { [Key in keyof ColorTable]: ColorTable[Key] extends string ? never : Key; }[keyof ColorTable];
 /** 스케일 단계. 50~950의 11단계 */
-export type ColorStep = keyof Color["blue"];
+export type ColorStep = keyof ColorTable["blue"];
 /** Primitive 이름. 예: `blue-600`, `white` */
-export type PrimitiveColorName = { [Key in keyof Color]: Color[Key] extends string ? Key : never; }[keyof Color] | { [Family in ColorFamily]: `${Family}-${ColorStep}`; }[ColorFamily];
+export type PrimitiveColorName = { [Key in keyof ColorTable]: ColorTable[Key] extends string ? Key : never; }[keyof ColorTable] | { [Family in ColorFamily]: `${Family}-${ColorStep}`; }[ColorFamily];
 /**
  * Primitive 이름을 정본 hex로 바꾼다.
  * @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).

package/dist/contrast.d.ts

@@ -1,4 +1,5 @@
-import { SemanticColorName } from "./semantic.js";
+import { ColorSlot } from "./color-slot.js";
+import { SemanticColorName, ThemeName } from "./semantic.js";
 /** 함께 쓰이는 글자(또는 경계)와 배경의 짝. Utility class 이름으로 적는다. */
 export interface ContrastPair {
   readonly foreground: SemanticColorName;
@@ -11,15 +12,40 @@ export interface ContrastExclusion {
   readonly token: SemanticColorName;
   readonly reason: string;
 }
+declare const surfaces: readonly ["bg-canvas", "bg-surface", "bg-raised"];
 export declare const contrastPairs: readonly ContrastPair[];
 /**
  * 대비 검사에서 뺀 Semantic Token과 이유.
  * @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
  */
 export declare const contrastExclusions: readonly ContrastExclusion[];
+/** 색 이름 하나에서 함께 쓰는 슬롯 짝. 배경은 같은 색의 슬롯이거나 표면 층 Token이다. */
+export interface ColorContrastRule {
+  readonly foreground: ColorSlot;
+  readonly background: ColorSlot | (typeof surfaces)[number];
+  /** 텍스트는 4.5, UI 경계는 3 */
+  readonly minRatio: 4.5 | 3;
+}
+/**
+ * 색 이름 하나의 대비 쌍 규칙.
+ * @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+ */
+export declare const colorContrastRules: readonly ColorContrastRule[];
+/** 대비 쌍 규칙 하나를 Theme 하나에서 검사한 결과 */
+export interface ColorContrastResult extends ColorContrastRule {
+  readonly theme: ThemeName;
+  readonly ratio: number;
+  readonly pass: boolean;
+}
+/**
+ * 색 이름 하나의 슬롯 hex로 대비 쌍 규칙을 light·dark에서 검사한다. 표면 층은 Tide Token 값을 쓴다.
+ * @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
+ */
+export declare function checkColorContrast(slotHex: Readonly<Record<ThemeName, Readonly<Record<ColorSlot, string>>>>): ColorContrastResult[];
 /**
  * 두 색의 WCAG 2.x 대비비(1~21). 순서는 상관없다.
  * 반투명 색(8자리 hex)은 받지 않는다. 대비 검사에서 overlay와 shadow는 제외한다.
  * @internal `@tide-tds/foundation/internal` 전용. 앱 개발자용 공개 계약이 아니다(문서 앱·빌드 스크립트·테스트용).
  */
-export declare function contrastRatio(foreground: string, background: string): number;
+export declare function contrastRatio(foreground: string, background: string): number;
+export {};