@iyulab/components 1.22.0 → 1.23.0

package/dist/components/skeleton/USkeleton.styles.js

@@ -52,6 +52,70 @@ var styles = css`
     transform: translateX(-100%);
   }
 
+  /* === 여러 줄(lines) ===
+     기본(단일 막대)에서는 :host 자신이 막대다 — 그 모양을 바꾸지 않는다. lines 가 붙었을
+     때만 호스트가 «막대들의 통»이 되고, 색·모양·효과는 각 .line 이 받는다.
+     ⚠마지막 줄을 짧게 만드는 것은 장식이 아니라 신호다 — 문단의 끝을 그렇게 읽는다. */
+  :host([lines]) {
+    display: flex;
+    flex-direction: column;
+    gap: var(--skeleton-line-gap, 0.5em);
+    height: auto;
+    background-color: transparent;
+    animation: none;
+    overflow: visible;
+  }
+  :host([lines])::after {
+    content: none;
+  }
+  :host([lines]) .line {
+    height: var(--skeleton-height);
+    background-color: var(--skeleton-color);
+    border-radius: inherit;
+  }
+  :host([lines]) .line:last-child {
+    width: var(--skeleton-last-line-width, 60%);
+  }
+  :host([lines][effect="pulse"]) .line {
+    animation: pulse 1.5s ease-in-out infinite;
+  }
+  :host([lines][effect="shimmer"]) .line {
+    position: relative;
+    overflow: hidden;
+  }
+  :host([lines][effect="shimmer"]) .line::after {
+    content: '';
+    position: absolute;
+    inset: 0;
+    background: linear-gradient(
+      90deg,
+      transparent,
+      var(--skeleton-shimmer-color),
+      transparent
+    );
+    animation: shimmer 1.5s infinite;
+    transform: translateX(-100%);
+  }
+
+  /* ★**장식만 멈춘다.**
+     시트의 reduce 규칙은 지속시간 축(--u-duration-*)을 0 으로 누르는 방식이라 animation
+     속성을 직접 쓰는 이 자리에는 닿지 않는다 — 그 규칙이 animation: none 으로 강제하지
+     않는 것은 의도다(로딩 스피너처럼 «회전 자체가 신호»인 움직임까지 죽이면 진행 여부를
+     알 수 없다).
+
+     스켈레톤은 다르다: **기본값이 이미 animation: none** 이고, 정지한 회색 블록이
+     «로딩 중»을 그대로 나른다. 즉 pulse/shimmer 는 **opt-in 장식**이고, WCAG 2.2.2 의
+     «움직임이 본질인 것» 예외에 해당하지 않는다.
+     ⇒ 여기서만 멈춘다. u-spinner 는 건드리지 않는다. */
+  @media (prefers-reduced-motion: reduce) {
+    :host([effect="pulse"]),
+    :host([effect="shimmer"])::after,
+    :host([lines][effect="pulse"]) .line,
+    :host([lines][effect="shimmer"]) .line::after {
+      animation: none;
+    }
+  }
+
   @keyframes pulse {
     0%, 100% {
       opacity: 1;

package/dist/components/tab-panel/UTabPanel.d.ts

@@ -29,8 +29,10 @@ export declare class UTabPanel extends UElement {
     placement: TabPanelPlacement;
     /** 선택된 탭값 */
     value: string;
-    /** 탭 추가/삭제 가능 여부 */
-    editable: boolean;
+    /**
+     * 네이티브 전역 속성. ⚠**이 컴포넌트에 탭 재정렬 기능은 없다** — 브라우저의 드래그를
+     * 켤 뿐이고, 놓았을 때 순서를 바꾸는 코드는 존재한 적이 없다.
+     */
     draggable: boolean;
     private tabs;
     private panels;

package/dist/components/tab-panel/UTabPanel.js

@@ -14,7 +14,6 @@ var UTabPanel = class UTabPanel extends UElement {
 		this.variant = "line";
 		this.placement = "top";
 		this.value = "";
-		this.editable = false;
 		this.draggable = false;
 		this.tabs = [];
 		this.panels = [];
@@ -144,10 +143,6 @@ __decorate([property({
 	type: String,
 	reflect: true
 }), __decorateMetadata("design:type", Object)], UTabPanel.prototype, "value", void 0);
-__decorate([property({
-	type: Boolean,
-	reflect: true
-}), __decorateMetadata("design:type", Object)], UTabPanel.prototype, "editable", void 0);
 __decorate([property({
 	type: Boolean,
 	reflect: true

package/dist/components/tag/UTag.d.ts

@@ -14,6 +14,7 @@ export type TagColor = "neutral" | "primary" | "info" | "success" | "warning" |
  * @slot suffix - 태그 뒤에 표시할 콘텐츠
  *
  * @csspart content - 콘텐츠 영역
+ * @csspart icon - 상태 아이콘 (`icon` + 역할 색일 때만 렌더된다)
  *
  * @cssprop --tag-color - 텍스트 색상
  * @cssprop --tag-bg-color - 배경 색상
@@ -31,6 +32,12 @@ export declare class UTag extends UElement {
     color: TagColor;
     /** 태그를 둥글게 표시합니다. */
     rounded: boolean;
+    /**
+     * 상태를 **색과 무관하게** 나르는 아이콘을 붙입니다(`info`·`success`·`warning`·`danger`).
+     * 색각 이상·흑백 인쇄에서 상태가 갈리게 하는 축입니다.
+     * 의미가 없는 색(`neutral`·`primary`·장식 축)에서는 아무것도 그리지 않습니다.
+     */
+    icon: boolean;
     render(): import('lit-html').TemplateResult<1>;
 }
 declare global {

package/dist/components/tag/UTag.js

@@ -1,8 +1,10 @@
 import { UElement } from "../UElement.js";
 import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.142.0/helpers/esm/decorateMetadata.js";
 import __decorate from "../../_virtual/_@oxc-project_runtime@0.142.0/helpers/esm/decorate.js";
+import "../icon/UIcon.js";
+import { statusIcon } from "../../utilities/statusIcon.js";
 import { styles } from "./UTag.styles.js";
-import { html } from "lit";
+import { html, nothing } from "lit";
 import { customElement, property } from "lit/decorators.js";
 //#region src/components/tag/UTag.ts
 var UTag = class UTag extends UElement {
@@ -11,13 +13,16 @@ var UTag = class UTag extends UElement {
 		this.variant = "filled";
 		this.color = "neutral";
 		this.rounded = false;
+		this.icon = false;
 	}
 	static {
 		this.styles = [super.styles, styles];
 	}
 	render() {
+		const iconName = this.icon ? statusIcon(this.color) : void 0;
 		return html`
       <div class="base" part="base">
+        ${iconName ? html`<u-icon class="icon" part="icon" lib="internal" name=${iconName}></u-icon>` : nothing}
         <slot name="prefix"></slot>
         <span class="content" part="content">
           <slot></slot>
@@ -39,6 +44,10 @@ __decorate([property({
 	type: Boolean,
 	reflect: true
 }), __decorateMetadata("design:type", Object)], UTag.prototype, "rounded", void 0);
+__decorate([property({
+	type: Boolean,
+	reflect: true
+}), __decorateMetadata("design:type", Object)], UTag.prototype, "icon", void 0);
 UTag = __decorate([customElement("u-tag")], UTag);
 //#endregion
 export { UTag };

package/dist/components/tag/UTag.styles.js

@@ -189,6 +189,10 @@ var styles = css`
     border: 1px solid var(--tag-border-color);
     border-radius: inherit;
   }
+  /* 상태 아이콘 — .base 의 gap 이 간격을 정한다. */
+  .icon {
+    flex-shrink: 0;
+  }
   :host([rounded]) {
     border-radius: var(--u-radius-pill, 9999px);
   }

package/dist/components/tree/UTree.d.ts

@@ -34,9 +34,11 @@ export declare class UTree extends UElement {
     checkCascade: boolean;
     /** 트리 펼치기 트리거 방식 */
     trigger: TreeItemTrigger;
-    /** 드래그 앤드 드롭 지원 */
+    /**
+     * 네이티브 전역 속성. ⚠**이 컴포넌트에 드래그 앤드 드롭 구현은 없다** — 브라우저의
+     * 드래그를 켤 뿐이고, 드롭을 받아 트리를 재배치하는 코드는 존재한 적이 없다.
+     */
     draggable: boolean;
-    droppable: boolean;
     private expandIcon?;
     private collapseIcon?;
     private anchor;

package/dist/components/tree/UTree.js

@@ -16,7 +16,6 @@ var UTree = class UTree extends UElement {
 		this.checkCascade = false;
 		this.trigger = "item";
 		this.draggable = false;
-		this.droppable = false;
 		this.anchor = null;
 		this._items = [];
 		this.handleSlotChange = (e) => {
@@ -300,10 +299,6 @@ __decorate([property({
 	type: Boolean,
 	reflect: true
 }), __decorateMetadata("design:type", Boolean)], UTree.prototype, "draggable", void 0);
-__decorate([property({
-	type: Boolean,
-	reflect: true
-}), __decorateMetadata("design:type", Boolean)], UTree.prototype, "droppable", void 0);
 __decorate([state(), __decorateMetadata("design:type", typeof Node === "undefined" ? Object : Node)], UTree.prototype, "expandIcon", void 0);
 __decorate([state(), __decorateMetadata("design:type", typeof Node === "undefined" ? Object : Node)], UTree.prototype, "collapseIcon", void 0);
 UTree = __decorate([customElement("u-tree")], UTree);

package/dist/components/tree-item/UTreeItem.d.ts

@@ -35,8 +35,11 @@ export declare class UTreeItem extends UElement {
     trigger: TreeItemTrigger;
     /** 아이템의 고유값 */
     value: string;
+    /**
+     * 네이티브 전역 속성. ⚠**드롭을 받아 트리를 재배치하는 구현은 없다** — `UTree` 의 같은
+     * 속성과 같은 상태다.
+     */
     draggable: boolean;
-    droppable: boolean;
     leaf: boolean;
     depth: number;
     selected: boolean;

package/dist/components/tree-item/UTreeItem.js

@@ -22,7 +22,6 @@ var UTreeItem = class UTreeItem extends UElement {
 		this.trigger = "item";
 		this.value = "";
 		this.draggable = false;
-		this.droppable = false;
 		this.leaf = true;
 		this.depth = 0;
 		this.selected = false;
@@ -185,10 +184,6 @@ __decorate([property({
 	type: Boolean,
 	reflect: true
 }), __decorateMetadata("design:type", Boolean)], UTreeItem.prototype, "draggable", void 0);
-__decorate([property({
-	type: Boolean,
-	reflect: true
-}), __decorateMetadata("design:type", Boolean)], UTreeItem.prototype, "droppable", void 0);
 __decorate([state(), __decorateMetadata("design:type", Boolean)], UTreeItem.prototype, "leaf", void 0);
 __decorate([state(), __decorateMetadata("design:type", Number)], UTreeItem.prototype, "depth", void 0);
 __decorate([state(), __decorateMetadata("design:type", Boolean)], UTreeItem.prototype, "selected", void 0);

package/dist/index.d.ts

@@ -17,6 +17,7 @@ export * from './components/copy-button/UCopyButton.js';
 export * from './components/dialog/UDialog.js';
 export * from './components/divider/UDivider.js';
 export * from './components/drawer/UDrawer.js';
+export * from './components/expander/UExpander.js';
 export * from './components/field/UField.js';
 export * from './components/form/UForm.js';
 export * from './components/icon/UIcon.js';

package/dist/index.js

@@ -27,6 +27,7 @@ import { UCopyButton } from "./components/copy-button/UCopyButton.js";
 import { UDialog } from "./components/dialog/UDialog.js";
 import { UDivider } from "./components/divider/UDivider.js";
 import { UDrawer } from "./components/drawer/UDrawer.js";
+import { UExpander } from "./components/expander/UExpander.js";
 import { UField } from "./components/field/UField.js";
 import { UForm } from "./components/form/UForm.js";
 import { UOption } from "./components/option/UOption.js";
@@ -53,4 +54,4 @@ import { BrowserStorage } from "./utilities/BrowserStorage.js";
 import { Dialog } from "./utilities/Dialog.js";
 import { Theme } from "./utilities/Theme.js";
 import { Toast } from "./utilities/Toast.js";
-export { BrowserStorage, Dialog, IconCache, IconRegistry, Locale, OverlayManager, Theme, Toast, UAlert, UAvatar, UBadge, UBreadcrumb, UBreadcrumbItem, UButton, UButtonGroup, UCard, UCarousel, UCheckbox, UChip, UCopyButton, UDialog, UDivider, UDrawer, UElement, UField, UFloatingElement, UForm, UFormControlElement, UIcon, UIconButton, UInput, UMenu, UMenuItem, UOption, UOverlayElement, UPanel, UPopover, UProgressBar, UProgressRing, URadio, URating, USelect, USkeleton, USlider, USpinner, USplitPanel, USwitch, UTab, UTabPanel, UTag, UTextarea, UTooltip, UTree, UTreeItem, arrayAttrConverter, booleanAttrConverter, dateAttrConverter, getDefaultBaseUrl, getParentElement, jsonAttrConverter, querySelectorAllWithin, querySelectorWithin, setDefaultBaseUrl, urlAttrConverter };
+export { BrowserStorage, Dialog, IconCache, IconRegistry, Locale, OverlayManager, Theme, Toast, UAlert, UAvatar, UBadge, UBreadcrumb, UBreadcrumbItem, UButton, UButtonGroup, UCard, UCarousel, UCheckbox, UChip, UCopyButton, UDialog, UDivider, UDrawer, UElement, UExpander, UField, UFloatingElement, UForm, UFormControlElement, UIcon, UIconButton, UInput, UMenu, UMenuItem, UOption, UOverlayElement, UPanel, UPopover, UProgressBar, UProgressRing, URadio, URating, USelect, USkeleton, USlider, USpinner, USplitPanel, USwitch, UTab, UTabPanel, UTag, UTextarea, UTooltip, UTree, UTreeItem, arrayAttrConverter, booleanAttrConverter, dateAttrConverter, getDefaultBaseUrl, getParentElement, jsonAttrConverter, querySelectorAllWithin, querySelectorWithin, setDefaultBaseUrl, urlAttrConverter };

package/dist/react/UExpander.d.ts

@@ -0,0 +1,16 @@
+import React from 'react';
+import { UExpander as UExpanderElement } from '../components/expander/UExpander';
+import { type ExpandEventDetail } from '../events/ExpandEvent';
+import { type CollapseEventDetail } from '../events/CollapseEvent';
+
+export declare const UExpander: React.ForwardRefExoticComponent<
+  Omit<Partial<UExpanderElement>, keyof React.HTMLAttributes<UExpanderElement>>
+    & Omit<React.HTMLAttributes<UExpanderElement>, 'onExpand' | 'onCollapse'>
+    & React.RefAttributes<UExpanderElement>
+    & {
+  onExpand?: (event: CustomEvent<ExpandEventDetail>) => void;
+  onCollapse?: (event: CustomEvent<CollapseEventDetail>) => void;
+  }
+>;
+
+export type UExpanderProps = React.ComponentProps<typeof UExpander>;

package/dist/react/UExpander.js

@@ -0,0 +1,13 @@
+import React from 'react';
+import { createComponent } from '@lit/react';
+import { UExpander as UExpanderElement } from '../components/expander/UExpander.js';
+
+export const UExpander = createComponent({
+  react: React,
+  tagName: 'u-expander',
+  elementClass: UExpanderElement,
+  events: {
+    onExpand: 'expand',
+    onCollapse: 'collapse',
+  },
+});

package/dist/react/index.d.ts

@@ -25,6 +25,7 @@ export { UIconButton, UIconButtonProps } from './UIconButton';
 export { UIcon, UIconProps } from './UIcon';
 export { UForm, UFormProps } from './UForm';
 export { UField, UFieldProps } from './UField';
+export { UExpander, UExpanderProps } from './UExpander';
 export { UDrawer, UDrawerProps } from './UDrawer';
 export { UDivider, UDividerProps } from './UDivider';
 export { UDialog, UDialogProps } from './UDialog';

package/dist/react/index.js

@@ -25,6 +25,7 @@ export { UIconButton } from './UIconButton.js';
 export { UIcon } from './UIcon.js';
 export { UForm } from './UForm.js';
 export { UField } from './UField.js';
+export { UExpander } from './UExpander.js';
 export { UDrawer } from './UDrawer.js';
 export { UDivider } from './UDivider.js';
 export { UDialog } from './UDialog.js';

package/dist/utilities/Dialog.js

@@ -115,7 +115,7 @@ var Dialog = class {
 		try {
 			await dialog.updateComplete;
 		} catch (error) {
-			console.error("[Dialog] 다이얼로그를 표시하지 못했습니다.", error);
+			console.error("[Dialog] Failed to show the dialog.", error);
 			dialog.remove();
 			return null;
 		}

package/dist/utilities/Locale.d.ts

@@ -14,6 +14,31 @@ export type LocaleTag = SupportedLocale | (string & {});
 /** 라이브러리가 제공하는 chrome 문자열 키. 지금은 검증 메시지뿐이지만 이후 다른 UI 문구도 추가될 수 있다. */
 export type LocaleMessageKey = 'valueMissing' | 'badInput' | 'typeMismatch' | 'patternMismatch' | 'rangeUnderflow' | 'rangeOverflow' | 'stepMismatch' | 'tooShort' | 'tooLong';
 type LocaleTable = Record<LocaleMessageKey, string>;
+/**
+ * 한 패키지(또는 앱 영역)의 문자열 묶음.
+ *
+ * 키 유니온을 **소비자가** 정하므로 라이브러리의 키셋은 커지지 않는다:
+ * ```ts
+ * const t = Locale.namespace<'empty' | 'loading'>('u-data-view');
+ * t.register('en', { empty: 'No data', loading: 'Loading…' });
+ * t.text('empty');
+ * ```
+ */
+export interface LocaleNamespace<K extends string = string> {
+    /** 네임스페이스 이름. */
+    readonly name: string;
+    /**
+     * 로케일 하나의 테이블(전체 또는 일부)을 등록한다.
+     * 같은 로케일에 반복 호출하면 **병합**된다 — 일부 키만 넘겨도 나머지가 사라지지 않는다.
+     */
+    register(locale: LocaleTag, table: Partial<Record<K, string>>): void;
+    /**
+     * 활성 로케일 기준으로 문자열을 찾는다.
+     * 사슬(정확 일치 → base → en)에 없으면 **키 자체를 돌려준다** — 조용히 빈 문자열이
+     * 되는 것보다 화면에 드러나는 편이 낫다.
+     */
+    text(key: K, params?: Record<string, string | number>): string;
+}
 /**
  * 검증 메시지 로케일을 관리하는 정적 유틸리티입니다.
  */
@@ -34,5 +59,14 @@ export declare class Locale {
      * `params`가 있으면 템플릿의 `{name}` 자리를 치환합니다.
      */
     static getValue(key: LocaleMessageKey, params?: Record<string, string | number>): string;
+    /**
+     * 네임스페이스 핸들을 얻습니다 — 같은 이름이면 **같은 저장소**를 가리킵니다.
+     *
+     * 상위 패키지가 자기 화면 문자열을 담는 자리입니다. 검증 메시지(`getValue`)의 키셋과
+     * 완전히 분리돼 있어, 이 API 를 써도 라이브러리의 `LocaleMessageKey` 는 커지지 않습니다.
+     *
+     * @param name 네임스페이스 이름. 패키지·컴포넌트 단위를 권장합니다(예: `'u-data-view'`).
+     */
+    static namespace<K extends string = string>(name: string): LocaleNamespace<K>;
 }
 export {};

package/dist/utilities/Locale.js

@@ -39,21 +39,29 @@ function detectLocale() {
 	return "en";
 }
 var active = detectLocale();
-/** 정확 일치 → base 언어(ko-KR → ko) → en 순으로 값을 찾는다. */
-function lookup(locale, key) {
+/** 정확 일치 → base 언어(ko-KR → ko) → en 순의 조회 사슬. */
+function chainOf(locale) {
 	const norm = locale.toLowerCase();
 	const base = norm.split("-")[0];
-	const chain = base === norm ? [norm, "en"] : [
+	return base === norm ? [norm, "en"] : [
 		norm,
 		base,
 		"en"
 	];
-	for (const tag of chain) {
+}
+/** 템플릿의 `{name}` 자리를 치환한다. 값이 없는 자리는 그대로 남긴다(디버깅 단서). */
+function interpolate(template, params) {
+	return params ? template.replace(/\{(\w+)\}/g, (_, name) => params[name] != null ? String(params[name]) : `{${name}}`) : template;
+}
+function lookup(locale, key) {
+	for (const tag of chainOf(locale)) {
 		const value = overrides.get(tag)?.[key] ?? builtins.get(tag)?.[key];
 		if (value) return value;
 	}
 	return builtins.get("en")[key];
 }
+/** ns → 정규화 로케일 태그 → 테이블. */
+var namespaces = /* @__PURE__ */ new Map();
 /**
 * 검증 메시지 로케일을 관리하는 정적 유틸리티입니다.
 */
@@ -85,8 +93,37 @@ var Locale = class {
 	* `params`가 있으면 템플릿의 `{name}` 자리를 치환합니다.
 	*/
 	static getValue(key, params) {
-		const template = lookup(active, key);
-		return params ? template.replace(/\{(\w+)\}/g, (_, name) => params[name] != null ? String(params[name]) : `{${name}}`) : template;
+		return interpolate(lookup(active, key), params);
+	}
+	/**
+	* 네임스페이스 핸들을 얻습니다 — 같은 이름이면 **같은 저장소**를 가리킵니다.
+	*
+	* 상위 패키지가 자기 화면 문자열을 담는 자리입니다. 검증 메시지(`getValue`)의 키셋과
+	* 완전히 분리돼 있어, 이 API 를 써도 라이브러리의 `LocaleMessageKey` 는 커지지 않습니다.
+	*
+	* @param name 네임스페이스 이름. 패키지·컴포넌트 단위를 권장합니다(예: `'u-data-view'`).
+	*/
+	static namespace(name) {
+		return {
+			name,
+			register(locale, table) {
+				const byLocale = namespaces.get(name) ?? /* @__PURE__ */ new Map();
+				const norm = locale.toLowerCase();
+				byLocale.set(norm, {
+					...byLocale.get(norm),
+					...table
+				});
+				namespaces.set(name, byLocale);
+			},
+			text(key, params) {
+				const byLocale = namespaces.get(name);
+				for (const tag of chainOf(active)) {
+					const value = byLocale?.get(tag)?.[key];
+					if (value) return interpolate(value, params);
+				}
+				return key;
+			}
+		};
 	}
 };
 //#endregion

package/dist/utilities/Theme.d.ts

@@ -65,6 +65,30 @@ export declare class Theme {
     static set(theme: ThemeType): void;
     /** 시스템 테마 변경을 처리하는 메서드 */
     private static handleSystemThemeChanged;
+    /** 마지막으로 지정된 브랜드 시드. 테마가 바뀌면 이 값으로 램프를 다시 계산한다. */
+    private static accentSeed;
+    /**
+     * 브랜드 색 하나로 `--u-primary-*` 램프를 만든다.
+     *
+     * ```ts
+     * Theme.accent('#6A1B9A');   // 램프 5단 + 면 위 글자색이 계산된다
+     * Theme.accent(null);        // 해제 — 시트 기본값으로 되돌아간다
+     * ```
+     *
+     * 종전에는 소비자가 램프를 **손으로 열 줄 적었고**, 그 값이 대비 계약을 만족하는지는
+     * 아무것도 확인하지 않았다. 여기서는 «면 위 글자 4.5 · 바탕 위 글자 4.5 · 단 구분 1.20 ·
+     * 그래픽 3.0» 을 만족하는 값을 **계산해서** 넣는다(`utilities/accent.ts`).
+     *
+     * ⚠**바탕은 계산 시점의 `--u-bg-color` 를 읽는다** — 소비자가 바탕을 덮었으면 그 값을
+     * 기준으로 계산되고, 테마가 바뀌면 **다시 계산한다**(라이트/다크가 다른 램프를 갖는다).
+     * ⇒ `Theme.set()` · 시스템 테마 변경 뒤에 자동으로 재적용된다.
+     *
+     * ⚠**변수는 `documentElement` 의 인라인 스타일로 들어간다** — 시트보다 우선하므로
+     * 로드 순서에 기대지 않는다.
+     */
+    static accent(seed: string | null): void;
+    /** 현재 시드를 현재 테마의 바탕에 맞춰 다시 계산해 적용한다. */
+    private static applyAccent;
     /** 디버그 모드시 로그 출력 함수 (인스턴스 스코프) */
     private static log;
 }

package/dist/utilities/Theme.js

@@ -1,7 +1,17 @@
 import { BrowserStorage } from "./BrowserStorage.js";
 import dark_css_default from "../_virtual/_glob-assets_raw/dark.css.e8ac080d.js";
 import light_css_default from "../_virtual/_glob-assets_raw/light.css.637cb2f8.js";
+import { accentCustomProperties, deriveAccentRamp } from "./accent.js";
 //#region src/utilities/Theme.ts
+/** 프로퍼티 «이름»만 필요할 때 쓰는 더미 — 값은 쓰지 않는다. */
+var EMPTY_RAMP = {
+	weakest: "#000",
+	weaker: "#000",
+	weak: "#000",
+	color: "#000",
+	strong: "#000",
+	txt: "#000"
+};
 /**
 * 스타일 시트 번들 로드, 내부 자산에서 CSS를 인라인으로 가져옵니다.
 * 빌드 시점에 정적 파일을 포함시키기 위해 vite의 `import.meta.glob`을 사용합니다.
@@ -139,6 +149,7 @@ var Theme = class {
 		} catch (e) {
 			this.log("Error applying theme:", e);
 		}
+		this.applyAccent();
 		if (this.storage !== null) {
 			this.storage.set(this.STORAGE_THEME_KEY, theme);
 			this.log("saved theme to storage", theme);
@@ -150,9 +161,50 @@ var Theme = class {
 				const isDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
 				document.documentElement.setAttribute("theme", isDark ? "dark" : "light");
 				this.log("system theme changed, applied", isDark ? "dark" : "light");
+				this.applyAccent();
 			}
 		};
 	}
+	static {
+		this.accentSeed = null;
+	}
+	/**
+	* 브랜드 색 하나로 `--u-primary-*` 램프를 만든다.
+	*
+	* ```ts
+	* Theme.accent('#6A1B9A');   // 램프 5단 + 면 위 글자색이 계산된다
+	* Theme.accent(null);        // 해제 — 시트 기본값으로 되돌아간다
+	* ```
+	*
+	* 종전에는 소비자가 램프를 **손으로 열 줄 적었고**, 그 값이 대비 계약을 만족하는지는
+	* 아무것도 확인하지 않았다. 여기서는 «면 위 글자 4.5 · 바탕 위 글자 4.5 · 단 구분 1.20 ·
+	* 그래픽 3.0» 을 만족하는 값을 **계산해서** 넣는다(`utilities/accent.ts`).
+	*
+	* ⚠**바탕은 계산 시점의 `--u-bg-color` 를 읽는다** — 소비자가 바탕을 덮었으면 그 값을
+	* 기준으로 계산되고, 테마가 바뀌면 **다시 계산한다**(라이트/다크가 다른 램프를 갖는다).
+	* ⇒ `Theme.set()` · 시스템 테마 변경 뒤에 자동으로 재적용된다.
+	*
+	* ⚠**변수는 `documentElement` 의 인라인 스타일로 들어간다** — 시트보다 우선하므로
+	* 로드 순서에 기대지 않는다.
+	*/
+	static accent(seed) {
+		this.accentSeed = seed;
+		this.applyAccent();
+	}
+	/** 현재 시드를 현재 테마의 바탕에 맞춰 다시 계산해 적용한다. */
+	static applyAccent() {
+		if (typeof document === "undefined") return;
+		const root = document.documentElement;
+		const names = Object.keys(accentCustomProperties(EMPTY_RAMP));
+		if (!this.accentSeed) {
+			for (const n of names) root.style.removeProperty(n);
+			return;
+		}
+		const bg = getComputedStyle(root).getPropertyValue("--u-bg-color").trim() || "#ffffff";
+		const ramp = deriveAccentRamp(this.accentSeed, bg);
+		for (const [name, value] of Object.entries(accentCustomProperties(ramp))) root.style.setProperty(name, value);
+		this.log("accent applied", this.accentSeed, "→", ramp);
+	}
 	/** 디버그 모드시 로그 출력 함수 (인스턴스 스코프) */
 	static log(...args) {
 		if (this._isDebugMode) console.log("[theme]", ...args);

package/dist/utilities/accent.d.ts

@@ -0,0 +1,52 @@
+/**
+ * **브랜드 악센트 시드 → 역할 램프 파생.**
+ *
+ * 소비자가 시드 색 하나를 주면 `--u-primary-*` 5단과 그 면 위의 글자색을 계산한다.
+ * 종전에는 소비자가 램프를 **손으로 열 줄 적었고**, 그 값들이 대비 계약을 만족하는지는
+ * 아무것도 확인하지 않았다.
+ *
+ * ## 🔴 왜 CSS 만으로 하지 않는가 — 실측이 정한 것이다
+ *
+ * `color-mix()` 로 고정 비율만 섞으면 **밝은 시드에서 계약이 깨진다** — 노랑 시드의
+ * `-strong` 이 바탕 대비 **2.21**(기준 4.5)이었다. 목표 대비까지 섞으려면 **대비를 계산**
+ * 해야 하고 CSS 에는 그 수단이 없다. ⇒ 계산은 JS 가 하고, 결과만 커스텀 프로퍼티로 넣는다.
+ *
+ * ## ⚠ 두 목표를 «동시에» 건다
+ *
+ * 대비만 목표로 삼으면 시드가 이미 4.5 를 넘을 때 탐색이 **시드 자신에서 멈춰**
+ * `-strong` 과 `-color` 가 같은 값이 된다(실측: 5역할 중 4). 그러면 계약은 만족하는데
+ * **위계가 사라진다.** 그래서 «바탕과 4.5» 와 «`-color` 와 1.20» 을 함께 만족시킨다.
+ *
+ * ## 방향은 «바탕 기준»이다 — 라이트/다크가 같은 코드로 돈다
+ *
+ * `-strong` 은 바탕에서 **멀어지는** 쪽(라이트면 검정, 다크면 흰색), `-weak` 이하는 바탕에
+ * **가까워지는** 쪽이다. 다크 시트가 팔레트를 반전시켜 놓은 것과 같은 방향이다.
+ */
+/** 역할 램프 한 벌. 시트의 `--u-{role}-color-*` 와 이름이 1:1 이다. */
+export interface AccentRamp {
+    weakest: string;
+    weaker: string;
+    weak: string;
+    color: string;
+    strong: string;
+    /** 면(`color`) 위에 놓이는 글자색 — `--u-{role}-txt-color`. */
+    txt: string;
+}
+/** 대비 계약의 문턱값 — `tests/build/token-contrast.test.ts` 와 같은 값이다. */
+export declare const AA_TEXT = 4.5;
+export declare const AA_GRAPHIC = 3;
+/** `-strong` 이 `-color` 와 갈려 보이기 위한 최소 대비(2026-08-04 채택). */
+export declare const MIN_STEP_SEPARATION = 1.2;
+/** `#rgb`·`#rrggbb`·`rgb(r g b)` 를 [r,g,b] 로. 해석할 수 없으면 `null`. */
+export declare function parseColor(value: string): [number, number, number] | null;
+export declare function toHex([r, g, b]: [number, number, number]): string;
+export declare function luminance(color: string): number;
+/** WCAG 2.1 명암비. */
+export declare function contrast(a: string, b: string): number;
+/** `color-mix(in srgb, a p%, b)` 와 같은 계산. */
+export declare function mix(a: string, b: string, p: number): string;
+/** 면 위의 글자를 고른다 — 검정/흰색 중 대비가 큰 쪽. */
+export declare function pickOnColor(surface: string): string;
+export declare function deriveAccentRamp(seed: string, bg: string): AccentRamp;
+/** 램프를 커스텀 프로퍼티 이름 → 값 맵으로. */
+export declare function accentCustomProperties(ramp: AccentRamp, role?: string): Record<string, string>;