@iyulab/components 1.40.2 → 1.41.0

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # Changelog
 
+## [1.41.0] - 2026-09-16
+
+### Fixed
+
+- **`u-field` drew its label but never connected it to the control it wraps** — the shadow `label`
+  had no `for`, and the slotted control's `id`, `aria-label` and `aria-labelledby` were all empty.
+  Every control in a labelled form was therefore unnamed in the accessibility tree while looking
+  completely normal on screen, with no console signal. This is the exact shape this package's own
+  reference documentation teaches (`<u-field label="Email"><u-input></u-input></u-field>`), so
+  following the docs produced the defect. `u-field` now copies its `label` onto the slotted element
+  as `aria-label` (and `description` as `aria-description`); `aria-labelledby` is not usable here
+  because it does not cross shadow boundaries.
+- **`u-field.focus()` and clicking its label did nothing when a custom-element control was
+  slotted** — the target search used a focusability test that does not look inside shadow roots, so
+  it only ever matched native elements. It now also recognizes form-associated custom elements, and
+  falls back to searching inside a slotted wrapper.
+- **`u-switch` ignored its inherited `label` property** — unlike its sibling `u-checkbox`, the
+  default slot had no fallback, so `<u-switch label="…">` rendered neither a visible label nor an
+  accessible name.
+- **A field label did not reach `u-checkbox`, `u-switch` or `u-file-input`.** Those three take
+  their accessible name from their own content — the first two wrap the native control in a
+  `<label>`, and the third's focusable element is a "choose file" button — so the mechanism that
+  works for the other seven controls did nothing for them. An empty checkbox or switch inside a
+  labelled field was named by nothing but its required marker. They now take the field's label
+  when, and only when, they have no name of their own.
+
+### Added
+
+- **Form controls now forward a host `aria-label` / `aria-description` to the native control inside
+  their shadow root.** Previously only `u-button` did this, so setting `aria-label` directly on
+  `u-input`, `u-select`, `u-textarea`, `u-date-picker`, `u-radio`, `u-rating` or `u-slider` had no
+  effect on the accessible name. A control's own `label` still wins over the host attribute.
+- **Two development-mode warnings on `u-field`**: a label with nothing focusable in the default
+  slot (the label names nothing), and a label set on both the field and the slotted control (the
+  label renders twice).
+
+### Notes
+
+- A control that already carries its own `label`, `aria-label` or `aria-labelledby` is left
+  untouched — overriding it would make the visible label and the accessible name disagree
+  (WCAG SC 2.5.3 Label in Name).
+- `u-file-input` **composes** rather than overrides: its trigger is named "<visible text>,
+  <field label>", so the visible text stays part of the accessible name (SC 2.5.3) while several
+  file pickers on one screen remain distinguishable.
+- All ten form controls are covered by a reach gate that drives each one in a real browser
+  (`tests/browser/field-name-reach-census.browser.test.ts`). A new form control has to be added to
+  that table or it sits outside the gate.
+
+## [1.40.3] - 2026-09-13
+
+### Fixed
+
+- **`createDevWarner`/`devWarnOnce`, and the `u-icon`/`u-split-panel` warnings built on them, were
+  a complete no-op in every published release since 1.40.1** — the guard used
+  `import.meta.env.DEV`, which Vite resolves statically at this library's own build time (not the
+  consumer's), so the published dist always shipped with `false` baked in and Rollup's dead-code
+  elimination removed the warning body entirely. No published dev-mode warning from this package
+  has ever actually fired for a consumer. Replaced with `process.env.NODE_ENV !== 'production'`,
+  which this library's own build leaves untouched and each consumer's own bundler resolves against
+  its own dev/production build (the same convention used by other libraries in this ecosystem for
+  the same reason). A new test asserts the built dist directly, not just the source.
+
 ## [1.40.2] - 2026-09-13
 
 ### Added

package/README.md

@@ -128,6 +128,37 @@ Theme.set('system');
 
 자세한 내용은 [docs/theming.md](./docs/theming.md)를 참고하세요.
 
+## Accessibility
+
+기준판은 **WCAG 2.2** 입니다. 아래는 이 패키지가 **테스트로 재서 보장하는 것**이고, 그 밖의
+성공 기준까지 포함한 전체 준수 선언이 아닙니다.
+
+| 성공 기준 | 보장 | 어디서 재는가 |
+|---|---|---|
+| SC 1.4.3 · 1.4.11 명암비 | 역할 토큰의 `-color`·`-color-strong`·`-bg-color` 단계가 텍스트 4.5 / 비텍스트 3.0 을 라이트·다크 양쪽에서 충족 | `tests/build/token-contrast.test.ts` |
+| SC 2.5.8 타깃 크기(최소) | 등록된 모든 컴포넌트의 포인터 타깃이 24×24 CSS px 이상이거나 간격 예외(중심 간 24px)를 충족하고, 그 좌표에서 실제로 눌린다 | `tests/browser/target-size.browser.test.ts`(실제 크로미움) |
+| SC 2.1.1 키보드(포인터 커서 검사) | 픽스처가 그리는 어떤 요소도 포인터 커서를 보이면서 상호작용 요소가 아닌 채로 있지 않다 — 클릭만 받는 `div` 가 들어오지 못한다(키 처리 자체는 컴포넌트 테스트가 잰다) | 같은 파일 |
+| SC 1.3.1 정보와 관계 · SC 4.1.2 이름·역할·값 | `u-field` 의 `label`/`description` 이 슬롯된 컨트롤의 접근성 이름·설명으로 실제로 도달한다(네이티브 엘리먼트 · `u-*` 폼 컨트롤 양쪽) | `tests/browser/field-label-association.browser.test.ts` |
+
+🔴**폼 컨트롤의 접근성 이름은 «한 곳에서만» 준다.** `u-field` 는 자기 `label` 을 슬롯된 컨트롤에
+`aria-label` 로 얹고(섀도우 경계를 넘지 못하는 `aria-labelledby` 대신 문자열 복사다), 폼 컨트롤은
+호스트의 `aria-label` 을 내부 네이티브 컨트롤로 내려보낸다. **컨트롤이 자기 `label`·`aria-label`·
+`aria-labelledby` 를 이미 가지면 `u-field` 는 덮지 않는다** — 덮으면 눈에 보이는 라벨과 접근성
+이름이 어긋난다(SC 2.5.3 Label in Name). 양쪽에 `label` 을 주면 라벨이 **두 번 그려지고**, 개발
+모드 콘솔이 그 자리를 지목한다.
+
+```html
+<!-- ✅ 라벨은 한 곳 -->
+<u-field label="Keyword"><u-input></u-input></u-field>
+<u-input label="Keyword"></u-input>
+
+<!-- ❌ 두 번 그려진다 -->
+<u-field label="Keyword"><u-input label="Keyword"></u-input></u-field>
+```
+
+⚠ 타깃 크기 보장은 `--u-density` **`14px` 이상**에서 성립합니다 — 컨트롤 패딩이 `em` 이라 그보다
+낮추면 타깃이 함께 줄어듭니다([docs/theming.md](./docs/theming.md)의 밀도 절 참고).
+
 ## Localization
 
 라이브러리가 **스스로 생성하는 문자열**(검증 메시지)은 내장 로케일 14종을 갖고 있으며,

package/dist/components/UElement.js

@@ -1,12 +1,37 @@
 import { styles } from "./UElement.styles.js";
 import { LitElement, render } from "lit";
 //#region src/components/UElement.ts
+/**
+* 모든 UI 컴포넌트의 기반 클래스.
+* LitElement를 확장하여 이벤트 발행 및 렌더 교체 헬퍼를 제공합니다.
+*/
+/**
+* 디자인 토큰 시트 부재를 개발 빌드에서 1회 경고한다.
+*
+* 토큰이 없으면 컴포넌트 시트의 `var(--u-…)` 가 전부 무효가 되어 테두리·배경이 **에러 없이**
+* 사라진다. CSS 는 이때 아무 신호도 내지 않으므로, 소비자는 자기 CSS 를 의심하며 며칠을 쓴다.
+* 실제로 운영 화면이 무스타일로 렌더된 사례가 있었다 — 토큰 주입이 `Theme.init()` 호출
+* (셸이 대신 부른다)에만 딸려 있어서, 셸 밖에서 렌더되는 로그인 화면만 조용히 깨졌다.
+*
+* ★리터럴 폴백(1.14.0)이 그 **소멸**은 막는다. 그래도 경고는 유지한다 — 폴백은 라이트
+* 시트 값을 구워 넣은 것이라 **다크 테마가 라이트 색으로 렌더되고**, 테마 변수 오버라이드도
+* 먹지 않는다. 폴백은 *"조용히 사라지지 않게"* 하는 안전망이지 *"시트 없이 써도 된다"* 가
+* 아니다. 둘을 섞으면 이 경고가 고발하는 무증상 열화가 형태만 바꿔 돌아온다.
+*/
+var tokenCheckDone = false;
+function warnIfTokensMissing() {
+	if (tokenCheckDone || typeof document === "undefined") return;
+	tokenCheckDone = true;
+	if (getComputedStyle(document.documentElement).getPropertyValue("--u-blue-600").trim()) return;
+	console.warn("[@iyulab/components] No design-token sheet found in the document — components render with their built-in fallbacks (baked from the light theme). Dark theme and theme variable overrides will not apply.\n  Static CSS:  import '@iyulab/components/styles/tokens.css'\n  At runtime:  Theme.init()\n  (The @iyulab/modern-app shell calls Theme.init() for you. Screens rendered outside the shell — login, onboarding, embeds — need one of the two.)");
+}
 var UElement = class extends LitElement {
 	static {
 		this.styles = styles;
 	}
 	connectedCallback() {
 		super.connectedCallback();
+		if (process.env.NODE_ENV !== "production") warnIfTokensMissing();
 	}
 	/**
 	* 커스텀 이벤트를 생성하여 발행합니다.

package/dist/components/UFormControlElement.d.ts

@@ -62,6 +62,42 @@ export declare abstract class UFormControlElement<T> extends UElement {
      */
     protected commit(flags: ValidityStateFlags, message: string, anchor?: HTMLElement): void;
     connectedCallback(): void;
+    /**
+     * 호스트에 세팅된 `aria-label`/`aria-description` 은 접근성 트리에 노출되는 노드가 아니다 —
+     * 그것은 shadow DOM 안쪽의 네이티브 컨트롤이고, 섀도우 경계를 넘지 않으므로 자동으로
+     * 반영되지 않는다(속성은 붙어 있는데 접근 가능한 이름이 빈 채로 남는다).
+     *
+     * ⚠**이 처방은 오랫동안 `u-button` 한 곳에만 있었다.** 폼 컨트롤 열 종이 같은 구조인데
+     * 같은 경로가 없어서, 바깥에서 라벨을 소유하는 래퍼(`u-field`)가 슬롯된 컨트롤에 이름을
+     * 줄 수단 자체가 없었다 — 라벨은 그려지는데 컨트롤은 이름이 없는 «조용한 결함» 이다.
+     * ⇒ 사본을 열 벌 만드는 대신 **공통 기반에 한 번** 둔다.
+     *
+     * ⚠`aria-label` 은 Lit 리액티브 프로퍼티가 아니라 `observedAttributes` 에 없다 — 그 목록에
+     * 없는 속성은 `attributeChangedCallback` 자체가 호출되지 않아(커스텀 엘리먼트 표준 동작)
+     * 초기 렌더만 되고 연결 후 변경이 반영되지 않는다. 명시적으로 추가해야 한다.
+     */
+    static get observedAttributes(): string[];
+    attributeChangedCallback(name: string, old: string | null, value: string | null): void;
+    /**
+     * 내부 네이티브 컨트롤에 실을 접근성 이름. 자기 `label` 이 우선이고, 없으면 호스트의
+     * `aria-label` 을 쓴다 — 후자는 `u-field` 같은 «바깥 라벨 소유자» 가 채우는 경로다.
+     */
+    protected get resolvedAriaLabel(): string | undefined;
+    /**
+     * 이름을 **자기 내용에서** 얻는 컨트롤(`u-checkbox`·`u-switch`)용 축.
+     *
+     * 그 둘은 네이티브 `<label>` 이 컨트롤을 감싸는 구조라, 감싸개 안의 텍스트가 곧 접근성
+     * 이름이다 — 그래서 위 `resolvedAriaLabel` 처럼 **무조건** 얹으면 눈에 보이는 라벨을
+     * 덮어쓴다(WCAG SC 2.5.3 Label in Name). ⇒ 자기 `label` 도 슬롯 내용도 없어서 감싸개가
+     * **비어 있을 때만** 호스트의 `aria-label` 을 쓴다. 전수 실측에서 라벨을 단 `u-field`
+     * 안에 빈 체크박스/스위치를 넣으면 이름이 «별표 하나» 뿐이었다.
+     */
+    protected get contentAriaLabel(): string | undefined;
+    protected hasSlottedLabel: boolean;
+    /** 기본 슬롯에 실제 내용이 들어왔는지 — 공백만 있는 텍스트 노드는 내용이 아니다. */
+    protected handleLabelSlotChange: (e: Event) => void;
+    /** `resolvedAriaLabel` 과 같은 규칙의 설명 축. */
+    protected get resolvedAriaDescription(): string | undefined;
     protected updated(changedProperties: PropertyValues): void;
     /**
      * 어떤 속성이 바뀌었을 때 `setValidity()`를 다시 호출할지 결정합니다.

package/dist/components/UFormControlElement.js

@@ -2,7 +2,7 @@ import { UElement } from "./UElement.js";
 import __decorateMetadata from "../_virtual/_@oxc-project_runtime@0.149.0/helpers/esm/decorateMetadata.js";
 import __decorate from "../_virtual/_@oxc-project_runtime@0.149.0/helpers/esm/decorate.js";
 import { styles } from "./UFormControlElement.styles.js";
-import { property } from "lit/decorators.js";
+import { property, state } from "lit/decorators.js";
 //#region src/components/UFormControlElement.ts
 /**
 * 폼 컨트롤 컴포넌트의 공통 기반 클래스입니다.
@@ -17,6 +17,11 @@ var UFormControlElement = class extends UElement {
 		this.invalid = false;
 		this.novalidate = false;
 		this.customMessage = "";
+		this.hasSlottedLabel = false;
+		this.handleLabelSlotChange = (e) => {
+			const slot = e.target;
+			this.hasSlottedLabel = slot.assignedNodes({ flatten: true }).some((n) => n.nodeType === Node.ELEMENT_NODE || !!n.textContent?.trim());
+		};
 	}
 	static {
 		this.styles = [super.styles, styles];
@@ -68,6 +73,55 @@ var UFormControlElement = class extends UElement {
 		super.connectedCallback();
 		if (!this.internals && "attachInternals" in this) this.internals = this.attachInternals();
 	}
+	/**
+	* 호스트에 세팅된 `aria-label`/`aria-description` 은 접근성 트리에 노출되는 노드가 아니다 —
+	* 그것은 shadow DOM 안쪽의 네이티브 컨트롤이고, 섀도우 경계를 넘지 않으므로 자동으로
+	* 반영되지 않는다(속성은 붙어 있는데 접근 가능한 이름이 빈 채로 남는다).
+	*
+	* ⚠**이 처방은 오랫동안 `u-button` 한 곳에만 있었다.** 폼 컨트롤 열 종이 같은 구조인데
+	* 같은 경로가 없어서, 바깥에서 라벨을 소유하는 래퍼(`u-field`)가 슬롯된 컨트롤에 이름을
+	* 줄 수단 자체가 없었다 — 라벨은 그려지는데 컨트롤은 이름이 없는 «조용한 결함» 이다.
+	* ⇒ 사본을 열 벌 만드는 대신 **공통 기반에 한 번** 둔다.
+	*
+	* ⚠`aria-label` 은 Lit 리액티브 프로퍼티가 아니라 `observedAttributes` 에 없다 — 그 목록에
+	* 없는 속성은 `attributeChangedCallback` 자체가 호출되지 않아(커스텀 엘리먼트 표준 동작)
+	* 초기 렌더만 되고 연결 후 변경이 반영되지 않는다. 명시적으로 추가해야 한다.
+	*/
+	static get observedAttributes() {
+		return [
+			...super.observedAttributes,
+			"aria-label",
+			"aria-description"
+		];
+	}
+	attributeChangedCallback(name, old, value) {
+		super.attributeChangedCallback(name, old, value);
+		if (name === "aria-label" || name === "aria-description") this.requestUpdate();
+	}
+	/**
+	* 내부 네이티브 컨트롤에 실을 접근성 이름. 자기 `label` 이 우선이고, 없으면 호스트의
+	* `aria-label` 을 쓴다 — 후자는 `u-field` 같은 «바깥 라벨 소유자» 가 채우는 경로다.
+	*/
+	get resolvedAriaLabel() {
+		return this.label ?? this.getAttribute("aria-label") ?? void 0;
+	}
+	/**
+	* 이름을 **자기 내용에서** 얻는 컨트롤(`u-checkbox`·`u-switch`)용 축.
+	*
+	* 그 둘은 네이티브 `<label>` 이 컨트롤을 감싸는 구조라, 감싸개 안의 텍스트가 곧 접근성
+	* 이름이다 — 그래서 위 `resolvedAriaLabel` 처럼 **무조건** 얹으면 눈에 보이는 라벨을
+	* 덮어쓴다(WCAG SC 2.5.3 Label in Name). ⇒ 자기 `label` 도 슬롯 내용도 없어서 감싸개가
+	* **비어 있을 때만** 호스트의 `aria-label` 을 쓴다. 전수 실측에서 라벨을 단 `u-field`
+	* 안에 빈 체크박스/스위치를 넣으면 이름이 «별표 하나» 뿐이었다.
+	*/
+	get contentAriaLabel() {
+		if (this.label || this.hasSlottedLabel) return void 0;
+		return this.getAttribute("aria-label") ?? void 0;
+	}
+	/** `resolvedAriaLabel` 과 같은 규칙의 설명 축. */
+	get resolvedAriaDescription() {
+		return this.description ?? this.getAttribute("aria-description") ?? void 0;
+	}
 	updated(changedProperties) {
 		super.updated(changedProperties);
 		if (this.shouldValidate(changedProperties)) this.setValidity();
@@ -117,5 +171,6 @@ __decorate([property({ type: String }), __decorateMetadata("design:type", String
 __decorate([property({ type: String }), __decorateMetadata("design:type", String)], UFormControlElement.prototype, "description", void 0);
 __decorate([property({ type: String }), __decorateMetadata("design:type", String)], UFormControlElement.prototype, "name", void 0);
 __decorate([property(), __decorateMetadata("design:type", Object)], UFormControlElement.prototype, "value", void 0);
+__decorate([state(), __decorateMetadata("design:type", Object)], UFormControlElement.prototype, "hasSlottedLabel", void 0);
 //#endregion
 export { UFormControlElement };

package/dist/components/checkbox/UCheckbox.js

@@ -6,6 +6,7 @@ import { Locale } from "../../utilities/Locale.js";
 import { styles } from "./UCheckbox.styles.js";
 import { html } from "lit";
 import { customElement, property, query } from "lit/decorators.js";
+import { ifDefined } from "lit/directives/if-defined.js";
 import { live } from "lit/directives/live.js";
 //#region src/components/checkbox/UCheckbox.ts
 var UCheckbox = class UCheckbox extends UFormControlElement {
@@ -43,6 +44,7 @@ var UCheckbox = class UCheckbox extends UFormControlElement {
       <label class="wrapper" part="wrapper">
         <input part="input"
           type="checkbox"
+          aria-label=${ifDefined(this.contentAriaLabel)}
           ?disabled=${this.disabled || this.readonly}
           ?required=${this.required}
           .checked=${live(this.checked)}
@@ -55,7 +57,7 @@ var UCheckbox = class UCheckbox extends UFormControlElement {
           ></u-icon>
         </span>
         <span class="label" part="label">
-          <slot>${this.label}</slot>
+          <slot @slotchange=${this.handleLabelSlotChange}>${this.label}</slot>
           <span class="required" ?hidden=${!this.required}>*</span>
         </span>
       </label>

package/dist/components/date-picker/UDatePicker.js

@@ -203,8 +203,8 @@ var UDatePicker = class UDatePicker extends UFormControlElement {
           role="combobox"
           aria-haspopup="dialog"
           aria-expanded=${this.open}
-          aria-label=${ifDefined(this.label)}
-          aria-description=${ifDefined(this.description)}
+          aria-label=${ifDefined(this.resolvedAriaLabel)}
+          aria-description=${ifDefined(this.resolvedAriaDescription)}
           aria-controls=${this.calendarId}
         >
           <span class="text-content ${!displayText ? "placeholder" : ""}">${displayText || this.placeholder || ""}</span>

package/dist/components/field/UField.d.ts

@@ -1,3 +1,4 @@
+import { PropertyValues } from 'lit';
 import { UElement } from '../UElement.js';
 /**
  * 폼 컨트롤의 공통 레이아웃을 제공하는 필드 컴포넌트입니다.
@@ -33,6 +34,51 @@ export declare class UField extends UElement {
      *  공개 API로도 노출해, 소비자가 임의의 폼 컨트롤(자체 웹 컴포넌트가 아닌 것 포함)을
      *  슬롯에 꽂아도 host의 `.focus()`가 `UInput.focus()`와 같은 계약으로 동작하게 한다. */
     focus(options?: FocusOptions): void;
+    private get assignedRoots();
+    /**
+     * 포커스 대상은 **감싸개 안쪽까지** 본다. 이 패키지의 폼 컨트롤들은 자기 내부 `u-field` 에
+     * `<div class="container">` 를 슬롯하고 진짜 `<input>` 은 그 안에 있다 — 최상위만 보면
+     * *라이브러리 자신의 정상 사용*이 «컨트롤 없음» 이 된다(첫 판이 실제로 그렇게 오탐했다).
+     */
+    private get focusTarget();
+    /**
+     * 라벨이 가리키는 대상 — `focus()` 와 접근성 이름 부여가 **같은 것**을 골라야 한다.
+     *
+     * 🔴**`isFocusable()` 만으로는 이 리포의 주된 사용 형태를 통째로 놓친다.** `tabbable` 은
+     * 기본적으로 섀도우 루트를 들여다보지 않으므로 `<u-input>` 같은 커스텀 엘리먼트 호스트에
+     * `false` 를 돌려준다(실측: `isFocusable(u-input)=false` · `isFocusable(<input>)=true`).
+     * ⇒ 종전 `focus()` 는 **네이티브 엘리먼트를 슬롯한 경우에만** 동작했고, 레퍼런스 문서가
+     * 가르치는 `u-*` 컨트롤 형태에서는 라벨 클릭이 **조용히 아무 일도 하지 않았다.**
+     *
+     * ⇒ 판정을 «포커스 가능» 하나가 아니라 **«폼 컨트롤인가»** 로 넓힌다: 네이티브로 포커스
+     * 가능하거나, **form-associated 커스텀 엘리먼트**(`static formAssociated = true` — 이
+     * 패키지의 `UFormControlElement` 전부가 그렇다)이면 대상이다. 섀도우를 파고들어 안쪽
+     * 네이티브 노드를 잡지는 않는다 — 그것은 컨트롤 자신의 API 를 우회하는 것이고, 그쪽이
+     * 다시 렌더하면 우리가 얹은 속성이 지워진다.
+     */
+    private get controlToName();
+    protected firstUpdated(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    /**
+     * 🔴**이 컴포넌트의 존재 이유가 «라벨과 컨트롤을 한 칸으로 짝짓는 것»인데, 오랫동안
+     * 라벨을 «그리기만» 하고 연결하지 않았다** — 섀도의 `label` 에 `for` 가 없고 슬롯된
+     * 컨트롤의 `id`·`aria-label`·`aria-labelledby` 가 전부 빈 채였다 — 라벨을 가진 폼 한 장이
+     * 통째로 «이름 없는 입력» 이 된다. 화면은 멀쩡하고 콘솔도 조용해서 **시각 사용자에게는
+     * 아무 신호가 없다.**
+     *
+     * ⚠**`aria-labelledby` 로 잇지 않는다 — 섀도우 경계를 넘지 못한다.** 그 대신 «문자열
+     * 복사»를 슬롯 호스트의 `aria-label` 로 얹고, 폼 컨트롤 쪽이 그것을 내부 네이티브
+     * 컨트롤로 내려보낸다(`UFormControlElement.resolvedAriaLabel` — `u-button` 이 먼저 채택한
+     * 처방을 공통 기반으로 올린 것). 네이티브 엘리먼트를 슬롯한
+     * 경우에는 그 호스트가 곧 컨트롤이라 같은 한 줄이 그대로 듣는다.
+     *
+     * ⚠**자기 이름을 이미 가진 컨트롤은 건드리지 않는다** — 그쪽이 더 구체적이고,
+     * 덮으면 눈에 보이는 라벨과 접근성 이름이 어긋난다(WCAG 2.5.3 Label in Name).
+     */
+    private nameSlottedControl;
+    /** 우리가 얹은 값인지 소비자가 준 값인지 가르기 위한 표식 — 소비자 값을 덮지 않는다. */
+    private lastAppliedLabel?;
+    private lastAppliedDescription?;
     private handleLabelClick;
 }
 declare global {

package/dist/components/field/UField.js

@@ -1,6 +1,7 @@
 import { UElement } from "../UElement.js";
 import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.149.0/helpers/esm/decorateMetadata.js";
 import __decorate from "../../_virtual/_@oxc-project_runtime@0.149.0/helpers/esm/decorate.js";
+import { devWarnOnce } from "../../utilities/devWarning.js";
 import { styles } from "./UField.styles.js";
 import { html, nothing } from "lit";
 import { customElement, property } from "lit/decorators.js";
@@ -43,11 +44,89 @@ var UField = class UField extends UElement {
 	*  공개 API로도 노출해, 소비자가 임의의 폼 컨트롤(자체 웹 컴포넌트가 아닌 것 포함)을
 	*  슬롯에 꽂아도 host의 `.focus()`가 `UInput.focus()`와 같은 계약으로 동작하게 한다. */
 	focus(options) {
-		const nodes = (this.shadowRoot?.querySelector("slot:not([name])"))?.assignedElements({ flatten: true }) || [];
-		for (const node of nodes) if (isFocusable(node)) {
-			node.focus(options);
+		this.focusTarget?.focus(options);
+	}
+	get assignedRoots() {
+		return (this.shadowRoot?.querySelector("slot:not([name])"))?.assignedElements({ flatten: true }) || [];
+	}
+	/**
+	* 포커스 대상은 **감싸개 안쪽까지** 본다. 이 패키지의 폼 컨트롤들은 자기 내부 `u-field` 에
+	* `<div class="container">` 를 슬롯하고 진짜 `<input>` 은 그 안에 있다 — 최상위만 보면
+	* *라이브러리 자신의 정상 사용*이 «컨트롤 없음» 이 된다(첫 판이 실제로 그렇게 오탐했다).
+	*/
+	get focusTarget() {
+		const named = this.controlToName;
+		if (named) return named;
+		for (const root of this.assignedRoots) {
+			if (isFocusable(root)) return root;
+			const inner = Array.from(root.querySelectorAll("*")).find((n) => isFocusable(n));
+			if (inner) return inner;
+		}
+		return null;
+	}
+	/**
+	* 라벨이 가리키는 대상 — `focus()` 와 접근성 이름 부여가 **같은 것**을 골라야 한다.
+	*
+	* 🔴**`isFocusable()` 만으로는 이 리포의 주된 사용 형태를 통째로 놓친다.** `tabbable` 은
+	* 기본적으로 섀도우 루트를 들여다보지 않으므로 `<u-input>` 같은 커스텀 엘리먼트 호스트에
+	* `false` 를 돌려준다(실측: `isFocusable(u-input)=false` · `isFocusable(<input>)=true`).
+	* ⇒ 종전 `focus()` 는 **네이티브 엘리먼트를 슬롯한 경우에만** 동작했고, 레퍼런스 문서가
+	* 가르치는 `u-*` 컨트롤 형태에서는 라벨 클릭이 **조용히 아무 일도 하지 않았다.**
+	*
+	* ⇒ 판정을 «포커스 가능» 하나가 아니라 **«폼 컨트롤인가»** 로 넓힌다: 네이티브로 포커스
+	* 가능하거나, **form-associated 커스텀 엘리먼트**(`static formAssociated = true` — 이
+	* 패키지의 `UFormControlElement` 전부가 그렇다)이면 대상이다. 섀도우를 파고들어 안쪽
+	* 네이티브 노드를 잡지는 않는다 — 그것은 컨트롤 자신의 API 를 우회하는 것이고, 그쪽이
+	* 다시 렌더하면 우리가 얹은 속성이 지워진다.
+	*/
+	get controlToName() {
+		for (const node of this.assignedRoots) if (node.constructor.formAssociated === true || isFocusable(node)) return node;
+		return null;
+	}
+	firstUpdated(changed) {
+		super.firstUpdated(changed);
+		(this.shadowRoot?.querySelector("slot:not([name])"))?.addEventListener("slotchange", () => this.nameSlottedControl());
+	}
+	updated(changed) {
+		super.updated(changed);
+		if (changed.has("label") || changed.has("description")) this.nameSlottedControl();
+	}
+	/**
+	* 🔴**이 컴포넌트의 존재 이유가 «라벨과 컨트롤을 한 칸으로 짝짓는 것»인데, 오랫동안
+	* 라벨을 «그리기만» 하고 연결하지 않았다** — 섀도의 `label` 에 `for` 가 없고 슬롯된
+	* 컨트롤의 `id`·`aria-label`·`aria-labelledby` 가 전부 빈 채였다 — 라벨을 가진 폼 한 장이
+	* 통째로 «이름 없는 입력» 이 된다. 화면은 멀쩡하고 콘솔도 조용해서 **시각 사용자에게는
+	* 아무 신호가 없다.**
+	*
+	* ⚠**`aria-labelledby` 로 잇지 않는다 — 섀도우 경계를 넘지 못한다.** 그 대신 «문자열
+	* 복사»를 슬롯 호스트의 `aria-label` 로 얹고, 폼 컨트롤 쪽이 그것을 내부 네이티브
+	* 컨트롤로 내려보낸다(`UFormControlElement.resolvedAriaLabel` — `u-button` 이 먼저 채택한
+	* 처방을 공통 기반으로 올린 것). 네이티브 엘리먼트를 슬롯한
+	* 경우에는 그 호스트가 곧 컨트롤이라 같은 한 줄이 그대로 듣는다.
+	*
+	* ⚠**자기 이름을 이미 가진 컨트롤은 건드리지 않는다** — 그쪽이 더 구체적이고,
+	* 덮으면 눈에 보이는 라벨과 접근성 이름이 어긋난다(WCAG 2.5.3 Label in Name).
+	*/
+	nameSlottedControl() {
+		const control = this.controlToName;
+		if (!control) {
+			if (this.label && !this.focusTarget) devWarnOnce("field-no-control", `u-field label="${this.label}" has no focusable control in its default slot — the label names nothing. Slot a form control, or drop the label.`);
 			return;
 		}
+		if (!!control.label || control.hasAttribute("aria-labelledby") || control.hasAttribute("aria-label") && control.getAttribute("aria-label") !== this.lastAppliedLabel) {
+			if (this.label && control.label) devWarnOnce("field-double-label", `u-field label="${this.label}" wraps a control that also sets label="${control.label}" — the label renders twice. Set it on one of them.`);
+			return;
+		}
+		if (this.label) {
+			control.setAttribute("aria-label", this.label);
+			this.lastAppliedLabel = this.label;
+		} else if (this.lastAppliedLabel !== void 0) {
+			control.removeAttribute("aria-label");
+			this.lastAppliedLabel = void 0;
+		}
+		if (this.description) control.setAttribute("aria-description", this.description);
+		else if (control.getAttribute("aria-description") === this.lastAppliedDescription) control.removeAttribute("aria-description");
+		this.lastAppliedDescription = this.description;
 	}
 };
 __decorate([property({

package/dist/components/file-input/UFileInput.d.ts

@@ -37,6 +37,17 @@ export declare class UFileInput extends UFormControlElement<File[] | null> {
      *  넘긴다 — 네이티브 `<input type="file" multiple>`의 제출 형태와 동일하다. */
     protected updated(changedProperties: PropertyValues): void;
     private syncFormValue;
+    /**
+     * 이 컨트롤의 포커스 대상은 값을 담는 입력이 아니라 **파일 선택 버튼**이다. 그래서 바깥
+     * 라벨을 그대로 `aria-label` 로 얹으면 버튼의 보이는 글자("파일 선택")가 접근성 이름에서
+     * 사라진다 — WCAG SC 2.5.3 Label in Name 위반이고, 음성 조작 사용자가 보이는 글자로
+     * 그 버튼을 부를 수 없게 된다. ⇒ **덮지 않고 합성한다**: 보이는 글자를 **앞에** 두고
+     * 라벨을 맥락으로 덧붙인다(이름이 보이는 글자를 담으므로 2.5.3 을 만족하고, 같은 화면에
+     * 파일 선택 버튼이 여럿일 때 서로 구분된다).
+     *
+     * 라벨이 없으면 아무것도 얹지 않는다 — 버튼의 보이는 글자가 곧 이름이다.
+     */
+    private get triggerAriaLabel();
     render(): import('lit-html').TemplateResult<1>;
     protected setValidity(): void;
     reset(): void;

package/dist/components/file-input/UFileInput.js

@@ -65,6 +65,20 @@ var UFileInput = class UFileInput extends UFormControlElement {
 			this.internals?.setFormValue(fd);
 		}
 	}
+	/**
+	* 이 컨트롤의 포커스 대상은 값을 담는 입력이 아니라 **파일 선택 버튼**이다. 그래서 바깥
+	* 라벨을 그대로 `aria-label` 로 얹으면 버튼의 보이는 글자("파일 선택")가 접근성 이름에서
+	* 사라진다 — WCAG SC 2.5.3 Label in Name 위반이고, 음성 조작 사용자가 보이는 글자로
+	* 그 버튼을 부를 수 없게 된다. ⇒ **덮지 않고 합성한다**: 보이는 글자를 **앞에** 두고
+	* 라벨을 맥락으로 덧붙인다(이름이 보이는 글자를 담으므로 2.5.3 을 만족하고, 같은 화면에
+	* 파일 선택 버튼이 여럿일 때 서로 구분된다).
+	*
+	* 라벨이 없으면 아무것도 얹지 않는다 — 버튼의 보이는 글자가 곧 이름이다.
+	*/
+	get triggerAriaLabel() {
+		const label = this.resolvedAriaLabel;
+		return label ? `${Locale.getValue("chooseFile")}, ${label}` : void 0;
+	}
 	render() {
 		const files = this.value ?? [];
 		const hasFiles = files.length > 0;
@@ -81,6 +95,7 @@ var UFileInput = class UFileInput extends UFormControlElement {
         <div class="container" part="container">
           <button class="trigger" part="trigger"
             type="button"
+            aria-label=${ifDefined(this.triggerAriaLabel)}
             ?disabled=${this.disabled || this.readonly}
             @click=${this.handleTriggerClick}
           >${Locale.getValue("chooseFile")}</button>

package/dist/components/input/UInput.js

@@ -180,8 +180,8 @@ var UInput = class UInput extends UFormControlElement {
 
           <input part="input"
             type=${this.type === "password" && this.showPassword ? "text" : this.type}
-            aria-label=${ifDefined(this.label)}
-            aria-description=${ifDefined(this.description)}
+            aria-label=${ifDefined(this.resolvedAriaLabel)}
+            aria-description=${ifDefined(this.resolvedAriaDescription)}
             name=${ifDefined(this.name)}
             ?required=${this.required}
             ?disabled=${this.disabled}

package/dist/components/radio/URadio.js

@@ -93,8 +93,8 @@ var URadio = class URadio extends UFormControlElement {
       >
         <div class="container" part="container"
           role="radiogroup"
-          aria-label=${ifDefined(this.label)}
-          aria-description=${ifDefined(this.description)}>
+          aria-label=${ifDefined(this.resolvedAriaLabel)}
+          aria-description=${ifDefined(this.resolvedAriaDescription)}>
           <slot @slotchange=${this.handleSlotChange}></slot>
         </div>
       </u-field>

package/dist/components/rating/URating.js

@@ -112,8 +112,8 @@ var URating = class URating extends UFormControlElement {
         .validationMessage=${this.validationMessage}
       >
         <div class="symbols" part="container" role="radiogroup"
-          aria-label=${ifDefined(this.label)}
-          aria-description=${ifDefined(this.description)}>
+          aria-label=${ifDefined(this.resolvedAriaLabel)}
+          aria-description=${ifDefined(this.resolvedAriaDescription)}>
           ${Array.from({ length: this.max }, (_, i) => {
 			const score = i + 1;
 			const fill = Math.max(0, Math.min(1, value - score + 1));

package/dist/components/select/USelect.js

@@ -173,8 +173,8 @@ var USelect = class USelect extends UFormControlElement {
 
         <div class="container" part="container" tabindex=${this.disabled ? "-1" : "0"}
           role="combobox"
-          aria-label=${ifDefined(this.label)}
-          aria-description=${ifDefined(this.description)}
+          aria-label=${ifDefined(this.resolvedAriaLabel)}
+          aria-description=${ifDefined(this.resolvedAriaDescription)}
           aria-haspopup=${this.searchable ? "dialog" : "listbox"}
           aria-expanded=${this.open}
           aria-controls=${this.searchable ? this.popupId : this.listboxId}>
@@ -209,7 +209,7 @@ var USelect = class USelect extends UFormControlElement {
       <u-popover part="popover"
         id=${this.popupId}
         role=${ifDefined(this.searchable ? "dialog" : void 0)}
-        aria-label=${ifDefined(this.searchable ? this.label || Locale.getValue("search") : void 0)}
+        aria-label=${ifDefined(this.searchable ? this.resolvedAriaLabel || Locale.getValue("search") : void 0)}
         scrollable
         autofocus
         for=".container"

package/dist/components/slider/USlider.js

@@ -230,7 +230,7 @@ var USlider = class USlider extends UFormControlElement {
 		return html`
       <div class="thumb" part=${isEnd ? "thumb-end" : "thumb"}
         role="slider"
-        aria-label=${ifDefined(this.label)}
+        aria-label=${ifDefined(this.resolvedAriaLabel)}
         aria-valuenow=${val}
         aria-valuemin=${this.min}
         aria-valuemax=${this.max}

package/dist/components/split-panel/USplitPanel.js

@@ -2,6 +2,7 @@ import { UElement } from "../UElement.js";
 import __decorateMetadata from "../../_virtual/_@oxc-project_runtime@0.149.0/helpers/esm/decorateMetadata.js";
 import __decorate from "../../_virtual/_@oxc-project_runtime@0.149.0/helpers/esm/decorate.js";
 import { arrayAttrConverter } from "../../utilities/converters.js";
+import { devWarnOnce } from "../../utilities/devWarning.js";
 import { Locale } from "../../utilities/Locale.js";
 import { styles } from "./USplitPanel.styles.js";
 import { html } from "lit";
@@ -247,7 +248,14 @@ var USplitPanel = class USplitPanel extends UElement {
 	* 실측 18px. 호스트가 `overflow: hidden` 이라 패널 내용에 닿을 방법이 없고,
 	* 오류도 없다. 첫 배치 뒤 한 번 재서 개발 모드에서 알린다.
 	*/
-	warnIfCollapsed() {}
+	warnIfCollapsed() {
+		if (process.env.NODE_ENV === "production" || this.panels.length === 0 || !this.isConnected) return;
+		{
+			const height = this.getBoundingClientRect().height;
+			if (height >= 40) return;
+			devWarnOnce(`split-panel:${this.id || "height"}`, `u-split-panel is only ${Math.round(height)}px tall — it has no height of its own (its height: 100% found no sized parent), so its panels take one line of content and anything sized 100% inside them collapses to nothing. Give the host or its parent a height (e.g. height: 400px, or flex: 1 1 auto inside a sized parent).`);
+		}
+	}
 	appendSplitters() {
 		const root = this.renderRoot;
 		if (!root) return;

package/dist/components/switch/USwitch.js

@@ -5,6 +5,7 @@ import { Locale } from "../../utilities/Locale.js";
 import { styles } from "./USwitch.styles.js";
 import { html } from "lit";
 import { customElement, property, query } from "lit/decorators.js";
+import { ifDefined } from "lit/directives/if-defined.js";
 import { live } from "lit/directives/live.js";
 //#region src/components/switch/USwitch.ts
 var USwitch = class USwitch extends UFormControlElement {
@@ -38,6 +39,7 @@ var USwitch = class USwitch extends UFormControlElement {
       <label class="wrapper" part="wrapper">
         <input
           type="checkbox"
+          aria-label=${ifDefined(this.contentAriaLabel)}
           ?disabled=${this.disabled || this.readonly}
           ?required=${this.required}
           .checked=${live(this.checked)}
@@ -60,7 +62,13 @@ var USwitch = class USwitch extends UFormControlElement {
           </span>
         </span>
         <span class="label" part="label">
-          <slot></slot>
+          <!-- 형제 u-checkbox 는 슬롯 폴백으로 label 을 그리는데 여기만 없었다 — 상속받은
+               공개 프로퍼티(UFormControlElement.label)를 이 컴포넌트만 한 번도 읽지 않아
+               u-switch 에 label 속성을 주면 눈에 보이는 라벨도 접근성 이름도 생기지 않았다
+               문서는 기본 슬롯만 가르쳐 왔으므로 문서 위반이
+               아니라 «선언은 있는데 동작이 없는» 자리다.
+               주의: 이 주석에 백틱을 쓰지 말 것 — html 태그드 템플릿을 그 자리에서 끝낸다. -->
+          <slot @slotchange=${this.handleLabelSlotChange}>${this.label}</slot>
           <span class="required" ?hidden=${!this.required}>*</span>
         </span>
       </label>

package/dist/components/textarea/UTextarea.js

@@ -56,8 +56,8 @@ var UTextarea = class UTextarea extends UFormControlElement {
         <div class="container" part="container">
           <textarea part="textarea"
             scrollable
-            aria-label=${ifDefined(this.label)}
-            aria-description=${ifDefined(this.description)}
+            aria-label=${ifDefined(this.resolvedAriaLabel)}
+            aria-description=${ifDefined(this.resolvedAriaDescription)}
             ?required=${this.required}
             ?disabled=${this.disabled}
             ?readonly=${this.readonly}

package/dist/utilities/accent.d.ts

@@ -41,7 +41,7 @@ export declare const MIN_STEP_SEPARATION = 1.2;
 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 명암비. */
+/** WCAG 2.x 명암비(상대 휘도 공식 — 2.2 에서 바뀌지 않았다). */
 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;

package/dist/utilities/accent.js

@@ -39,7 +39,7 @@ function luminance(color) {
 	const [r, g, b] = rgb.map((v) => channelLum(v / 255));
 	return .2126 * r + .7152 * g + .0722 * b;
 }
-/** WCAG 2.1 명암비. */
+/** WCAG 2.x 명암비(상대 휘도 공식 — 2.2 에서 바뀌지 않았다). */
 function contrast(a, b) {
 	const [x, y] = [luminance(a), luminance(b)];
 	return (Math.max(x, y) + .05) / (Math.min(x, y) + .05);

package/dist/utilities/devWarning.d.ts

@@ -2,9 +2,17 @@
  * 개발 모드 «사용 안내» 경고 — 오류 경로가 아닌, ***조용히 틀리는*** 상태를 한 번 알린다.
  *
  * 이 패키지에는 같은 모양의 경고가 이미 있다(`UElement.warnIfTokensMissing` — 토큰 시트 부재).
- * 공통 규약: `[<패키지>]` 네임스페이스 · 개발 모드에서만(`import.meta.env.DEV`) ·
+ * 공통 규약: `[<패키지>]` 네임스페이스 · 개발 모드에서만(`process.env.NODE_ENV !== 'production'`) ·
  * 같은 키로는 **한 번만** · 무엇이 틀렸는지가 아니라 **무엇을 하면 되는지**를 적는다.
  *
+ * ⚠**`import.meta.env.DEV` 를 쓰지 않는다** — Vite 는 이 라이브러리 **자신의** `vite build`
+ * 시점에 그 값을 정적으로 `false` 로 치환하고, Rollup 의 dead-code elimination 이 이후
+ * 분기를 통째로 지운다. 소비자가 dev 서버로 띄워도 이미 게시본에서 죽은 코드라 살아나지
+ * 않는다(2026-09-13 실측 — 1.40.1·1.40.2 게시본에서 이 경고가 전부 no-op 이었다).
+ * `process.env.NODE_ENV` 는 이 라이브러리의 빌드가 손대지 않고 그대로 dist 에 남아,
+ * **소비자 자신의** 번들러가 소비자의 빌드 시점에 치환한다(React 등 생태계 라이브러리와
+ * 동일한 관례) — `tests/build/dev-warning-dist.test.ts` 가 게시본에 대해 이 계약을 지킨다.
+ *
  * 이 파일이 생긴 계기: 소비앱의 메뉴 30개가 해석되지 않는 아이콘 이름으로 **한꺼번에 같은
  * 큐브 폴백**을 그렸는데 신호가 0 이었다(소비자 실측). 폴백은 의도된 것이라(접힌 사이드바에서
  * 아이콘이 없으면 메뉴가 «높이만 있는 빈 줄» 이 된다) 제거가 답이 아니다 — **없는 것은 경고다.**

package/dist/utilities/devWarning.js

@@ -3,9 +3,17 @@
 * 개발 모드 «사용 안내» 경고 — 오류 경로가 아닌, ***조용히 틀리는*** 상태를 한 번 알린다.
 *
 * 이 패키지에는 같은 모양의 경고가 이미 있다(`UElement.warnIfTokensMissing` — 토큰 시트 부재).
-* 공통 규약: `[<패키지>]` 네임스페이스 · 개발 모드에서만(`import.meta.env.DEV`) ·
+* 공통 규약: `[<패키지>]` 네임스페이스 · 개발 모드에서만(`process.env.NODE_ENV !== 'production'`) ·
 * 같은 키로는 **한 번만** · 무엇이 틀렸는지가 아니라 **무엇을 하면 되는지**를 적는다.
 *
+* ⚠**`import.meta.env.DEV` 를 쓰지 않는다** — Vite 는 이 라이브러리 **자신의** `vite build`
+* 시점에 그 값을 정적으로 `false` 로 치환하고, Rollup 의 dead-code elimination 이 이후
+* 분기를 통째로 지운다. 소비자가 dev 서버로 띄워도 이미 게시본에서 죽은 코드라 살아나지
+* 않는다(2026-09-13 실측 — 1.40.1·1.40.2 게시본에서 이 경고가 전부 no-op 이었다).
+* `process.env.NODE_ENV` 는 이 라이브러리의 빌드가 손대지 않고 그대로 dist 에 남아,
+* **소비자 자신의** 번들러가 소비자의 빌드 시점에 치환한다(React 등 생태계 라이브러리와
+* 동일한 관례) — `tests/build/dev-warning-dist.test.ts` 가 게시본에 대해 이 계약을 지킨다.
+*
 * 이 파일이 생긴 계기: 소비앱의 메뉴 30개가 해석되지 않는 아이콘 이름으로 **한꺼번에 같은
 * 큐브 폴백**을 그렸는데 신호가 0 이었다(소비자 실측). 폴백은 의도된 것이라(접힌 사이드바에서
 * 아이콘이 없으면 메뉴가 «높이만 있는 빈 줄» 이 된다) 제거가 답이 아니다 — **없는 것은 경고다.**
@@ -21,7 +29,13 @@ var warned = /* @__PURE__ */ new Set();
 * 프로덕션 빌드에서는 호출 자체가 no-op 이다.
 */
 function createDevWarner(scope) {
-	return (key, message) => {};
+	return (key, message) => {
+		if (process.env.NODE_ENV === "production") return;
+		const scoped = `${scope} ${key}`;
+		if (warned.has(scoped)) return;
+		warned.add(scoped);
+		console.warn(`[${scope}] ${message}`);
+	};
 }
 /** `key` 당 한 번만, 개발 모드에서만 `[@iyulab/components]` 로 `console.warn` 한다. */
 var devWarnOnce = createDevWarner("@iyulab/components");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@iyulab/components",
   "description": "web-components library based on lit-element made by iyulab",
-  "version": "1.40.2",
+  "version": "1.41.0",
   "keywords": [
     "iyulab",
     "components",
@@ -86,7 +86,7 @@
     "@eslint/js": "^10.0.1",
     "@types/node": "^26.1.1",
     "@types/react": "^19.2.14",
-    "@vitest/browser-playwright": "^4.1.10",
+    "@vitest/browser-playwright": "^5.0.0",
     "eslint": "^10.1.0",
     "eslint-plugin-lit": "^2.3.1",
     "globals": "^17.7.0",
@@ -97,6 +97,6 @@
     "vite": "^8.1.4",
     "vite-plugin-dts": "^5.0.3",
     "vite-plugin-static-copy": "^4.1.1",
-    "vitest": "^4.1.10"
+    "vitest": "^5.0.0"
   }
 }

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

@@ -23,6 +23,43 @@ Layout wrapper for form controls. Renders label, required marker, description te
 
 ---
 
+## Accessible name
+
+`u-field` does more than draw the label — it **names the control you slot into it**. The label text
+is copied onto the slotted element as `aria-label` (and `description` as `aria-description`), and
+`u-*` form controls pass that through to the native control inside their shadow root.
+`aria-labelledby` is not used: it does not cross shadow boundaries.
+
+**Set the label in one place only.** If the slotted control already carries its own `label`,
+`aria-label`, or `aria-labelledby`, the field leaves it alone — overriding it would make the visible
+label and the accessible name disagree (WCAG SC 2.5.3 Label in Name). Setting `label` on *both*
+renders the label twice; a development-mode console warning points at that spot.
+
+```html
+<!-- label on the field -->
+<u-field label="Email"><u-input type="email" name="email"></u-input></u-field>
+
+<!-- or on the control — not both -->
+<u-input label="Email" type="email" name="email"></u-input>
+
+<!-- native elements work the same way -->
+<u-field label="Notes"><textarea name="notes"></textarea></u-field>
+```
+
+A `u-field` that has a `label` but nothing focusable in its default slot also warns: that label
+names nothing.
+
+All ten form controls take the field's label this way. Three of them get it slightly differently,
+because their name normally comes from their own content:
+
+| Control | How the field label reaches it |
+|---------|-------------------------------|
+| `u-checkbox`, `u-switch` | Only when they have no label text of their own (own `label`, or content in the default slot). Their own text always wins. |
+| `u-file-input` | Composed into the trigger button's name as `"<button text>, <field label>"`, so the visible text stays part of the accessible name. |
+| everything else | Directly, on the native control inside the shadow root. |
+
+---
+
 ## Slots
 
 | Name | Description |

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

@@ -25,7 +25,7 @@ Toggle switch (on/off). Supports custom track and thumb content via slots. Form-
 
 | Name | Description |
 |------|-------------|
-| *(default)* | Label text |
+| *(default)* | Label text (falls back to the `label` property) |
 | `track-checked` | Content inside the track when checked |
 | `track-unchecked` | Content inside the track when unchecked |
 | `thumb-checked` | Thumb content when checked |
@@ -35,6 +35,7 @@ Toggle switch (on/off). Supports custom track and thumb content via slots. Form-
 
 | Property | Type | Default | Reflect | Description |
 |----------|------|---------|---------|-------------|
+| `label` | `string` | — | — | Label text — fallback for the default slot |
 | `checked` | `boolean` | `false` | ✓ | On/off state |
 | `disabled` | `boolean` | `false` | ✓ | Disable |
 | `readonly` | `boolean` | `false` | ✓ | Read-only |