Skip to content

feat(docs): release 0.15.0 with tighter spacing, a redrawn landing and an archive strip - #200

Merged
tmccoy14 merged 7 commits into
mainfrom
feat/docs-compact-spacing
Oct 19, 2026
Merged

tmccoy14 merged 7 commits into
mainfrom
feat/docs-compact-spacing

Conversation

@tmccoy14

@tmccoy14 tmccoy14 commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

Need

Guardian, Integrity Python SDK, Verifiable Compute and the component site are long pages of prose and examples. Readers should see a section's text together, and the landing page should get them to the right section fast.

Problem

  • Spacing: 0.14.1 puts 80px above a 20px h2 and 48px above an h3, more than any of 11 prose docs sites (median 53px: Stripe 46, Next.js 45, Starlight 53, GitHub 68) and 12 component-library docs sites (median about 45px above an h2, 25px above an h3). The footer area runs 445px below the last paragraph, against Starlight's 265px.
  • Landing: a grey header panel on every card, underlined links, a fixed three-column grid that leaves empty space beside a two-card row, and a title that wraps with the sidebar open.
  • Archive banner: a boxed alert inside the article that says interactive examples are not shown, which holds only for pages with live component examples.

Change

One spacing scale for every site, no options:

  • 48px above an h2, 32px above an h3, 32px under the page header
  • 16px below paragraphs, lists, code, tables, tabs, alerts and rules
  • 64px around the article footer, and a one-line site footer the header's height (69px)
  • Labels and h4 to h6 keep their gaps; heading labels stay automatic, as on main
  • The README's spacing table is updated

Landing page

  • Larger title that takes the full width and stays on one line at 1024px and up; mono section labels like the sidebar's
  • Cards with a 16px title, an optional Lucide icon beside it, quiet link rows and a brand hover
  • Columns follow each section's card count, so every row spans the width; a lone card lays out sideways. Descriptions share a row height through subgrid

Every page

  • Dark mode only: a faint brand wash behind the page header, drawn by the content column so it spans it at any width. It fades out above the body text, so only the title and description sit on it, at 9.8:1 or better
  • Archived versions open with a full-width strip like Studio's archived banner: "You're viewing archived documentation for v1.2.0. See the latest version (v1.2.1)." The link still opens the same page in the latest version

Evidence

Heading gaps, measured in the browser:

Above h2 Above h3
0.14.1 80px 48px
This PR 48px 32px
12 component-library docs (median) ~45px ~25px
11 prose docs (median) 53px —

Component sites measured: shadcn/ui, Radix Themes, MUI, Mantine, Chakra, Primer, Carbon, Atlassian, Ant Design, Headless UI, Tailwind (React Aria and Polaris didn't measure).

  • On the component site's Alert, Card and Toast pages, each example still reads as its own block; pages run 8 to 12% shorter
  • Guardian's Troubleshooting page goes from 2458px to 2090px; the site footer from 101px to 69px, the header's height
  • Run locally on all three docs sites from this branch's build: every page loads, every landing link returns 200, titles stay on one line from 1024px to 1920px, and Guardian's docs ci passes
  • 218 docs tests pass

Not covered

  • Headless Chromium only
  • Each site's config and landing changes land in their own repos after 0.15.0 is published. Guardian also adds an intro sentence under the h2s that would otherwise become labels, and updates its archive-banner check for the new wording

🤖 Generated with Claude Code

tmccoy14 and others added 4 commits October 16, 2026 15:05
…labels

Adds two site-level options. `spacing: 'compact'` tightens the vertical
rhythm for long prose pages: 48px above an h2, 32px above an h3, 32px under
the page header, 16px below paragraphs, lists and blocks, 64px around the
article footer, and a site footer as tall as the header. `headingLabels:
false` keeps every h2 a title, so sibling sections stop switching between a
title and a mono label depending on whether they open with a sentence.

Both default to 0.14.1's behavior, so the component site is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Compile docs.css with Tailwind in a test and check that each compact
  override follows its comfortable value, that the h2 label applies only
  while labels are on, and that DocsShell writes both <html> attributes
- Give headingLabels a heading-labels variant beside compact, in the same
  selector style
- Document the top-level options with a snippet, the pager-to-links gap,
  and the footer's dependence on --eq-docs-header-height
- Tabs take the 24px block gap (16px compact) like other blocks

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The pre-commit formatter re-staged all of chrome.css, so the previous commit
carried an unrelated landing-page rule. It matched nothing on this branch.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Landing: a larger title, mono section labels like the sidebar's, and cards
  with a 16px title, quiet link rows and a brand hover in place of the grey
  header panel and underlined links
- Columns follow each section's card count so every row spans the width; a
  lone card lays out sideways. A newline in the description is kept
- Landing cards take an optional `icon`, a Lucide name beside the title
- Dark mode draws a faint brand wash behind every page's header, drawn by
  DocsPage's column so it spans the column at any width. It fades out above
  the body text, so only the title and description sit on it

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@Shrinks99 Shrinks99 left a comment •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

If the spacing is not as desired, I don't want to add site-level overrides that change it on a per-site basis. This should be a global style and we should fix it so it looks nice on all of them.

… on one line

- An archived page's banner is a strip across the content column, like
  Studio's archived banner: an archive badge and "You're viewing archived
  documentation for v1.2.0. See the latest version (v1.2.1)." The link still
  opens the same page in the latest version
- The banner no longer says interactive examples are not shown; it held only
  for pages with live component examples
- The landing title takes the full width, at 36px below 1280px and 48px above,
  so a long title stays on one line with the sidebar open

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@tmccoy14 tmccoy14 changed the title feat(docs): release 0.15.0 with compact spacing and optional heading labels feat(docs): release 0.15.0 with compact spacing, a redrawn landing and an archive strip Oct 19, 2026
…options

Review asked for one global style rather than site-level overrides. The
compact values become the defaults on every site, and `spacing` and
`headingLabels` are removed.

- 48px above an h2, 32px above an h3, 32px under the page header, 16px below
  paragraphs, lists and blocks, 64px around the article footer, and a one-line
  site footer as tall as the header. Labels and h4 to h6 keep their gaps
- Measured on 12 component-library docs sites (shadcn/ui, Radix, MUI, Mantine,
  Chakra, Primer, Carbon, Atlassian, Ant Design, Headless UI, Tailwind): median
  about 45px above an h2 and 25px above an h3, so the scale is at or above
  them on component pages as well as prose
- Heading labels stay automatic everywhere, as on main
- Tabs keep their 16px, which now matches every other block

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@tmccoy14 tmccoy14 changed the title feat(docs): release 0.15.0 with compact spacing, a redrawn landing and an archive strip feat(docs): release 0.15.0 with tighter spacing, a redrawn landing and an archive strip Oct 19, 2026
@tmccoy14

Copy link
Copy Markdown
Contributor Author

@Shrinks99 agreed, thanks. d37a6ae removes spacing and headingLabels: the tighter scale is now the only one, on every site, and heading labels behave as on main.

Since #198 moved the headings to 80/48 for the component site, I checked component docs as well as prose ones before making it global:

Above h2 Above h3
0.14.1 80px 48px
This PR 48px 32px
12 component-library docs (median) ~45px ~25px

Sites: shadcn/ui, Radix Themes, MUI, Mantine, Chakra, Primer, Carbon, Atlassian, Ant Design, Headless UI, Tailwind. On our own Alert, Card and Toast pages each example still reads as its own block, and the pages run 8 to 12% shorter. @matthewmr-eqty, worth a look at those three since they were the ones #198 fixed.

Where labels misfired on Guardian, the fix is in Guardian's content (an intro sentence under the h2), not in equality.

- Landing columns divide the card count: two across for an even count, three
  for a multiple of three. Three cards lie sideways one per row until three
  fit, instead of leaving 2 + 1 with a gap on laptop widths
- The archive banner is an aside labelled "Archived version", a landmark,
  rather than a live status region
- README and CHANGELOG describe the column rule, the 32px either side of the
  footer rule, the label gaps and the page-description newline as built

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@tmccoy14
tmccoy14 merged commit baf4986 into main Oct 19, 2026
1 check passed
@tmccoy14
tmccoy14 deleted the feat/docs-compact-spacing branch October 19, 2026 14:44
tmccoy14 added a commit to eqtylab/integrity-py that referenced this pull request Oct 19, 2026
## Change

- **Dependencies:** `@eqtylab/docs` 0.15.0 and `@eqtylab/equality`
4.13.1 (the site had resolved equality 4.2.0). 0.15.0 brings the tighter
spacing scale, the redrawn landing with card icons, and the
archived-version strip
([equality#200](eqtylab/equality#200)).
`pnpm-workspace.yaml` adds 0.15.0 to the release-age exclusion, as
earlier bumps did
- **Min Version → Requirements:** the page is now
`/install/requirements/`, first in Install. `vercel.json` sends
`/(2.4.x|latest|dev)/install/min-version.html` straight to it, ahead of
the generic 2.4 rules, and does the same for the Astro-era
`/install/min-version/`. Archived versions keep their own `min-version`
pages
- **Landing page:**
  - card icons
  - Requirements in the Install card
  - Auth Service Signer in Examples
  - descriptions sized so each row's cards match
- **Init and Config:** the title matches the other API pages
- **Section titles:** an h2 directly above an h3 renders as a mono
label, so API Reference on Init and Config and Functions on Statements
each get a one-sentence intro, outside the generated blocks

## Verification

- `pnpm install --frozen-lockfile` and `pnpm build` pass from a clean
install
- `scripts/check_old_links.py docs-site/dist`: 329 of 329 old addresses
land, the same as `main`
- Every landing link resolves; the icons render

## Not covered

- No CHANGELOG entry: docs-only, as with the 0.14.1 move
- `scripts/test_render_api_docs.py` wasn't run locally (needs `griffe`);
the intros sit outside the generated markers the renderer replaces

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
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.

2 participants