docs(site): add figure visual style guide and contributor docs#302
Open
nitindavegit wants to merge 1 commit into
Open
docs(site): add figure visual style guide and contributor docs#302nitindavegit wants to merge 1 commit into
nitindavegit wants to merge 1 commit into
Conversation
📝 WalkthroughWalkthroughThree documentation files are added or updated to establish a unified contributor reference for curriculum figures. A new ChangesFigure Authoring Documentation
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@site/assets/figures/INDEX.md`:
- Line 5: The relative link path in the INDEX.md file is incorrect and points to
a non-existent location. In the markdown reference that links to the contributor
guide for figures, change the relative path from `../CONTRIBUTING-FIGURES.md` to
`../../CONTRIBUTING-FIGURES.md` to correctly resolve to the actual file
location. Apply this same fix to both occurrences mentioned in the comment (the
one on line 5 and the additional one on line 35).
In `@site/assets/figures/STYLE.md`:
- Around line 106-115: The code fences in the STYLE.md file are missing language
labels, which causes markdownlint to fail and makes the content ambiguous. Add
the `text` language identifier to both code fence blocks: the first fence
containing the CSS class definitions (.lf, .lf-head, .lf-body, etc.) should be
labeled ```text, and the second fence containing the file structure (site/,
figures.js, etc.) at lines 270-290 should also be labeled ```text. This will
satisfy the linter and clarify the content type for users.
In `@site/CONTRIBUTING-FIGURES.md`:
- Around line 34-37: The "Interactive Widgets" section in
CONTRIBUTING-FIGURES.md currently states "140+ existing" but this contradicts
the count of "134+ across 13 modules" mentioned in STYLE.md. Update the widget
count in the Interactive Widgets section header to match the STYLE.md reference,
or remove the specific numeric count entirely and use only a general descriptor
like "Many existing" if the exact count is subject to frequent changes. Ensure
both documentation files maintain consistent widget count information.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 12b9702a-294d-4178-a26f-9d72bf1f9f58
📒 Files selected for processing (3)
site/CONTRIBUTING-FIGURES.mdsite/assets/figures/INDEX.mdsite/assets/figures/STYLE.md
| Every figure shipped under `site/assets/figures/` is listed below. FIG numbers are global, monotonically increasing, and never reused. | ||
|
|
||
| The aesthetic is documented in the `blueprint-diagram` Claude Code skill, which is distributed separately from this repo (per the project's "no vendor/tooling artifacts in repos" rule). The skill source lives under `~/.claude/skills/blueprint-diagram/` once installed; ask a maintainer for the install path or follow the [How to add](#how-to-add) section below for a manual workflow that does not require the skill. | ||
| The visual style is defined in [`STYLE.md`](STYLE.md) — read it before authoring a new figure. For the interactive widget system (slider-driven, theme-aware figures embedded via the ` ```figure ` fence), see [`site/CONTRIBUTING-FIGURES.md`](../CONTRIBUTING-FIGURES.md). |
There was a problem hiding this comment.
Fix the contributor-guide link target.
From site/assets/figures/INDEX.md, ../CONTRIBUTING-FIGURES.md points at site/assets/CONTRIBUTING-FIGURES.md, which does not exist. Use the repo-local path instead.
Suggested fix
- see [`site/CONTRIBUTING-FIGURES.md`](../CONTRIBUTING-FIGURES.md)
+ see [`site/CONTRIBUTING-FIGURES.md`](../../CONTRIBUTING-FIGURES.md)Also applies to: 35-35
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@site/assets/figures/INDEX.md` at line 5, The relative link path in the
INDEX.md file is incorrect and points to a non-existent location. In the
markdown reference that links to the contributor guide for figures, change the
relative path from `../CONTRIBUTING-FIGURES.md` to
`../../CONTRIBUTING-FIGURES.md` to correctly resolve to the actual file
location. Apply this same fix to both occurrences mentioned in the comment (the
one on line 5 and the additional one on line 35).
Comment on lines
+106
to
+115
| ``` | ||
| .lf margin: 28px 0; border: 1px solid var(--rule-soft) | ||
| .lf-head padding: 12px 16px; border-bottom: 1px solid var(--rule-soft) | ||
| .lf-body padding: 16px | ||
| .lf-grid display: grid; 2 columns; gap: 12px 24px | ||
| .lf-ctrl flex column; gap: 4px | ||
| .lf-out margin-top: 18px; padding-top: 14px; dashed top border | ||
| .lf-bar height: 10px; margin-top: 12px | ||
| .lf-cap padding: 12px 16px; border-top: 1px solid var(--rule-soft) | ||
| ``` |
There was a problem hiding this comment.
Label the schematic code fences.
Both blocks are illustrative snippets, but the missing fence language trips markdownlint and makes them ambiguous to copy.
Suggested fix
-```
+```text
.lf margin: 28px 0; border: 1px solid var(--rule-soft)
...
-```
+```-```
+```text
site/
figures.js — 10 core animated SVG explainers
...
-```
+```Also applies to: 270-290
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 106-106: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@site/assets/figures/STYLE.md` around lines 106 - 115, The code fences in the
STYLE.md file are missing language labels, which causes markdownlint to fail and
makes the content ambiguous. Add the `text` language identifier to both code
fence blocks: the first fence containing the CSS class definitions (.lf,
.lf-head, .lf-body, etc.) should be labeled ```text, and the second fence
containing the file structure (site/, figures.js, etc.) at lines 270-290 should
also be labeled ```text. This will satisfy the linter and clarify the content
type for users.
Source: Linters/SAST tools
Comment on lines
+34
to
+37
| ## Interactive Widgets (140+ existing) | ||
|
|
||
| These are slider/select-driven tools embedded inside a styled card (`.lf` container). Users drag parameters and see the output update in real time. | ||
|
|
There was a problem hiding this comment.
Reconcile the widget count with the style guide.
This says 140+ existing, but STYLE.md already says 134+ across 13 modules. Please keep the headline in sync or remove the exact count.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@site/CONTRIBUTING-FIGURES.md` around lines 34 - 37, The "Interactive Widgets"
section in CONTRIBUTING-FIGURES.md currently states "140+ existing" but this
contradicts the count of "134+ across 13 modules" mentioned in STYLE.md. Update
the widget count in the Interactive Widgets section header to match the STYLE.md
reference, or remove the specific numeric count entirely and use only a general
descriptor like "Many existing" if the exact count is subject to frequent
changes. Ensure both documentation files maintain consistent widget count
information.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this PR does
Adds two new docs — a visual style guide (
STYLE.md) and a contributor guide (CONTRIBUTING-FIGURES.md) — that document the existing figure system conventions so contributors can create and embed figures without reverse-engineering 7,000 lines of JS and CSS.Kind of change
Checklist
LESSON_TEMPLATE.mdstructure[Name](phases/...)), not bare textdocs/en.mdclaimsPhase / lesson
N/A — site-wide docs.
Notes for reviewer
STYLE.mdextracts the blueprint aesthetic (colors, typography, line weights, spacing, animation principles) that already exists in the codebase but was undocumented.CONTRIBUTING-FIGURES.mdcovers all three figure types: interactive widgets, animated explainers, and static SVGs.INDEX.mdto link to both new files and added interactive/animated figure instructions to the "How to add" section.