docs: Add package documentation for sigil-sxml, sigil-css, and sigil-web

Changed

 docs/css.md | 269 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 269 insertions(+)

Diff

docs/css.mdadded

@@ -0,0 +1,269 @@

# CSS

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

```scheme

(import (sigil css))

```

## Basic Rules

+10

+11

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

+12

+13

```scheme

+14

(css->string

+15

(css ".button"

+16

(background "#007bff")

+17

(color "white")

+18

(padding "0.5rem 1rem")

+19

(border-radius "4px")))

+20

```

+21

+22

Output:

+23

+24

```css

+25

.button {

+26

background: #007bff;

+27

color: white;

+28

padding: 0.5rem 1rem;

+29

border-radius: 4px;

+30

}

+31

```

+32

+33

## Nested Selectors

+34

+35

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

+36

+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

```

+48

+49

Output:

+50

+51

```css

+52

.card {

+53

padding: 1rem;

+54

border: 1px solid #ddd;

+55

}

+56

+57

.card:hover {

+58

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

+59

}

+60

+61

.card .title {

+62

font-weight: bold;

+63

font-size: 1.25rem;

+64

}

+65

```

+66

+67

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

+68

+69

```scheme

+70

(css ".nav"

+71

(display "flex")

+72

(css ".item"

+73

(padding "0.5rem")))

+74

```

+75

+76

## css->string

+77

+78

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

+79

+80

```scheme

+81

(css->string

+82

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

+83

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

+84

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

+85

```

+86

+87

## CSS Variables

+88

+89

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

+90

+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

+104

Wrap 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

+116

Define 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

+128

Create 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

+153

Helpers 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

+179

Add `@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

+189

Insert 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

+199

Group 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

```