zelda-hyrule-ui-vue 0.1.0 — Vue 3 MVP (11 components)

EN

The official Vue 3 port is live: zelda-hyrule-ui-vue@0.1.0

npm i zelda-hyrule-ui-vue

11 components — 8 core (Button Card Dialog Modal Divider Loading HealthBar StaminaWheel) + 3 signature Sheikah pieces (SheikahBackground SheikahScanlines SheikahSymbol).

• Props 1:1 with the React version — same names, same enums, same defaults. Vue idioms only where the framework differs: callbacks → emits (onClose → @close), children/icon/footer → slots, class/style native fallthrough.
• Pixel-identical to React — both packages compile the exact same Less modules, design tokens, Figma-exact SVGs, and bundled Hylia Serif from a shared packages/core.
• Modal a11y built in — Teleport to body, focus trap/restore, Escape close, scroll lock. Requires vue >= 3.5.
• Usage mapping for AI assistants & humans: skill/references/vue-usage.md

The remaining components are being ported — vote / track at #2.

Also in this release: the repo is now an npm-workspaces monorepo (packages/core + react + vue). The React package zelda-hyrule-ui is unaffected — its build output was verified byte-identical after the refactor.

中文

官方 Vue 3 移植版上线：zelda-hyrule-ui-vue@0.1.0

npm i zelda-hyrule-ui-vue

11 个组件——8 个核心（Button Card Dialog Modal Divider Loading HealthBar StaminaWheel）+ 3 个希卡味道命门（SheikahBackground SheikahScanlines SheikahSymbol）。

• Props 与 React 版 1:1 对齐——同名、同枚举、同默认值；仅框架差异处用 Vue 习惯：回调转 emit（onClose → @close），children/icon/footer 转 slot，class/style 原生透传。
• 与 React 版像素级一致——两个包从共享的 packages/core 编译同一份 Less 样式、设计 token、Figma 逐节点 SVG 和内嵌 Hylia Serif 字体。
• Modal 内置无障碍——Teleport 到 body、焦点圈定/还原、Escape 关闭、滚动锁定。要求 vue >= 3.5。
• 用法映射（AI / 人类通用）：skill/references/vue-usage.md

其余组件移植中——催更 / 跟进见 #2。

本次同步：仓库重构为 npm workspaces monorepo（packages/core + react + vue）。React 包 zelda-hyrule-ui 不受影响——重构后构建产物经逐字节比对验证一致。

---

Unofficial, non-commercial fan project. Not affiliated with or endorsed by Nintendo.
非官方、非商用粉丝项目，与任天堂无任何隶属或背书关系。

v0.4.0 — Modal: portal + focus trap (requires React 18)

🧱 Modal hardened to component-library standards

Changes

• Portal rendering — Modal now renders into document.body via createPortal, so the overlay is no longer clipped when an ancestor has overflow: hidden, transform, or a stacking context. (SSR-safe: falls back to inline render when there's no document.)
• Focus management — focus moves into the dialog on open, is restored to the previously focused element on close, and is trapped inside the dialog (Tab/Shift+Tab cycle within it).
• useId() — replaces the hardcoded id="modal-title", so multiple modals on one page no longer create duplicate, invalid IDs.
• Body scroll lock — the body's original overflow is restored on close instead of being blanked.

⚠️ Breaking

• React peer dependency raised to >=18 (useId requires React 18). If you're on React 17, stay on 0.3.x.

The public Modal props are unchanged — only internals were reworked.

---

🧱 Modal 重构到组件库标准（中文）

变更

• Portal 渲染 —— Modal 现在通过 createPortal 渲染到 document.body，遮罩不再被祖先的 overflow: hidden、transform 或层叠上下文裁切。（SSR 安全：无 document 时回退为原地渲染。）
• 焦点管理 —— 打开时焦点移入对话框，关闭时还原到之前聚焦的元素，并在对话框内捕获焦点（Tab / Shift+Tab 在弹窗内循环，不会跑到背后被遮挡的元素）。
• useId() —— 替换写死的 id="modal-title"，同一页面多个 Modal 不再产生重复的非法 id。
• 滚动锁定 —— 关闭时还原 body 原有的 overflow，而不是粗暴清空。

⚠️ 不兼容变更

• React peer 依赖提升到 >=18（useId 需要 React 18）。如果你还在用 React 17，请继续使用 0.3.x。

Modal 对外 props 没有变化，只重写了内部实现。

---

Full changelog: v0.3.0...v0.4.0

v0.3.0 — remove masterCycle (breaking) + cubeBomb plus fix

⚠️ Breaking change + API honesty

Breaking

• SheikahAbility: removed 'masterCycle' from AbilityType. It had no source asset in the original Figma kit (no corresponding node), so under this project's node-by-node export principle it could only ever render a fallback icon. Keeping it in the public type union was a false promise — especially harmful for AI consumers told to trust the types. Removing it makes the API honest and aligns AbilityType with SheikahRune's RuneType.

  Migration: if you used <SheikahAbility ability="masterCycle" />, switch to one of the supported runes: roundBomb · cubeBomb · magnesis · stasis · cryonis · camera.

Fixes

• cubeBomb's plus state now uses its own cube-bomb art instead of borrowing the round-bomb-plus icon.
• Synced skill/references/props-quickref.md and docs/FULL_COMPONENT_PLAN.md.

Note: the cubeBomb / camera wrong-icon fixes and the font-bundling fix shipped in v0.2.1 — this release adds the breaking type cleanup on top.

---

⚠️ 不兼容变更 + API 诚实性（中文）

不兼容变更

• SheikahAbility：从 AbilityType 中移除了 'masterCycle'。 它在原始 Figma 素材包里没有对应节点，按本项目"逐节点导出、不手绘"的原则，它只能永远渲染一个回退图标。把它留在对外类型里是一个无法兑现的承诺——对"被告知要信任类型"的 AI 使用者尤其有害。移除后 API 更诚实，且让 AbilityType 与 SheikahRune 的 RuneType 对齐。

  迁移： 如果你用了 <SheikahAbility ability="masterCycle" />，请改用受支持的能力之一：roundBomb · cubeBomb · magnesis · stasis · cryonis · camera。

修复

• cubeBomb 的 plus 加强态改用自己的方块炸弹图标，不再借用圆形炸弹的 plus 图标。
• 同步更新了 skill/references/props-quickref.md 和 docs/FULL_COMPONENT_PLAN.md。

注：cubeBomb / camera 的图标修复以及字体打包修复已在 v0.2.1 发布——本次在此基础上追加了这个不兼容的类型清理。

---

Full changelog: v0.2.1...v0.3.0

v0.2.1 — bug fixes (font bundling, Toast, Next.js)

🩹 Patch release — bug fixes from a code review

This is a patch release fixing real bugs that affected npm users, plus documentation accuracy.

🔴 Bug fixes (affect package users)

• Hylia Serif font is now actually bundled. Previously the @font-face only lived in the demo's index.html, so package users silently fell back to Georgia. The font now ships in dist/index.css (with the .ttf externalized to dist/files/) and works on import 'zelda-hyrule-ui/style'.
• SheikahAbility — cubeBomb and camera now render their correct icons (they were pointing at placeholder SVGs even though the real assets existed).
• Toast — the auto-dismiss timer no longer resets when a parent re-renders with an inline onClose callback (now held in a ref).
• Next.js App Router — added a 'use client' banner so hook-using components (Toast/Modal) can be imported directly without wrapping.

📝 Docs

• License wording fixed: code is MIT; commercial use is discouraged due to Nintendo IP (risk-on-user), replacing the self-contradictory "MIT for personal use only".
• Corrected a non-existent design token in the README (#1A1A2E → real Sheikah panel rgba(10,20,40,0.85)).
• AI_USAGE.md no longer implies the library has only 8 components; points to the skill references for the full 83-component prop enums.
• Misc drift fixes (version stamps, bundle size, contributing SVG convention).

---

🩹 补丁版本 —— 源自一次代码审查（中文）

本次为补丁版本，修复了影响 npm 用户的真实 bug，并订正了文档准确性。

🔴 Bug 修复（影响包用户）

• Hylia Serif 字体现在真正打进包了。 此前 @font-face 只存在于 demo 的 index.html，导致包用户的标题字体静默退化成 Georgia。现在字体随 dist/index.css 发布（.ttf 外置到 dist/files/），import 'zelda-hyrule-ui/style' 即生效。
• SheikahAbility —— cubeBomb 和 camera 现在渲染正确的图标（之前指向了占位 SVG，尽管真实素材就在仓库里）。
• Toast —— 自动消失的定时器不再因父组件传入内联 onClose 回调重渲染而被重置（已用 ref 收住）。
• Next.js App Router —— 增加 'use client' 标记，用了 hooks 的组件（Toast/Modal）可直接 import，无需自己包一层。

📝 文档

• 修正自相矛盾的许可证表述：代码为 MIT；因涉及任天堂 IP，不建议商用、风险自负——替换掉原来的"MIT 仅供个人使用"。
• 修正 README 里不存在的设计 token（#1A1A2E → 真实希卡面板色 rgba(10,20,40,0.85)）。
• AI_USAGE.md 不再暗示库只有 8 个组件；指向 skill references 获取全部 83 个组件的 props 枚举。
• 其他漂移订正（版本戳、包体积、贡献指南的 SVG 约定）。

🙏 Credits / 致谢

Thanks to the external review that surfaced these issues. 感谢指出这些问题的外部代码审查。

---

Full changelog: v0.2.0...v0.2.1

v0.2.0 — Precision, Mobile & Compliance

A big quality release: licensing compliance, a full mobile overhaul, and three waves of high-precision Figma node-level icon restoration. No breaking API changes.

一次重量级的质量更新：许可证合规、移动端全面重做、三波 Figma 节点级高精度图标还原。无破坏性 API 变更，可直接升级。

npm install zelda-hyrule-ui@0.2.0

---

✨ Highlights / 核心更新

🎯 High-precision icon restoration (3 waves) / 高精度图标还原（三波）
Replaced emoji, unicode glyphs, and hand-drawn geometric approximations with icons rebuilt from exact Figma node coordinates — the core fix for the "looks AI-generated" feedback.

把 emoji、unicode 字符、手画几何近似，全部替换为从 Figma 节点精确坐标重建的图标——针对"看起来像 AI 生成"反馈的核心整改。

• Wave 1: SheikahCompendiumFilters, SheikahTextTitle, SheikahRune
• Wave 2: BonusEffectIcon (14 icons, game-accurate colors), MenuSections, QuestListItem
• Wave 3: RupeeType (7-facet gem), RupeeCounter, QuestTypeIcon, MapQuestMarker, MapBeacon, AttackDefenseValues, MapHeroLocation (also fixed wrong color), QuestNotification

📱 Mobile overhaul / 移动端全面重做

• Component-level adaptation: FitScale auto-scales oversized console-UI components to fit phone screens; fixed docs-page horizontal overflow; comfortable >=44px tap targets.
• Framework re-layout: KPI broadsheet hero, auto-numbered sections, unified chapter markers.
• 组件级自适应 + 页面框架重排，手机上不再错乱。

⚖️ Licensing & IP compliance / 许可证与 IP 合规

• Documented CC BY 4.0 attribution for the source Figma kit (Hunter Paramore).
• Prominent unofficial / non-commercial fan-project disclaimers; clarified the trademark layer (Nintendo) vs. the CC BY design layer.

🤖 AI / Skill improvements / AI 与 Skill 改进

• SKILL.md split into a routing layer + on-demand references/ (progressive disclosure).
• New layout-bridge.md: interop guide to pair with layout skills for Zelda-style PPT / social cards (MIT-safe, no AGPL code merged).

---

Notes

• Unofficial fan project, not affiliated with or endorsed by Nintendo. The Legend of Zelda and related trademarks (C) Nintendo.
• UI design based on the Zelda BOTW UI Kit by Hunter Paramore (CC BY 4.0).

Full Changelog: https://github.com/chaos-xxl/zelda-hyrule-ui/commits/v0.2.0