playbooks

home / skills / ladderchaos / tora-skills / ui-rules

ui-rules skill

/ui-rules

This skill enforces designer-friendly UI constraints for building accessible, fast interfaces with agents by applying Tailwind defaults and tested patterns.

npx playbooks add skill ladderchaos/tora-skills --skill ui-rules

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.9 KB
---
description: Opinionated constraints for building better interfaces with agents.
name: ui-rules
---


# UI Rules

Opinionated constraints for building better interfaces with agents.

## Stack

- MUST use Tailwind CSS defaults (spacing, radius, shadows) before custom values
- MUST use `motion/react` (formerly `framer-motion`) when JavaScript animation is required
- SHOULD use `tw-animate-css` for entrance and micro-animations in Tailwind CSS
- MUST use `cn` utility (`clsx` + `tailwind-merge`) for class logic

## Components

- MUST use accessible component primitives for anything with keyboard or focus behavior (`Base UI`, `React Aria`, `Radix`)
- MUST use the project's existing component primitives first
- NEVER mix primitive systems within the same interaction surface
- SHOULD prefer [`Base UI`](https://base-ui.com/react/components) for new primitives if compatible with the stack
- MUST add an `aria-label` to icon-only buttons
- NEVER rebuild keyboard or focus behavior by hand unless explicitly requested

## Interaction

- MUST use an `AlertDialog` for destructive or irreversible actions
- SHOULD use structural skeletons for loading states
- NEVER use `h-screen`, use `h-dvh`
- MUST respect `safe-area-inset` for fixed elements
- MUST show errors next to where the action happens
- NEVER block paste in `input` or `textarea` elements

## Animation

- NEVER add animation unless it is explicitly requested
- MUST animate only compositor props (`transform`, `opacity`)
- NEVER animate layout properties (`width`, `height`, `top`, `left`, `margin`, `padding`)
- SHOULD avoid animating paint properties (`background`, `color`) except for small, local UI (text, icons)
- SHOULD use `ease-out` on entrance
- NEVER exceed `200ms` for interaction feedback
- MUST pause looping animations when off-screen
- MUST respect `prefers-reduced-motion`
- NEVER introduce custom easing curves unless explicitly requested
- SHOULD avoid animating large images or full-screen surfaces

## Typography

- MUST use `text-balance` for headings and `text-pretty` for body/paragraphs
- MUST use `tabular-nums` for data
- SHOULD use `truncate` or `line-clamp` for dense UI
- NEVER modify `letter-spacing` (`tracking-`) unless explicitly requested

## Layout

- MUST use a fixed `z-index` scale (no arbitrary `z-x`)
- SHOULD use `size-x` for square elements instead of `w-x` + `h-x`

## Performance

- NEVER animate large `blur()` or `backdrop-filter` surfaces
- NEVER apply `will-change` outside an active animation
- NEVER use `useEffect` for anything that can be expressed as render logic

## Design

- NEVER use gradients unless explicitly requested
- NEVER use purple or multicolor gradients
- NEVER use glow effects as primary affordances
- SHOULD use Tailwind CSS default shadow scale unless explicitly requested
- MUST give empty states one clear next action
- SHOULD limit accent color usage to one per view
- SHOULD use existing theme or Tailwind CSS color tokens before introducing new ones

Overview

This skill provides opinionated UI constraints and conventions to build consistent, accessible interfaces when integrating agents. It captures practical rules for styling, components, interaction, animation, typography, layout, performance, and design to reduce ambiguity during development. Use it to align teams and speed implementation of agent-facing UI patterns.

How this skill works

The skill codifies required and recommended rules that inspect design and implementation choices against the standards (e.g., Tailwind defaults, accessible primitives, animation constraints). It surfaces concrete guidance like required ARIA, animation properties, and layout primitives so developers make predictable, performant decisions. It is meant to be referenced during design reviews, PRs, and UI implementation to catch anti-patterns early.

When to use it

  • Onboard new front-end developers to a shared UI pattern set
  • During design reviews or pull request checks for agent-facing interfaces
  • When defining or extending component libraries and design systems
  • Before introducing animations or new visual treatments
  • When choosing primitives for keyboard and focus behavior

Best practices

  • Start from project component primitives; prefer Base UI for new primitives when compatible
  • Use Tailwind defaults first, then custom values; keep a fixed z-index scale
  • Use accessible primitives (React Aria, Radix) for keyboard/focus interactions; never mix primitive systems in a single surface
  • Animate only compositor properties (transform, opacity) and respect prefers-reduced-motion
  • Place errors adjacent to the action, show skeletons for loading, and give clear next actions for empty states

Example use cases

  • Implementing an agent chat UI with consistent spacing, focus handling, and accessible controls
  • Adding a destructive confirmation: use an AlertDialog primitive with clear focus management
  • Introducing micro-animations for entrance states using motion/react and tw-animate-css while limiting duration to <=200ms
  • Creating dense data views that use tabular-nums, truncate or line-clamp, and a single accent color
  • Reviewing a PR to ensure no layout animations, no arbitrary z-index values, and no blocked paste on inputs

FAQ

Are animations allowed anywhere?

No. Animate only when explicitly requested and limit animations to transform and opacity with durations <=200ms. Respect prefers-reduced-motion.

Which component primitives should I use?

Use the project’s existing primitives first. Prefer accessible libraries (Base UI, React Aria, Radix) and never mix different primitive systems within one interaction surface.

Can I use custom shadows, gradients, or color tokens?

Prefer Tailwind default shadows and theme tokens. Avoid gradients, purple/multicolor gradients, and glow effects unless explicitly requested.