Style the API reference with the Smile ID design system

[Ed Fricker (beastawakens)]

User description

The published API reference now takes its colours, type and spacing from the Smile ID design system's token layer instead of a set of hand-picked hex values. The rendering is the same shape as before — a spec switcher next to a Redoc pane — it just follows the brand.

Changes

• docs/tokens.css is a verbatim copy of the design system's generated dist/css/tokens.css. The page consumes var(--si-*) throughout, and the Redoc theme reads the same values out of the cascade at runtime, so there is one source of truth rather than two.
• DM Sans for body and UI, Epilogue for headings only. Previously Epilogue was used for everything, which the brand guide reserves for display type.
• The official off-white logo lockup replaces a hand-rolled dot and text wordmark. It inherits its colour, so it follows the header.
• The Redoc theme targets token colours, and its HTTP method colours now come from the brand palette rather than a stray purple.
• Small screens get a scrolling row of spec chips instead of a squashed vertical rail, and the header drops its subtitle rather than a navigation link.
• Added an SVG favicon, which was the only console error on the page.
• The deploy workflow stages all of docs/ rather than named files, so the next asset needs no workflow change.
• CI now checks that every --si-* token docs/index.html references is defined in docs/tokens.css. A rename in a future refresh fails the build instead of silently unstyling the page.

The second commit applies the findings from a four-pass review: dropping a shape.borderRadius theme key that Redoc v2.4.0 never reads, guarding the color-mix rail background with @supports so an unsupported browser cannot leave the switcher invisible, and removing a selector that targeted one of Redoc's generated class names.

How to test

Serve the repo root and open docs/index.html, or check the Pages deployment once merged.

python3 -m http.server 8899
open http://localhost:8899/docs/index.html

Worth a look: the spec switcher at desktop and at 420px wide, the code sample panel on the right, and the browser console (should be clean). docs/tokens.css is generated — review the two lines that reference it, not its contents.

🤖 Generated with Claude Code

https://claude.ai/code/session_014NpGbnum1AQPfQMvLSDa1D

---

PR Type

Enhancement, Documentation

---

Description

• Restyle API reference using Smile ID design tokens

• Vendor docs/tokens.css as single source of truth

• Read Redoc theme colours from CSS cascade

• Add CI token check, favicon, and mobile chip nav

---

Diagram Walkthrough

flowchart LR
  tokens["docs/tokens.css<br/>(design tokens)"] --> page["docs/index.html"]
  tokens --> redoc["Redoc theme<br/>(read from cascade)"]
  page --> redoc
  ci["validate.yml"] -- "checks --si-* defined" --> tokens
  deploy["deploy-docs.yml"] -- "stages docs/" --> site["_site"]

Loading

File Walkthrough

	Relevant files
Enhancement	tokens.css Add vendored Smile ID design tokens                                            docs/tokens.css Add vendored design system token file (generated, do not edit) Defines --si-* colours, spacing, radii, typography, and components Includes light and dark theme variable sets +486/-0  index.html Restyle page with design tokens and logo                                  docs/index.html Replace hand-picked hex vars with var(--si-*) tokens Read Redoc theme colours from the CSS cascade at runtime Swap dot wordmark for official SVG logo and add favicon Add scrolling chip nav and trimmed header for small screens +169/-115
Configuration changes	validate.yml Add token-definition validation check                                        .github/workflows/validate.yml Add CI step checking every --si-* token referenced is defined Fails the build on undefined tokens in docs/tokens.css +12/-0    deploy-docs.yml Stage entire docs directory on deploy                                        .github/workflows/deploy-docs.yml Stage all of docs/ instead of named files New assets need no workflow change +2/-1
Documentation	README.md Document design tokens provenance                                                README.md Document that docs/tokens.css is a verbatim vendored copy Record provenance and refresh instructions Note the CI token-definition check +13/-0

---

---

Need help?

Type /help how to ... in the comments thread for any questions about PR-Agent usage.

Check out the documentation for more information.

[prfectionist]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 3 🔵🔵🔵⚪⚪

🏅 Score: 80

🧪 No relevant tests

🔒 No security concerns identified

🔀 Multiple PR themes Sub-PR theme: CI/deploy workflow changes (stage docs/ and token validation) Relevant files: .github/workflows/deploy-docs.yml .github/workflows/validate.yml Sub-PR theme: Design system token styling for the API reference page Relevant files: docs/index.html docs/tokens.css README.md

⚡ Recommended focus areas for review Undefined token reference The Redoc runtime theme reads --si-color-brand-blue-bright, --si-color-brand-green, --si-color-brand-orange-blood, and --si-color-surface-alt via getComputedStyle. The CI check in validate.yml only greps docs/index.html for --si-* names inside the HTML/CSS text, so tokens referenced solely from the JS v("--si-...") calls are also matched (they appear in index.html). Confirm all of these are actually present in tokens.css — e.g. --si-color-brand-green and --si-color-surface-alt are defined, but verify none of the JS-referenced names were renamed. If any of those computed values return an empty string, Redoc receives empty color strings and may throw or render with broken colors at init time. The uncertain part is whether Redoc tolerates empty strings for these theme keys. const T = { primary: v("--si-color-primary"), primaryBright: v("--si-color-brand-blue-bright"), cream: v("--si-color-surface-alt"), orange: v("--si-color-feedback-warning-fill"), orangeBlood: v("--si-color-brand-orange-blood"), green: v("--si-color-brand-green"), red: v("--si-color-feedback-error-fill"), title: v("--si-color-text-title"), body: v("--si-color-text-body"), border: v("--si-color-border"), bodyFont: v("--si-text-style-body-font-family"), displayFont: v("--si-text-style-heading-page-font-family"), // No monospace token in the design system. codeFont: 'ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace' }; Token check gap The token validation only scans docs/index.html, but tokens are also consumed by the Redoc JS via v("--si-..."). Those references do appear in index.html so they are covered, but the regex ^ *$name *: matches a token defined only inside the [data-theme="dark"] block as well as the :root block. If a token is defined only in the dark-theme block and not in :root, the check passes but the light-mode page would have an undefined value. Consider scoping the definition check to the :root block to avoid false positives. - name: Check design tokens referenced by the docs page are defined run: | set -euo pipefail missing=0 for name in $(grep -oE -- '--si-[a-z0-9-]+' docs/index.html | sort -u); do if ! grep -qE -- "^ *$name *:" docs/tokens.css; then echo "Undefined design token referenced in docs/index.html: $name" missing=1 fi done exit $missing