name	tailwind-design-system
description	Code-generation skill for building and standardizing design systems in this repo with Tailwind CSS v4, design tokens, and component-library patterns.
metadata	{"family":"design","owner":"design + engineering","last_reviewed":"2026-05-04T00:00:00.000Z","version":"1.1.0"}

Tailwind Design System

This is a code-generation skill. Use it only for UI system implementation work in the repo.

Use When

creating or changing Tailwind CSS v4 design tokens
standardizing shared component variants
changing theme, dark mode, focus, animation, spacing, radius, or color systems
migrating or reviewing Tailwind v3 patterns in code that should follow v4
implementing shared UI primitives that must work across page families

For one-off page layout work, prefer frontend-design first and add this skill only when tokens, variants, or reusable system patterns change.

Core Rules

Tailwind v4 configuration belongs in CSS with @theme, not a new tailwind.config.ts, unless the repo already requires one.
Use semantic tokens first: brand token -> semantic token -> component usage.
Use existing primitives and cn from @/lib/utils before introducing new wrappers.
Prefer component variant maps or CVA-style APIs over repeated long class strings.
Keep dark mode and theme behavior centralized.
Use CSS transitions and native keyframes; do not add heavy animation libraries for design-system work.
Preserve accessibility defaults: visible focus rings, disabled states, keyboard behavior, and sufficient contrast.

Repo Workflow

Inspect existing Tailwind v4 setup, global CSS, shared primitives, and page-shell styles.
Identify whether the change is token-level, primitive-level, or feature-level.
Reuse current naming and spacing/radius/color conventions unless a system-level inconsistency is the actual problem.
Keep feature-specific styling inside the feature. Promote only reusable, cross-feature patterns into shared primitives.
Verify with the relevant UI checks from verification-checklist; for broad UI changes include responsive and visual audits.

References

Load these only when the task needs the detail:

references/core-patterns.md for Tailwind v4 setup, token hierarchy, CVA/button/card/form/grid examples, and utility patterns.
references/advanced-patterns.md for native CSS animations, dark mode, @utility, theme modifiers, namespace overrides, container queries, migration checklist, and detailed best practices.

Tailwind Design System

This is a code-generation skill. Use it only for UI system implementation work in the repo.

Use When

creating or changing Tailwind CSS v4 design tokens

standardizing shared component variants

changing theme, dark mode, focus, animation, spacing, radius, or color systems

migrating or reviewing Tailwind v3 patterns in code that should follow v4

implementing shared UI primitives that must work across page families

For one-off page layout work, prefer frontend-design first and add this skill only when tokens, variants, or reusable system patterns change.

Core Rules

Tailwind v4 configuration belongs in CSS with @theme, not a new tailwind.config.ts, unless the repo already requires one.

Use semantic tokens first: brand token -> semantic token -> component usage.

Use existing primitives and cn from @/lib/utils before introducing new wrappers.

Prefer component variant maps or CVA-style APIs over repeated long class strings.

Keep dark mode and theme behavior centralized.

Use CSS transitions and native keyframes; do not add heavy animation libraries for design-system work.

Preserve accessibility defaults: visible focus rings, disabled states, keyboard behavior, and sufficient contrast.

Repo Workflow

Inspect existing Tailwind v4 setup, global CSS, shared primitives, and page-shell styles.

Identify whether the change is token-level, primitive-level, or feature-level.

Reuse current naming and spacing/radius/color conventions unless a system-level inconsistency is the actual problem.

Keep feature-specific styling inside the feature. Promote only reusable, cross-feature patterns into shared primitives.

Verify with the relevant UI checks from verification-checklist; for broad UI changes include responsive and visual audits.

References

Load these only when the task needs the detail:

references/core-patterns.md for Tailwind v4 setup, token hierarchy, CVA/button/card/form/grid examples, and utility patterns.

references/advanced-patterns.md for native CSS animations, dark mode, @utility, theme modifiers, namespace overrides, container queries, migration checklist, and detailed best practices.

tailwind-design-system