| 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.