AgentSkillsCN

React

React

SKILL.md

Agent Rules – React UI

Before implementing or modifying ANY UI:

  1. •Read docs/agent/SKILL.md
  2. •Reuse existing TailAdmin components and tokens
  3. •Do not create new components unless reuse is impossible

name: react-tailadmin-ui-consistency description: Use this skill FIRST for any React UI or styling work. Enforces consistent TailAdmin design tokens, Tailwind utility grammar, reusable components, and dark mode parity.

React UI Consistency Playbook – TailAdmin (Tailwind)

This skill enforces UI consistency across the React codebase. Before implementing or modifying ANY UI (layout, styling, components), you MUST follow this file.

The goal is simple:

Any new UI must look like it already belongs to the project.

Source of Truth (READ FIRST)

Before writing UI code, review these files:

  • •src/styles/tailwind.css
    (design tokens: colors, typography, spacing, shadows, dark mode)
  • •tailwind.config.js
    (theme extensions and palette)
  • •Existing UI primitives (reuse first):
    • •src/components/button.tsx
    • •src/components/text-field/input-field.tsx
    • •src/components/text-field/label-field.tsx
    • •src/components/text-field/checkbox-field.tsx
  • •Similar screens under:
    • •src/pages/** (copy layout and style patterns)

If these files do not exist yet, create minimal versions before implementing UI.

Non-Negotiable Rules

1) Reuse existing components first

  • •Always prefer existing primitives (Button, Input, Label, CheckboxField, etc.).
  • •Do NOT restyle native HTML elements if a shared component already exists.
  • •If an existing component covers ≥ 80% of the requirement, reuse or extend it.

2) Creating new components (ALLOWED WITH CONDITIONS)

Creating a new component is allowed ONLY when all conditions below are met:

  1. •No existing component or example covers at least 80% of the required behavior or layout.
  2. •The component is reusable (intended for multiple screens) OR represents a new UI primitive (e.g. Badge, EmptyState, StatusPill, StatCard).
  3. •The component follows the existing TailAdmin style grammar:
    • •uses existing design tokens and utility patterns
    • •supports dark mode when applicable
    • •avoids hardcoded colors, spacing, or typography
    • •uses consistent props naming (variant, size, tone, etc.)

If a similar component exists, extend or compose it instead of creating a new one.

One-off components with no reuse intent are discouraged.

3) Use tokens and established utility patterns

  • •Prefer existing TailAdmin patterns:
    • •spacing: px-4, py-2.5, h-11, gap-4
    • •radius: rounded-lg
    • •shadows: shadow-theme-xs
    • •typography: text-sm, text-title-sm
  • •Prefer token-based colors:
    • •brand: bg-brand-500, hover:bg-brand-600
    • •neutral: text-gray-800, border-gray-300
    • •dark mode: dark:bg-gray-900, dark:text-white/90
  • •Avoid random values such as mt-[7px], text-[13px] unless strictly necessary.

4) Dark mode is mandatory

  • •Any new UI must include dark: equivalents.
  • •Follow existing conventions:
    • •dark:bg-gray-900
    • •dark:text-white/90
    • •dark:border-gray-700
    • •dark:hover:bg-white/[0.03]

Missing dark mode styles is considered incomplete work.

5) Interaction states are required

Any interactive UI must include:

  • •hover state
  • •focus state (ring or border)
  • •disabled state when applicable

Follow existing Button and Input behavior for consistency.

Workflow (FOLLOW IN ORDER)

  1. •

    Find a similar existing UI

    • •Look for a comparable screen in src/pages/**.
    • •Copy layout and spacing patterns instead of inventing new ones.
  2. •

    Compose from primitives

    • •Build UI using shared components first.
    • •Only create new components if reuse is not possible (see rules above).
  3. •

    Apply styling using TailAdmin grammar
    Common patterns to reuse:

    • •containers: flex flex-col gap-*, max-w-* mx-auto
    • •cards: rounded-lg bg-white dark:bg-gray-900 shadow-theme-xs
    • •buttons: use Button variants instead of custom class strings
  4. •

    Ensure dark mode parity

    • •Every background, border, and text color must have a dark equivalent.
  5. •

    Run a consistency check

    • •Compare spacing, typography, and colors with similar screens.
    • •Verify hover/focus/disabled states.
    • •Check responsiveness at common breakpoints.

Definition of Done (UI)

A UI change is DONE only when:

  • •Existing primitives are reused or extended where possible
  • •New components (if any) meet the creation conditions
  • •No hardcoded colors or random spacing values are introduced
  • •Dark mode styles are present
  • •Hover, focus, and disabled states are implemented
  • •UI matches spacing and typography of similar screens
  • •Code is reusable and not a one-off hack

Common Pitfalls (AVOID)

  • •Creating new components without searching existing ones
  • •Styling raw <button> or <input> instead of using shared primitives
  • •Missing dark: styles
  • •Mixing multiple styling systems in one component
  • •Hardcoding hex colors or arbitrary pixel values
  • •Adding ad-hoc variants instead of extending existing components

Final Rule

If you are unsure:

Copy the closest existing screen or component and adapt it.
Do not invent new UI patterns without clear justification.