@conscience-technology/ctds 0.4.1 → 0.4.3

package/assets/components/Hint/Hint.module.css

@@ -0,0 +1,75 @@
+/* Hint ──────────────────────────────────────────────────────
+   흐름 속 참고 한 줄~두 줄. 배경·테두리 없음, 아이콘 + muted 텍스트.
+
+   두 줄 넘어가면 둘째 줄 이후가 아이콘 폭만큼 들여쓰기 되도록
+   hanging indent 패턴 사용:
+     padding-left:  아이콘 폭 + gap
+     text-indent:  -(아이콘 폭 + gap)   → 첫 줄만 아이콘 자리로 되돌림
+   아이콘은 inline-flex + vertical-align으로 첫 줄 line-box 안에 걸침. */
+.root {
+  display: block;
+  color: var(--hint-fg, var(--fg-muted));
+  font-family: var(--font-sans);
+  line-height: 1.6;
+  /* 저자가 넣은 "\n" 또는 JSX 안 줄 바꿈을 실제 줄 바꿈으로 보존 —
+     긴 문장이 어중간한 자리에서 자동 줄 바꿈되지 않도록 저자 호흡을 존중. */
+  white-space: pre-line;
+}
+
+.icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  /* 아이콘 중앙을 x-height 중앙에 맞춤 — text-bottom은 디센더 라인 기준이라
+     살짝 아래로 처짐. -0.125em 보정으로 캡 하이트 중앙에 정렬. */
+  vertical-align: middle;
+  transform: translateY(-0.08em);
+  color: var(--hint-accent, var(--fg-muted));
+  margin-inline-end: var(--space-1_5);
+}
+
+/* Size ─────────────────────────────────────────────────────── */
+.sm {
+  font-size: var(--text-sm);
+  padding-inline-start: calc(var(--icon-size-sm) + var(--space-1_5));
+  text-indent: calc(-1 * (var(--icon-size-sm) + var(--space-1_5)));
+}
+.sm .icon > svg {
+  width: var(--icon-size-sm);
+  height: var(--icon-size-sm);
+}
+
+.md {
+  font-size: var(--text-base);
+  padding-inline-start: calc(var(--icon-size-md) + var(--space-1_5));
+  text-indent: calc(-1 * (var(--icon-size-md) + var(--space-1_5)));
+}
+.md .icon > svg {
+  width: var(--icon-size-md);
+  height: var(--icon-size-md);
+}
+
+/* Tones ────────────────────────────────────────────────────
+   neutral: 아이콘·텍스트 모두 fg-muted (기본).
+   그 외 tone: 아이콘만 톤 색, 텍스트는 muted 유지 — Callout보다 더 조용함.
+   필요하면 Callout으로 승격. */
+.neutral {
+  --hint-fg: var(--fg-muted);
+  --hint-accent: var(--fg-muted);
+}
+.brand {
+  --hint-fg: var(--fg-muted);
+  --hint-accent: var(--primary);
+}
+.success {
+  --hint-fg: var(--fg-muted);
+  --hint-accent: var(--success);
+}
+.warning {
+  --hint-fg: var(--fg-muted);
+  --hint-accent: var(--warning);
+}
+.destructive {
+  --hint-fg: var(--fg-muted);
+  --hint-accent: var(--destructive);
+}

package/assets/components/Hint/Hint.tsx

@@ -0,0 +1,75 @@
+"use client";
+
+import { forwardRef, type HTMLAttributes, type ReactNode } from "react";
+
+import { Icon, type IconName } from "../Icon";
+
+import styles from "./Hint.module.css";
+
+/**
+ * Hint — 흐름 속에 스며드는 참고 한 줄~두 줄.
+ * 아이콘 하나 + muted 텍스트. 액션·배경·테두리 없음.
+ *
+ * 아이콘 수직 정렬은 flex가 아니라 line-box에 흘려넣고,
+ * 둘째 줄은 hanging indent로 아이콘 폭만큼 들여쓰기 — Hint.module.css 참고.
+ *
+ * **아이콘 + 텍스트 한 줄짜리 안내는 반드시 이 컴포넌트 경유.**
+ * `<Icon /> + <span>` 수제 조립 금지 — [[feedback_no_hand_rolled_components]].
+ */
+export type HintSize = "sm" | "md";
+export type HintTone =
+  | "neutral"
+  | "brand"
+  | "success"
+  | "warning"
+  | "destructive";
+
+export interface HintProps extends HTMLAttributes<HTMLSpanElement> {
+  icon?: IconName;
+  size?: HintSize;
+  /** 아이콘·텍스트 공통 톤. 기본 neutral(muted). 톤 색이 필요하면 brand/success/warning/destructive. */
+  tone?: HintTone;
+  children?: ReactNode;
+}
+
+const sizeClass: Record<HintSize, string> = {
+  sm: styles.sm,
+  md: styles.md,
+};
+
+const toneClass: Record<HintTone, string> = {
+  neutral: styles.neutral,
+  brand: styles.brand,
+  success: styles.success,
+  warning: styles.warning,
+  destructive: styles.destructive,
+};
+
+const Hint = forwardRef<HTMLSpanElement, HintProps>(
+  (
+    { className, icon = "info", size = "sm", tone = "neutral", children, ...rest },
+    ref,
+  ) => {
+    const rootClass = [
+      styles.root,
+      sizeClass[size],
+      toneClass[tone],
+      className ?? "",
+    ]
+      .filter(Boolean)
+      .join(" ");
+
+    return (
+      <span ref={ref} className={rootClass} {...rest}>
+        <span className={styles.icon} aria-hidden>
+          <Icon name={icon} />
+        </span>
+        {children}
+      </span>
+    );
+  },
+);
+
+Hint.displayName = "Hint";
+
+export { Hint };

package/assets/components/Hint/index.ts

@@ -0,0 +1,2 @@
+export { Hint } from "./Hint";
+export type { HintProps, HintSize, HintTone } from "./Hint";

package/assets/components/_data.ts

@@ -559,6 +559,7 @@ export const componentSlugs: Record<string, string> = {
   "Dropdown Menu": "overlay/dropdown-menu",
   Disclosure: "overlay/disclosure",
   Callout: "feedback/callout",
+  Hint: "feedback/hint",
   Modal: "feedback/modal",
   Drawer: "feedback/drawer",
   Toast: "feedback/toast",
@@ -640,7 +641,7 @@ export const components: { id: string; title: string; items: string[] }[] = [
     title: "Feedback",
     items: [
       "Modal", "Alert Dialog", "Drawer", "Popover", "Hover Card",
-      "Toast", "Callout", "Progress Bar", "Spinner",
+      "Toast", "Callout", "Hint", "Progress Bar", "Spinner",
     ],
   },
   {

package/assets/components/index.ts

@@ -34,6 +34,7 @@ export * from "./FileIcon";
 export * from "./FilterButton";
 export * from "./GalleryItem";
 export * from "./GeneratedImage";
+export * from "./Hint";
 export * from "./Icon";
 export * from "./IconButton";
 export * from "./IdentityButton";

package/assets/components/tokens.css

@@ -253,7 +253,7 @@
   --fg:            oklch(0.22  var(--tone-chroma) var(--tone-hue));
   /* muted/subtle/disabled은 fg 톤의 알파 — 색 있는 배경 위에서도 자연스럽게 섞임.
      라이트: 어두운 잉크(≈0.18)를 낮은 알파로 얹음. */
-  --fg-muted:      oklch(0.18 var(--tone-chroma) var(--tone-hue) / 0.60);
+  --fg-muted:      oklch(0.18 var(--tone-chroma) var(--tone-hue) / 0.82);
   --fg-subtle:     oklch(0.18 var(--tone-chroma) var(--tone-hue) / 0.42);
   --fg-disabled:   oklch(0.18 var(--tone-chroma) var(--tone-hue) / 0.26);
   /* border는 배경 대비 알파 기반 hairline — 겹치면 자연스럽게 짙어짐.
@@ -597,7 +597,7 @@
   :root {
     --border:        oklch(0.18 var(--tone-chroma) var(--tone-hue) / 0.42);
     --border-strong: oklch(0.18 var(--tone-chroma) var(--tone-hue) / 0.60);
-    --fg-muted:      oklch(0.18 var(--tone-chroma) var(--tone-hue) / 0.82);
+    --fg-muted:      oklch(0.18 var(--tone-chroma) var(--tone-hue) / 0.92);
     --fg-subtle:     oklch(0.18 var(--tone-chroma) var(--tone-hue) / 0.66);
   }
   :root[data-mode="dark"] {
@@ -620,7 +620,7 @@
     --bg-elev-2:     #ffffff;
     --fg:            #1a1a1a;
     --fg-strong:     #0a0a0a;
-    --fg-muted:      #666666;
+    --fg-muted:      #444444;
     --fg-subtle:     #999999;
     --fg-disabled:   #c0c0c0;
     --border:        rgba(0, 0, 0, 0.08);
@@ -635,7 +635,7 @@
     --bg-elev-2:     #1f1f1f;
     --fg:            #f0f0f0;
     --fg-strong:     #ffffff;
-    --fg-muted:      #a0a0a0;
+    --fg-muted:      #b8b8b8;
     --fg-subtle:     #7a7a7a;
     --fg-disabled:   #4a4a4a;
     --border:        rgba(255, 255, 255, 0.08);
@@ -699,7 +699,7 @@
      fg-muted 알파 0.60은 다크 bg(0.20) 위에서 effective L ≈ 0.65, 콘트라스트 ≈ 3.5:1.
      WCAG AA "normal text" 4.5:1 임계 아래 — 보조 라벨·placeholder 전용.
      중요한 보조 텍스트에는 --fg를 쓸 것. prefers-contrast: more에서 자동 상향됨. */
-  --fg-muted:      oklch(0.95 var(--tone-chroma) var(--tone-hue) / 0.60);
+  --fg-muted:      oklch(0.95 var(--tone-chroma) var(--tone-hue) / 0.72);
   --fg-subtle:     oklch(0.95 var(--tone-chroma) var(--tone-hue) / 0.40);
   --fg-disabled:   oklch(0.95 var(--tone-chroma) var(--tone-hue) / 0.24);
   /* 다크 모드: fg 톤(밝은 잉크)을 낮은 알파로 얹음. */
@@ -744,7 +744,7 @@
   --bg-muted:      oklch(0.955 var(--tone-chroma) var(--tone-hue));
   --fg-strong:     oklch(0.12  var(--tone-chroma) var(--tone-hue));
   --fg:            oklch(0.22  var(--tone-chroma) var(--tone-hue));
-  --fg-muted:      oklch(0.18 var(--tone-chroma) var(--tone-hue) / 0.60);
+  --fg-muted:      oklch(0.18 var(--tone-chroma) var(--tone-hue) / 0.82);
   --fg-subtle:     oklch(0.18 var(--tone-chroma) var(--tone-hue) / 0.42);
   --fg-disabled:   oklch(0.18 var(--tone-chroma) var(--tone-hue) / 0.26);
   --border:        oklch(0.18 var(--tone-chroma) var(--tone-hue) / 0.08);

package/assets/prompts/components/hint.md

@@ -1,42 +1,58 @@
 # Hint
 
 ### 원칙
-흐름 속에 스며드는 **참고 한 줄~두 줄**. 아이콘 하나와 muted 텍스트로만 구성된 가장 가벼운 안내. 페이지 폭을 차지하지 않고, 톤도 신호도 띠지 않는다. 자리의 성격은 "이 자리에서 알아야 할 것"의 각주 — [[components/callout]]처럼 액션으로 유도하지 않고, [[recipes/page-banner]]처럼 상태를 외치지 않는다.
+흐름 속에 스며드는 **참고 한 줄~두 줄**. 아이콘 하나와 muted 텍스트로만 구성된 가장 가벼운 안내. 페이지 폭을 차지하지 않고, 자리의 성격은 "이 자리에서 알아야 할 것"의 각주 — [[components/callout]]처럼 액션으로 유도하지 않고, [[recipes/page-banner]]처럼 상태를 외치지 않는다.
+
+**아이콘 + 텍스트 조합의 모든 안내는 반드시 이 컴포넌트 경유.** 와이어프레임·페이지에 `<Icon /> + <span>`을 수제로 조립해서 "ℹ️ 어쩌구" 한 줄을 만드는 패턴 영구 금지 — Hint 하나로 통일한다. 수제 조립은 size·color·vertical-align·둘째 줄 들여쓰기가 매번 어긋나서 리듬이 깨지는 반복 함정이다 ([[feedback_no_hand_rolled_components]], [[feedback_local_derivative_over_handrolled]]).
 
 ### Do
-- 아이콘은 **1개 고정**, text는 1~2줄. 길어지면 Callout 또는 별도 블록으로.
-- 톤 색 금지 — `fg-muted` 하나만. tone·variant 축 없음.
-- 아이콘 수직 정렬은 **첫 줄 캡 하이트 중앙** — flex align-items 트릭 대신 `display: inline` + `vertical-align`로 line box 안에 흘려넣기 (내부 구현 책임).
-- 폼 필드 helper text는 [[components/form-field]]의 자체 helper를 쓴다. Hint는 **블록 단위 안내** — 폼 밖, 섹션 안 설명.
+- **아이콘 + 텍스트 한 줄짜리 안내는 전부 Hint**. 폼 helper, 섹션 각주, 리스트 하단 주석 등.
+- 아이콘은 **1개 고정**, 자유롭게 선택 (`info` `question` `brackets-square` `clock` `shield-check` 등 상황에 맞게).
+- 텍스트는 1~2줄. 두 줄 넘어가면 둘째 줄은 아이콘 폭만큼 자동 들여쓰기 (hanging indent — 컴포넌트가 처리).
+- **줄 바꿈이 애매하면 저자가 호흡 단위로 끊어준다.** 긴 문장이 어중간한 자리에서 자동 줄 바꿈되면 리듬이 깨짐. 문장이 두 호흡으로 나뉘면 `.` 바로 뒤에서 사람이 `\n`을 넣어 **문장 단위로** 끊어라 (JSX에서는 중괄호 안 템플릿 리터럴 또는 두 `<Hint>` 분리). 자동 줄 바꿈에 맡기면 "···하고 승인한 / 뒤 실행을" 같은 어색한 지점에서 꺾인다.
+- 색은 **neutral이 기본**. 톤 신호가 꼭 필요할 때만 brand/success/warning/destructive — 아이콘 색만 바뀌고 텍스트는 muted 유지 ([[components/callout]]보다 조용).
+- 아이콘 수직 정렬은 **첫 줄 캡 하이트 중앙** — flex align-items 트릭 대신 `vertical-align: text-bottom`으로 line box 안에 흘려넣기 (내부 구현 책임).
 
 ### Don't
+- [HARD] **아이콘 + 텍스트를 수제 조립 금지** — `<span><Icon/> …</span>`, `<div className="hint"><Icon/>…</div>` 전부 금지. 반드시 `<Hint>` 사용.
 - [HARD] 액션 버튼을 넣지 않는다 — 액션이 필요하면 [[components/callout]].
-- [HARD] 톤 신호(warning·destructive·success 배경)를 띠지 않는다 — 신호가 필요하면 [[components/callout]] 또는 [[recipes/page-banner]].
-- [HARD] 배경 + 테두리 금지 ([[PRINCIPLES]] §5b). Hint는 **배경·테두리 둘 다 없음**이 기본.
+- [HARD] 배경·테두리 둘 다 금지 ([[PRINCIPLES]] §5b). Hint는 **배경·테두리 둘 다 없음**이 기본.
+- [HARD] 톤 신호를 띠는 **배경**은 금지 — 톤이 필요하면 아이콘 색만 (`tone="warning"`). 배경까지 가야 하면 [[components/callout]].
 - [SOFT] 3줄 이상 텍스트 금지 — 길어지면 섹션 자체가 "안내 블록"이 돼야 함. Hint는 각주 성격 유지.
 - [SOFT] 리스트·강조 같은 서식 금지. 평문만.
+- [SOFT] 폼 필드 helper text는 [[components/form-field]]의 자체 helper를 쓴다. Hint는 **폼 밖, 섹션 안 설명** 전용.
 
 ### Fallback
-아이콘이 애매하면 `info` 또는 `question`. 자리가 코드/기술 설명이면 `brackets-square`.
+아이콘이 애매하면 `info`. 질문·도움말이면 `question`, 코드·기술 설명이면 `brackets-square`.
 
 ### 관련
-- [[components/callout]] — 톤·액션 있는 안내 블록. Hint는 액션 없음.
+- [[components/callout]] — 톤·액션·배경 있는 안내 블록. Hint는 액션 없음, 배경 없음.
 - [[recipes/page-banner]] — 페이지 폭 상태 바. Hint는 흐름 속 각주.
 - [[components/form-field]] — 폼 helper text 전용 자리.
-- [[tokens/color]] — fg-muted
+- [[tokens/color]] — fg-muted, primary/success/warning/destructive
 - [[tokens/typography]] — text-sm 기본, line-height 1.6
 
 ### Props 시그니처
 ```tsx
 <Hint
-  icon={IconName}        // default: "info"
-  size="sm | md"         // default: "sm" (앱 리듬 기본)
+  icon={IconName}                        // default: "info" — 자유롭게
+  size="sm | md"                         // default: "sm"
+  tone="neutral | brand | success | warning | destructive"  // default: "neutral"
 >{children}</Hint>
 ```
 
 ### Variant 매트릭스
-variant 축 **없음**. Hint는 "참고 각주" 성격 하나만 — 톤·강도 다 제거해서 가장 조용함.
+tone은 **아이콘 색만** 스왑. 텍스트는 전 톤에서 fg-muted 고정 — Callout보다 조용한 성격을 유지한다.
+
+| tone | 아이콘 색 | 자리 |
+|---|---|---|
+| `neutral` | `fg-muted` | 기본. 그냥 각주. |
+| `brand` | `primary` | 자리의 핵심 기능을 가리키는 각주. |
+| `success` | `success` | 완료·안전 상태 각주. |
+| `warning` | `warning` | 주의 각주 (배경 띠까지 가면 Callout). |
+| `destructive` | `destructive` | 되돌릴 수 없는 결과 각주. |
 
+### Size 가이드
 | size | font-size | line-height | icon size | 자리 |
 |---|---|---|---|---|
 | `sm` | `--text-sm` | 1.6 | 16 | 섹션 안 각주 (기본) |
@@ -44,14 +60,30 @@ variant 축 **없음**. Hint는 "참고 각주" 성격 하나만 — 톤·강도
 
 ### 조합 예시
 ```tsx
+// 기본 각주
+<Hint>최근 30일 활동만 표시됩니다.</Hint>
+
+// 아이콘 자유 선택
+<Hint icon="clock">업로드한 파일은 24시간 동안 임시 저장소에 남아 있습니다.</Hint>
+
+// 긴 설명 — 저자가 문장 단위로 호흡을 끊어줌 (자동 줄 바꿈 금지)
 <Hint icon="brackets-square">
-  문서 등록은 추출·정리까지 자동 처리합니다. AI 작업 계획을 요청하고 승인한 뒤 실행을 요청하면,
-  연결된 실행기가 코드 변경안과 테스트 결과를 작성합니다.
+  {`문서 등록은 추출과 정리까지 자동 처리합니다.
+AI 작업 계획을 요청하고 승인한 뒤 실행을 요청하면, 연결된 실행기가 코드 변경안과 테스트 결과를 작성합니다.`}
+</Hint>
+
+// 톤 신호 — 아이콘 색만
+<Hint icon="shield-check" tone="success">
+  2단계 인증이 활성화되어 있습니다.
+</Hint>
+
+<Hint icon="warning" tone="warning">
+  이 작업은 되돌릴 수 없습니다.
 </Hint>
 ```
 
 ### 구현 노트 (벤더 코드에만 적용)
-아이콘 수직 정렬이 **반복 함정**이라 명시:
-- flex `align-items: center/flex-start` + `margin-top` 보정 조합은 **금지** — line-height 바뀔 때마다 어긋남
-- 내부 구현은 **`display: inline` + `vertical-align: text-bottom`** (또는 유사 line-box 정렬) 조합으로 자동 정렬
-- line-height는 `1.6` 고정 (muted 다줄 가독성 — [[tokens/spacing]] "텍스트 gap·line-height" 기본 1.5보다 한 눈금 높음)
+- 아이콘 수직 정렬은 **`display: inline-flex` + `vertical-align: text-bottom`** 조합으로 line box 안에 자동 정렬. flex `align-items` + `margin-top` 보정 조합은 **금지** (line-height 바뀔 때마다 어긋남).
+- 둘째 줄 들여쓰기는 **hanging indent** 패턴: `padding-inline-start: icon + gap` + `text-indent: -(icon + gap)`.
+- line-height는 `1.6` 고정 (muted 다줄 가독성).
+- tone은 `--hint-accent` CSS 변수 하나만 스왑 — `--hint-fg`는 전 톤에서 `--fg-muted` 유지.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@conscience-technology/ctds",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "CTDS — 하이브리드 디자인 시스템 설치 · 온보딩 CLI (shadcn식 코드 생성기)",
   "type": "module",
   "sideEffects": [