tailwind

Name: tailwind
Author: gaia-react

20stars3forks

How to install tailwind?

gaia-react/gaia/tailwind

$npx -y skills add gaia-react/gaia --skill tailwind

Installs into the current project.

Summary

Patterns and conventions for all Tailwind styling. Use this skill whenever writing Tailwind class names, combining conditional classes, building component variants, or choosing between twJoin and twMerge. Also trigger when the user asks about custom values, defining @theme tokens

Files · 1

View on GitHub

SKILL.md

1	# Tailwind
2
3	## units
4
5	Always use Tailwind units first. For custom values, always use `rem`, never `px`.
6
7	```jsx
8	// BAD - tailwind units available but custom rem used
9	return <div className="p-[1.0625rem]" />;
10
11	// GOOD - uses tailwind units
12	return <div className="p-4.25" />;
13	```
14
15	## tailwind-merge
16
17	Use tailwind-merge to concatenate class names in React components instead of template literals or array joins.
18
19	- `twJoin`: for conditional class combinations (no override needed)
20	- `twMerge`: allow class override (merges conflicting utilities; perfect for setting default and optional classes)
21
22	### Examples
23
24	```tsx
25	import {twMerge, twJoin} from 'tailwind-merge';
26
27	// BAD, template literals with potential conflicts
28	return <span className={`bg-gray-500 ${isBlue ? 'bg-blue-500' : ''}`} />;
29
30	// GOOD - twJoin for conditional classes, but no override needed
31	return <span className={twJoin('bg-gray-800', isBlue && 'text-blue-500')} />;
32
33	// GOOD, twMerge for override, twJoin for conditional classes
34	return <span className={twMerge('text-white', isBlue && 'text-blue-500')} />;
35	```
36
37	The key distinction: use `twMerge` when a component accepts a `className` prop that should be able to override defaults, `twJoin` would leave both conflicting classes on the element, but `twMerge` resolves the conflict:
38
39	```tsx
40	// twMerge enables callers to override component defaults
41	function Button({className}: {className?: string}) {
42	return (
43	<button
44	className={twMerge('bg-blue-500 px-4 py-2 text-white', className)}
45	/>
46	);
47	}
48
49	// bg-red-500 wins, twMerge removes the conflicting bg-blue-500
50	<Button className="bg-red-500" />;
51	```
52
53	## Conditional classes
54
55	Pass falsy values directly to `twJoin` / `twMerge`, they're skipped.
56
57	```tsx
58	// correct
59	twJoin('base', isActive && 'bg-blue-500', error && 'border-red-500');
60
61	// ternaries that produce two positive values are fine
62	twJoin('base', condition ? 'a' : 'b');
63	```
64
65	Don't wrap class lists in template literals to concatenate, pass each class as a separate argument. Template literals inside `twJoin` / `twMerge` are acceptable only when interpolating a pre-built string from a lookup table (e.g., `ICON_POSITION[iconPosition]` from a `Record<string, string>`).
66
67	## Variant / size lookup tables
68
69	Extract multi-class variant strings into `Record` constants at the top of the file, then reference them positionally, not via interpolation.
70
71	```ts
72	const VARIANTS: Record<Variant, string> = {
73	primary: 'border border-blue-400 bg-blue-500 text-white ...',
74	secondary: '...',
75	};
76
77	// usage
78	twJoin('rounded-sm px-3 py-2', VARIANTS[variant]);
79	```
80
81	## Custom Values
82
83	When Tailwind's built-in scale doesn't have an exact value, use an arbitrary value with `rem`, never `px`:
84
85	```tsx
86	// BAD, px unit
87	<p className="text-[9px]" />
88
89	// GOOD, rem unit
90	<p className="text-[0.5625rem]" />
91	```
92
93	Use arbitrary values sparingly. If the same custom value appears more than once, add it to the tailwind.css `@theme` instead.
94
95	## Custom Theme Tokens
96
97	When adding `@theme` tokens to `app/styles/tailwind.css`, name them by role, not by the utility they'll be used with. The CSS variable suffix becomes the suffix on every generated utility (`bg-`, `text-`, `border-`, `ring-`, `fill-`, `stroke-`, `from-`, `to-`, etc.), so a token containing a utility prefix produces stuttering class names.
98
99	Lint check before naming: mentally expand `bg-{name}`, `text-{name}`, `border-{name}`. If any reads as a stutter or nonsense, rename.
100
101	```css
102	/* BAD, produces bg-bg, text-bg, border-bg-tint, text-text-muted */
103	--color-bg: #141413;
104	--color-bg-tint: #181c1e;
105	--color-text: #e0e0e0;
106	--color-text-muted: #999;
107
108	/* GOOD, produces bg-canvas, bg-surface, text-ink, text-muted */
109	--color-canvas: #141413;
110	--color-surface: #181c1e;
111	--color-ink: #e0e0e0;
112	--color-muted: #999;
113	```
114
115	Role vocabulary that survives the lint check: `canvas`, `surface`, `surface-raised`, `ink`, `muted`, `subtle`, `primary`, `brand-*`, `success`, `warning`, `danger`, palette-style names like `claude-500`. Avoid token names starting with `bg-`, `text-`, `border-`, `ring-`, `fill-`, `stroke-`, `from-`, `to-`, `outline-`, `shadow-`.
116
117	For paired light/dark colors, prefer defining an `@utility` (like the existing `bg-body`, `text-body`) over a single `@theme` token, `@utility` binds two palette values together; a `@theme` token exposes one hex on every utility prefix.

People who liked this also viewed

6 picks

Type

tailwind

20stars3forks

View on GitHub

How to install tailwind?

gaia-react/gaia/tailwind

$npx -y skills add gaia-react/gaia --skill tailwind

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Tailwind
2
3	## units
4
5	Always use Tailwind units first. For custom values, always use `rem`, never `px`.
6
7	```jsx
8	// BAD - tailwind units available but custom rem used
9	return <div className="p-[1.0625rem]" />;
10
11	// GOOD - uses tailwind units
12	return <div className="p-4.25" />;
13	```
14
15	## tailwind-merge
16
17	Use tailwind-merge to concatenate class names in React components instead of template literals or array joins.
18
19	- `twJoin`: for conditional class combinations (no override needed)
20	- `twMerge`: allow class override (merges conflicting utilities; perfect for setting default and optional classes)
21
22	### Examples
23
24	```tsx
25	import {twMerge, twJoin} from 'tailwind-merge';
26
27	// BAD, template literals with potential conflicts
28	return <span className={`bg-gray-500 ${isBlue ? 'bg-blue-500' : ''}`} />;
29
30	// GOOD - twJoin for conditional classes, but no override needed
31	return <span className={twJoin('bg-gray-800', isBlue && 'text-blue-500')} />;
32
33	// GOOD, twMerge for override, twJoin for conditional classes
34	return <span className={twMerge('text-white', isBlue && 'text-blue-500')} />;
35	```
36
37	The key distinction: use `twMerge` when a component accepts a `className` prop that should be able to override defaults, `twJoin` would leave both conflicting classes on the element, but `twMerge` resolves the conflict:
38
39	```tsx
40	// twMerge enables callers to override component defaults
41	function Button({className}: {className?: string}) {
42	return (
43	<button
44	className={twMerge('bg-blue-500 px-4 py-2 text-white', className)}
45	/>
46	);
47	}
48
49	// bg-red-500 wins, twMerge removes the conflicting bg-blue-500
50	<Button className="bg-red-500" />;
51	```
52
53	## Conditional classes
54
55	Pass falsy values directly to `twJoin` / `twMerge`, they're skipped.
56
57	```tsx
58	// correct
59	twJoin('base', isActive && 'bg-blue-500', error && 'border-red-500');
60
61	// ternaries that produce two positive values are fine
62	twJoin('base', condition ? 'a' : 'b');
63	```
64
65	Don't wrap class lists in template literals to concatenate, pass each class as a separate argument. Template literals inside `twJoin` / `twMerge` are acceptable only when interpolating a pre-built string from a lookup table (e.g., `ICON_POSITION[iconPosition]` from a `Record<string, string>`).
66
67	## Variant / size lookup tables
68
69	Extract multi-class variant strings into `Record` constants at the top of the file, then reference them positionally, not via interpolation.
70
71	```ts
72	const VARIANTS: Record<Variant, string> = {
73	primary: 'border border-blue-400 bg-blue-500 text-white ...',
74	secondary: '...',
75	};
76
77	// usage
78	twJoin('rounded-sm px-3 py-2', VARIANTS[variant]);
79	```
80
81	## Custom Values
82
83	When Tailwind's built-in scale doesn't have an exact value, use an arbitrary value with `rem`, never `px`:
84
85	```tsx
86	// BAD, px unit
87	<p className="text-[9px]" />
88
89	// GOOD, rem unit
90	<p className="text-[0.5625rem]" />
91	```
92
93	Use arbitrary values sparingly. If the same custom value appears more than once, add it to the tailwind.css `@theme` instead.
94
95	## Custom Theme Tokens
96
97	When adding `@theme` tokens to `app/styles/tailwind.css`, name them by role, not by the utility they'll be used with. The CSS variable suffix becomes the suffix on every generated utility (`bg-`, `text-`, `border-`, `ring-`, `fill-`, `stroke-`, `from-`, `to-`, etc.), so a token containing a utility prefix produces stuttering class names.
98
99	Lint check before naming: mentally expand `bg-{name}`, `text-{name}`, `border-{name}`. If any reads as a stutter or nonsense, rename.
100
101	```css
102	/* BAD, produces bg-bg, text-bg, border-bg-tint, text-text-muted */
103	--color-bg: #141413;
104	--color-bg-tint: #181c1e;
105	--color-text: #e0e0e0;
106	--color-text-muted: #999;
107
108	/* GOOD, produces bg-canvas, bg-surface, text-ink, text-muted */
109	--color-canvas: #141413;
110	--color-surface: #181c1e;
111	--color-ink: #e0e0e0;
112	--color-muted: #999;
113	```
114
115	Role vocabulary that survives the lint check: `canvas`, `surface`, `surface-raised`, `ink`, `muted`, `subtle`, `primary`, `brand-*`, `success`, `warning`, `danger`, palette-style names like `claude-500`. Avoid token names starting with `bg-`, `text-`, `border-`, `ring-`, `fill-`, `stroke-`, `from-`, `to-`, `outline-`, `shadow-`.
116
117	For paired light/dark colors, prefer defining an `@utility` (like the existing `bg-body`, `text-body`) over a single `@theme` token, `@utility` binds two palette values together; a `@theme` token exposes one hex on every utility prefix.

People who liked this also viewed

6 picks

Type