PUI

Rules for AI agents

Read this section before generating any PUI interface.

1. Use the PUI components from @/components/ui/*. Install what is missing with npx @aline-aroucha/pui add <name>. Don't hand-build Button, Input, Select and so on.
2. Color only through tokens. Use the semantic Tailwind classes generated from the tokens: bg-background, text-foreground, bg-primary text-primary-foreground, text-muted-foreground, border-border, bg-success text-success-foreground. Never use hex, rgb() or the Tailwind palette (bg-teal-600, text-gray-500, bg-white, text-black).
3. Every background has its text pair. bg-primary → text-primary-foreground; bg-accent → text-accent-foreground. Don't put text-white on a color: in the dark theme the pair is dark text.
4. Dark mode is automatic through the .dark class on <html>. Don't write dark: color overrides; the tokens already switch.
5. Spacing on the 4px scale: gap-2 (8), gap-4 (16), gap-6 (24), gap-8 (32), py-12 (48). No arbitrary values (p-[13px]).
6. Radii: rounded-md on controls, rounded-lg on alerts and popovers, rounded-xl on cards, rounded-full on avatars and switches.
7. One primary action per area. The others are secondary, outline or ghost.
8. UI copy in US English, sentence case, en-US formats ($1,280.00, Oct 21, 2026, 9:42 AM).
9. Accessibility: every control has a Label; icon-only buttons have an aria-label; status is never conveyed by color alone (add an icon or a word).
10. Icons: Heroicons from @heroicons/react, at the size each style was drawn for: Micro (16/solid, size-4) in buttons, fields and badges; Mini (20/solid, size-5) in menus, lists and next to headings; Outline (24/outline, size-6) in navigation and empty states. Never lucide-react. Decorative icons stay hidden from screen readers (Heroicons sets aria-hidden by default).
11. Behavior follows Magoo. Before building or changing a component, read its Magoo page (or ask the Magoo MCP) and meet its keyboard, screen reader, touch and acceptance criteria.

Behavior and accessibility

PUI defines how things look; how they behave follows Magoo 1.6.0, the interaction-behavior library by Marcelo Sales (MIT). Every component page has an Accessibility section adapted from its Magoo entry, with the Magoo IDs it is based on.

• Every interactive state is visible: hover, pressed, keyboard focus (solid 2px ring), selected, disabled, invalid. None depends on color alone.
• Keyboard: Tab / Shift+Tab follow the visual order; Enter and Space act like the native element; Esc closes overlays; focus is never trapped outside dialogs and always lands somewhere predictable after an element closes.
• Screen readers hear a name, a role and a state for every control. Messages are announced by urgency: role="alert" only for critical ones, role="status" for the rest, never on every keystroke.
• Forms: persistent labels, instructions and errors tied to the field (Field), values kept after an invalid submit, concrete error text.
• Touch: labels are part of the target; controls keep comfortable touch areas, also with zoom.
• Motion: animations stop when the person prefers reduced motion; a loader never replaces the final message.
• Components PUI doesn't ship yet (Modal, Dialogs, Toasts, Accordion, Menu, Tooltip, Radio button, Slider, Autocomplete, Dates, File upload, Breadcrumb, Pagination, Step indicator, Carousel, Drag and drop, Links, Lists, Headings, Page regions, Tabbar) still follow their Magoo page when you build them.

Agents can query Magoo directly through its read-only MCP server (Node.js 20.19+):

{
  "mcpServers": {
    "magoo": { "command": "npx", "args": ["-y", "@acessibilidade/magoo-mcp@1.6.0"] }
  }
}

Magoo is educational guidance, not a certification: verify each behavior in the implementation.

Color

Neutrals lean slightly toward the brand green so they don't read as stock gray. The brand appears sparingly and on purpose: main action, active item, focus, links, chart series 1.

• Checked text pairs: every text color is ≥ 4.5:1 on the backgrounds its usage names, in both themes; field borders (input) and the focus ring (ring) are ≥ 3:1.
• success, warning, destructive-foreground and the matching Badge variants are PUI additions to shadcn, for record status.
• border is decorative (≈1.3:1). When a border outlines a control, use input.
• Charts: chart-1 … chart-5 in order; they also differ in lightness, not only in hue.

Typography

Geist for UI and headings, Geist Mono for code and aligned numbers (both from Google Fonts, the same as shadcn v4). The UI base is 14px (text-sm); content pages use 16px with leading-7.

• Headings h1–h4 in tracking-tight, with text-wrap: balance. One h1 per screen.
• UI: body (14/20). Labels: label (14/14, 500). Captions and badges: caption (12/16).
• Numbers in columns: font-mono tabular-nums, right-aligned.

Spacing, radius and shadow

• 4px scale (space-1 to space-12). Lay out with flex/grid and gap, not with margins on each child.
• --radius = 0.5rem; radius-sm 4px, radius-md 6px, radius-lg 8px, radius-xl 12px, as shadcn derives them.
• Subtle shadows: shadow-xs on controls, shadow-sm on cards, shadow-md on popovers, shadow-lg on dialogs. Surfaces separate through border first, then shadow.

States

• Focus: solid 2px ring in ring with a 2px offset (focus-visible:ring-2 ring-ring ring-offset-2), keyboard only.
• Hover: primary darkens 10%; ghost and outline get bg-accent text-accent-foreground.
• Disabled: opacity-50 and pointer-events-none. Explain nearby why it is disabled.
• Error: aria-invalid + destructive border + a message in text-destructive below the field.
• Loading: a Skeleton shaped like the content; in buttons, a spinning Loader2 icon + label ("Saving…").

Voice and content

• Direct and calm, like an experienced colleague. Address the reader as "you".
• Buttons use verbs that name the result: "Save changes", "Delete project", "Export CSV". Avoid "OK", "Submit", "Click here".
• Errors say what happened and how to fix it, without apologizing: "The card ending in 4821 has expired. Update your payment method."
• Sentence case in headings and buttons ("Account details", not "Account Details"). No emoji in the UI.
• Empty states say what will appear and how to start: "No orders yet. Orders from the ERP show up here after the first sync."

Iconography

Icons come from Heroicons (MIT), by the makers of Tailwind CSS, through @heroicons/react. Each style is drawn for one size, so pick the style by size instead of scaling:

• Icons inherit currentColor; color them with text tokens (text-muted-foreground, text-destructive), never with hex.
• An icon next to text is decorative: Heroicons renders aria-hidden="true" by default. An icon-only button needs aria-label on the button.
• Status icons pair with a word: CheckCircleIcon + "Paid", ExclamationTriangleIcon + "Pending", ExclamationCircleIcon + "Declined".
• Components from shadcn/ui that PUI doesn't ship import lucide-react; replace those icons with their Heroicons match before using them:

PUI has no logo yet: the name is set in type. When a mark exists, it goes in the "Logos" asset group.

Components

PUI ships 17 components: Alert, Avatar, Badge, Button, Card, Checkbox, Field, Input, Label, PasswordInput, Select, Separator, Skeleton, Switch, Table, Tabs, Textarea. They start from the shadcn/ui source, adjusted to the PUI tokens (destructive text pairs, solid focus ring, badge radius, success and warning variants) and to the Magoo behavior rules (urgency-based alert roles, hover and pressed feedback, mixed checkbox, keyboard-scrollable tables, reduced motion). Any other shadcn/ui component (Dialog, DropdownMenu, Sheet, Sonner, Command…) also works: it inherits the PUI tokens automatically.

Using it in code

In a React project with Tailwind v4 (Next.js or Vite):

npx @aline-aroucha/pui init
npx @aline-aroucha/pui add button input label card

init sets up the project, installs the PUI theme and writes AGENTS.md + CLAUDE.md, the files that make Claude, Cursor and Copilot follow these rules.