Skip to content

improvement(docs): make the API reference read as code and unify its type token - #6653

Merged
waleedlatif1 merged 8 commits into
stagingfrom
improvement/docs-api-ref-design
Aug 13, 2026
Merged

improvement(docs): make the API reference read as code and unify its type token#6653
waleedlatif1 merged 8 commits into
stagingfrom
improvement/docs-api-ref-design

Conversation

@waleedlatif1

Copy link
Copy Markdown
Collaborator

Summary

  • Make the API reference read as code: parameter names, types, and paths were rendering in the body sans face because the page-wide font override outranked .font-mono on specificity
  • Unify the type slot — scalar, union (string | null), array (array<T>), and schema reference each carried their own chip definition and rendered at different sizes, weights, faces, and box heights; they are now one code token reusing the docs inline-code recipe at the platform's 20px chip height
  • Demote row metadata: required and header were filled pills, required on the error token, which made a constraint the loudest thing on the page. Both are now uncontained text, leaving the type token as the only box on a row
  • Fix a live content bug: the rule hiding the trailing In: header line matched p:has(> code), so it also hid the entire API key description on every API reference page. Matched by position now, and the description shortened to one line
  • Pin the two application/json labels and the status-code tabs to one treatment; they rendered the same strings at different weights and faces
  • Match the few lucide glyphs fumadocs renders itself to emcn's 1.55 stroke, so the docs have one icon weight

Cleanup in the same pass: removed the four ::-webkit-scrollbar rules (a non-auto scrollbar-width makes Chromium ignore them, so they never ran), an order: 2 block the type-token rule already covered, and the pre-wrap rules that never applied because fumadocs sizes the block with w-max. Named the two repeated values (--font-mono-stack, written out 11 times; --text-code, 9 times) and collapsed the metadata face from seven hand-synced copies into one rule.

Type of Change

  • Bug fix
  • Improvement

Testing

Tested manually against the running docs server in both light and dark themes, verifying computed styles rather than by eye — every type slot now resolves to the same face, size, weight, and 20px box, and the auth chip matches the path chip exactly (57px, was 65px). Confirmed lint:check, check:openapi (7 specs, 135 operations), check:api-validation, docs type-check, and a full docs production build.

Notes

Deliberately left for a follow-up, since each is a change of a different kind:

  • Syntax highlighting is still the stock Shiki GitHub theme. The platform already defines its own code palette for Monaco (SIM_LIGHT_RULES / SIM_DARK_RULES) — notably strings green rather than blue, which is most of a JSON response body. Both config hooks exist (shikiOptions on createAPIPage, rehypeCodeOptions for MDX); the work is authoring the TextMate scope mapping.
  • The auth row still fabricates header / required / string through CSS content:. All seven specs declare the same apiKey/in: header scheme so it is accurate today, but it is a stylesheet asserting an API fact, and pseudo-element text is not selectable or findable with Cmd+F. renderOperationLayout already receives the dereferenced schema, so an app-owned auth component would read it properly.
  • renderHeading and renderCodeBlock would let us drop fumadocs' lucide glyphs for the emcn Heading/CodeBlock components the app already owns, retiring the stroke-width rule.

Checklist

  • Code follows project style guidelines
  • Self-reviewed my changes
  • Tests added/updated and passing
  • No new warnings introduced
  • I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

… type token

The API-page font override matched every span/div/p inside the page, which
outranks the .font-mono class on specificity, so every parameter name, type,
and identifier silently rendered in the body sans face. Exclude .font-mono so
code tokens stay monospace.

Consolidate the three divergent type-slot treatments — plain scalar, union,
and schema reference each carried their own chip definition, differing in
size, weight, face, and box height — onto one code token that reuses the docs
inline-code recipe and the platform's 20px chip height.

Demote the row metadata: 'required' and 'header' were filled pills, 'required'
on the error token, making a constraint the loudest element on the page and a
page of required parameters read as a page of alarms. Both are now uncontained
text, leaving the type token as the only box on the row.

Pin the two 'application/json' labels to one treatment; the Request Body and
Response headers rendered the same string at different weights and faces.
…icons to emcn

Status codes in the example panel are numeric literals and render as code
everywhere else on the page, including the Response header's own trigger, but
fumadocs rendered the strip in the body sans face. Language tabs sit in a
separate container and stay sans — those are product names, not code.

fumadocs draws a few lucide glyphs on API pages that its client-component
overrides do not expose (the heading anchor and the code-block copy button).
emcn strokes at 1.55 and lucide at 2, so those icons read heavier than every
icon around them; match the weight.
…d wrap example code

The auth row collapses its real `<token>` type and renders the chip through
::after, so the span is only a wrapper — but it still matched the type-token
rule and kept that rule's border, height, and gap. The border drew a second
empty box around the real chip and the gap opened in front of it, because the
collapsed text remains an anonymous flex item; together they pushed the chip
right by roughly 8px that no other row had.

Example-panel code overflowed sideways instead of wrapping: fumadocs sizes the
block with `w-max`, so it grew to its longest line inside a 400px scroller and
the existing pre-wrap never applied. Cap the width, switch break-all to
overflow-wrap anywhere so only unfittable tokens split, and reserve room for
the copy button fumadocs floats over the first line.
Wrapping restarts every continuation line at column zero, and in a JSON body
indentation is what carries nesting depth — so a wrapped response misreports
its own structure. A hanging indent keeps the depth but needs the shiki lines
forced from flex rows to blocks, which breaks the line rhythm.

Removes the pre-wrap rules rather than repointing them: fumadocs sizes the
block with w-max, so the previous rule never took effect and overflow was
already the behaviour on the page.
…ible

An `array<T>` slot holds its angle brackets as bare text nodes, which become
anonymous flex items, so the slot's gap prised `array<` and `>` away from the
type they wrap. Drop the gap and let the union separator carry its own margin;
this also makes the auth row's gap override redundant.

The separator was dimmed twice, by a muted token and again by opacity, which
on the dark chip fill left `string | null` reading as `string null`.
…reference CSS

The rule hiding the trailing `In: header` line matched `p:has(> code)`, which
is a shape, not a target — every scheme description in our specs cites a status
code, so the whole explanation of personal vs workspace-scoped keys was
display:none on every API reference page. Match the last child instead, and
shorten the description to one line now that it renders.

The dropdown trigger's hover rule had been left below a new id-qualified base
rule that outranked it, so the trigger could no longer change colour on hover.

Removes what does not run: the four `::-webkit-scrollbar` rules (specifying a
non-auto scrollbar-width makes Chromium ignore them, and Firefox never had
them) and an `order: 2` block whose selectors and declaration the type-token
rule above it already carried.

Names the two values the API reference repeats — the monospace stack, written
out eleven times, and the 12.5px code size, written nine — as --font-mono-stack
and --text-code. Also drops four !important declarations that already won on
specificity, a --text-muted fallback that can never fire, and a lucide selector
subsumed by the one beside it.
…mentary

The metadata face — size, leading, weight, mono stack — was written out in seven
rules that a comment asked future readers to keep in sync by hand; it is now one
rule those seven consume, each adding only its own colour, content, and order.
The auth row's chip likewise re-derived all eleven declarations of the type
token and now joins that rule, keeping only its label.

Comments were running longer than the rules they documented — 88 added comment
lines against 73 declarations. Trimmed to the load-bearing facts: cascade traps,
browser behaviour, and the bugs a rule prevents. Dropped the block narrating why
the wrap rules were reverted, which duplicated its own commit message.

Also retires a scrollbar token left unreferenced by the webkit removal, moves
the last two fumadocs colours in our own components onto platform tokens, and
brings the callout icon to 1.55 so the docs really do have one icon weight.
@vercel

vercel Bot commented Aug 13, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
docs Ready Ready Preview Aug 13, 2026 2:28am

Request Review

@cursor

cursor Bot commented Aug 13, 2026

Copy link
Copy Markdown

PR Summary

Low Risk
Docs-only CSS and OpenAPI description strings; no runtime API or auth behavior changes.

Overview
API reference typography and chips — Parameter names, types, and paths now use Geist Mono because the page-wide sans override excludes .font-mono. Scalar, union, array, and schema-reference type slots share one inline-code chip (--text-code, --font-mono-stack, 20px height); union | separators inherit mono and are muted.

Row metadatarequired and header are plain error/secondary text instead of filled pills so constraints are not the loudest element on each row.

Content bug — The rule that hid redundant “In: header” text used p:has(> code) and also hid the full API key description; it now targets only the last paragraph in auth property blocks.

Consistency — Status dropdown, application/json labels, and status-code tabs share one metadata mono treatment. Lucide icons in the docs layout use 1.55 stroke to match emcn.

Cleanup — Removed ineffective ::-webkit-scrollbar rules, unused scrollbar-hover token, duplicate type-token order: 2 block, and pre-wrap on example panels. OpenAPI apiKey security description is shortened in seven specs and shared.ts.

Reviewed by Cursor Bugbot for commit 256147f. Configure here.

@greptile-apps

greptile-apps Bot commented Aug 13, 2026

Copy link
Copy Markdown
Contributor

Greptile Summary

The PR standardizes API-reference typography and metadata styling while fixing the selector that hid API-key descriptions. It also shortens the shared API-key description and regenerates the seven OpenAPI documents.

  • Unifies scalar, union, array, and schema-reference type tokens.
  • Aligns content-type labels, status controls, metadata, and icon stroke weights.
  • Restores API-key descriptions by narrowing the trailing-location selector.
  • Regenerates all v2 OpenAPI specifications from the updated shared contract.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename Overview
apps/docs/app/global.css Refines the fenced API-reference presentation rules and fixes the overly broad selector that hid authentication descriptions.
apps/sim/lib/api/contracts/v2/openapi/shared.ts Shortens the shared API-key description used to generate the public OpenAPI documents.
apps/docs/openapi-v2-billing.json Regenerates the billing OpenAPI document with the updated shared API-key description.
apps/docs/openapi-v2-files-audit.json Regenerates the files-audit OpenAPI document with the updated shared API-key description.
apps/docs/openapi-v2-knowledge.json Regenerates the knowledge OpenAPI document with the updated shared API-key description.
apps/docs/openapi-v2-logs.json Regenerates the logs OpenAPI document with the updated shared API-key description.
apps/docs/openapi-v2-resources.json Regenerates the resources OpenAPI document with the updated shared API-key description.
apps/docs/openapi-v2-tables.json Regenerates the tables OpenAPI document with the updated shared API-key description.
apps/docs/openapi-v2-workflows.json Regenerates the workflows OpenAPI document with the updated shared API-key description.

Reviews (3): Last reviewed commit: "fix(docs): keep the union separator in t..." | Re-trigger Greptile

Comment thread apps/docs/app/global.css
@waleedlatif1

Copy link
Copy Markdown
Collaborator Author

@greptile

@waleedlatif1

Copy link
Copy Markdown
Collaborator Author

@cursor review

Comment thread apps/docs/app/global.css
The `|` between union members is a classless span, so the page-wide
`span:not(.font-mono)` rule assigned it the body sans face while the members
beside it stayed mono — one chip rendering in two faces.

Applies the inherit reset to every descendant of a type token rather than just
its links, so anything fumadocs nests there later is covered too.
@waleedlatif1

Copy link
Copy Markdown
Collaborator Author

@greptile

@waleedlatif1

Copy link
Copy Markdown
Collaborator Author

@cursor review

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

Reviewed by Cursor Bugbot for commit 256147f. Configure here.

@waleedlatif1
waleedlatif1 merged commit 29853fb into staging Aug 13, 2026
29 of 30 checks passed
@waleedlatif1
waleedlatif1 deleted the improvement/docs-api-ref-design branch August 13, 2026 02:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant