Monorepo for Aesthetic.Computer
aesthetic.computer
1# KidLisp Cards — Status Report & Improvement Plan
2
3## What We Have
4
5### LaTeX → SVG Pipeline (`/kidlisp.com/cards/`)
6
7**4 cards exist** (from 118 possible functions):
8- `drawing-line` — `(line x1 y1 x2 y2)`
9- `drawing-box` — `(box x y w h)`
10- `colors-ink` — `(ink color [alpha])`
11- `colors-wipe` — `(wipe [color])`
12
13**Build system:** `build.sh` compiles `.tex` → PDF → SVG via `pdflatex` + `pdf2svg`.
14
15**Emacs integration:** `kidlisp-cards.el` with keybindings for creating/building/previewing cards.
16
17### Book UI in kidlisp.com Editor
18
19The cards show up in a "book stack" inside the reference panel:
20- 3D flip animation (front = SVG card, back = card-back.svg)
21- Spread view (grid layout)
22- Stack physics (offset/scale/rotation for depth)
23- Only renders SVG cards for `aesthetic-computer` platform (other platforms use DOM-based cards)
24
25### Card Back
26
27A minimal card-back.svg (3.2KB) with a generic pattern.
28
29---
30
31## What's Dated / Broken
32
33### 1. Wrong fonts — doesn't match kidlisp.com
34
35The LaTeX cards use `\sffamily` (Computer Modern Sans) and `\ttfamily` (Computer Modern Mono). These don't match kidlisp.com's design at all.
36
37**kidlisp.com uses:**
38- `'Berkeley Mono Variable'` / `'Noto Sans Mono'` — code
39- `'YWFTProcessing-Regular'` / `'YWFTProcessing-Bold'` — display/titles
40- `'Comic Relief'` — fun/body text
41
42**Fix:** Embed these webfonts in the SVGs (or switch the whole pipeline from LaTeX to HTML/CSS → SVG, which would make font matching trivial and eliminate the LaTeX dependency entirely).
43
44### 2. Wrong syntax highlighting colors
45
46The LaTeX cards use their own color palette:
47- `klfunction: #FF6B6B` (coral)
48- `klnumber: #4ECDC4` (cyan)
49- `klstring: #FFE66D` (yellow)
50- `klparen: #888888` (gray)
51
52**kidlisp.com dark mode uses:**
53- Functions: `#61afef` (blue)
54- Numbers: `#d19a66` (orange)
55- Strings: `#e5c07b` (warm yellow)
56- Operators: `#98c379` (green)
57- Variables: `#e06c75` (red)
58- Comments: `#6a6a6a`
59
60These need to match so the cards feel like they belong on the site.
61
62### 3. Only 4 of 118 functions covered
63
64The 12 categories in KidLisp, with suggested priority cards:
65
66| Category | Functions | Cards | Priority additions |
67|----------|-----------|-------|-------------------|
68| Drawing | 17 | 2 (line, box) | `circle`, `tri`, `plot`, `shape`, `fill`/`outline` |
69| Colors | 2 | 2 (ink, wipe) | done for now |
70| Transform | 12 | 0 | `scroll`, `zoom`, `spin`, `blur`, `sort` |
71| Media | 7 | 0 | `paste`, `write`, `tape` |
72| Audio | 6 | 0 | `mic`, `amplitude`, `speaker`, `melody` |
73| 3D | 8 | 0 | `cube`, `form`, `trans` |
74| Control | ~10 | 0 | `def`, `later`, `if`, `repeat`, `once` |
75| Math | ~12 | 0 | `random`/`?`, `wiggle`, `sin`/`cos` |
76| Timing | ~4 | 0 | `1s`, `0.5s...`, `0.1s!` |
77| System | ~5 | 0 | `width`/`w`, `frame`/`f`, `fps` |
78| Navigation | ~3 | 0 | `$codeId`, `jump` |
79| Misc | ~5 | 0 | `...` (cycle), `choose`, `bunch` |
80
81**Minimum viable deck:** ~25 cards covering the most-used functions (could be informed by the live popularity data from `/api/store-kidlisp?stats=functions`).
82
83### 4. Examples are too simple / not from real pieces
84
85Current card examples are synthetic:
86- `(line 0 0 width height)` — technically correct but boring
87- `(box 10 10 100 50)` — doesn't show what makes KidLisp fun
88
89**Better approach:** Pull real code snippets from top community pieces (the data is already available via `topHitsData` in the learn tab). Show the function in context, in a pattern someone actually used.
90
91### 5. LaTeX pipeline is heavyweight
92
93Requires `texlive`, `pdf2svg`, a full TeX installation. Building a card is slow (~2-3 sec each). Hard to iterate on design. Doesn't support the project's webfonts natively.
94
95### 6. Card back is generic
96
97The card-back.svg is a plain pattern. Should feature the KidLisp logo, the `( )` motif, or a generative pattern that matches the site identity.
98
99---
100
101## Proposed Improvements
102
103### Phase 1: Switch from LaTeX to HTML/CSS → SVG
104
105**Why:** Eliminates font mismatch entirely. Uses the same CSS variables, webfonts, and syntax highlighting as kidlisp.com. Cards become trivial to build — just an HTML template rendered to SVG via Puppeteer or even served as inline HTML.
106
107**New pipeline:**
1081. Card data lives in a JSON/JS array (function name, category, description, example code, diagram type)
1092. An HTML template uses kidlisp.com's fonts, colors, and `highlightKL()` syntax highlighter
1103. Build script uses Puppeteer (already available via oven) to screenshot to SVG/PNG
1114. Or: skip pre-rendering entirely — render cards as live DOM in the book UI
112
113**Card template zones (same layout, better rendering):**
114```
115┌─────────────────────────┐
116│ CATEGORY (muted) │ ← YWFTProcessing-Regular
117│ FUNCTION NAME │ ← YWFTProcessing-Bold, large
118│ one-line description │ ← Comic Relief
119│ ┌───────────────────┐ │
120│ │ visual diagram │ │ ← canvas/SVG illustration
121│ └───────────────────┘ │
122│ ┌───────────────────┐ │
123│ │ (fn arg1 arg2) │ │ ← Berkeley Mono, syntax-highlighted
124│ │ (fn in context) │ │ with kidlisp.com colors
125│ └───────────────────┘ │
126└─────────────────────────┘
127```
128
129### Phase 2: Expand to 25+ cards using real examples
130
131Source the "Example" code block from actual community pieces:
1321. Query popularity data for each function
1332. Find the top-viewed piece that uses it cleanly
1343. Extract a minimal snippet showing the function in real context
135
136**Priority functions for first 25 cards:**
137`wipe`, `ink`, `line`, `box`, `circle`, `tri`, `plot`, `fill`, `outline`,
138`repeat`, `def`, `later`, `if`, `once`, `?`/`random`, `wiggle`,
139`sin`, `scroll`, `zoom`, `spin`, `blur`, `paste`, `write`, `mic`, `amplitude`
140
141### Phase 3: Deck design & polish
142
143- **Card back:** Generative pattern using the `( )` motif in YWFTProcessing, dark bg matching kidlisp.com's `#111`
144- **Category color bands:** Each category gets a subtle accent color on the card edge (Drawing = blue, Transform = orange, Audio = green, etc.)
145- **Rarity indicator:** Functions used in <5% of pieces could get a "rare" badge — gamifies exploration
146- **Card numbering:** `4/118` style — shows completeness and invites collection
147
148### Phase 4: Interactive cards (skip pre-rendering)
149
150Instead of static SVG files, render cards as live DOM elements:
151- The code block could be **runnable** — tap to see the output
152- Syntax highlighting via the existing `highlightKL()` function
153- Cards could show a **live animated thumbnail** (the same oven WebP we use for list items)
154- Eliminates the build step entirely — card data is just JSON
155
156---
157
158## Decision: LaTeX vs HTML/CSS vs Live DOM
159
160| Approach | Fonts | Colors | Build time | Iterability | Interactivity |
161|----------|-------|--------|-----------|-------------|---------------|
162| LaTeX → SVG | Wrong (CM) | Wrong (custom) | Slow (~2s/card) | Hard | None |
163| HTML → SVG (Puppeteer) | Correct | Correct | Medium (~1s/card) | Good | None |
164| **Live DOM** | **Correct** | **Correct** | **None** | **Instant** | **Full** |
165
166**Recommendation:** Move to live DOM rendering. The card data (function, category, description, example) stays in a JSON structure. The book UI already renders DOM-based cards for non-AC platforms — extend that with the kidlisp.com font/color treatment and syntax highlighting. Keep the LaTeX pipeline as a print/export option if physical cards are ever wanted.
167
168---
169
170## Quick Wins (can do now)
171
1721. **Update `svgCards` color palette** to match kidlisp.com dark mode vars
1732. **Add 5 more LaTeX cards** for the most popular functions (`circle`, `repeat`, `def`, `scroll`, `blur`)
1743. **Improve existing examples** — replace `(line 0 0 width height)` with a real snippet from a popular piece
1754. **Build a card data JSON** with all 118 functions — even before rendering, this becomes the source of truth for both the Learn tab reference and the card system