@iyulab/components 1.23.0 → 1.24.0

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # Changelog
 
+## [1.24.0] - 2026-08-04
+
+### Added
+
+- 🔴**`u-text` — 의미 타이포그래피 스케일(7단)을 마크업에서 쓰는 자리.**
+  시트는 `1.21.0` 부터 단마다 **크기·굵기·행간·자간** 네 값을 갖고 있었지만 **그 단을
+  적용하는 컴포넌트가 없었다** — 소비자가 스케일을 쓰려면 자기 CSS 에서 토큰을 직접
+  참조해야 했고, 그러면 «컴포넌트만으로 화면을 짓는다»가 그 자리에서 깨졌다.
+  ⇒ 우리가 준 것은 **값**이고 필요했던 것은 **자리**다.
+
+  ```html
+  <u-text level="1" variant="display">문서 제목</u-text>
+  <u-text variant="subtitle" tone="weak">한 줄 설명</u-text>
+  <u-text>본문</u-text>
+  <u-text variant="caption" tone="weak">보조 문구</u-text>
+  ```
+
+  ★**시각 축(`variant`)과 의미 축(`level`)이 독립**이다 — `level` 을 주면 섀도 루트에 실제
+  `<h1>`~`<h6>` 을 렌더해 heading 으로 읽히고(슬롯 텍스트가 접근가능 이름), 주지 않으면
+  `<p>` 다. 그래서 *"페이지의 두 번째 제목이 시각적으로 가장 큰"* 배치가 마크업을
+  거짓말시키지 않고 표현된다.
+
+  ⚠**`tone` 은 중립 강조 축이다**(`default`·`weak`·`strong`·`inverse`) — 역할색이
+  아니다. 소비 화면 실측에서 나온 색 다섯 중 셋이 이 축이었고 나머지 둘은 **링크**와
+  **콜아웃 박스**라 이 컴포넌트의 축이 아니었다.
+
+  ⚠**값을 새로 정의하지 않는다** — 7단 × 4속성을 시트에서 읽기만 한다. 회귀 12건이
+  *"어떤 크기인가"* 가 아니라 ***"시트가 말한 그 값을 쓰는가"*** 를 잰다.
+  같은 이유로 `overline` 에 `text-transform: uppercase` 를 **붙이지 않았다** — 관습이긴 하나
+  소비자가 쓴 글자를 바꾸고, CJK 에는 효과가 없어 **같은 단이 언어에 따라 다르게 보인다.**
+
+### Fixed
+
+- 🔴**`u-field` 안의 컨트롤이 필드 폭을 채우지 않아 폼 격자가 어긋났다.** 실측: 같은 231px
+  칸 안에서 `u-input` 202 · `u-select` 71/92/108 · `u-textarea` 168 — **오른쪽 끝이 다섯
+  군데에서 다 달랐다.** 컨트롤 자신의 기본값(`inline-block`)은 옳지만, `u-field` 로 감싼
+  순간 그것은 **폼의 한 칸**이다 ⇒ 라벨·설명·검증 문구의 배치를 책임지는 이 컴포넌트가
+  폭도 함께 정한다(`::slotted(*) { width: 100% }`).
+  ⚠소비자가 인라인 `style` 로 폭을 주면 그쪽이 이긴다.
+
+### Added
+
+- **`u-icon[fallback]`** — 이름·URL 이 해석되지 않을 때 대신 그릴 SVG 원문.
+  «아이콘이 안 보인다»가 **«누를 것이 없다»** 가 되는 자리가 있다(접힌 사이드바의 메뉴 항목).
+  해석 실패는 이름 미지정 · 404 · SVG 파싱 실패를 **모두** 포함한다.
+
+### Documentation
+
+- 🔴**`Theme.accent(seed)` 가 `primary` 역할 토큰 **7종 중 6종**만 세팅한다는 것을 명시했다.**
+  `--u-primary-bg-color`(`u-tag` 의 `--tag-hue-surface` 가 읽는 «글자를 얹는 옅은 면»)는
+  시트 기본값으로 남으므로, **시드만 넣으면 태그·선택된 행 같은 옅은 면이 파랑으로 남는다.**
+  실측된 증상이 *"버튼은 브랜드인데 선택된 표 행은 파랑"* 이다.
+  ⇒ `usage.md` 브랜드 절에 **7종 표**와 한 줄 해법을, `Theme.accent` JSDoc 에 같은 내용을 적었다.
+
+  ⚠**파생을 붙이지 않은 이유**: 이 토큰은 `info`·`success`·`danger`·`warning` 과 한 세트로
+  **5계열 × 2테마 = 10개 값이 손으로 짝지어져** 있고, 두 테마가 같은 계약을 쓰지 않는다
+  (바탕 대비비 실측 — 라이트 **1.142** · 다크 **1.030**). 도출식으로 바꾸는 것은 팔레트
+  값 결정이라 별도 판단이 필요하다.
+
+  브라우저 회귀 2건이 이 문서가 참인지 잰다 — **결손을 고정하는 것이 아니라**, 나중에 파생이
+  붙으면 그 테스트가 뒤집히면서 문서도 고치라고 알린다.
+
 ## [1.23.0] - 2026-08-04
 
 ### Added

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) [year] [fullname]
+Copyright (c) 2024 iyulab
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -76,7 +76,7 @@ npx skills add ./node_modules/@iyulab/components
 
 **Navigation** — `u-menu`, `u-menu-item`, `u-tab-panel`, `u-breadcrumb`, `u-breadcrumb-item`, `u-tree`, `u-tree-item`
 
-**Layout & Display** — `u-avatar`, `u-card`, `u-carousel`, `u-divider`, `u-icon`, `u-panel`, `u-split-panel`, `u-tag`
+**Layout & Display** — `u-avatar`, `u-card`, `u-carousel`, `u-divider`, `u-icon`, `u-panel`, `u-split-panel`, `u-tag`, `u-text`
 
 ## Theming
 

package/dist/components/field/UField.styles.js

@@ -15,6 +15,21 @@ var styles = css`
     color: var(--u-danger-color-strong, #C62828);
   }
 
+  /* 🔴**라벨을 단 컨트롤은 필드 폭을 채운다.**
+     컨트롤 자신의 기본값은 inline-block(자기 내용만큼)이 옳다 — 문장 안에 놓이는 경우가
+     있기 때문이다. 그러나 u-field 로 감싼 순간 그것은 **폼의 한 칸**이고, 칸마다 컨트롤이
+     제각각의 폭을 가지면 격자가 너덜너덜해진다. 실측: 같은 231px 칸 안에서 input 202 ·
+     select 71/92/108 · textarea 168 — **오른쪽 끝이 다섯 군데에서 다 달랐다.**
+     ⇒ 라벨·설명·검증 문구의 배치를 책임지는 이 컴포넌트가 폭도 함께 정한다.
+
+     ⚠소비자가 인라인 style 로 폭을 주면 그쪽이 이긴다(인라인 > ::slotted).
+     ⚠이 주석에 백틱을 쓰지 말 것 — css 태그드 템플릿을 그 자리에서 끝낸다(이 파일이 실제로
+     그렇게 깨졌고, cycle-217 이 만든 타입 게이트가 잡았다). */
+  ::slotted(*) {
+    width: 100%;
+    box-sizing: border-box;
+  }
+
   .header {
     display: flex;
     flex-direction: row;

package/dist/components/icon/UIcon.d.ts

@@ -1,4 +1,3 @@
-import { nothing } from 'lit';
 import { UElement } from '../UElement.js';
 export type IconLibrary = (string & {}) | "internal" | "tabler" | "heroicons" | "lucide" | "bootstrap";
 /**
@@ -14,9 +13,23 @@ export declare class UIcon extends UElement {
     lib?: IconLibrary;
     /** 사용할 아이콘 이름을 지정합니다. */
     name?: string;
-    render(): import('lit-html/directive.js').DirectiveResult<{
-        new (_partInfo: import('lit-html/directive.js').PartInfo): import('lit-html/directives/until.js').UntilDirective<typeof nothing | Promise<import('lit-html/directive.js').DirectiveResult<typeof import('lit-html/directives/unsafe-html.js').UnsafeHTMLDirective>>>;
-    }>;
+    /**
+     * 이름·URL 이 **해석되지 않을 때** 대신 그릴 SVG 원문.
+     *
+     * ★**«아이콘이 안 보인다»가 «자리 자체가 사라진다»가 되는 곳이 있다.** 사이드바가 접히면
+     * 라벨이 숨고 아이콘만 남는데, 그 아이콘이 해석에 실패하면 그 메뉴는 **누를 것이 없는
+     * 빈 줄**이 된다 — 이름이 잘못됐는지, 파일이 없는지, 아이콘을 안 준 것인지 화면에서
+     * 구분되지 않고 **탐색 수단이 통째로 사라진다.**
+     *
+     * ⇒ 그런 자리는 «없으면 안 그린다»가 아니라 **«없으면 대신 그린다»** 여야 한다.
+     * 해석 실패는 `name` 미지정 · 파일 없음(404) · SVG 파싱 실패를 **모두** 포함한다.
+     *
+     * ⚠소비자가 주는 값은 `sanitize()` 를 거친다(`name` 경로와 같은 처리).
+     */
+    fallback?: string;
+    render(): import('lit-html/directive.js').DirectiveResult<typeof import('lit-html/directives/unsafe-html.js').UnsafeHTMLDirective>;
+    /** 해석 결과가 없으면 `fallback` 으로 대신한다. 둘 다 없을 때만 아무것도 그리지 않는다. */
+    private paint;
     private resolve;
     private sanitize;
 }

package/dist/components/icon/UIcon.js

@@ -14,13 +14,15 @@ var UIcon = class UIcon extends UElement {
 	}
 	render() {
 		if (this.src) return until(IconRegistry.resolveUrl(this.src).then((html) => {
-			const sanitized = this.sanitize(html);
-			return sanitized ? unsafeHTML(sanitized) : nothing;
+			return this.paint(this.sanitize(html));
 		}), nothing);
-		if (this.name) return until(this.resolve(this.name).then((html) => {
-			return html ? unsafeHTML(html) : nothing;
-		}), nothing);
-		return nothing;
+		if (this.name) return until(this.resolve(this.name).then((html) => this.paint(html)), nothing);
+		return this.paint(void 0);
+	}
+	/** 해석 결과가 없으면 `fallback` 으로 대신한다. 둘 다 없을 때만 아무것도 그리지 않는다. */
+	paint(html) {
+		const resolved = html ?? this.sanitize(this.fallback);
+		return resolved ? unsafeHTML(resolved) : nothing;
 	}
 	async resolve(name) {
 		let html = void 0;
@@ -50,6 +52,7 @@ var UIcon = class UIcon extends UElement {
 __decorate([property({ type: String }), __decorateMetadata("design:type", String)], UIcon.prototype, "src", void 0);
 __decorate([property({ type: String }), __decorateMetadata("design:type", Object)], UIcon.prototype, "lib", void 0);
 __decorate([property({ type: String }), __decorateMetadata("design:type", String)], UIcon.prototype, "name", void 0);
+__decorate([property({ type: String }), __decorateMetadata("design:type", String)], UIcon.prototype, "fallback", void 0);
 UIcon = __decorate([customElement("u-icon")], UIcon);
 //#endregion
 export { UIcon };

package/dist/components/text/UText.d.ts

@@ -0,0 +1,38 @@
+import { UElement } from '../UElement.js';
+export type TextVariant = "display" | "title" | "subtitle" | "body" | "label" | "caption" | "overline";
+/** 중립 강조 축. **역할색이 아니다** — 역할색이 필요하면 그것은 별도 축이다. */
+export type TextTone = "default" | "weak" | "strong" | "inverse";
+/** 제목 단계. 값이 있으면 heading 으로 읽힌다. */
+export type TextLevel = 1 | 2 | 3 | 4 | 5 | 6;
+/**
+ * 의미 타이포그래피 스케일(7단)을 마크업에서 쓰는 자리입니다.
+ *
+ * 시트는 단마다 **크기·굵기·행간·자간** 네 값을 갖고 있으나, 그 단을 *적용하는* 것이
+ * 없어 소비자는 자기 CSS 에서 타이포 토큰을 직접 참조해야 했습니다.
+ * 이 컴포넌트는 그 자리를 대신하며, **값을 새로 정의하지 않고 토큰만 읽습니다.**
+ *
+ * `level` 을 주면 섀도 루트에 실제 `<h1>`~`<h6>` 을 렌더하므로 heading 으로 읽힙니다
+ * (슬롯 텍스트가 접근가능 이름이 됩니다). 주지 않으면 `<p>` 입니다.
+ *
+ * ⚠ 시각 축(`variant`)과 의미 축(`level`)은 **독립**입니다 — 페이지의 두 번째 제목이
+ * 시각적으로 가장 클 수 있습니다(`level="2" variant="display"`).
+ *
+ * @slot - 텍스트 내용
+ *
+ * @csspart base - 렌더된 `<p>` 또는 `<h1>`~`<h6>` 요소
+ */
+export declare class UText extends UElement {
+    static styles: import('lit').CSSResultGroup[];
+    /** 의미 타이포그래피 단계 */
+    variant: TextVariant;
+    /** 중립 강조 축 (역할색이 아니다) */
+    tone: TextTone;
+    /** 제목 단계. 지정하면 heading 요소로 렌더된다 */
+    level?: TextLevel;
+    protected render(): import('lit-html').TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'u-text': UText;
+    }
+}

package/dist/components/text/UText.js

@@ -0,0 +1,45 @@
+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 { styles } from "./UText.styles.js";
+import { customElement, property } from "lit/decorators.js";
+import { html, literal } from "lit/static-html.js";
+//#region src/components/text/UText.ts
+var PARAGRAPH = literal`p`;
+var HEADINGS = {
+	1: literal`h1`,
+	2: literal`h2`,
+	3: literal`h3`,
+	4: literal`h4`,
+	5: literal`h5`,
+	6: literal`h6`
+};
+var UText = class UText extends UElement {
+	constructor(..._args) {
+		super(..._args);
+		this.variant = "body";
+		this.tone = "default";
+	}
+	static {
+		this.styles = [super.styles, styles];
+	}
+	render() {
+		const tag = this.level && HEADINGS[this.level] ? HEADINGS[this.level] : PARAGRAPH;
+		return html`<${tag} class="text" part="base"><slot></slot></${tag}>`;
+	}
+};
+__decorate([property({
+	type: String,
+	reflect: true
+}), __decorateMetadata("design:type", Object)], UText.prototype, "variant", void 0);
+__decorate([property({
+	type: String,
+	reflect: true
+}), __decorateMetadata("design:type", Object)], UText.prototype, "tone", void 0);
+__decorate([property({
+	type: Number,
+	reflect: true
+}), __decorateMetadata("design:type", Object)], UText.prototype, "level", void 0);
+UText = __decorate([customElement("u-text")], UText);
+//#endregion
+export { UText };

package/dist/components/text/UText.styles.d.ts

@@ -0,0 +1 @@
+export declare const styles: import('lit').CSSResult;

package/dist/components/text/UText.styles.js

@@ -0,0 +1,91 @@
+import { css } from "lit";
+//#region src/components/text/UText.styles.ts
+var styles = css`
+  :host {
+    display: block;
+    color: var(--u-txt-color, #212121);
+  }
+
+  /*
+   * 기본은 body 다. :host([variant="body"]) 규칙을 따로 두지 않는 이유는
+   * 값이 같기 때문이며, 부수 효과로 **알 수 없는 variant 가 body 로 흐른다**
+   * (조용히 폰트가 사라지는 것보다 낫다).
+   */
+  .text {
+    margin: 0;
+    font-family: inherit;
+    font-size: var(--u-text-body-size, 14px);
+    font-weight: var(--u-text-body-weight, 400);
+    line-height: var(--u-text-body-leading, 1.6);
+    letter-spacing: var(--u-text-body-tracking, 0);
+  }
+
+  :host([variant="display"]) .text {
+    font-size: var(--u-text-display-size, 26px);
+    font-weight: var(--u-text-display-weight, 700);
+    line-height: var(--u-text-display-leading, 1.4);
+    letter-spacing: var(--u-text-display-tracking, -0.02em);
+  }
+
+  :host([variant="title"]) .text {
+    font-size: var(--u-text-title-size, 20px);
+    font-weight: var(--u-text-title-weight, 700);
+    line-height: var(--u-text-title-leading, 1.45);
+    letter-spacing: var(--u-text-title-tracking, -0.01em);
+  }
+
+  :host([variant="subtitle"]) .text {
+    font-size: var(--u-text-subtitle-size, 16px);
+    font-weight: var(--u-text-subtitle-weight, 600);
+    line-height: var(--u-text-subtitle-leading, 1.5);
+    letter-spacing: var(--u-text-subtitle-tracking, 0);
+  }
+
+  :host([variant="label"]) .text {
+    font-size: var(--u-text-label-size, 13px);
+    font-weight: var(--u-text-label-weight, 600);
+    line-height: var(--u-text-label-leading, 1.5);
+    letter-spacing: var(--u-text-label-tracking, 0);
+  }
+
+  :host([variant="caption"]) .text {
+    font-size: var(--u-text-caption-size, 12px);
+    font-weight: var(--u-text-caption-weight, 400);
+    line-height: var(--u-text-caption-leading, 1.5);
+    letter-spacing: var(--u-text-caption-tracking, 0);
+  }
+
+  /*
+   * ⚠ overline 에 text-transform: uppercase 를 붙이지 않는다.
+   *
+   * 눈썹 텍스트의 관습이긴 하나 ⑴시트가 정의하는 것은 네 속성뿐이라 다섯 번째를 여기서
+   * 정하면 이 컴포넌트가 «두 번째 정의처»가 되고 ⑵소비자가 쓴 글자를 조용히 바꾸며
+   * ⑶CJK 에는 아무 효과가 없어 **같은 단이 언어에 따라 다르게 보인다.**
+   * 대문자가 필요한 자리는 그 자리가 정한다.
+   */
+  :host([variant="overline"]) .text {
+    font-size: var(--u-text-overline-size, 11px);
+    font-weight: var(--u-text-overline-weight, 700);
+    line-height: var(--u-text-overline-leading, 1.45);
+    letter-spacing: var(--u-text-overline-tracking, 0.06em);
+  }
+
+  /*
+   * tone 은 **중립 강조 축**이다 — 역할색(info/success/danger…)이 아니다.
+   * 소비앱 실측에서 나온 색 다섯 중 셋이 이 축이었고, 나머지 둘은 링크와
+   * 콜아웃 박스라 u-text 의 문제가 아니었다.
+   */
+  :host([tone="weak"]) {
+    color: var(--u-txt-color-weak, #757575);
+  }
+
+  :host([tone="strong"]) {
+    color: var(--u-txt-color-strong, #000000);
+  }
+
+  :host([tone="inverse"]) {
+    color: var(--u-txt-color-inverse, #FFFFFF);
+  }
+`;
+//#endregion
+export { styles };

package/dist/index.d.ts

@@ -41,6 +41,7 @@ export * from './components/switch/USwitch.js';
 export * from './components/tab/UTab.js';
 export * from './components/tab-panel/UTabPanel.js';
 export * from './components/tag/UTag.js';
+export * from './components/text/UText.js';
 export * from './components/textarea/UTextarea.js';
 export * from './components/tooltip/UTooltip.js';
 export * from './components/tree/UTree.js';

package/dist/index.js

@@ -47,6 +47,7 @@ import { USplitPanel } from "./components/split-panel/USplitPanel.js";
 import { USwitch } from "./components/switch/USwitch.js";
 import { UTab } from "./components/tab/UTab.js";
 import { UTabPanel } from "./components/tab-panel/UTabPanel.js";
+import { UText } from "./components/text/UText.js";
 import { UTextarea } from "./components/textarea/UTextarea.js";
 import { UTreeItem } from "./components/tree-item/UTreeItem.js";
 import { UTree } from "./components/tree/UTree.js";
@@ -54,4 +55,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, 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 };
+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, UText, UTextarea, UTooltip, UTree, UTreeItem, arrayAttrConverter, booleanAttrConverter, dateAttrConverter, getDefaultBaseUrl, getParentElement, jsonAttrConverter, querySelectorAllWithin, querySelectorWithin, setDefaultBaseUrl, urlAttrConverter };

package/dist/react/UText.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+import { UText as UTextElement } from '../components/text/UText';
+
+export declare const UText: React.ForwardRefExoticComponent<
+  Omit<Partial<UTextElement>, keyof React.HTMLAttributes<UTextElement>>
+    & Omit<React.HTMLAttributes<UTextElement>, never>
+    & React.RefAttributes<UTextElement>
+    & {
+  }
+>;
+
+export type UTextProps = React.ComponentProps<typeof UText>;

package/dist/react/UText.js

@@ -0,0 +1,10 @@
+import React from 'react';
+import { createComponent } from '@lit/react';
+import { UText as UTextElement } from '../components/text/UText.js';
+
+export const UText = createComponent({
+  react: React,
+  tagName: 'u-text',
+  elementClass: UTextElement,
+  events: {},
+});

package/dist/react/index.d.ts

@@ -2,6 +2,7 @@ export { UTreeItem, UTreeItemProps } from './UTreeItem';
 export { UTree, UTreeProps } from './UTree';
 export { UTooltip, UTooltipProps } from './UTooltip';
 export { UTextarea, UTextareaProps } from './UTextarea';
+export { UText, UTextProps } from './UText';
 export { UTag, UTagProps } from './UTag';
 export { UTabPanel, UTabPanelProps } from './UTabPanel';
 export { UTab, UTabProps } from './UTab';

package/dist/react/index.js

@@ -2,6 +2,7 @@ export { UTreeItem } from './UTreeItem.js';
 export { UTree } from './UTree.js';
 export { UTooltip } from './UTooltip.js';
 export { UTextarea } from './UTextarea.js';
+export { UText } from './UText.js';
 export { UTag } from './UTag.js';
 export { UTabPanel } from './UTabPanel.js';
 export { UTab } from './UTab.js';

package/dist/utilities/Theme.d.ts

@@ -85,6 +85,19 @@ export declare class Theme {
      *
      * ⚠**변수는 `documentElement` 의 인라인 스타일로 들어간다** — 시트보다 우선하므로
      * 로드 순서에 기대지 않는다.
+     *
+     * 🔴**`--u-primary-bg-color` 는 세팅하지 않는다 — 이 자가 덮는 것은 7종 중 6종이다.**
+     * 그 토큰은 «글자를 얹는 옅은 면»(`u-tag` 의 `--tag-hue-surface`)이라 램프의 어느 단과도
+     * 성질이 다르고, 시트는 그 자리를 **5계열 × 2테마 = 10개 값으로 손수 짝지어** 두었다
+     * (라이트/다크가 같은 대비비를 쓰지 않는다 — 실측 1.14 대 1.03). 도출식으로 바꾸는 것은
+     * 팔레트 값 결정이라 사람 판단이 필요하다.
+     *
+     * ⇒ **시드만 넣으면 태그·선택된 행 같은 옅은 면이 파랑으로 남는다.** 함께 세팅할 것:
+     *
+     * ```ts
+     * Theme.accent('#7c3aed');
+     * document.documentElement.style.setProperty('--u-primary-bg-color', '#f3e8ff');
+     * ```
      */
     static accent(seed: string | null): void;
     /** 현재 시드를 현재 테마의 바탕에 맞춰 다시 계산해 적용한다. */

package/dist/utilities/Theme.js

@@ -186,6 +186,19 @@ var Theme = class {
 	*
 	* ⚠**변수는 `documentElement` 의 인라인 스타일로 들어간다** — 시트보다 우선하므로
 	* 로드 순서에 기대지 않는다.
+	*
+	* 🔴**`--u-primary-bg-color` 는 세팅하지 않는다 — 이 자가 덮는 것은 7종 중 6종이다.**
+	* 그 토큰은 «글자를 얹는 옅은 면»(`u-tag` 의 `--tag-hue-surface`)이라 램프의 어느 단과도
+	* 성질이 다르고, 시트는 그 자리를 **5계열 × 2테마 = 10개 값으로 손수 짝지어** 두었다
+	* (라이트/다크가 같은 대비비를 쓰지 않는다 — 실측 1.14 대 1.03). 도출식으로 바꾸는 것은
+	* 팔레트 값 결정이라 사람 판단이 필요하다.
+	*
+	* ⇒ **시드만 넣으면 태그·선택된 행 같은 옅은 면이 파랑으로 남는다.** 함께 세팅할 것:
+	*
+	* ```ts
+	* Theme.accent('#7c3aed');
+	* document.documentElement.style.setProperty('--u-primary-bg-color', '#f3e8ff');
+	* ```
 	*/
 	static accent(seed) {
 		this.accentSeed = seed;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@iyulab/components",
   "description": "web-components library based on lit-element made by iyulab",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "keywords": [
     "iyulab",
     "components",
@@ -42,14 +42,15 @@
     "test:browser": "vitest run --project=browser",
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix",
-    "build": "eslint && npm run typecheck:plugins && vite build && npm run build:plugins && npm run test:react-types",
+    "build": "npm run typecheck && eslint && npm run typecheck:plugins && vite build && npm run build:plugins && npm run test:react-types",
     "test:react-types": "tsc -p tsconfig.react-smoke.json",
     "typecheck:plugins": "tsc -p plugins/tsconfig.json",
     "docs:cssprops": "node scripts/cssprops-doc.mjs --write",
     "docs:react-events": "node scripts/react-events-doc.mjs --write",
     "docs:tokens": "node scripts/design-tokens-doc.mjs --write",
     "build:plugins": "tsc -p plugins/tsconfig.build.json",
-    "probe:seed-ramp": "node scripts/seed-ramp.mjs"
+    "probe:seed-ramp": "node scripts/seed-ramp.mjs",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@floating-ui/dom": "^1.8.0",

package/skills/iyulab-components/SKILL.md

@@ -59,6 +59,7 @@ import { UButton, UInput } from '@iyulab/components/react';
 
 - [`u-button`](./references/components/button.md) — Versatile button with multiple variants; renders as `<a>` when `href` is set
 - [`u-icon-button`](./references/components/icon-button.md) — Square icon-only button with built-in tooltip
+- [`u-copy-button`](./references/components/copy-button.md) — Copies text to the clipboard with a transient confirmation
 - [`u-button-group`](./references/components/button-group.md) — Groups buttons with shared variant and disabled state
 
 ### Form Controls
@@ -109,6 +110,7 @@ import { UButton, UInput } from '@iyulab/components/react';
 - [`u-chip`](./references/components/chip.md) — Selectable/removable chip tag
 - [`u-tag`](./references/components/tag.md) — Non-interactive label tag
 - [`u-icon`](./references/components/icon.md) — SVG icon from built-in or external icon library
+- [`u-text`](./references/components/text.md) — Semantic typography step; optional heading level
 
 ---
 

package/skills/iyulab-components/references/components/copy-button.md

@@ -0,0 +1,80 @@
+# u-copy-button
+
+```ts
+import '@iyulab/components/dist/components/copy-button/UCopyButton.js';
+```
+
+**Tag:** `u-copy-button`
+
+Copies text to the clipboard and shows a transient confirmation by swapping its icon.
+
+Two shapes:
+
+- **Icon only** (default) — the default slot becomes the tooltip.
+- **Icon + label** — set `label` to render visible text beside the icon.
+
+The clipboard logic is identical in both.
+
+```html
+<!-- Icon only; slot content is the tooltip -->
+<u-copy-button value="npm i @iyulab/components">Copy install command</u-copy-button>
+
+<!-- Icon + label -->
+<u-copy-button value="RESULT-1024" label="Copy result"></u-copy-button>
+
+<!-- Stays in the copied state until reset explicitly -->
+<u-copy-button value="token" .delay=${0}></u-copy-button>
+```
+
+## Changing or cancelling what gets copied
+
+The `copy` event fires **before** the write, so a handler can rewrite the payload or cancel:
+
+```ts
+button.addEventListener('copy', (e: ClipboardEvent) => {
+  e.clipboardData?.setData('text/plain', transform(button.value));
+  e.preventDefault(); // cancel the built-in write
+});
+```
+
+---
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| *(default)* | Tooltip content, icon-only shape. Unused when `label` is set |
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `variant` | `'solid'\|'outline'\|'ghost'\|'link'` | `'ghost'` | ✓ | Button style |
+| `rounded` | `boolean` | `false` | ✓ | Circular shape |
+| `disabled` | `boolean` | `false` | ✓ | Disabled state |
+| `copied` | `boolean` | `false` | ✓ | Currently showing the copied state |
+| `tooltipPlacement` | `Placement` | `"top"` | | Tooltip placement (`tooltip-placement`) |
+| `tooltipOffset` | `OffsetOptions` | `4` | | Tooltip distance (`tooltip-offset`) |
+| `delay` | `number` | `1_000` | | Milliseconds before leaving the copied state; `0` or less keeps it |
+| `value` | `string` | — | | Text to copy |
+| `label` | `string` | — | | Inline label; switches to the icon + label shape |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `copy` | native `ClipboardEvent` | Fires before the write. `preventDefault()` cancels it; `clipboardData.setData` replaces the payload |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `button` | Inner button element |
+| `icon` | Icon element |
+| `tooltip` | Tooltip element (icon-only shape) |
+
+## Sizing
+
+This component keeps a **fixed** font size (18px) rather than inheriting the surrounding
+typography — it reads as an affordance next to text of any size. See
+[design-tokens.md](../../../../docs/design-tokens.md) for the four components that do this.

package/skills/iyulab-components/references/components/icon.md

@@ -30,8 +30,19 @@ Renders an SVG icon by name from a registered icon library. Inline `src` also ac
 <u-icon src='<svg ...>...</svg>'></u-icon>
 ```
 
+```html
+<!-- Fallback: drawn when the name does not resolve -->
+<u-icon name="might-not-exist" fallback='<svg viewBox="0 0 16 16">...</svg>'></u-icon>
+```
+
 For registering custom libraries, see [icons.md](../utilities/icons.md).
 
+> **When you need `fallback`.** An icon that fails to resolve renders nothing. That is usually
+> harmless — but not where the icon is the only hit target. A collapsed sidebar hides labels, so
+> a nav item with no visible icon becomes an **empty row the user cannot click**: the screen
+> becomes unreachable. `fallback` covers all three failure modes (no `name`, 404, unparseable SVG).
+> Keep the fallback **inline**; a fallback that fetches reproduces the very failure it covers.
+
 ---
 
 ## Properties
@@ -41,6 +52,7 @@ For registering custom libraries, see [icons.md](../utilities/icons.md).
 | `lib` | `'internal'\|'tabler'\|'heroicons'\|'lucide'\|'bootstrap'\|string` | — | Icon library identifier |
 | `name` | `string` | — | Icon name (library-specific; append `:filled` / `:solid` for filled variants) |
 | `src` | `string` | — | Raw SVG string (overrides `lib`/`name`) |
+| `fallback` | `string` | — | Raw SVG drawn when `name`/`src` cannot be resolved (missing, 404, or unparseable) |
 
 ## CSS Parts
 

package/skills/iyulab-components/references/components/text.md

@@ -0,0 +1,79 @@
+# u-text
+
+```ts
+import '@iyulab/components/dist/components/text/UText.js';
+```
+
+**Tag:** `u-text`
+
+Semantic typography. Applies one of the seven design-token type steps
+(`display` → `overline`) so markup can use the scale without any consumer CSS.
+The component reads the token sheet — it never defines its own type values.
+
+```html
+<u-text level="1" variant="display">Document title</u-text>
+<u-text variant="subtitle" tone="weak">One-line description</u-text>
+
+<u-text>Body copy is the default step.</u-text>
+<u-text variant="caption" tone="weak">Helper text</u-text>
+
+<u-text variant="overline">Section</u-text>
+```
+
+## Visual step and heading level are independent
+
+`variant` chooses how the text *looks*; `level` chooses what it *is*. When
+`level` is set the component renders a real `<h1>`–`<h6>` in its shadow root, so
+assistive technology reads it as a heading whose accessible name is the slotted
+text. Without `level` it renders a `<p>`.
+
+```html
+<!-- Second-level heading that is visually the largest thing on the page -->
+<u-text level="2" variant="display">Overview</u-text>
+```
+
+This keeps the document outline honest while leaving the visual hierarchy free.
+
+> **Do not nest a heading inside the slot** — `<u-text><h2>…</h2></u-text>` makes
+> the UA rule `h2 { font-size: 1.5em }` multiply the step's font size. Use
+> `level` instead. Wrapping the other way (`<h2><u-text>…</u-text></h2>`) is safe
+> because the steps are absolute sizes, but the outer heading keeps its UA
+> margin, so `level` is still the simpler choice.
+
+## Colour
+
+`tone` is a **neutral emphasis axis**, not a role-colour axis. Semantic status
+colour belongs to the component that owns the status (`u-alert`, `u-tag`,
+`u-badge`), and link colour belongs to the link.
+
+---
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| *(default)* | Text content |
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `variant` | `'display'\|'title'\|'subtitle'\|'body'\|'label'\|'caption'\|'overline'` | `'body'` | ✓ | Semantic type step |
+| `tone` | `'default'\|'weak'\|'strong'\|'inverse'` | `'default'` | ✓ | Neutral emphasis axis |
+| `level` | `1\|2\|3\|4\|5\|6` | — | ✓ | Heading level; renders `<h1>`–`<h6>` |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `base` | The rendered `<p>` or `<h1>`–`<h6>` element |
+
+## Design tokens read
+
+| Step | Tokens |
+|------|--------|
+| `display` · `title` · `subtitle` · `body` · `label` · `caption` · `overline` | `--u-text-{step}-size`, `--u-text-{step}-weight`, `--u-text-{step}-leading`, `--u-text-{step}-tracking` |
+| `tone` | `--u-txt-color`, `--u-txt-color-weak`, `--u-txt-color-strong`, `--u-txt-color-inverse` |
+
+Spacing between blocks is **not** this component's concern — it has no margin.
+The surrounding layout decides rhythm (`u-group-box`, `u-card`, a flex column).

package/skills/iyulab-components/references/usage.md

@@ -78,6 +78,32 @@ accent surface ≥ 4.5:1, accent text on the page background ≥ 4.5:1, `-strong
 from `-color`, and `-weak` usable as a non-text graphic (≥ 3:1). It is **recalculated when the
 theme changes**, because those targets are relative to the page background.
 
+#### How many tokens does the `primary` role have? **Seven.**
+
+`Theme.accent()` sets **six** of them:
+
+| Token | `Theme.accent()` | What reads it |
+|---|---|---|
+| `--u-primary-color` | ✅ | accent surface — 21 source files |
+| `--u-primary-color-strong` | ✅ | text/icons on the page background; hover · active · link · focus ring — 14 files |
+| `--u-primary-color-weak` | ✅ | non-text graphics |
+| `--u-primary-color-weaker` | ✅ | decorative |
+| `--u-primary-color-weakest` | ✅ | decorative |
+| `--u-primary-txt-color` | ✅ | text on the accent surface |
+| **`--u-primary-bg-color`** | 🔴**no** | tinted **surface behind text** — `u-tag`'s `--tag-hue-surface` |
+
+🔴 **`Theme.accent()` does not touch `--u-primary-bg-color`.** It stays on the sheet default
+(a blue tint), so a seeded brand leaves tinted surfaces blue. Set it yourself alongside the seed:
+
+```ts
+Theme.accent('#7c3aed');
+document.documentElement.style.setProperty('--u-primary-bg-color', '#f3e8ff');
+```
+
+Pick a tint that keeps your body text readable on it — the built-in sheet values sit at roughly
+1.14:1 (light) and 1.03:1 (dark) against the page background. Deriving this step automatically is
+tracked as open work, because the sheet pairs it by hand across five colour roles and two themes.
+
 **Manual override** — you must set the steps you use, not just one:
 
 ```css
@@ -86,11 +112,36 @@ theme changes**, because those targets are relative to the page background.
   --u-primary-color: #7c3aed;         /* accent surface */
   --u-primary-color-strong: #5b21b6;  /* text/icons on the page background */
   --u-primary-txt-color: #ffffff;     /* text on the accent surface */
+  --u-primary-bg-color: #f3e8ff;      /* tinted surface behind text */
 }
 ```
 
 ⚠ Setting `--u-primary-color` alone is **not enough**: hover/focus/link colors resolve from
 `--u-primary-color-strong`, so they stay on the default ramp and your brand looks half-applied.
+The measured symptom is a *selected table row* or *tag* that stays blue while buttons turn brand —
+that one is `--u-primary-bg-color`.
+
+### Typography
+
+The sheet defines seven semantic steps — `display`, `title`, `subtitle`, `body`, `label`,
+`caption`, `overline` — each with `-size`, `-weight`, `-leading`, `-tracking`. Use them from
+markup with [`u-text`](./components/text.md) instead of writing your own CSS:
+
+```html
+<u-text level="1" variant="display">Document title</u-text>
+<u-text variant="subtitle" tone="weak">One-line description</u-text>
+<u-text>Body copy</u-text>
+<u-text variant="caption" tone="weak">Helper text</u-text>
+```
+
+`variant` is the visual step and `level` is the document level — they are independent, and
+`level` renders a real `<h1>`–`<h6>` so the heading is read as one.
+
+To rebrand typography, override the tokens rather than the screens:
+
+```css
+:root { --u-text-title-size: 22px; --u-text-title-weight: 800; }
+```
 
 ---