Repository navigation
Add themed Kubernetes diagrams and image contribution guidance - #3518
samironsoctopus wants to merge 9 commits into
Conversation
Replace the Deploy Container and Load Balancer diagrams with Figma exports in light and dark variants. Images marked theme-light-only or theme-dark-only are hidden by the html[data-theme] attribute, so the swap follows the site's theme toggle as well as the OS setting. SVG figures now fill the content column, and the zoom lightbox no longer caps vector images at their exported width. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Replace both diagrams with revised Figma exports, and update the Deploy Container figure's width and height to the new 480x270 size. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Add guidance to the README on deciding whether a page needs a screenshot, sizing PNGs and SVGs for the content column, creating clear images, and adding light and dark variants with the theme-light-only and theme-dark-only classes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Pull request environment is available at https://stoctodocspr3518.z22.web.core.windows.net/. You can view the ephemeral environment status in Octopus Deploy. This environment will be automatically deprovisioned when the pull request is closed, or after 7 days of inactivity. |
SVG files are markup, not prose, so cspell flags attribute names such as stroke-dasharray. Diagram labels exported from Figma are outlined paths, so there's no text in them to check. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…loy/docs into si/update-kubernetes-diagrams
| - For a screenshot, capture the same view with Octopus in its light theme and again in its dark theme. | ||
| - For a diagram, export each variant with a solid background in the page color for that theme: `#FFFFFF` for light and `#111A23` for dark. These are the `colorBackgroundPrimaryDefault` design token in each theme, so the diagram blends into the page. | ||
| 2. Name the files with a `-light` and `-dark` suffix, such as `load-balancer-light.svg` and `load-balancer-dark.svg`. | ||
| 3. Add both images to the `figure` with HTML `<img>` tags, and give each one a theme class: |
There was a problem hiding this comment.
I think we're supposed to use the :img directive rather than raw HTML. It de-clutters the content and gives us more flexibility (e.g. if the class changes from theme-light-only to a different word, we can fix it in the directive rather than across many markdown files). It also avoids people having to duplicate alt-text and measure image sizes manually
The image resizing pipeline relies on that tag. If it doesn't handle light/dark then we would be better to fix it rather than suggesting people sidestep it with HTML
There was a problem hiding this comment.
I asked Claude to help with a fix here. The way the bots want me to respond to you is:
Agreed, thanks. I'd used raw HTML because the directive couldn't handle this case. It rewrote every image to a /docs/i/x/ path, but img.mjs only generates variants for PNG, JPG and WebP, so SVGs pointed at files that didn't exist. It also dropped the default resp-img class whenever a class like .theme-light-only was set.
Fixed both in f04e163. SVGs now keep their own path and take their width and height from the file. As a bonus, an @2x screenshot now shows at half its pixel size, so the README no longer tells anyone to measure images or use HTML. The diagrams now use :img{.theme-light-only …} and the README examples match.
I've left a themed flag for a follow-up. It would output both variants from one directive and remove the duplicated alt text.
There was a problem hiding this comment.
If this looks like slop and it ends up making our image support or theme support more flaky, just let me know. We have an upcoming project doing more renovation work in the doc set, where I can advocate for proper development resourcing to support light and dark themed images.
|
|
||
| 1. Create a light and a dark variant of the image: | ||
| - For a screenshot, capture the same view with Octopus in its light theme and again in its dark theme. | ||
| - For a diagram, export each variant with a solid background in the page color for that theme: `#FFFFFF` for light and `#111A23` for dark. These are the `colorBackgroundPrimaryDefault` design token in each theme, so the diagram blends into the page. |
There was a problem hiding this comment.
What's on my mind is the discussion about near-future theme changes; It would invalidate guidance like "111A23 for dark"
The :img directive rewrote every image to a /docs/i/ path, but img.mjs only generates variants for raster images, so an SVG pointed at a file that never existed. It also dropped resp-img whenever a class was set. SVGs now keep their own path and take their width and height from the file, and an @2x image shows at half its pixel size. The Kubernetes diagrams and the README guidance use the directive instead of raw <img> tags, so sizes no longer have to be set by hand. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Summary
Replaces two diagrams on the Kubernetes step pages with light and dark variants that follow the site theme. Also adds contributor guidance on when to use screenshots and how to make images follow the theme.
Themed images
theme-light-onlyandtheme-dark-onlyclasses insrc/styles/main.css. They key offhtml[data-theme], so images follow the site's theme toggle as well as the OS setting.<picture>withprefers-color-schemewould only follow the OS setting, and the zoom lightbox would always show its fallback image.kubernetes-resources.mdwith light and dark SVGs exported from Figma.kubernetes-resources.mdandkubernetes-service.mdwith light and dark SVGs, stored in the sharedpublic/docs/img/kubernetes/steps/folder.deploy-container.svgandloadbalancer.svg, which nothing else referenced.SVG sizing
figurenow fill the content column (figure img[src$='.svg'] { width: 100%; }), because they scale without losing sharpness. This also widenshigh-availability.svgslightly, from 800px to the column width. The other existing SVG figures were already column-width.src/scripts/modules/figures.jsno longer limits vector images to their exported width. PNG and JPG keep the existing limit.Contributor guidance (
README.md)Testing
markdownlint-cli2passes on the changed pages and the README.astro dev:pnpm buildor the Playwright test suite.Follow-up
#16191Fbackground. The README recommends the page colour#111A23.src/styles/main.cssstill says content images sit on a white background. The rule now uses a colour that changes with the theme.🤖 Generated with Claude Code