@iyulab/components 1.22.0 → 1.24.0

package/CHANGELOG.md

@@ -1,5 +1,247 @@
 # 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
+
+- **`u-expander` — 제목을 눌러 본문을 접고 펴는 디스클로저.**
+
+  ```html
+  <u-expander label="배송 정보" open>
+    <p>본문</p>
+  </u-expander>
+  ```
+
+  헤더는 **네이티브 `<button>`** 이라 Enter/Space·포커스 순서가 그대로 따라온다. 높이 전환은
+  grid 트랙(`0fr` ↔ `1fr`)이라 콘텐츠 높이를 JS 로 재지 않으며, `prefers-reduced-motion:
+  reduce` 에서 멈춘다(접힘/펼침의 결과는 정지 상태에서도 그대로 읽히므로 이 전환은 장식이다).
+
+  ⚠**접힘의 요점은 높이가 아니라 «도달 불가»다** — `overflow: hidden` 만으로 접으면 화면에서
+  사라진 콘텐츠가 **접근성 트리와 탭 순서에 그대로 남는다.** `visibility` 를 함께 옮겨
+  접힌 본문이 포커스를 받지 못하게 한다(회귀 테스트가 이 조건만 따로 잰다).
+
+### Changed
+
+- **콘솔 진단 문구가 영어로 이주했다** — 토큰 시트 부재 경고 · `[Dialog]` 표시 실패 ·
+  `[IconRegistry]` 리졸브 실패. 화면 문자열이 아니라 **개발자 대면 진단**이고, 검색 가능성과
+  이슈 재현 공유에서 영어가 유리하다는 판단이다(로케일 레지스트리에 넣지 않는다 — 사용자가
+  읽는 문자열이 아니다). 문구를 판별식으로 쓰던 테스트가 있다면 *"무엇을 말하는가"* 로 좁힐 것.
+
+### Removed
+
+- 🔴**한 번도 동작한 적 없는 선언 3종을 걷었다.** 전부 «선언 + 문서»만 있고 그 값을 읽는
+  코드가 **어디에도 없었다**(전수 검색). 동작이 없었으므로 **깨질 동작도 없다.**
+
+  | 제거 | 문서가 약속하던 것 | 대체 |
+  |---|---|---|
+  | `u-panel[collapsible]` | *"Allow the panel to collapse"* | **`u-expander`**(위) |
+  | `u-tab-panel[editable]` | *"Allow adding/removing tabs"* | 없음 — 탭 추가/삭제는 소비자가 슬롯을 직접 다룬다 |
+  | `u-tree[droppable]` · `u-tree-item[droppable]` | *"Enable drop" / "Accepts drops"* | 없음 — 아래 참조 |
+
+  ⚠**`draggable` 은 남는다** — 그것은 네이티브 전역 속성이라 브라우저가 드래그 자체는
+  켜 준다. 다만 문서가 *"Allow reordering tabs by drag"*·*"Enable drag"* 로 **재정렬/드롭
+  기능을 약속**하고 있었고 그런 코드는 존재한 적이 없다 ⇒ **문서를 사실로 정정**했다
+  (*"native drag attribute — no built-in reordering"*). 드래그 재정렬·트리 드롭은 수요가
+  모이면 기능으로 설계한다.
+
+- **`Locale.namespace()` — 상위 패키지가 자기 화면 문자열을 담을 자리.**
+
+  ```ts
+  const t = Locale.namespace<'empty' | 'loading'>('u-data-view');
+  t.register('en', { empty: 'No data', loading: 'Loading…' });
+  t.register('ko', { empty: '데이터가 없습니다' });
+  t.text('empty');                     // 활성 로케일 기준
+  ```
+
+  종전의 `Locale.register`/`getValue` 는 **검증 메시지 9키의 닫힌 유니온**(`LocaleMessageKey`)만
+  받는다. 상위 패키지의 화면 문자열은 그 유니온에 없고, 넣으면 기반 라이브러리에 소비자
+  도메인 어휘가 쌓인다. ⇒ 결과적으로 각 패키지가 **자기 레지스트리를 손으로 만들거나**
+  문자열을 하드코딩해 왔다.
+
+  ⚠**순수 가산이다** — `LocaleMessageKey`·`register`·`getValue` 세 시그니처를 하나도
+  건드리지 않는다. 키 유니온은 **소비자가** 제네릭으로 정하므로 라이브러리 키셋은 커지지 않는다.
+
+  조회 사슬(정확 일치 → base 언어 → `en`)과 `{name}` 치환은 검증 메시지와 **같은 구현을
+  공유한다** — 두 벌로 두면 한쪽만 고쳐진다. 사슬에 없는 키는 **키 자체**를 돌려준다
+  (조용히 빈 문자열이 되는 것보다 화면에 드러나는 편이 낫다).
+
+- **`Theme.accent(seed)` — 브랜드 색 하나로 `--u-primary-*` 램프를 만든다.**
+
+  ```ts
+  Theme.accent('#6A1B9A');   // 램프 5단 + 면 위 글자색이 계산된다
+  Theme.accent(null);        // 해제 — 시트 기본값으로
+  ```
+
+  종전에는 소비자가 램프를 **손으로 열 줄 적었고**, 그 값이 대비 계약을 만족하는지는
+  아무것도 확인하지 않았다. 이제 **계산해서** 넣는다 — 면 위 글자 4.5 · 바탕 위 글자 4.5 ·
+  `-strong` ↔ `-color` 구분 1.20 · 그래픽 3.0.
+
+  ⚠**CSS `color-mix()` 만으로는 안 된다** — 고정 비율은 밝은 시드에서 깨진다(노랑의
+  `-strong` 이 바탕 대비 **2.21**, 기준 4.5). 목표 대비까지 섞으려면 대비를 **계산**해야
+  하고 CSS 에는 그 수단이 없다. ⇒ 계산은 JS, 결과만 커스텀 프로퍼티로.
+
+  ⚠**테마가 바뀌면 다시 계산된다** — 대비 목표가 «바탕 기준»이라 라이트와 다크는 같은
+  시드에서 **다른 램프**를 갖는다. 바탕은 계산 시점의 `--u-bg-color` 를 읽으므로 소비자가
+  바탕을 덮었으면 그 값이 기준이 된다.
+
+- **`u-skeleton` 에 `lines` — 여러 줄 자리표시자.**
+
+  ```html
+  <u-skeleton lines="3" height="1em"></u-skeleton>   <!-- 막대 3개 · 마지막 줄은 짧게 -->
+  ```
+
+  종전에는 목록 한 줄·문단 자리표시자를 만들 때 **폭만 다른 막대를 손으로 반복**해야 했다
+  (이 리포 안에서만 12사용처). 마지막 줄을 짧게 그리는 것은 장식이 아니라 **문단의 끝**을
+  나타내는 신호다(`--skeleton-last-line-width`, 기본 60%). 줄 간격은
+  `--skeleton-line-gap`(기본 `0.5em`).
+
+  ⚠**단일 막대의 모양은 바뀌지 않는다** — `lines` 가 없으면 종전과 완전히 같고, 회귀
+  테스트가 그 계약을 감시한다. `pulse`/`shimmer` 는 줄마다 적용되며 `prefers-reduced-motion`
+  에서 함께 멈춘다.
+
+- **오버레이가 열릴 때 `autofocus` 를 존중하고, 없으면 첫 입력으로 간다** (`u-dialog`·`u-drawer`).
+
+  ```html
+  <u-drawer closable>
+    <span slot="header">주문 편집</span>
+    <u-input label="수량" autofocus></u-input>   <!-- 여기로 간다 -->
+  </u-drawer>
+  ```
+
+  종전에는 `focus-trap` 의 기본값(**첫 tabbable 노드**)에 맡겨져 있었다. 그 결과 ⑴`autofocus`
+  가 **무시되고**(focus-trap 은 그 속성을 보지 않는다) ⑵**버튼이 마크업 앞에 있으면 버튼이
+  포커스를 가져갔다**(확인/취소가 먼저 오는 다이얼로그가 그 모양이다 — 실측: 입력이 아니라
+  첫 버튼). ⇒ 순서를 계약으로 고정한다: `[autofocus]` → 첫 입력 컨트롤 → 첫 tabbable.
+
+  ⚠**시각적 변화가 있을 수 있다** — 버튼이 앞에 오는 다이얼로그는 이제 **입력**에서 시작한다.
+  기존 동작을 원하면 그 버튼에 `autofocus` 를 준다.
+
+- **`u-tag`·`u-badge` 에 `icon` — 상태가 «색 없이도» 구분된다.**
+
+  ```html
+  <u-tag color="danger" icon>실패</u-tag>     <!-- ✕ 원형 아이콘 -->
+  <u-tag color="success" icon>완료</u-tag>    <!-- ✓ 원형 아이콘 -->
+  ```
+
+  대비 계약(1.20.0)은 각 상태색이 **자기 바탕에서 읽히는가**를 지키지만 *구별되는가* 는 지키지
+  않는다 — 색각 이상(남성 약 8%)이나 흑백 인쇄에서는 «성공»과 «실패»가 같은 회색 알약이 된다.
+  역할 색 충돌 검사가 **색 공간에서**(ΔE) 세운 구분을 이 축은 **모양 공간에서** 세운다.
+
+  ⚠**의미가 없는 색에는 그리지 않는다** — 장식 축(`blue`·`purple` …)은 *색 자체*를 뜻하고
+  `neutral`·`primary` 는 상태가 아니다. 없는 의미를 아이콘으로 지어내면 그 아이콘이 **잘못된
+  정보를 나른다**. `u-badge variant="dot"` 도 콘텐츠를 렌더하지 않으므로 대상이 아니다.
+
+  ⚠**렌더는 가산이다** — `icon` 을 주지 않으면 종전 그대로다. 아이콘은 **내장 번들**에서 오므로
+  네트워크를 타지 않는다(오프라인에서도 그려진다).
+
+  ⚠**다만 번들 크기는 가산이 아니다** — `u-tag`·`u-badge` 가 `u-icon` 을 import 하고, 내부
+  아이콘 번들은 **빌드 시점 eager glob** 이다. 그래서 `dist/components/tag/UTag.js` 만 deep
+  import 하던 소비자도 이제 `UIcon`(2.3 KB)과 내장 SVG 세트(**~9.8 KB**, 19종)를 함께 받는다.
+  전체 라이브러리를 쓰는 소비자에게는 변화가 없다(이미 포함돼 있다).
+
+- **`u-skeleton` 의 `pulse`/`shimmer` 가 `prefers-reduced-motion: reduce` 에서 멈춘다.**
+
+  ⚠**스피너는 그대로 돈다** — 갈림길은 *멈추냐 마냐*가 아니라 **어느 움직임이 의미를
+  나르는가**였다. 스피너의 회전은 **신호**라 죽이면 진행 여부를 알 수 없다(WCAG 2.2.2 는
+  로딩 표시처럼 움직임이 본질인 것을 예외로 둔다). 스켈레톤은 **기본값이 이미 정적**이고
+  정지한 블록이 «로딩 중»을 그대로 나르므로 `pulse`/`shimmer` 는 장식이다.
+
+  ⚠시트의 reduce 규칙(`--u-duration-*: 0ms`)은 **`animation` 을 쓰는 자리에 닿지 않는다** —
+  지속시간 축을 경유하지 않기 때문이다. 그래서 컴포넌트에서 명시적으로 멈춘다.
+
+### Changed
+
+- ⚠**`u-dialog`·`u-drawer` 제목이 2px 작아진다** — `18px` 리터럴 → `--u-text-subtitle-size`(16px).
+
+  종전에는 *다이얼로그 제목 18 · 얼럿 제목 16* 으로 **같은 위계가 두 값**이었다. 18px 는
+  타입 스케일 7단에 **없는 단**이라 리터럴로만 존재할 수 있었고, 그래서 소비자가 스케일을
+  조율해도 이 두 자리는 따라오지 않았다.
+
+  ⚠**단을 늘리지 않았다** — 18px 를 요구하는 타이포 자리는 전수 **둘뿐**이고(`u-copy-button`
+  의 18px 는 아이콘 크기다), 단일 수요로 축을 늘리는 것은 선제 확장이다. 같은 패키지의
+  `u-alert` 가 이미 `subtitle` 을 쓰고 있어 **선례를 따랐다**.
+
+  ⚠**헤더의 닫기 버튼은 `font-size: inherit` 이라 함께 2px 작아진다.**
+
+  `tests/build/type-scale.test.ts` 가 *"제목 위계를 가진 컴포넌트가 같은 단을 읽는가"* 를
+  대조한다 — 리터럴로 다시 갈라지면 발화한다.
+
+### Fixed
+
+- **역할 색의 «의미 충돌» 검사를 뒀다**(`tests/build/role-color-collision.test.ts`).
+  대비 검사는 각 역할색을 **자기 바탕에 대해** 재므로 *"저장(primary)과 삭제(danger)가
+  같은 색"* 인 상태도 **양쪽 다 통과한다** — 대비는 *읽히는가*를 묻지 *구별되는가*를 묻지
+  않는다. 이제 역할끼리의 거리를 CIELAB ΔE 로 잰다(임계 20).
+
+  ⚠**`primary` 와 `info` 는 기본값이 의도적으로 같으므로 면제**다(브랜딩은 `primary` 만
+  바꾼다). 면제쌍의 **근거가 시트 주석에 남아 있는지**도 함께 잰다 — 근거 없는 면제가
+  쌓이면 검사가 아무것도 지키지 않게 된다.
+
+  실측: 면제쌍을 뺀 최소 거리가 **38.7**(라이트 `-strong` 의 warning/danger)이라 정상적인
+  램프 조율에는 발화하지 않는다.
+
 ## [1.22.0] - 2026-08-03
 
 ### 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
 
@@ -104,6 +104,38 @@ Theme.set('system');
 
 자세한 내용은 [docs/theming.md](./docs/theming.md)를 참고하세요.
 
+## Localization
+
+라이브러리가 **스스로 생성하는 문자열**(검증 메시지)은 내장 로케일 14종을 갖고 있으며,
+활성 로케일 하나로 전부 따라옵니다.
+
+```ts
+import { Locale } from '@iyulab/components';
+
+Locale.set('ko');                                   // 활성 로케일
+Locale.register('nl', { valueMissing: '…' });       // 검증 메시지 override
+```
+
+### 네임스페이스 — 상위 패키지·앱의 문자열 (1.23.0~)
+
+검증 메시지 키셋은 **닫혀 있습니다**(9키). 그 위에 자기 문자열을 담으려면 네임스페이스를
+씁니다 — 키 유니온은 **쓰는 쪽이** 정하므로 라이브러리 키셋은 커지지 않습니다.
+
+```ts
+const t = Locale.namespace<'empty' | 'loading'>('u-data-view');
+
+t.register('en', { empty: 'No data', loading: 'Loading…' });   // 기본은 영어
+t.register('ko', { empty: '데이터가 없습니다' });               // 필요한 언어만 추가
+
+t.text('empty');                        // 활성 로케일 기준
+t.text('greet', { who: 'Ann' });        // {name} 치환
+```
+
+- 조회 사슬은 검증 메시지와 같습니다: **정확 일치 → base 언어(`ko-KR` → `ko`) → `en`**.
+- 같은 이름의 네임스페이스는 **같은 저장소**를 가리킵니다(모듈 어디서 만들어도 됩니다).
+- 사슬에 없는 키는 **키 자체**를 돌려줍니다 — 조용히 빈 문자열이 되지 않습니다.
+- `Locale.set()` 하나로 검증 메시지와 네임스페이스가 함께 전환됩니다.
+
 ## Documentation
 
 | 문서 | 내용 |

package/dist/components/UOverlayElement.d.ts

@@ -65,6 +65,24 @@ export declare abstract class UOverlayElement extends UElement {
     requestClose(source: string): void;
     /** 오버레이가 열릴 때 설정을 적용합니다. */
     private setup;
+    /**
+     * 열릴 때 포커스를 받을 요소를 정한다 — **입력을 먼저 본다.**
+     *
+     * 순서: `[autofocus]` → 첫 입력 컨트롤 → (없으면) focus-trap 기본값(첫 tabbable).
+     *
+     * 🔴**두 분기가 «각각» 무엇을 하는지 되돌려 재서 갈랐다** — 이 함수는 그 기록이다.
+     *
+     *   `[autofocus]`  → `u-drawer` 에서 갈린다. `focus-trap` 은 그 속성을 존중하지 않는다
+     *                    (v7 `getInitialFocusNode` 는 «첫 tabbable» 로 폴백한다).
+     *   첫 입력 우선   → `u-dialog` 에서 갈린다. 버튼이 DOM 순서상 앞이면 기본값은 **버튼**을
+     *                    잡는다(실측: 제거하면 `button#b1`, 복원하면 `input`).
+     *
+     * ⚠**`u-drawer` 만으로는 두 번째 분기를 판별할 수 없었다** — 슬롯 배치 때문에 기본값도
+     * 우연히 첫 입력에 떨어진다. *"되돌려도 통과한다"* 를 *"이 코드는 아무것도 안 한다"* 로
+     * 읽을 뻔했고, **판별하는 입력을 찾은 뒤에야** 갈렸다.
+     * (`tests/browser/overlay-initial-focus.browser.test.ts` 가 둘 다 감시한다.)
+     */
+    private resolveInitialFocus;
     /** 오버레이가 닫힐 때 설정을 해제합니다. */
     private cleanup;
     /** host 자체를 클릭한 경우(백드롭)만 닫기 요청 */

package/dist/components/UOverlayElement.js

@@ -102,12 +102,36 @@ var UOverlayElement = class extends UElement {
 				clickOutsideDeactivates: false,
 				allowOutsideClick: true,
 				fallbackFocus: this,
+				initialFocus: () => this.resolveInitialFocus(),
 				trapStack: OverlayManager.trapStack,
 				tabbableOptions: { getShadowRoot: true }
 			});
 			this.focusTrap.activate();
 		}
 	}
+	/**
+	* 열릴 때 포커스를 받을 요소를 정한다 — **입력을 먼저 본다.**
+	*
+	* 순서: `[autofocus]` → 첫 입력 컨트롤 → (없으면) focus-trap 기본값(첫 tabbable).
+	*
+	* 🔴**두 분기가 «각각» 무엇을 하는지 되돌려 재서 갈랐다** — 이 함수는 그 기록이다.
+	*
+	*   `[autofocus]`  → `u-drawer` 에서 갈린다. `focus-trap` 은 그 속성을 존중하지 않는다
+	*                    (v7 `getInitialFocusNode` 는 «첫 tabbable» 로 폴백한다).
+	*   첫 입력 우선   → `u-dialog` 에서 갈린다. 버튼이 DOM 순서상 앞이면 기본값은 **버튼**을
+	*                    잡는다(실측: 제거하면 `button#b1`, 복원하면 `input`).
+	*
+	* ⚠**`u-drawer` 만으로는 두 번째 분기를 판별할 수 없었다** — 슬롯 배치 때문에 기본값도
+	* 우연히 첫 입력에 떨어진다. *"되돌려도 통과한다"* 를 *"이 코드는 아무것도 안 한다"* 로
+	* 읽을 뻔했고, **판별하는 입력을 찾은 뒤에야** 갈렸다.
+	* (`tests/browser/overlay-initial-focus.browser.test.ts` 가 둘 다 감시한다.)
+	*/
+	resolveInitialFocus() {
+		const explicit = this.querySelector("[autofocus]");
+		if (explicit) return explicit;
+		const control = this.querySelector("input, select, textarea, u-input, u-textarea, u-select, u-checkbox, u-radio, u-switch, u-slider");
+		if (control) return control;
+	}
 	/** 오버레이가 닫힐 때 설정을 해제합니다. */
 	cleanup() {
 		this.focusTrap?.deactivate();

package/dist/components/badge/UBadge.d.ts

@@ -22,6 +22,11 @@ export declare class UBadge extends UElement {
     color: BadgeColor;
     /** 부모 요소 기준 배치 위치 (설정 시 position: absolute) */
     anchor?: BadgeAnchor;
+    /**
+     * 상태를 **색과 무관하게** 나르는 아이콘을 붙입니다(`info`·`success`·`warning`·`danger`).
+     * 의미가 없는 색(`neutral`·`primary`·장식 축)과 `variant="dot"` 에서는 그리지 않습니다.
+     */
+    icon: boolean;
     render(): import('lit-html').TemplateResult<1> | typeof nothing;
 }
 declare global {

package/dist/components/badge/UBadge.js

@@ -1,6 +1,8 @@
 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 "./UBadge.styles.js";
 import { html, nothing } from "lit";
 import { customElement, property } from "lit/decorators.js";
@@ -10,14 +12,17 @@ var UBadge = class UBadge extends UElement {
 		super(..._args);
 		this.variant = "pill";
 		this.color = "blue";
+		this.icon = false;
 	}
 	static {
 		this.styles = [super.styles, styles];
 	}
 	render() {
 		if (this.variant === "dot") return nothing;
+		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>
         <slot></slot>
         <slot name="suffix"></slot>
@@ -37,6 +42,10 @@ __decorate([property({
 	type: String,
 	reflect: true
 }), __decorateMetadata("design:type", Object)], UBadge.prototype, "anchor", void 0);
+__decorate([property({
+	type: Boolean,
+	reflect: true
+}), __decorateMetadata("design:type", Object)], UBadge.prototype, "icon", void 0);
 UBadge = __decorate([customElement("u-badge")], UBadge);
 //#endregion
 export { UBadge };

package/dist/components/badge/UBadge.styles.js

@@ -140,6 +140,12 @@ var styles = css`
     transform: translate(-50%, 50%);
   }
 
+  /* 상태 아이콘 — prefix 슬롯과 같은 간격을 쓴다. */
+  .icon {
+    flex-shrink: 0;
+    margin-right: 0.25em;
+  }
+
   /* === Slots === */
   ::slotted([slot="prefix"]) {
     margin-right: 0.25em;

package/dist/components/dialog/UDialog.styles.js

@@ -89,7 +89,7 @@ var styles = css`
     justify-content: space-between;
     gap: var(--u-space-sm, 8px);
     padding: var(--u-space-md, 12px) var(--u-space-lg, 16px);
-    font-size: 18px;
+    font-size: var(--u-text-subtitle-size, 16px);
     font-weight: 600;
     line-height: 1.3;
     border-bottom: 1px solid var(--u-border-color, #E0E0E0);

package/dist/components/drawer/UDrawer.styles.js

@@ -77,7 +77,7 @@ var styles = css`
     justify-content: space-between;
     gap: var(--u-space-sm, 8px);
     padding: var(--u-space-md, 12px) var(--u-space-lg, 16px);
-    font-size: 18px;
+    font-size: var(--u-text-subtitle-size, 16px);
     font-weight: 600;
     line-height: 1.3;
     border-bottom: 1px solid var(--u-border-color, #E0E0E0);

package/dist/components/expander/UExpander.d.ts

@@ -0,0 +1,38 @@
+import { UElement } from '../UElement.js';
+/**
+ * 제목을 눌러 본문을 접고 펴는 디스클로저(익스팬더) 컴포넌트입니다.
+ *
+ * @slot - 펼쳤을 때 보이는 본문
+ * @slot header - 제목 영역을 통째로 대체하는 콘텐츠 (`label` 보다 우선)
+ * @slot suffix - 제목 우측에 놓이는 콘텐츠 (상태 배지·보조 액션 등)
+ *
+ * @csspart header - 제목 버튼 영역
+ * @csspart icon - 펼침 표시 아이콘
+ * @csspart label - 제목 텍스트 영역
+ * @csspart content - 본문을 감싸는 영역
+ *
+ * @event expand - 펼쳐질 때 발생 (취소 가능)
+ * @event collapse - 접힐 때 발생 (취소 가능)
+ */
+export declare class UExpander extends UElement {
+    static styles: import('lit').CSSResultGroup[];
+    /** 펼침 여부 */
+    open: boolean;
+    /** 비활성화 여부 */
+    disabled: boolean;
+    /** 제목 텍스트 (`header` 슬롯이 있으면 그쪽이 이깁니다) */
+    label: string;
+    render(): import('lit-html').TemplateResult<1>;
+    /** 펼칩니다. `expand` 이벤트가 취소되면 아무 일도 하지 않고 `false` 를 돌려줍니다. */
+    expand(): boolean;
+    /** 접습니다. `collapse` 이벤트가 취소되면 아무 일도 하지 않고 `false` 를 돌려줍니다. */
+    collapse(): boolean;
+    /** 현재 상태의 반대로 바꿉니다. */
+    toggle(): boolean;
+    private handleClick;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'u-expander': UExpander;
+    }
+}

package/dist/components/expander/UExpander.js

@@ -0,0 +1,78 @@
+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 { styles } from "./UExpander.styles.js";
+import { html } from "lit";
+import { customElement, property } from "lit/decorators.js";
+//#region src/components/expander/UExpander.ts
+var UExpander = class UExpander extends UElement {
+	constructor(..._args) {
+		super(..._args);
+		this.open = false;
+		this.disabled = false;
+		this.label = "";
+		this.handleClick = () => {
+			this.toggle();
+		};
+	}
+	static {
+		this.styles = [super.styles, styles];
+	}
+	render() {
+		return html`
+      <div class="frame">
+        <button class="header" part="header" type="button"
+          aria-expanded=${this.open ? "true" : "false"}
+          aria-controls="content"
+          ?disabled=${this.disabled}
+          @click=${this.handleClick}
+        >
+          <u-icon class="icon" part="icon" lib="internal" name="chevron-right"></u-icon>
+          <span class="label" part="label"><slot name="header">${this.label}</slot></span>
+          <slot name="suffix"></slot>
+        </button>
+
+        <div class="content" part="content" id="content" role="region">
+          <div class="inner">
+            <div class="body"><slot></slot></div>
+          </div>
+        </div>
+      </div>
+    `;
+	}
+	/** 펼칩니다. `expand` 이벤트가 취소되면 아무 일도 하지 않고 `false` 를 돌려줍니다. */
+	expand() {
+		if (this.disabled || this.open) return false;
+		if (this.fire("expand")) {
+			this.open = true;
+			return true;
+		}
+		return false;
+	}
+	/** 접습니다. `collapse` 이벤트가 취소되면 아무 일도 하지 않고 `false` 를 돌려줍니다. */
+	collapse() {
+		if (this.disabled || !this.open) return false;
+		if (this.fire("collapse")) {
+			this.open = false;
+			return true;
+		}
+		return false;
+	}
+	/** 현재 상태의 반대로 바꿉니다. */
+	toggle() {
+		return this.open ? this.collapse() : this.expand();
+	}
+};
+__decorate([property({
+	type: Boolean,
+	reflect: true
+}), __decorateMetadata("design:type", Object)], UExpander.prototype, "open", void 0);
+__decorate([property({
+	type: Boolean,
+	reflect: true
+}), __decorateMetadata("design:type", Object)], UExpander.prototype, "disabled", void 0);
+__decorate([property({ type: String }), __decorateMetadata("design:type", Object)], UExpander.prototype, "label", void 0);
+UExpander = __decorate([customElement("u-expander")], UExpander);
+//#endregion
+export { UExpander };

package/dist/components/expander/UExpander.styles.d.ts

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