feat: adopt GitHub visual language system in image generation guidelines

.github/workflows/guidelines.md

@@ -110,6 +110,72 @@ Existing single-theme workshop images are migration candidates, not exceptions:
    instead of duplicating the binary.
 - Do not delete an original asset until no Markdown or HTML reference uses it.
 
+## GitHub visual language system
+
+When a generated diagram or illustration depicts a GitHub concept — such as an issue, pull request, discussion, commit, repository, or workflow run — use the GitHub visual language to represent it. This keeps diagrams recognisable to learners who already know the GitHub UI and avoids generic icon fonts or ambiguous shapes.
+
+### Octicon-inspired shapes
+
+Embed simplified Octicon-style shapes directly in SVG markup as inline `<path>` or geometric primitives. Do not link to external icon files or import icon fonts — diagrams must be self-contained.
+
+| Concept | Shape guidance |
+|---------|----------------|
+| Issue (open) | Circle outline (`r 8`) with a smaller filled dot inside; stroke and fill use the open/green semantic color |
+| Issue (closed) | Solid circle with an ✕ or checkmark path inside; fill uses the closed semantic color |
+| Pull request (open) | Two small circles connected by a curved branch path (branch left, merge right); stroke uses the open/green color |
+| Pull request (merged) | Same branch shape with a diamond merge point; fill and stroke use the merged/purple color |
+| Pull request (draft) | Dashed circle outline with a pencil stub; stroke and fill use the muted/grey color |
+| Discussion | Rounded speech-bubble outline (rect + pointer triangle); stroke uses the accent color |
+| Commit | Small solid circle (`r 5`) centred on a horizontal branch line |
+| Repository | Open book or folder outline using two rounded rect halves |
+| Workflow / Actions run | Right-pointing filled triangle (play button) inside a rounded square |
+| Schedule trigger | Clock face: circle outline + two short line segments for hands |
+
+Use these shapes at 16 × 16 or 24 × 24 logical units; scale to fit the diagram's label boxes using a `transform="scale(...)"` or by drawing at the target size directly.
+
+### Primer semantic colors for entity states
+
+Apply state-specific colors consistently so learners can interpret diagram nodes at a glance.
+
+| State | Light mode | Dark mode | Applies to |
+|-------|-----------|-----------|------------|
+| Open | `#1a7f37` | `#3fb950` | Open issues, open PRs |
+| Closed | `#cf222e` | `#f85149` | Closed issues, closed PRs |
+| Merged | `#8250df` | `#a371f7` | Merged pull requests |
+| Draft | `#57606a` | `#8b949e` | Draft PRs, pending items |
+| In progress | `#9a6700` | `#e3b341` | Running workflow steps, in-flight items |
+| Done / Success | `#1a7f37` | `#3fb950` | Completed steps, passing checks |
+| Skipped | `#57606a` | `#8b949e` | Skipped steps, inactive paths |
+| Danger / Error | `#cf222e` | `#f85149` | Failed checks, error states |
+
+When the diagram is theme-aware, apply the matching column's values to each SVG variant.
+
+### GitHub visual language usage rules
+
+- **Always use GitHub icons** when a node represents a GitHub entity (issue, PR, discussion, commit, repository). Do not substitute plain rectangles or generic bullet shapes for recognisable GitHub concepts.
+- **Accompany every icon node with a text label.** The icon conveys type; the label conveys content. Together they must be readable without prior knowledge of the icon.
+- **Match state to color.** An open-issue node must use the open/green semantic color; a merged-PR node must use the merged/purple color. Do not use accent blue for concept nodes that have an explicit state color.
+- **Keep icon shapes minimal.** Octicon-inspired primitives should be legible at diagram scale — omit ornamental detail that disappears below 24 px.
+- **Use accent blue (`#0969da` / `#2f81f7`) for non-GitHub-entity highlights** such as data flows, trigger arrows, or focus callouts that do not correspond to a GitHub object.
+- **Do not mix icon vocabularies.** Never combine Octicon-style shapes with Material Design, Font Awesome, or other third-party icon conventions in the same diagram.
+
+### Enforcing the visual language spec
+
+Run the static SVG visual language checker locally before committing new or updated SVG files:
+
+```bash
+node scripts/check-svg-visual-language.js
+```
+
+To check specific files only:
+
+```bash
+SVG_FILES="workshop/images/foo-light.svg workshop/images/foo-dark.svg" \
+  node scripts/check-svg-visual-language.js
+```
+
+The check runs automatically in CI via `.github/workflows/svg-visual-language-check.yml` whenever SVG files change. Pull requests that introduce violations in changed SVG files will fail the check. Push events that introduce violations on `main` will create or update a tracked issue.
+
 ## Alert callouts: use `<details>` only for multi-line content
 
 ### Alert level ceiling

.github/workflows/svg-visual-language-check.yml

@@ -0,0 +1,112 @@
+name: SVG Visual Language Check
+
+on:
+  push:
+    paths:
+      - "**/*.svg"
+      - "scripts/check-svg-visual-language.js"
+      - ".github/workflows/svg-visual-language-check.yml"
+  pull_request:
+    paths:
+      - "**/*.svg"
+      - "scripts/check-svg-visual-language.js"
+      - ".github/workflows/svg-visual-language-check.yml"
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  svg-visual-language:
+    name: SVG Visual Language (GitHub VLS)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Setup Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: "20"
+
+      - name: Find changed SVG files
+        id: changed
+        if: github.event_name == 'push'
+        run: |
+          if git cat-file -e "${{ github.event.before }}" 2>/dev/null; then
+            files=$(git diff --name-only --diff-filter=ACMR \
+              "${{ github.event.before }}" "${{ github.sha }}" -- '*.svg' || true)
+          else
+            # First push or force-push: check all SVG files
+            files=$(git ls-files '*.svg' || true)
+          fi
+          echo "files<<EOF" >> "$GITHUB_OUTPUT"
+          echo "$files" >> "$GITHUB_OUTPUT"
+          echo "EOF" >> "$GITHUB_OUTPUT"
+
+      - name: Run visual language check on changed SVG files (push)
+        id: check-push
+        if: github.event_name == 'push'
+        continue-on-error: true
+        env:
+          SVG_FILES: ${{ steps.changed.outputs.files }}
+        run: node scripts/check-svg-visual-language.js
+
+      - name: Run visual language check on all SVG files (pull_request)
+        id: check-pr
+        if: github.event_name == 'pull_request'
+        continue-on-error: true
+        run: node scripts/check-svg-visual-language.js
+
+      - name: File issue for violations found on main
+        if: >
+          (steps.check-push.outcome == 'failure') &&
+          github.event_name == 'push' &&
+          github.ref == 'refs/heads/main'
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const title = 'SVG visual language violation detected on main'
+            const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`
+            const body = [
+              'The SVG visual language check failed on `main`.',
+              '',
+              `Workflow run: ${runUrl}`,
+              '',
+              'One or more workshop SVG files do not follow the GitHub visual language system',
+              'defined in `.github/workflows/guidelines.md`.',
+              '',
+              'Common violations:',
+              '- Unicode status/icon characters (✓ ✗ ⚡ 🕐 ▶) used instead of Octicon-inspired SVG paths',
+              '- Missing `role="img"` or accessible label on root `<svg>` element',
+              '- State-labeled shapes (Open, Closed, Merged, Draft) using off-palette fill colors',
+              '- Non-standard canvas width for themed (-light/-dark) variants',
+              '',
+              'See the workflow run for the full list of violations and which files to fix.',
+              'Refer to `.github/workflows/guidelines.md` § "GitHub visual language system" for the spec.',
+            ].join('\n')
+            const { owner, repo } = context.repo
+            const { data: search } = await github.rest.search.issuesAndPullRequests({
+              q: `repo:${owner}/${repo} is:issue is:open in:title "${title}"`,
+              per_page: 5,
+            })
+            const existing = search.items.find((i) => i.title === title)
+            if (existing) {
+              await github.rest.issues.createComment({
+                owner, repo, issue_number: existing.number, body,
+              })
+            } else {
+              await github.rest.issues.create({
+                owner, repo, title, body,
+                labels: ['bug', 'accessibility'],
+              })
+            }
+
+      - name: Fail job when violations found on a pull request
+        if: >
+          steps.check-pr.outcome == 'failure' &&
+          github.event_name == 'pull_request'
+        run: |
+          echo "SVG visual language violations found. See the check output above for details."
+          echo "Refer to .github/workflows/guidelines.md § 'GitHub visual language system' for the spec."
+          exit 1

.github/workflows/workshop-explanatory-diagrams.md

@@ -228,17 +228,40 @@ Match the visual family of the UI screenshot workflow while staying conceptual:
   primary text `#24292f`, muted text `#57606a`, and accent `#0969da`
 - Dark palette: background `#0d1117`, panel `#161b22`, border `#30363d`,
   primary text `#f0f6fc`, muted text `#8b949e`, and accent `#2f81f7`
-- Adapt semantic success, attention, danger, and done colors for sufficient
-  contrast in each theme
+- Apply Primer semantic state colors from `.github/workflows/guidelines.md`
+  (GitHub visual language system section) when nodes represent GitHub entities
+  with a defined state (open, closed, merged, draft, in-progress, done, error)
 - Use simple labeled boxes, arrows, chips, dashed groupings, and numbered badges
 - Keep labels short and learner-friendly
 - Add a short title inside the graphic and a short annotation below it
 - Add `role="img"` and `aria-label` matching the Markdown alt text
 - Output valid, self-contained SVG only
 
+### GitHub icon usage in diagrams
+
+When a diagram node represents a GitHub concept, use an Octicon-inspired inline
+shape as described in the GitHub visual language system section of
+`.github/workflows/guidelines.md`. Embed the shape directly in the SVG — do not
+reference external files or icon fonts.
+
+Key shapes:
+
+- **Issue**: circle outline with inner dot (open/green) or solid circle with ✕
+  (closed/red)
+- **Pull request**: two-circle branch-and-merge path (open/green or merged/purple)
+- **Discussion**: rounded speech-bubble outline (accent blue)
+- **Commit**: small solid circle on a horizontal branch line
+- **Workflow run**: right-pointing filled triangle inside a rounded square
+- **Schedule trigger**: clock face (circle + two hand segments)
+
+Always label every icon node with a short text label. Use the icon to convey
+type and the label to convey content. Apply the matching Primer state color so
+the diagram is self-explanatory to anyone familiar with the GitHub UI.
+
 ### Diagram content rules
 
 - Explain the concept, not a literal product screenshot
+- Use GitHub visual language icons when a node represents a GitHub entity
 - Keep the visual readable at a glance
 - Use a left-to-right or top-to-bottom flow unless another layout is clearly
   better

.github/workflows/workshop-ui-screenshots.md

@@ -233,17 +233,27 @@ change set.
 - Represent GitHub's navigation tabs (Code, Issues, Pull requests, Actions,
   etc.) as a horizontal tab bar with the relevant tab underlined in the palette
   accent color.
+- **Use GitHub visual language icons** (Octicon-inspired inline SVG shapes) for
+  any GitHub entity that appears in the illustration. Follow the shape guide and
+  Primer semantic state color table in the GitHub visual language system section
+  of `.github/workflows/guidelines.md`. Do not substitute plain rectangles or
+  generic symbols for recognisable GitHub concepts.
+- For Issues and Pull requests tabs/rows: include the Octicon-inspired icon
+  (circle-with-dot for issues; branch-merge path for PRs) in the matching state
+  color (open/green, closed/red, merged/purple, draft/grey) alongside each row.
+- For Discussions: use a rounded speech-bubble outline in accent blue.
 - For Actions-tab screenshots: show a workflow list panel with a single row
-  representing the relevant workflow, a status icon (green ✓ for success,
-  yellow (in-progress hourglass) for in-progress), and the workflow name.
+  representing the relevant workflow, a status icon (filled play-triangle in
+  `#1a7f37` for success, hourglass or spinner in `#9a6700` for in-progress) and
+  the workflow name. Apply Primer semantic state colors from the guidelines.
 - For Run workflow button: render a blue button labelled "Run workflow" in the
   Actions sidebar.
 - For Codespace/fork/commit dialogs: use a centered modal panel with the
   palette's panel background and border colors.
 - For schedule badge / workflow list badge: render the Actions sidebar list with
-  a clock icon and "Scheduled" label.
-- For skipped steps: render the job-step list with a grey `-` icon and
-  "Skipped" label next to the step name.
+  a clock-face icon (Octicon clock shape) and "Scheduled" label.
+- For skipped steps: render the job-step list with a grey dash icon in the
+  skipped/muted color and "Skipped" label next to the step name.
 - For summary/run log panels: render a dark panel (`#0d1117`) with monospace
   output lines in `#c9d1d9`, showing representative output from the described
   step.