Tailwind classes in OCaml
anil.recoil.org
1# Tailwind OCaml
2
3An OCaml library for generating Tailwind CSS classes with compile-time
4validation and a companion HTML generation library using Htmlit.
5
6This project provides two main libraries:
7
8- **`tailwind`**: Core library for type-safe Tailwind CSS class generation
9- **`tailwind-html`**: HTML component library built on top of [Htmlit](https://github.com/dbuenzli/htmlit)
10
11## Features
12
13- Compile-time validation of Tailwind classes
14- Type-safe color variants and sizes
15- Exhaustive pattern matching for all utility classes
16
17### Comprehensive Coverage
18- **Typography**: Font sizes, weights, line heights, text alignment, decorations
19- **Layout**: Display, position, flexbox, grid, spacing
20- **Colors**: Full color palette with variants
21- **Effects**: Shadows, borders, rounded corners, transitions
22- **Responsive**: Breakpoint-based responsive utilities
23- **Variants**: Hover, focus, and other state variants
24
25### Using Dune
26
27Add to your `dune-project`:
28
29```dune
30(package
31 (name myproject)
32 (depends
33 ocaml
34 dune
35 tailwind
36 tailwind-html
37 htmlit))
38```
39
40## Quick Start
41
42### Basic Usage
43
44```ocaml
45open Tailwind
46
47(* Create a styled div *)
48let styled_div =
49 let classes = tw [
50 Display.flex;
51 Flexbox.(to_class (justify `Center));
52 Flexbox.(to_class (align_items `Center));
53 Color.bg (Color.make `Gray ~variant:`V100 ());
54 Spacing.(to_class (p (Size.rem 2.0)));
55 ] in
56 Printf.sprintf "<div class=\"%s\">Content</div>" (to_string classes)
57```
58
59### With Htmlit Integration
60
61```ocaml
62open Htmlit
63open Tailwind
64
65let classes_attr tailwind_classes =
66 At.class' (Tailwind.to_string tailwind_classes)
67
68let create_card title content =
69 El.div ~at:[classes_attr (tw [
70 Patterns.card;
71 Spacing.(to_class (p (Size.rem 1.5)));
72 Effects.shadow_md;
73 ])] [
74 El.h2 ~at:[classes_attr (tw [
75 Typography.(to_class (font_size `Xl));
76 Typography.(to_class (font_weight `Bold));
77 Spacing.(to_class (mb (Size.rem 1.0)));
78 ])] [El.txt title];
79 El.p [El.txt content];
80 ]
81```
82
83## Examples
84
85The `examples/` directory contains several demonstration files:
86
87### Running Examples
88
89```bash
90# Build all examples
91dune build examples/
92
93# Run comprehensive showcase (generates HTML + CSS)
94dune exec examples/comprehensive_showcase.exe
95
96# Run basic usage example
97dune exec examples/basic_usage.exe
98
99# Run HTML integration example
100dune exec examples/tailwind_html_example.exe
101```
102
103### Comprehensive Showcase
104
105The comprehensive showcase demonstrates all library features and generates:
106- `showcase.html` - Complete HTML page with all Tailwind classes
107- `input.css` - Tailwind v4 CSS with custom theme extensions
108
109```bash
110dune exec examples/comprehensive_showcase.exe
111# Then open showcase.html in your browser
112```
113
114## Tailwind v4 Support
115
116This library supports Tailwind v4's CSS-first approach:
117
118```css
119/* Generated input.css - no config file needed! */
120@import "tailwindcss";
121
122@theme {
123 --font-sans: 'Inter', system-ui, sans-serif;
124 --color-brand-600: #2563eb;
125 /* Custom theme extensions */
126}
127```
128
129To process the CSS:
130```bash
131npx tailwindcss@next -i input.css -o output.css
132```
133
134## Module Documentation
135
136### Core Modules
137
138#### `Tailwind`
139Main module that exports all utilities and provides the `tw` function for composing classes.
140
141#### `Color`
142Type-safe color system with variants:
143```ocaml
144Color.bg (Color.make `Blue ~variant:`V600 ())
145Color.text Color.white
146Color.border (Color.make `Gray ~variant:`V200 ())
147```
148
149#### `Typography`
150Font utilities:
151```ocaml
152Typography.(to_class (font_size `Xl2))
153Typography.(to_class (font_weight `Bold))
154Typography.(to_class (line_height `Relaxed))
155```
156
157#### `Spacing`
158Margin and padding utilities:
159```ocaml
160Spacing.(to_class (p (Size.rem 1.0))) (* padding *)
161Spacing.(to_class (mx Size.auto)) (* margin-x auto *)
162Spacing.(to_class (gap `All (Size.px 16.0))) (* gap *)
163```
164
165#### `Layout`
166Layout utilities:
167```ocaml
168Layout.(to_class (width (Size.percent 100.0)))
169Layout.(to_class (height Size.screen))
170Layout.(to_class (max_width (Size.rem 64.0)))
171```
172
173#### `Flexbox`
174Flexbox utilities:
175```ocaml
176Display.flex
177Flexbox.(to_class (justify `Between))
178Flexbox.(to_class (align_items `Center))
179Flexbox.(to_class (direction `Col))
180```
181
182#### `Grid`
183CSS Grid utilities:
184```ocaml
185Display.grid
186Grid.(to_class (template_cols (`Cols 3)))
187Grid.(to_class (gap (Size.rem 1.0)))
188```
189
190#### `Effects`
191Visual effects:
192```ocaml
193Effects.shadow_lg
194Effects.rounded_md
195Effects.border
196Effects.transition `All
197```
198
199#### `Responsive`
200Responsive utilities:
201```ocaml
202Responsive.(to_class (at_breakpoint `Md Display.flex))
203Responsive.(to_class (at_breakpoint `Lg (Grid.(to_class (template_cols (`Cols 4))))))
204```
205
206#### `Variants`
207State variants:
208```ocaml
209Variants.hover (Color.bg (Color.make `Blue ~variant:`V700 ()))
210Variants.focus Effects.ring
211```
212
213#### `Patterns`
214Common layout patterns:
215```ocaml
216Patterns.container ()
217Patterns.card
218Patterns.flex_center
219Patterns.stack ~gap:(Size.rem 1.0) ()
220Patterns.sticky_header
221```
222
223### HTML Components (`tailwind-html`)
224
225Pre-built components using Htmlit:
226
227```ocaml
228open Tailwind_html
229
230(* Button component *)
231Button.primary ~text:"Click me" ~onclick:"handleClick()"
232
233(* Card component *)
234Card.simple ~title:"Card Title" ~content:"Card content here"
235
236(* Layout components *)
237Layout.container [
238 Layout.row [
239 Layout.col ~span:6 [content];
240 Layout.col ~span:6 [content];
241 ]
242]
243```
244
245## Testing
246
247Run the test suite:
248
249```bash
250dune test
251```
252
253## Contributing
254
255Contributions are welcome! Please:
256
2571. Fork the repository
2582. Create a feature branch
2593. Make your changes with tests
2604. Submit a pull request
261
262## License
263
264MIT License - see LICENSE file for details
265
266## Acknowledgments
267
268- Built on top of [Htmlit](https://github.com/dbuenzli/htmlit) by Daniel Bünzli
269- Inspired by [Tailwind CSS](https://tailwindcss.com/)
270
271## Resources
272
273- [Tailwind CSS Documentation](https://tailwindcss.com/docs)
274- [Tailwind v4 Alpha](https://tailwindcss.com/blog/tailwindcss-v4-alpha)
275- [Htmlit Documentation](https://erratique.ch/software/htmlit/doc/)