Skip to content

🏗️✨：give the handbook a page of its own #1880

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
openinf-commit-queue merged 1 commit into from
Sep 2, 2026
Merged

🏗️✨：give the handbook a page of its own #1880

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
155 changes: 71 additions & 84 deletions _assets/styles/_docs.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,10 +14,6 @@ $docs-primary-tint: tint-color($primary, 30%);
$docs-muted: #4b433c;
$docs-hairline: rgb(167 151 139 / 55%);

// A pale wash with deep-shade text, so the chip clears AA at this size.
$docs-flag-bg: tint-color($quaternary, 88%);
$docs-flag-text: shade-color($quaternary, 25%);

// Scoped to `main` to keep the resets off the navbar and footer, which are
// its siblings under the same body class. The padding replaces what
// `main > .container` gives the footer elsewhere.
Expand All @@ -40,8 +36,10 @@ $docs-flag-text: shade-color($quaternary, 25%);
// Ink, so it carries on from the navbar rather than leaving a pale band
// between the two.
.docs-head {
position: relative;
padding-top: calc(#{$navbar-height} + clamp(2rem, 5vw, 3.5rem));
padding-bottom: clamp(2.25rem, 5vw, 3.5rem);
overflow: hidden;
color: $body-bg;
background-color: $body-color;
}
Expand All @@ -50,7 +48,30 @@ $docs-flag-text: shade-color($quaternary, 25%);
outline-color: $body-bg;
}

// The ring off the logogram, the same drawing home's masthead and the news
// head use, tuned for the glance panel it sits behind here.
.docs-head-ring {
position: absolute;
inset-block-start: 0;
inset-inline-end: 0;
z-index: 0;
width: min(48vw, 360px);
aspect-ratio: 1;
color: $docs-primary-tint;
pointer-events: none;
opacity: 0.12;
transform: translate(22%, -30%);
}

.docs-head-ring svg {
display: block;
width: 100%;
height: auto;
}

.docs-head-grid {
position: relative;
z-index: 1;
display: grid;
grid-template-columns: minmax(0, 1.4fr) minmax(0, 0.85fr);
gap: clamp(2rem, 5vw, 4rem);
Expand Down Expand Up @@ -79,26 +100,28 @@ $docs-flag-text: shade-color($quaternary, 25%);
color: rgb(231 231 214 / 76%);
}

/* --- Head: the invite -----------------------------------------------
The shape `.join` has on the home page, carrying the handbook's own gap.
Both branches read the count the list further down is built from.
/* --- Head: at a glance ---------------------------------------------------
The shape `.join` has on the home page and `.hb-stat` gives the handbook:
an eyebrow, a headline number, and a row that leads on. Here the number
is every page this index gathers, so the two children read as one family
rather than the handbook having copied the parent.
*/

.invite {
.docs-glance {
padding: 1.25rem 1.375rem;
background-color: rgb(231 231 214 / 4%);
border: 1px solid rgb(231 231 214 / 20%);
}

.invite-eyebrow {
.docs-glance-eyebrow {
font-family: $font-family-monospace;
font-size: 0.6875rem;
color: $tertiary;
text-transform: uppercase;
letter-spacing: 0.08em;
}

.invite-title {
.docs-glance-title {
display: flex;
flex-wrap: wrap;
gap: 0.5rem;
Expand All @@ -110,34 +133,29 @@ $docs-flag-text: shade-color($quaternary, 25%);
color: $body-bg;
}

.invite-num {
.docs-glance-num {
font-family: $font-family-monospace;
font-size: clamp(2.25rem, 5vw, 2.75rem);
line-height: 0.9;
color: $docs-primary-tint;
}

.invite-what {
.docs-glance-what {
margin-top: 0.75rem !important;
font-size: 0.9375rem;
line-height: 1.6;
color: rgb(231 231 214 / 70%);
}

.invite-row {
.docs-glance-row {
padding-top: 0.875rem;
margin-top: 1rem !important;
border-top: 1px solid rgb(231 231 214 / 16%);
}

// Links on the ink. `.docs main a` is (0,1,2), so a band rule needs `main`
// to reach them.
.docs-index main .docs-head a {
color: $body-bg;
}

// The treatment `.join-row a` gives the home page's equivalent link.
.docs-index main .invite-row a {
// The treatment `.join-row a` gives the home page's equivalent link. Scoped
// to the head, where the ink is: parchment on a band would be invisible.
.docs-index main .docs-head .docs-glance-row a {
font-family: $font-family-monospace;
font-weight: 700;
color: $body-bg;
Expand Down Expand Up @@ -176,6 +194,17 @@ $docs-flag-text: shade-color($quaternary, 25%);
border-bottom: 1px solid $docs-hairline;
}

// The numbered voice `.area-num` gives the home page's SDK areas and
// `.rule-card-num` gives the handbook's grid, so a reader who has seen either
// already knows this is one entry in a counted set.
.docs-index .part-num {
display: block;
margin-bottom: 0.375rem;
font-family: $font-family-monospace;
font-size: 0.75rem;
color: $docs-link;
}

.docs-index .part-name {
font-size: 1.0625rem;
font-weight: 700;
Expand All @@ -188,9 +217,10 @@ $docs-flag-text: shade-color($quaternary, 25%);
color: $docs-muted;
}

/* --- The handbook -------------------------------------------------------
Alphabetical, one row per rule, name and point side by side so the names
read as an index. The numeral uses `.area-num`'s recipe from the home page.
/* --- The handbook --------------------------------------------------------
The rules live at their own page now; this is the teaser that sends a
reader there, styled as the arrow-link `.featured-link` gives the news
page's lead story.
*/

.docs-index .handbook-lede {
Expand All @@ -201,70 +231,27 @@ $docs-flag-text: shade-color($quaternary, 25%);
color: $docs-muted;
}

.docs-index .rule-list {
margin-top: 1.75rem !important;
}

.docs-index .rule {
display: grid;
grid-template-columns: minmax(0, 19rem) minmax(0, 1fr);
gap: 0.25rem 2rem;
padding-block: 0.875rem;
border-bottom: 1px solid rgb(167 151 139 / 35%);
}

.docs-index .rule:first-child {
border-top: 1px solid rgb(167 151 139 / 35%);
.docs-index .handbook-more {
margin-top: 1.25rem !important;
}

// A grid, so the numeral keeps its own column and stays beside the first
// line of a title long enough to wrap.
.docs-index .rule-name {
display: grid;
grid-template-columns: 1.375rem minmax(0, 1fr);
gap: 0.5rem;
align-items: baseline;
font-size: 0.9375rem;
.docs-index .handbook-link {
display: inline-flex;
gap: 0.375rem;
align-items: center;
font-weight: 700;
}

.docs-index .rule-num {
font-family: $font-family-monospace;
font-size: 0.75rem;
font-weight: 400;
color: $docs-link;
text-decoration: none;
border-bottom: 2px solid currentcolor;
}

.docs-index .rule-heading {
display: flex;
flex-wrap: wrap;
gap: 0.5rem;
align-items: baseline;
.docs-index .handbook-link-arrow {
display: inline-block;
transition: transform 0.15s ease;
}

.docs-index .rule-point {
font-size: 0.9375rem;
line-height: 1.6;
}

// The chip carries the state in text, so it does not rest on color alone.
.docs-index .rule-flag {
padding: 0.0625rem 0.4375rem;
font-family: $font-family-monospace;
font-size: 0.6875rem;
font-weight: 400;
color: $docs-flag-text;
text-transform: uppercase;
letter-spacing: 0.06em;
background-color: $docs-flag-bg;
}

.docs-index .handbook-gap {
max-width: 60ch;
margin-top: 1.5rem !important;
font-size: 0.9375rem;
line-height: 1.65;
color: $docs-muted;
.docs-index .handbook-link:hover .handbook-link-arrow {
transform: translateX(3px);
}

/* --- Not here yet --------------------------------------------------------
Expand Down Expand Up @@ -305,10 +292,10 @@ $docs-flag-text: shade-color($quaternary, 25%);
.docs-index .part-list {
grid-template-columns: minmax(0, 1fr);
}
}

// The name column stops earning its width once the point beside it wraps.
.docs-index .rule {
grid-template-columns: minmax(0, 1fr);
gap: 0.375rem;
@media (prefers-reduced-motion: reduce) {
.docs-index .handbook-link-arrow {
transition: none;
}
}
Loading
Loading