struxadotcloud/struxa

public

feat: global unslop6531421a month ago208 lines · 5.9 KB

1	# Customization & Theming
2
3	Components reference semantic CSS variable tokens. Change the variables to change every component.
4
5	## Contents
6
7	- How it works (CSS variables → Tailwind utilities → components)
8	- Color variables and OKLCH format
9	- Dark mode setup
10	- Changing the theme (presets, CSS variables)
11	- Adding custom colors (Tailwind v3 and v4)
12	- Border radius
13	- Customizing components (variants, className, wrappers)
14	- Checking for updates
15
16	---
17
18	## How It Works
19
20	1. CSS variables defined in `:root` (light) and `.dark` (dark mode).
21	2. Tailwind maps them to utilities: `bg-primary`, `text-muted-foreground`, etc.
22	3. Components use these utilities - changing a variable changes all components that reference it.
23
24	---
25
26	## Color Variables
27
28	Every color follows the `name` / `name-foreground` convention. The base variable is for backgrounds,
29
30	\| Variable \| Purpose \|
31	\| -------------------------------------------- \| -------------------------------- \|
32	\| `--background` / `--foreground`
33	\| `--card` / `--card-foreground`
34	\| `--primary` / `--primary-foreground`
35	\| `--secondary` / `--secondary-foreground`
36	\| `--muted` / `--muted-foreground`
37	\| `--accent` / `--accent-foreground`
38	\| `--destructive` / `--destructive-foreground`
39	\| `--border` \| Default border color \|
40	\| `--input` \| Form input borders \|
41	\| `--ring` \| Focus ring color \|
42	\| `--chart-1` through `--chart-5`
43	\| `--sidebar-*` \| Sidebar-specific colors \|
44	\| `--surface` / `--surface-foreground`
45
46	Colors use OKLCH: `--primary: oklch(0.205 0 0)` where values are lightness (0–1), chroma (0 = gray), and hue (0–360).
47
48	---
49
50	## Dark Mode
51
52	Class-based toggle via `.dark` on the root element. In Next.js, use `next-themes`:
53
54	```tsx
55	import { ThemeProvider }
56
57	<ThemeProvider attribute="
58	{children}
59	</ThemeProvider>;
60	```
61
62	---
63
64	## Changing the Theme
65
66	```bash
67	# Apply a preset code from ui.shadcn.com.
68	npx shadcn@latest apply --preset
69
70	# Positional shorthand also works.
71	npx shadcn@latest apply a2r6bw
72
73	# Switch to a named preset and overwrite existing components.
74	npx shadcn@latest apply --preset
75
76	# Preserve existing components instead.
77	npx shadcn@latest init --preset
78
79	# Use a custom theme URL.
80	npx shadcn@latest apply --preset
81	```
82
83	Or edit CSS variables directly in `globals.css`.
84
85	---
86
87	## Adding Custom Colors
88
89	Add variables to the file at `tailwindCssFile` from `npx shadcn@latest info` (typically `
90
91	```css
92	/* 1. Define in the global CSS file. */
93	:root {
94	--warning: oklch(0.84
95	--warning-foreground: oklch(0.28
96	}
97	.dark {
98	--warning: oklch(0.41
99	--warning-foreground: oklch(0.99
100	}
101	```
102
103	```css
104	/* 2a. Register with Tailwind v4 (@theme inline). */
105	@theme inline {
106	--color-warning: var(--warning
107	--color-warning-foreground: var(--warning-foreground
108	}
109	```
110
111	When `tailwindVersion` is `"v3"` (check via `
112
113	```js
114	// 2b. Register with Tailwind v3 (tailwind.config.js).
115	module.exports = {
116	theme: {
117	extend: {
118	colors: {
119	warning: "oklch(var(--warning) / <alpha-value>)",
120	"warning-foreground": "oklch(var(--warning-foreground) / <alpha-value>)"
121	},
122	},
123	},
124	};
125	```
126
127	```tsx
128	// 3. Use in components.
129	<div className="bg-warning text-warning-foreground
130	```
131
132	---
133
134	## Border Radius
135
136	`--radius` controls border radius globally. Components derive values from it (`rounded-lg` = `
137
138	---
139
140	## Customizing Components
141
142	See also: [rules/styling.md](./rules/styling.md
143
144	Prefer these approaches in order:
145
146	### 1. Built-in variants
147
148	```tsx
149	<Button variant="
150	Click
151	</Button>
152	```
153
154	### 2. Tailwind classes via `
155
156	```tsx
157	<Card className="
158	```
159
160	### 3. Add a new variant
161
162	Edit the component source to add a variant via `cva`:
163
164	```tsx
165	// components/ui/button.tsx
166	warning: "bg-warning text-warning-foreground hover:bg-warning/90",
167	```
168
169	### 4. Wrapper components
170
171	Compose shadcn/ui primitives into higher-level components:
172
173	```tsx
174	export function ConfirmDialog({
175	return (
176	<AlertDialog>
177	<AlertDialogTrigger asChild
178	<AlertDialogContent>
179	<AlertDialogHeader>
180	<AlertDialogTitle>{title
181	<AlertDialogDescription>{description
182	</AlertDialogHeader>
183	<AlertDialogFooter>
184	<AlertDialogCancel>Cancel</AlertDialogCancel
185	<AlertDialogAction onClick
186	</AlertDialogFooter>
187	</AlertDialogContent>
188	</AlertDialog>
189	);
190	}
191	```
192
193	---
194
195	## Checking for Updates
196
197	```bash
198	npx shadcn@latest add button
199	```
200
201	To preview exactly what would change before updating, use `--dry-run` and `--diff`:
202
203	```bash
204	npx shadcn@latest add button
205	npx shadcn@latest add button
206	```
207
208	See [Updating Components in SKILL.md](./SKILL.md#updating-components