ZUI — AI Agent Skills

Install the skills

npx skills add mrmartineau/zui

This writes the skill files into your project's .skills/ directory and registers them with your AI tooling.

Available skills

Skill	Use it for
`using-zui`	Building interfaces with ZUI — components, tokens, utilities, framework wrappers
`migrate-to-zui`	Porting an existing app from Tailwind, shadcn/ui, MUI, Chakra, Bootstrap, or a bespoke design system to ZUI
`zui-theme`	Building a documentation site with `@mrmartineau/zui-theme`

`using-zui`

Gives the AI assistant:

Component API — every zui-* class, variant axis, size, and shape for all components (Button, Badge, Card, Input, Dialog, Tooltip, Popover, and more)
Design tokens — the full set of --space-*, --step-*, --color-*, --radius-*, --shadow-*, --ease-*, and --z-* custom properties
Semantic theme tokens — --color-theme, --color-accent, --color-background, --color-surface, --color-border, --color-text, and state colours
Utility classes — layout (flex, flex-center, gap-*), spacing (p-*, m-*), typography (zui-text-*), flow (flow, prose), and visibility (sr-only)
CSS layer system — when to place custom CSS in zui.reset, zui.base, zui.components, or zui.utilities
Framework wrappers — import paths and prop names for @mrmartineau/zui/react, /astro, /solid, /svelte, and /vue
Icon convention — use <i class="ph ph-icon-name"></i> (HTML/Astro) or @phosphor-icons/react (React), never inline SVGs
Colour patterns — light-dark() for theme-aware values, oklch(from …) for tints and transparency

Prompt naturally once installed:

Add a success badge next to the user's name

Create a contact form with name, email, and message fields

The model will use correct ZUI classes and tokens rather than generic Tailwind or inline styles.

`migrate-to-zui`

A phased migration workflow for moving an existing project onto ZUI without a big-bang rewrite:

Audit — inventory component usage, theme values, and styling escape hatches before editing anything
Coexistence — install ZUI alongside the old library, with the layer order and reset/preflight settings that stop the two fighting
Token mapping — turn tailwind.config, createTheme, or extendTheme into a handful of CSS custom property overrides
Component mapping tables — Tailwind utilities, shadcn/ui components, MUI and Chakra props, plus Bootstrap quick hits
Gap strategy — what to do about Switch, Alert, Toast, Skeleton, Progress, Slider, and Combobox, which ZUI doesn't ship
Verification checklist — what must be true before the old dependency is uninstalled

Prompt examples:

Migrate this app from shadcn/ui to ZUI

Map our Tailwind theme config onto ZUI tokens

`zui-theme`

Covers scaffolding and integrating @mrmartineau/zui-theme, the source-only Astro docs theme built on ZUI — DocsLayout, file-based sidebar and TOC, the Demo component, and the theme switchers.

Manual installation

If your tooling doesn't support npx skills add, copy a skill file directly:

curl -o .skills/using-zui.md \
  https://raw.githubusercontent.com/mrmartineau/zui/main/skills/using-zui/SKILL.md

curl -o .skills/migrate-to-zui.md \
  https://raw.githubusercontent.com/mrmartineau/zui/main/skills/migrate-to-zui/SKILL.md

Or reference the skill content from the repository at skills/<skill-name>/SKILL.md.