docs/css.md — sigil-css

1# CSS

3> S-expression CSS with nesting, themes, and media queries.

5```scheme

6(import (sigil css))

7```

9## Basic Rules

The `css` macro creates CSS rules. Properties are written as `(property-name value)` where the property name is captured literally (not evaluated).

13```scheme

14(css->string

15 (css ".button"

16 (background "#007bff")

17 (color "white")

18 (padding "0.5rem 1rem")

19 (border-radius "4px")))

20```

22Output:

24```css

25.button {

26 background: #007bff;

27 color: white;

28 padding: 0.5rem 1rem;

29 border-radius: 4px;

30}

31```

33## Nested Selectors

35Use `&` to create nested rules, similar to Sass/SCSS. The suffix is appended directly to the parent selector.

37```scheme

38(css->string

39 (css ".card"

40 (padding "1rem")

41 (border "1px solid #ddd")

42 (& ":hover"

43 (box-shadow "0 2px 8px rgba(0,0,0,0.15)"))

44 (& " .title"

45 (font-weight "bold")

46 (font-size "1.25rem"))))

47```

49Output:

51```css

52.card {

53 padding: 1rem;

54 border: 1px solid #ddd;

55}

57.card:hover {

58 box-shadow: 0 2px 8px rgba(0,0,0,0.15);

59}

61.card .title {

62 font-weight: bold;

63 font-size: 1.25rem;

64}

65```

67Nested `css` forms create child selectors (space-separated):

69```scheme

70(css ".nav"

71 (display "flex")

72 (css ".item"

73 (padding "0.5rem")))

74```

76## css->string

78Render any number of CSS fragments (rules, variables, media queries, keyframes) into a single CSS string.

80```scheme

81(css->string

82 (css-vars (--primary "#007bff"))

83 (css ".btn" (background "var(--primary)"))

84 (css ".btn-lg" (padding "1rem 2rem")))

85```

87## CSS Variables

89Define CSS custom properties with `css-vars`. Creates a `:root` block.

91```scheme

92(css->string

93 (css-vars

94 (--bg "#0a0a0a")

95 (--fg "#e0e0e0")

96 (--accent "#f0c040"))

97 (css "body"

98 (background "var(--bg)")

99 (color "var(--fg)")))

100```

101

102## Media Queries

103

104Wrap rules in a `@media` block with `css-media`.

105

106```scheme

107(css->string

108 (css ".sidebar" (width "250px"))

109 (css-media "(max-width: 768px)"

110 (css ".sidebar" (display "none"))

111 (css ".content" (width "100%"))))

112```

113

114## Keyframes

115

116Define CSS animations with `css-keyframes`. Step names are symbols (`from`, `to`, or percentage symbols).

117

118```scheme

119(css->string

120 (css-keyframes "fade-in"

121 (from (opacity "0"))

122 (to (opacity "1")))

123 (css ".fade" (animation "fade-in 0.3s ease-in")))

124```

125

126## Themes

127

128Create reusable theme definitions and convert them to CSS custom properties.

129

130```scheme

131(define dark-theme

132 (make-theme

133 '(bg "#0a0a0a")

134 '(fg "#e0e0e0")

135 '(accent "#f0c040")))

136

137;; Look up a theme value

138(theme-ref dark-theme 'bg) ; => "#0a0a0a"

139

140;; Reference as CSS variable

141(theme-var 'bg) ; => "var(--bg)"

142

143;; Convert to :root CSS variables

144(css->string

145 (theme->css-vars dark-theme)

146 (css "body"

147 (background (theme-var 'bg))

148 (color (theme-var 'fg))))

149```

150

151## Unit and Color Helpers

152

153Helpers for common CSS units and color functions.

154

155| Helper | Example | Result |

156|--------|---------|--------|

157| `px` | `(px 16)` | `"16px"` |

158| `em` | `(em 1.5)` | `"1.5em"` |

159| `rem` | `(rem 2)` | `"2rem"` |

160| `%` | `(% 50)` | `"50%"` |

161| `rgb` | `(rgb 255 128 0)` | `"rgb(255, 128, 0)"` |

162| `rgba` | `(rgba 0 0 0 0.5)` | `"rgba(0, 0, 0, 0.5)"` |

163| `hsl` | `(hsl 200 50 60)` | `"hsl(200, 50%, 60%)"` |

164| `important` | `(important "red")` | `"red !important"` |

165

166```scheme

167(css->string

168 (css ".box"

169 (width (% 100))

170 (padding (rem 1))

171 (font-size (px 14))

172 (color (important "red"))))

173```

174

175## Additional Utilities

176

177### css-import

178

179Add `@import` rules for external stylesheets or fonts.

180

181```scheme

182(css->string

183 (css-import "https://fonts.googleapis.com/css2?family=Inter")

184 (css "body" (font-family "Inter, sans-serif")))

185```

186

187### css-raw

188

189Insert raw CSS strings for edge cases not covered by the DSL.

190

191```scheme

192(css->string

193 (css-raw "/* Browser-specific hack */")

194 (css ".main" (display "grid")))

195```

196

197### css-combine

198

199Group CSS fragments into a list for modular organization.

200

201```scheme

202(define button-styles

203 (css-combine

204 (css ".btn" (padding "0.5rem 1rem") (border "none"))

205 (css ".btn-primary" (background "blue") (color "white"))

206 (css ".btn-danger" (background "red") (color "white"))))

207

208(css->string button-styles)

209```

210

211## Common Patterns

212

213### Component Styles

214

215```scheme

216(import (sigil css))

217

218(define card-styles

219 (css-combine

220 (css ".card"

221 (border "1px solid #e0e0e0")

222 (border-radius "8px")

223 (padding "1.5rem")

224 (& ":hover"

225 (box-shadow "0 4px 12px rgba(0,0,0,0.1)"))

226 (& " .card-title"

227 (font-size "1.25rem")

228 (margin-bottom "0.5rem"))

229 (& " .card-body"

230 (color "#666")))))

231```

232

233### Responsive Design

234

235```scheme

236(css->string

237 (css ".grid"

238 (display "grid")

239 (grid-template-columns "repeat(3, 1fr)")

240 (gap (rem 1)))

241 (css-media "(max-width: 768px)"

242 (css ".grid"

243 (grid-template-columns "1fr"))))

244```

245

246### Themed Application

247

248```scheme

249(import (sigil css)

250 (sigil sxml))

251

252(define theme

253 (make-theme

254 '(bg "#ffffff")

255 '(fg "#1a1a1a")

256 '(primary "#007bff")))

257

258(define app-css

259 (css->string

260 (theme->css-vars theme)

261 (css "body"

262 (background (theme-var 'bg))

263 (color (theme-var 'fg)))

264 (css ".btn-primary"

265 (background (theme-var 'primary))

266 (color "white"))))

267

268(sxml->html `(style (*raw* ,app-css)))

269```