Component: ApiBadge - #3355
Conversation
The badge marks a piece of documentation with the HTTP method it describes, in the four methods the design covers: get, post, delete and put. Figma reports each badge as 20px tall including its border, so the padding subtracts the border width the way Button already does, which lands the geometry on the design's measurements exactly. The four marks are exported from Figma cropped to the glyph rather than to a 16px box, so each one is masked at the proportion it occupies within that box and takes its colour from currentColor. An img would give them nothing to take a colour from and they would come out black in both themes. The apiBadge colour tokens are not in design-system-tokens yet, so they are hand-written into vars.css for both themes alongside the nav ones that are waiting on the same thing. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
Pull request environment is available at https://stoctodocspr3355.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. |
The showcase page stretches every child of a simple-grid cell to the full column width, which is why Button already caps itself at fit-content. The badge needs the same cap: without it the background ran the width of the column instead of wrapping the icon and label. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Every one of the twenty-four values the design uses is an exact entry in the scales from design-system-tokens, on a regular pattern: 100/200/600 for background, border and text in light, and 900/700/300 in dark. Naming the scale entries says which step of which ramp each colour is, and it matches how the palette at the top of this file is already built. Badge and Label were the alternative and neither covers this. Badge carries success and danger only, with no text or border token for info or warning, and its backgrounds are the solid fills a filled pill wants rather than the tints this outlined badge needs. Label ships no colour tokens at all. Rendered output is unchanged: each scale entry resolves to the hex it replaced. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
| @@ -0,0 +1,125 @@ | |||
| --- | |||
| import type { HTMLAttributes } from 'astro/types'; | |||
There was a problem hiding this comment.
Having this be an astro component is annoying, because it means every docs page must be a .mdx instead of a .md, and the docs-generator must output <ApiBadge > into the markdown, which will render as broken when people try and view/preview the markdown locally or in the github diff.
I would strongly prefer that everything in the ApiDocs remains simple HTML with CSS styling, because Octopus Server devs are going to see it in their PR's over in the OctopusDeploy repo, where there is no astro.
Can we do this as something like <span class="api-get">GET</span> and have CSS do all the styling without needing components? It seems like that should be possible? Doesn't need to have perfect fidelity with the mockups
There was a problem hiding this comment.
Good call, it will likely follow something similar with how we do the CodeBlock enhancements, so won't have astro button support.
I did suspect that we would build the nav-menu a different way that would support the AstroComponents, though, but why have two different components, and we can come to that when we need it!
A badge is now a single span carrying one class: <span class="api-get">Get</span>. The class holds the colours and draws the icon from a ::before, so an author writes the label and nothing else, and api-icon-only drops the label for the icon on its own. The styles move to src/styles/api.css, loaded alongside vars.css and main.css in HtmlHead so they reach every page. Scoping them to a component would have tied them to the pages whose component graph includes it, and a .md article cannot import a component at all, which is where the badge is most wanted. api.css is the home for API documentation styles as more of them arrive. The Astro component is gone. It carried a props type, a label map and a branch to render two shapes, all to emit one span. The colour TODOs come out of vars.css along with the nav ones above them. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
| @@ -0,0 +1,82 @@ | |||
| :is(.api-get, .api-post, .api-delete, .api-put) { | |||
There was a problem hiding this comment.
I suspect that the API layout will have more "non-astro" components that will need styling, so I opted to have a new file separate from main.
There was a problem hiding this comment.
Nice. I was thinking it'd be cool if we could have a very-mini "api docs" site within the OctopusDeploy repo to optionally help developers see what the docs MD changes will look like when rendered. Probably we won't do it, but keeping API css separate would make it easier if we did
3 participants
Implements the ApiBadge design from Figma (node 1528-43714), in the four methods the design covers:
get,post,deleteandput. Each method has a labelled and an icon-only mode.There is existing Badge and Label components but these are different, the fact there is new color tokens imply that we aren't using the design system components, these will be unique to docs.
We will however use the design system tokens colours (until such a day when they create the actual tokens)
What is here
src/components/ApiBadge.astro— takesmethod(get/post/delete/put) andhasLabel(defaulttrue).src/assets/icons/—arrow-down-left.svg,arrow-up-right.svg,xmark.svgandpen-line.svg, exported from Figma.src/styles/vars.css— the--colorApiBadge*tokens for both themes.src/pages/components.mdx— an ApiBadge section showing both modes, on/components.Results
Visible here: https://stoctodocspr3355.z22.web.core.windows.net/components#apibadge
Dark Mode:
Light Mode:
🤖 Generated with Claude Code