enforce-rules-for-ui-components
Skill51k starsChanged 2 days agoMITView on GitHub
Enforce AIRI's rules for UI surfaces, borders, loading, skeleton, empty, and error states, and for the use of standard components. Use when you build, change, or review a Vue page, component, panel, card, list, dialog, or form in stage-web, stage-tamagotchi, stage-pocket, packages/stage-ui, packages/stage-pages, or packages/ui. Also use when you add a border, a spinner, a placeholder, a fetch or async state, or a new component, or when you consider writing a custom control instead of a shared one.
Adopted by
Steady: 0 new projects took it in the last 4 weeks, none the 4 weeks before.thin data
Who's talking about moeru-ai/airi
- Ian Li“Project AIRI - AI waifu / virtual characters”YouTube · Sep 7, 2025 · 30k views
- Github Updates“Airi Self hosted you owned Grok Companion (All You need to Know)”YouTube · Mar 7, 2026 · 9.5k views
- Skillmdpro“Project AIRI - Open Source AI VTuber That Plays Games (Neuro-sama Alternative)”YouTube · Mar 28, 2026 · 8.4k views
- GitHub Daily Trend AI Podcast“GitHub - moeru-ai/airi: 💖🧸 Self hosted, you owned Grok Companion, a container of souls of waifu...”YouTube · Aug 21, 2025 · 7k views
- Alex Hitt“Airi GitHub Overview: From Browser Chat Limits to a Self-Hosted Avatar Engine”YouTube · Jul 29, 2026 · 2.3k views
The biggest 5 of 96 mentions linking to the repository that our crawl found. Each line is their own headline.
See all 96
Talked about on GitHub, Bluesky, YouTube, Hacker News and the web (96 times).
On GitHub · 50
- May 9, 2026fix: correctly clean request body — moeru-ai/xsai2 reactions
- Nov 9, 2025Railway self-deployment issues — groupultra/telegram-search2 reactions
- Jun 22, 2026Integrate shared voice input session into desktop stage — Neko-233/airi1 reaction
- Apr 1, 2026test(node): add regression test for `EADDRINUSE` handling — h3js/crossws1 reaction · 2 comments
- Jun 27, 2025airi: init at 0.7.0 — NixOS/nixpkgs1 reaction · 4 comments
45 more on GitHub
- Nov 13, 2026agent-skills.github.moeru-ai.airi: 0.15.2 → 0.15.4 — sudosubin/agents.nix0 reactions
- Nov 9, 2026agent-skills.github.moeru-ai.airi: 0.15.1 → 0.15.2 — sudosubin/agents.nix0 reactions
- Nov 7, 2026Port AIRI Android capabilities into native NEXUS — mechy007/Nexus0 reactions
- Nov 4, 2026agent-skills.github.moeru-ai.airi: 0.15.0 → 0.15.1 — sudosubin/agents.nix0 reactions
- Nov 4, 2026agent-skills.github.moeru-ai.airi: 0.14.1 → 0.15.0 — sudosubin/agents.nix0 reactions
- Nov 1, 2026fix(deps): update dependency @proj-airi/ui to v0.14.1 — nekomeowww/iconify-inspector0 reactions · 1 comment
- Oct 30, 2026agent-skills.github.moeru-ai.airi: 0.14.0 → 0.14.1 — sudosubin/agents.nix0 reactions
- Oct 30, 2026agent-skills.github.moeru-ai.airi: 0.13.1 → 0.14.0 — sudosubin/agents.nix0 reactions
- Oct 29, 2026agent-skills.github.moeru-ai.airi: 0.13.0 → 0.13.1 — sudosubin/agents.nix0 reactions
- Oct 27, 2026agent-skills.github.moeru-ai.airi: 0.12.0 → 0.13.0 — sudosubin/agents.nix0 reactions
- Oct 23, 2026agent-skills.github.moeru-ai.airi: 0.11.3 → 0.12.0 — sudosubin/agents.nix0 reactions
- Oct 13, 2026fix(stage-tamagotchi): follow the cursor from DOM pointer events on Wayland — Somme4096/airi-tiny0 reactions
- Oct 11, 2026[下一版讨论] 参考 AIRI 增强角色演出:表情动作、口型与语音时序 — SlimeBoyOwO/LingChat0 reactions · 2 comments
- Oct 9, 2026最初の縦切り: 根拠付き履歴から一晩の反省会を再生できる居酒屋デモを作る — ryoryo34/agent-izakaya0 reactions
- Oct 9, 2026[Candidate] moeru-ai/airi/.agents/skills/agent-browser - agent-browser — ProSkillsMD/proskills0 reactions · 1 comment
- Oct 5, 2026Staleness report — csells/awesome-jarvis0 reactions · 5 comments
- Sep 30, 2026agent-skills.github.moeru-ai.airi: init at 0.11.3 — sudosubin/agents.nix0 reactions
- Sep 23, 2026feat(stage-ui): add cloud sync switches for providers and chats — lulu0119/airi0 reactions · 1 comment
- Sep 21, 2026`github-agents-or-bots` does not work on some pages of `apache/shardingsphere` — luoling8192/github-automated-contributors0 reactions · 2 comments
- Sep 19, 2026fix(electron): isolate IPC for bound window contexts — moeru-ai/eventa0 reactions
- Sep 5, 2026fix: verify airi clone pin after checkout — davins56/Anima-Protocol0 reactions · 7 comments
- Aug 28, 2026チャットをもっと楽しくしたい — omohikane/saku0 reactions · 2 comments
- Aug 4, 2026feat(cubism2): add verified Core provisioning for Vite — proj-airi/unplugin-live2d-sdk0 reactions
- Aug 4, 2026chore(deps): bump the production-dependencies group across 1 directory with 6 updates — bryce-seefieldt/portfolio-app0 reactions · 1 comment
- Jul 29, 2026🔥 GitHub Trending AI 早报 · 2026-07-30 · Top 6 项目 — happydog-intj/ai-xiaohongshu-daily0 reactions
- Jul 29, 2026🔥 GitHub Trending AI 早报 · 2026-07-30 · Top 6 项目 — Mystery406/ai-xiaohongshu-daily0 reactions
- Jul 29, 2026🔥 GitHub Trending AI 晚报 · 2026-07-29 · Top 6 项目 — Mystery406/ai-xiaohongshu-daily0 reactions
- Jul 29, 2026🔥 GitHub Trending AI 晚报 · 2026-07-29 · Top 6 项目 — happydog-intj/ai-xiaohongshu-daily0 reactions
- Jul 29, 2026Github trending [moeru-ai/airi] 开源AI虚拟角色容器 — web1992/github-trending0 reactions
- Jul 28, 2026🔥 GitHub Trending AI 早报 · 2026-07-29 · Top 6 项目 — happydog-intj/ai-xiaohongshu-daily0 reactions
- Jul 28, 2026🔥 GitHub Trending AI 早报 · 2026-07-29 · Top 6 项目 — Mystery406/ai-xiaohongshu-daily0 reactions
- Jul 28, 2026🔥 GitHub Trending AI 晚报 · 2026-07-28 · Top 6 项目 — Mystery406/ai-xiaohongshu-daily0 reactions
- Jul 28, 2026🔥 GitHub Trending AI 晚报 · 2026-07-28 · Top 6 项目 — happydog-intj/ai-xiaohongshu-daily0 reactions
- Jul 28, 2026Github trending [moeru-ai/airi] AI虚拟伴侣开源灵魂容器 — web1992/github-trending0 reactions
- Jul 27, 2026🔥 GitHub Trending AI 早报 · 2026-07-28 · Top 3 项目 — happydog-intj/ai-xiaohongshu-daily0 reactions
- Jul 27, 2026🔥 GitHub Trending AI 早报 · 2026-07-28 · Top 3 项目 — Mystery406/ai-xiaohongshu-daily0 reactions
- Jul 27, 2026🔥 GitHub Trending AI 晚报 · 2026-07-27 · Top 4 项目 — Mystery406/ai-xiaohongshu-daily0 reactions
- Jul 27, 2026🔥 GitHub Trending AI 晚报 · 2026-07-27 · Top 4 项目 — happydog-intj/ai-xiaohongshu-daily0 reactions
- Jul 22, 2026chore(deps): bump the production-dependencies group with 5 updates — bryce-seefieldt/portfolio-app0 reactions · 2 comments
- Jul 19, 2026fix(deps): update dependency @proj-airi/ui to v0.11.3 — nekomeowww/iconify-inspector0 reactions · 1 comment
- Jul 16, 2026GitHub trending [moeru-ai/airi] 开源复现Neuro-sama — web1992/github-trending0 reactions
- Jul 15, 2026🔥 GitHub Trending AI 早报 · 2026-07-16 · Top 8 项目 — happydog-intj/ai-xiaohongshu-daily0 reactions
- Jul 15, 2026🔥 GitHub Trending AI 早报 · 2026-07-16 · Top 8 项目 — Mystery406/ai-xiaohongshu-daily0 reactions
- Jul 15, 2026🔥 GitHub Trending AI 晚报 · 2026-07-15 · Top 8 项目 — Mystery406/ai-xiaohongshu-daily0 reactions
- Jul 15, 2026🔥 GitHub Trending AI 晚报 · 2026-07-15 · Top 8 项目 — happydog-intj/ai-xiaohongshu-daily0 reactions
On Bluesky · 32
- Feb 26, 2026I love how one of the devs literally has a trans flag pfp github.com/moeru-ai/airi — @claire.on-her.computer11 likes and reposts · 3 replies
- Jul 18, 2026🚀 Skyrocketing! 🚀 (200+ new stars) 📦 moeru-ai / airi ⭐ 42,791 (+402) 🗒 TypeScript 💖🧸 Self hosted, you-owned Grok Companion, a… — @github-trending-js.bsky.social5 likes and reposts · 1 reply
- Jul 31, 2026🚀 Skyrocketing! 🚀 (200+ new stars) 📦 moeru-ai / airi ⭐ 46,117 (+372) 🗒 TypeScript 💖🧸 Self hosted, you-owned Grok Companion, a… — @github-trending-js.bsky.social2 likes and reposts · 1 reply
- Jul 27, 2026今日のGitHubトレンド moeru-ai/airi Project AIRIは、Neuro-samaに触発され、AIワイフやバーチャルキャラクターを現実世界に具現化するための器を再現するプロジェクトです。… — @dailygithubtrends.bsky.social2 likes and reposts
- Jul 13, 2026📦 moeru-ai / airi ⭐ 41,668 (+57) 🗒 TypeScript 💖🧸 Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to… — @github-trending-js.bsky.social2 likes and reposts
27 more on Bluesky
- May 31, 2026セルフホスト可能なLLMベースのバーチャルキャラクター。LLMはクラウドサービスもローカルLLMも各種サポート。 — @matsuu.bsky.social2 likes and reposts
- Apr 8, 2026🚀 Skyrocketing! 🚀 (200+ new stars) 📦 moeru-ai / airi ⭐ 37,443 (+255) 🗒 TypeScript 💖🧸 Self hosted, you-owned Grok Companion, a… — @github-trending-js.bsky.social2 likes and reposts · 1 reply
- Mar 8, 2026This is Japan. — @halka.jp2 likes and reposts
- Mar 3, 2026🎉 Celebrating! 🎉 (500+ new stars) 📦 moeru-ai / airi ⭐ 21,939 (+842) 🗒 TypeScript 💖🧸 Self hosted, you-owned Grok Companion, a… — @github-trending.bsky.social2 likes and reposts · 1 reply
- Oct 26, 2026📦 moeru-ai / airi ⭐ 50,703 (+59) 🗒 TypeScript 💖🧸 Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to… — @github-trending-js.bsky.social1 likes and repost
- Sep 19, 2026🚀 GitHub Intelligence Drop CLI-Anything (Python • 🟢) ⭐ 49.6K → https://github.com/HKUDS/CLI-Anything airi (TypeScript • 🟢) ⭐ 49.3K →… — @githubfeed.bsky.social1 likes and repost
- Aug 23, 2026📦 moeru-ai / airi ⭐ 48,262 (+49) 🗒 TypeScript 💖🧸 Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to… — @github-trending-js.bsky.social1 likes and repost
- Aug 12, 2026Ninguém até hoje ter feito um desses assistentes de IA usando homens bara é sexismo, don't @ me github.com/moeru-ai/airi — @phalkmin.me1 likes and repost
- Jul 28, 2026🎉 Celebrating! 🎉 (500+ new stars) 📦 moeru-ai / airi ⭐ 43,710 (+554) 🗒 TypeScript 💖🧸 Self hosted, you-owned Grok Companion, a… — @github-trending-js.bsky.social1 likes and repost · 1 reply
- Jun 8, 2026📦 moeru-ai / airi ⭐ 40,816 (+43) 🗒 TypeScript 💖🧸 Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to… — @github-trending-js.bsky.social1 likes and repost
- Jun 8, 2026真面目にいうと、これにらいかちゃのモデル使ったらいい感じ動いてくれそう github.com/moeru-ai/airi — @lokxii.bsky.social1 likes and repost · 1 reply
- May 25, 2026📦 moeru-ai / airi ⭐ 39,555 (+32) 🗒 TypeScript 💖🧸 Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to… — @github-trending.bsky.social1 likes and repost
- Mar 29, 2026🚀 Skyrocketing! 🚀 (200+ new stars) 📦 moeru-ai / airi ⭐ 36,176 (+213) 🗒 TypeScript 💖🧸 Self hosted, you-owned Grok Companion, a… — @github-trending.bsky.social1 likes and repost · 1 reply
- Mar 29, 2026🚀 Skyrocketing! 🚀 (200+ new stars) 📦 moeru-ai / airi ⭐ 36,176 (+213) 🗒 TypeScript 💖🧸 Self hosted, you-owned Grok Companion, a… — @github-trending-js.bsky.social1 likes and repost · 1 reply
- Mar 7, 2026💎 Hidden Gem! 💎 (1000+ new stars) 📦 moeru-ai / airi ⭐ 30,357 (+1,362) 🗒 TypeScript 💖🧸 Self hosted, you-owned Grok Companion, a… — @github-trending-js.bsky.social1 likes and repost · 1 reply
- Feb 27, 2026🚀 Skyrocketing! 🚀 (200+ new stars) 📦 moeru-ai / airi ⭐ 17,889 (+229) 🗒 TypeScript 💖🧸 Self hosted, you-owned Grok Companion, a… — @github-trending.bsky.social1 likes and repost · 1 reply
- Feb 27, 2026🚀 Skyrocketing! 🚀 (200+ new stars) 📦 moeru-ai / airi ⭐ 17,889 (+229) 🗒 TypeScript 💖🧸 Self hosted, you-owned Grok Companion, a… — @github-trending-js.bsky.social1 likes and repost · 1 reply
- Feb 10, 2026found this today: github.com/moeru-ai/airi - 17k stars, open source Neuro-sama recreation. self-hosted AI VTuber that plays Minecraft AND… — @viridian.vampuppy.systems1 likes and repost
- Oct 31, 2025github.com/moeru-ai/airi — @heimusu.bsky.social1 likes and repost
- Aug 24, 2025今日のGitHubトレンド moeru-ai/airi このリポジトリは「Project AIRI」として、AIバーチャルキャラクター「Neuro-sama」の再構築を目的としています。… — @dailygithubtrends.bsky.social1 likes and repost
- Aug 21, 2025「AIRI」は、Web技術を多用してAIキャラクターを開発するプロジェクトらしい。ゲームプレイや会話も可能なAIを、ブラウザやデスクトップで動かせるのが特徴で、VTuberのような存在を誰でも手軽に作れる可能性があるかもしれない。 yug1224 starred… — @yug1224.com1 likes and repost
- Aug 20, 2025🚀 Skyrocketing! 🚀 (200+ new stars) 📦 moeru-ai / airi ⭐ 3,123 (+387) 🗒 Vue 💖🧸 Self hosted, you owned Grok Companion, a container of… — @github-trending.bsky.social1 likes and repost
- Jul 15, 2025Show HN: Recreation of Neuro-sama for a year, alternative of Grok Companion This is the project we've worked for over a year, gaining… — @llms.activitypub.awakari.com.ap.brid.gy1 likes and repost
- Sep 28, 2026🚀 Skyrocketing! 🚀 (200+ new stars) 📦 moeru-ai / airi ⭐ 49,672 (+216) 🗒 TypeScript 💖🧸 Self hosted, you-owned Grok Companion, a… — @github-trending-js.bsky.social0 likes and reposts · 1 reply
- Jul 27, 2026🎉 Celebrating! 🎉 (500+ new stars) 📦 moeru-ai / airi ⭐ 43,710 (+554) 🗒 TypeScript 💖🧸 Self hosted, you-owned Grok Companion, a… — @github-trending.bsky.social0 likes and reposts · 1 reply
- Mar 3, 2026🎉 Celebrating! 🎉 (500+ new stars) 📦 moeru-ai / airi ⭐ 21,939 (+842) 🗒 TypeScript 💖🧸 Self hosted, you-owned Grok Companion, a… — @github-trending-js.bsky.social0 likes and reposts · 1 reply
- Aug 24, 2025💎 Hidden Gem! 💎 (1000+ new stars) 📦 moeru-ai / airi ⭐ 8,795 (+1,317) 🗒 Vue 💖🧸 Self hosted, you owned Grok Companion, a container of… — @github-trending.bsky.social0 likes and reposts · 1 reply
On YouTube · 10
- Sep 7, 2025Project AIRI - AI waifu / virtual characters — Ian Li30k views · 21 comments
- Mar 7, 2026Airi Self hosted you owned Grok Companion (All You need to Know) — Github Updates9.5k views · 13 comments
- Mar 28, 2026Project AIRI - Open Source AI VTuber That Plays Games (Neuro-sama Alternative) — Skillmdpro8.4k views · 8 comments
- Aug 21, 2025GitHub - moeru-ai/airi: 💖🧸 Self hosted, you owned Grok Companion, a container of souls of waifu... — GitHub Daily Trend AI Podcast7k views · 8 comments
- Jul 29, 2026Airi GitHub Overview: From Browser Chat Limits to a Self-Hosted Avatar Engine — Alex Hitt2.3k views
5 more on YouTube
- Sep 29, 2026One AI Chats on Discord While Playing Minecraft? moeru-ai/airi Hands-On Test — DevCovery1.5k views
- Mar 8, 2026Let AI Play Minecraft with You! airi Hands-on Tutorial — Deploy a Game-playing AI Companion in 3... — DevCovery1.5k views · 3 comments
- Aug 14, 2026Project AIRI: A Self-Hosted AI Companion Experience | moeru-ai/airi — What's this repo1.1k views
- Sep 29, 2026一個 AI 同時聊 Discord 又玩 Minecraft?moeru-ai/airi 實測 — GitCovery467 views
- Oct 4, 2026Airi AI Companion – Self‑Hosted, User‑Owned Grok Bot for Voice Chat, Minecraft & Factorio — Next Horizon317 views · 3 comments
On Hacker News · 3
- Jul 15, 2025Show HN: Recreation of Neuro-sama for a year, alternative of Grok Companion10 points · 3 comments
- Jul 17, 2025The Open Source xAI Ani that's next level3 points · 1 comment
- Aug 21, 2025Airi: Digital Companion1 point
On the web · 1
- Oct 11, 2026moeru-ai/airi · 깃밥 — gitbap.com
In this repository41 other files it gives its agents.
- AGENTS.mdAGENTS.md
- server/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- server/CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- agent-browser-electronSkill
- agent-browserSkill
- analyze-io-tracesSkill
- create-prSkill
- design-audio-visualizationsSkill
- enforce-rules-for-fontsSkill
- enforce-rules-for-i18nSkill
- enforce-rules-for-pinia-syncedSkill
- enforce-rules-for-render-loopsSkill
- enforce-rules-for-typescriptSkill
- enforce-rules-for-ui-testsSkill
- enforce-rules-for-unocssSkill
- enforce-rules-for-vitestSkill
- eventaSkill
- piniaSkill
- pnpmSkill
- release-note-writerSkill
- simple-englishSkill
- stage-tamagotchi-godot-csharpSkill
- tsdownSkill
- unocssSkill
- upload-github-attachmentSkill
- use-agent-browser-for-airiSkill
- use-agent-browser-with-input-fileSkill
- use-vishot-for-airiSkill
- use-vishotSkill
- use-vishot-with-capacitorSkill
- use-vishot-with-electronSkill
- use-vishot-with-input-fileSkill
- use-vishot-with-webSkill
- vue-best-practicesSkill
- vueSkill
- vue-testing-best-practicesSkill
- vueuse-functionsSkill
- web-design-guidelinesSkill
- xsaiSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
19 rules. About 0 are common, 9 are distinctive, and 10 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
10
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 14
Do not add a border unless a fill change or spacing cannot separate the surface.
- Very specific: line 15
Use a neutral fill step, for example bg-neutral-50 on bg-white, or a dark-mode equivalent, before you try a border.
- Distinctive: line 18
Do not put a border inside another border.
- Distinctive: line 19
Use a dashed border only for a real drop zone.
- Very specific: line 20
When a border is necessary, obey the color limits in the Borders section of DESIGN.md.
- Very specific: line 21
Keep focus-visible outlines.
- Distinctive: line 31
Keep the real labels, headers, and actions visible during the load when they do not depend on the data.
- Very specific: line 32
Use a spinner only for a short action of unknown shape, or inside a control.
- Distinctive: line 33
Do not blank the page or show only a centered spinner for a whole settings page.
- Distinctive: line 40
Use a fill and a short text.
- Very specific: line 45
Use Alert with the danger or warning tone for a status that the user must read.
- Very specific: line 46
Use ContainerError for error details, and ErrorBoundary to keep a failed subtree from blanking the host layout.
- Distinctive: line 49
Do not show a raw stack or a JSON payload as the main message.
- Very specific: line 53
Before you write a control, search packages/ui/src/components and packages/stage-ui/src/components.
- Very specific: line 54
Use the existing component and its variants, for example Button, Select, FieldInput, Alert, Callout, Skeleton, and BottomDrawer.
- Distinctive: line 55
Do not copy a component into a page to change one style.
- Very specific: line 56
Do not build a raw <button>, <input>, or <select> when a shared component does the same job.
- Distinctive: line 64
Put the component at the correct level:
- Very specific: line 70
When the request needs speed, write a local component first.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Enforce AIRI UI Component Rules
AIRI interfaces stay calm when they reuse a small set of surfaces and components. Each page also must show what happens while data loads, when it is empty, and when it fails. Apply these rules with the AIRI Design Guide.
Prefer fills to borders
A border adds a line that the eye must read. Most separations work with a fill change, spacing, or grouping.
- Do not add a border unless a fill change or spacing cannot separate the surface.
- Use a neutral fill step, for example
bg-neutral-50onbg-white, or a dark-mode equivalent, before you try a border. - Show selection with a tinted fill and an indicator, for example a check icon, a radio dot, or a badge. Do not add a border color change on top.
- Show hover with a fill change, not with a border change.
- Do not put a border inside another border.
- Use a dashed border only for a real drop zone.
- When a border is necessary, obey the color limits in the Borders section of
DESIGN.md. - Keep
focus-visibleoutlines. An outline shows keyboard focus, and it is not a decorative border.
Design every async state
Each view that loads, saves, or streams data has four states: loading, empty, error, and ready. Design each state before you finish the view.
Loading
- For a first load of content with a known shape, show a skeleton with the
Skeletoncomponent of@proj-airi/ui. - Make the skeleton match the final layout: the same rows, columns, sizes, and gaps. When the data arrives, the layout must not jump.
- Keep the real labels, headers, and actions visible during the load when they do not depend on the data.
- Use a spinner only for a short action of unknown shape, or inside a control. Use the
loadingprop ofButton,BasicButton, orIconButtonfor an action. - Do not blank the page or show only a centered spinner for a whole settings page.
- For a refresh of data that is already visible, keep the old data visible and show a small progress cue.
- Respect reduced motion. Use
animation="none"onSkeletonwhen the user asks for reduced motion.
Empty
- Give a short text that tells what is missing and the next action, for example a button that creates the first item.
- Use a fill and a short text. Do not use a dashed frame or a large decorative illustration for an empty state.
Error
- Show an error near the content that failed. Do not replace the whole page for a local failure.
- Use
Alertwith thedangerorwarningtone for a status that the user must read. - Use
ContainerErrorfor error details, andErrorBoundaryto keep a failed subtree from blanking the host layout. - Give a retry action when a retry can succeed.
- Get the message with
errorMessageFrom(error)from@moeru/std. Put user-visible text inpackages/i18n. - Do not show a raw stack or a JSON payload as the main message.
Use the standard components
- Before you write a control, search
packages/ui/src/componentsandpackages/stage-ui/src/components. Readdocs/ai/context/ui-components.md. - Use the existing component and its variants, for example
Button,Select,FieldInput,Alert,Callout,Skeleton, andBottomDrawer. - Do not copy a component into a page to change one style. Use or add a prop or a variant.
- Do not build a raw
<button>,<input>, or<select>when a shared component does the same job.
When the standard components are not enough
Sometimes no shared component does the job, or the result does not look right. In that case, you can propose a new component or a change to a shared one.
- Tell the user which component you tried and why it does not fit. Show a screenshot or a story when you can.
- Propose the shape of the new API: the props, slots, emits, and the types.
- Put the component at the correct level:
packages/uifor a primitive with no business logic.packages/stage-ui/src/componentsfor a business component that several pages share.packages/stage-ui/src/components/scenarios/for a component of one page or one use case.packages/stage-ui/src/composables/for the logic that the component needs.
- Export the types next to the component. Add a Histoire story. Update
docs/ai/context/ui-components.mdfor apackages/uicomponent. - When the request needs speed, write a local component first. Shape its props so that it can move to
packages/uiorpackages/stage-uilater. Tell the user about the follow-up.
Review checklist
- Does each border have a reason that a fill change cannot cover?
- Does the view have a loading, empty, error, and ready state?
- Does the skeleton match the final layout, with no layout jump?
- Is each error near its content, readable, and recoverable when possible?
- Does each control come from
packages/uiorpackages/stage-ui? If not, is the reason written down?
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

