Skip to content

Commit db37573

Browse files
staredclaude
andcommitted
Add design guidelines documentation
Created CLAUDE.md documenting the project's design philosophy and technical direction for maintaining consistency and guiding future development. Key guidelines: - Tufte & D3 minimalism (no shadows, gradients, animations) - Explorable explanations approach - Markdown-based content with simple annotation syntax - Sequential color assignment (no spurious names) - Bidirectional hover without layout shifts - Accessibility focus with multiple color schemes - Minimal dependencies, data-driven architecture 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 639d67d commit db37573

File tree

1 file changed

+85
-0
lines changed

1 file changed

+85
-0
lines changed

CLAUDE.md

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# Interactive Math Framework - Design Guidelines
2+
3+
## Design Philosophy
4+
5+
**Tufte & D3 Minimalism**
6+
- Maximize data-ink ratio
7+
- No shadows, gradients, or unnecessary decorations
8+
- No animations or transitions (except simple opacity)
9+
- Clean typography (serif fonts)
10+
- Focus on content over decoration
11+
12+
**Explorable Explanations**
13+
- Interactive elements should be discoverable through hover
14+
- Color coding connects equation terms to plain-language descriptions
15+
- Natural language explanations, not just formulas
16+
- Inspired by https://p.migdal.pl/blog/2024/05/science-games-explorable-explanations/
17+
18+
## Content Format
19+
20+
**Markdown-Based**
21+
- Content lives in markdown files, separate from code
22+
- Simple, readable syntax without excessive abstraction
23+
- Three sections: equation, description, definitions
24+
25+
**Annotation Syntax**
26+
- LaTeX: `\mark[classname]{formula}` for colored terms
27+
- Prose: `[text]{.classname}` for references
28+
- Definitions: `## .classname` heading-based (allows full paragraphs, images)
29+
30+
## Color System
31+
32+
**Sequential Assignment**
33+
- Colors assigned by order of appearance in document
34+
- No spurious abstract names (no "primary", "secondary")
35+
- Color schemes are simple arrays: `['#color1', '#color2', ...]`
36+
- First term gets index 0, second gets index 1, etc.
37+
38+
**Accessibility**
39+
- Multiple color schemes including color-blind friendly (Wong palette)
40+
- High contrast option
41+
- Plain black option for printing
42+
- All interactions work without color
43+
44+
## Interactions
45+
46+
**Bidirectional Hover**
47+
- Hover over equation term → highlights matching description text
48+
- Hover over description text → highlights matching equation term
49+
- Shows detailed definition below
50+
51+
**No Layout Shifts**
52+
- Hover effects use only opacity changes
53+
- No bold, underline, or scale transforms that move text
54+
- Equation stays perfectly stable
55+
56+
## Technical Approach
57+
58+
**Minimal Dependencies**
59+
- KaTeX for math rendering
60+
- Simple markdown parser
61+
- No heavy frameworks (React, etc.) unless needed
62+
- Plain TypeScript + Vite
63+
64+
**Data-Driven**
65+
- No hardcoded content in JavaScript
66+
- Generic rendering logic
67+
- Easy to create new interactive equations
68+
- Just write markdown, framework handles the rest
69+
70+
## Framework Goals
71+
72+
**Reusable**
73+
- Not just for this equation
74+
- Pattern others can follow
75+
- Clear separation: content (markdown), logic (TypeScript), style (CSS)
76+
77+
**Simple**
78+
- Minimal syntax
79+
- Easy to understand and extend
80+
- Well-documented with README
81+
82+
**Beautiful**
83+
- Natural language over technical jargon
84+
- Clean, minimal aesthetic
85+
- Readable and approachable

0 commit comments

Comments
 (0)