Style guide

Palette

Navy, Sky, and Paper carry the site. Midnight grounds the dark theme, Coral and Cyan are small accents, and three warmer colors appear only as pale tints.

These ten hex values are the brand’s own, and everything else is built from them. The surfaces, inks, and borders a component actually uses are semantic tokens that point at these (see CSS tokens), which is how one palette serves both themes.

Core

Dark grounds

Accents

Supporting tints

What each color is for

Seagrass and Lantern rotate with Sky through the color-keyed pieces—the How-it-works steps, the service rows, and the trust-stack and “What we do” icons—as 9–18% washes mixed into Surface, or as their -ink steps where they carry meaning.

Nearest Pantone

Solid Coated, for reference only. Don’t substitute these into production files, and check a physical fan deck before a print run. Paper is a substrate, not an ink, so it has no match.

• The One Beacon RuleSky guides; it never reads. Use it for rules, icons, fills behind Navy text, and accents on dark grounds. Any text or meaningful mark on a light ground uses --link or --sky-ink instead.
• The Supporting Tints RuleSeagrass, Lantern, Sand, and Coral appear as pale washes, step accents, and small marks. They are never large fills or text on a light ground; where one must carry meaning, use its -ink step. The one solid use is the 3.5rem Who-we-help icon tiles, which always carry a Navy icon.
• The Color-Keyed Sections RuleServices and Who we help give each item its own accent so the eye can tell items apart at a glance. Color is never the only cue: every item keeps its icon and heading. Coral stays out of both, because in forms it means an error.

Light, dark, and contrast

The palette is fixed; what changes is which token points at what. Dark redefines 57 of the 73 custom properties, and no component knows which theme it is in.

Both panels below are the same markup. Each one takes a palette rather than being told its colors, which is what every component on the site does. The navy booking band, this guide’s bar, and its masthead keep their ground in both themes.

Measured contrast

Computed from the shipped token values by scripts/build-docs.js with the WCAG 2.1 formula, and rounded down to one decimal so that no pair is ever rounded up over a threshold. Text needs 4.5:1; large text and non-text marks such as the focus ring need 3:1. Each sample is painted from the tokens themselves, in its own theme’s scope.

The logo lockup is held to the same bar. WCAG 2.1 exempts logotypes from contrast (1.4.3, “Incidental”), so the “Healthcare Advocates” line would be allowed to sit at the raw Sky and Deep-tone·alt values it has in the logo files. It does not. The header line is drawn in --sky-ink (5.5:1 on the light ground) or #6FC3FF (9.8:1 in dark), and the footer line in #1E2B5A (5.5:1 on the Sky footer) or Cyan (13.6:1 on the dark one). The exemption is a fallback the site does not rely on.

Pairs that are never used

Recorded so that nobody reaches for them.

How the switch works

• The Semantic Token RuleComponents never hard-code light or dark values. If a rule needs a color that isn’t already a token, add a token. That is the whole reason a component can be unaware of the theme.
• Add it in three places, onceThe light value goes in :root, and the dark value in both dark blocks: the prefers-color-scheme one and the [data-theme="dark"] one. They carry identical values and must stay in lockstep; miss one and the toggle disagrees with the device.
• Don’t use Tailwind’s dark: for colorThe variant is configured and matches the same two states, but nothing in the markup uses it. A dark: utility is a color decision hidden in a class list.
• Re-check contrast on the dark sideThe -ink accents are darkened for the light ground and point back at brighter values in dark. On a bright accent ground in dark, put dark ink on it; that is what --cta-ink and --ba-after-ink are for.
• Test the toggle, not just the device settingTwo code paths reach dark. The gear in this guide’s bar opens Site preferences, which is the quickest way to exercise both.

Type system

Four typefaces, each with one job. Every heading is Questrial 400, so hierarchy comes from size and space and never from weight.

Roles

• The Level Voice RuleEvery heading is Questrial 400. Hierarchy comes from size and space, never from bold weights. Questrial ships one weight, so never request faux bold.
• The Figures-in-Mono RuleIBM Plex Mono is reserved for real figures and form validation errors. It is never a stylistic costume for labels or headings, which is why this guide’s own annotations are set in Questrial.

Type scale

Roles are named for the job and not the value. The heading sizes are fluid between a phone and a desktop value, and each step is at least 1.25 times the one below it.

The five heading and lede sizes are tokens in tailwind.config.js (fontSize); the smaller roles are set where they are used. Every sample below is set live in its own face and size.

• The Readable-First RuleBody text never drops below 18px, and supporting text never below 14px. Headings balance their line breaks and paragraphs wrap to avoid orphans. Older readers are a core audience, so legibility outranks density.
• Measure governs width; the scale only governs heightProse stops at 62 characters, legal pages and FAQ answers at 68, and ledes at 60.

The mark

The Advocate Beacon: a lighthouse inside a shield. Negative-space stripes wind up the tower so the shield color shows through them, and there is no separate stripe ink.

Five colorways, each tied to a specific ground. The tiles below are fixed to their documented ground, so they stay correct in either theme.

• 

  Primary
  Sky shield · Coral heart

• 

  Dark
  Light Sky shield · near-white heart

• 

  One-color
  Navy only: letterhead, stamps

• 

  Reversed
  Paper shield · Cyan heart

• 

  Deep-tone·alt
  Muted navy shield · Coral heart

Size and clear space

Where it appears

Favicons are a different drawing

A favicon is not a scaled-down full mark. The tower fills solid Navy with no stripes, and the lighthouse is scaled 1.625 times. It is correct for 16 to 48px only; use the full mark above that, and never regenerate a favicon from it.

The two favicon marks at 32px: primary, and the one drawn for a dark ground

Beside it

The Greater National Advocates badge is required in the site footer. It ships as assets/img/gna-logo-navy.svg and gna-logo-white.svg, and a full-color lockup replaces the white badge on paper.

Logo lockups

The mark with the wordmark, in four forms. All type is outlined, so there is no font dependency at a printer.

Shown here in Primary. Each form also ships in Dark, One-color, Reversed, and Deep-tone·alt: 20 files in all, in assets/logomarks/logos/, each as SVG plus 512, 1024, and 2048px PNG.

Horizontal
the default

Stacked
for a square space

Wordmark
no mark

Logotype
“Coastal” alone

Read the full asset README

Grid and measure

One centered reading column, 1000px at most, with a nine-column grid inside it and a 24px gutter.

Two layouts use the grid for a real column relationship: the hero and Lindsey’s bio. Everything else is a plain two- or three-up grid, because most of this site is one column of prose and a row of cards. Every one of them is drawn out under Layouts.

Those figures are the nominal grid, measured across the full 1000px. .canvas spends 2rem of that on side padding, so at full width a column actually measures about 83px and a six-column span about 616px. The ratios are what matter; the pixel values are there to size a comp.

Nine divides cleanly into thirds and keeps the page out of the twelve-column default. Two layouts set their own tracks on top of the nine: the hero puts four columns of text beside a five-column illustration, and About swaps the tracks for an 18–22rem portrait rail. Below 1024px .grid-9 becomes a single column and drops its children’s spans outright (grid-column: auto !important), so a span only ever describes the desktop layout.

The canvas

Every section is a .section for its vertical rhythm with a .canvas inside it for its width. Nothing sets its own max-width. This guide and the two code references are the exception: they are reference pages, and use the shell described at the top of this file.

Breakpoints

The hero’s illustration keeps a 38% track between 500 and 1023px and bleeds off the right edge, and is hidden altogether below 500px. The About rail turns sticky at 700px and, between 450 and 699px, drops out of grid layout entirely so the portrait can float right and the bio wraps around it. Both are documented where they live, at the foot of the utilities layer in src/input.css.

Measures

• The One Column of Attention RuleContent never spreads wider than the 1000px reading column, and no decision point shows more than a handful of equal options. The persistent Get started tab is the only floating element, and it tucks away once the intake form is on screen.
• Start with the canvas, not the gridA section is <section class="section"><div class="canvas">. Most of this site is one column, and one column is the right answer more often than it looks.
• Reach for .grid-9 only for a genuine column relationshipThere are two on the site: the hero and the About rail. For a row of cards use Tailwind directly, grid gap-gutter md:grid-cols-2, which is what every other section does.
• Prefix every span with lg:Below 1024px the grid is one column and unprefixed spans are overridden anyway, so an unprefixed span is at best noise and at worst a wrong guess about small screens.
• Use the gutter tokengap-gutter in markup, theme('gap.gutter') in CSS, never a literal 24px.
• Give a fixed rail a fixed trackWhen a column has an intrinsic width, a share of nine strands a gap beside it. About overrides the tracks with 22rem minmax(0, 1fr), because the rail only ever needs room for the portrait.
• Write plain width queries@media (min-width: 48rem) is enough. A PostCSS step rewrites it so the Larger and Largest text sizes keep the phone layout at any width. A rule that must survive that rewrite belongs in a container query instead.
• Don’t let meaning ride on column orderReader mode forces every grid to one column and clears each child’s placement, so the DOM order is the order a reader may get. Check that the section still reads top to bottom.

Layouts

A wireframe of every layout the site uses. Each frame draws the tracks and the reading order and leaves the content out, so it stays true as the copy changes.

The wide frame is the desktop layout and the narrow one beside it is the phone. A dashed outline around a whole group is the .canvas: a width limit rather than anything you can see on the page.

The page shell

The homepage, in order

Overlays and secondary pages

• Reader mode redraws all of themSite preferences, then Reader mode, narrows every canvas to 44rem and forces .grid, .grid-9, and the named layouts above to one column, clearing each child’s placement. Every diagram here becomes its phone frame, in DOM order, which is why none of these layouts may carry meaning in its column order.
• So do the Larger and Largest text sizesAt those two sizes a PostCSS step rewrites every width query, so the page keeps its phone layout and its hamburger at any window width. The narrow frame is what a desktop window shows at those settings.

Buttons and controls

Large, calm targets that say what happens next. An uppercase Questrial label, 12px corners, 48px tall at least, and a hair of lift on hover.

These are the real .btn classes from src/input.css. A button is a link when it goes somewhere and a <button> when it does something; both take the same classes. Every press plays one soft click (see Motion).

On the page ground: .btn-primary, .btn-ghost, and the focus ring, Navy in light and Sky in dark

On Navy, the booking band’s actions: .btn-on-dark, .btn-ghost-on-dark, and the ring in Sky

Every button shares one shape: min-height: 48px, 0.75rem by 1.4rem of padding, a 15px label tracked 0.06em. Hover lifts it 1px and a press dips it 1px, over 0.18s. A label stays on one line wherever it fits and wraps inside the button on a narrow phone or at the larger text sizes.

Icon controls

Round is reserved for controls that are only an icon. Each is at least 44px across and carries its name in aria-label and title.

.header-icon-btn at 44px, its focus ring, and .link-quiet, whose arrow nudges in its direction of travel

• Big enough to hitButtons are at least 48px tall and icon buttons at least 44px, and every control gets the 3px focus ring: Navy on light grounds, Sky on dark ones. Put .on-dark on a navy ground and the ring follows.
• One primary action in a viewA primary button never competes with a second one. The floating Get started tab is the only persistent control, and there is never a second floating one.
• Say what happens nextA label names the result: “Book a free call”, not “Submit”. Sentence case in the source; the CSS sets the capitals, so a screen reader reads words and not letters.

Components

Surfaces are pale and mostly flat. Structure comes from hairline borders and tonal washes, and a soft neutral lift is kept for photographs, pinned cards, and floating layers.

Surfaces

Three containers cover almost everything. Headings inside them drop their tracking.

.card, .tile, and .callout, live. Point at the tile.

Depth

In the dark theme shadows fade into the ground and the borders carry the separation.

Shape

Borders are 1px hairlines. Only an error state uses 2px, in Coral.

Icons

A hand-authored inline SVG sprite on a 24px grid: 1.75px strokes (2px for small UI glyphs such as plus, close, and check), round caps and joins, drawn in currentColor. The homepage carries the full sprite; the secondary pages carry the header and footer’s share, written in at build time from src/partials/icons.html, and this page carries its own few. Social marks are the only filled icons. The brief first asked for hand-drawn doodle icons; that was tried and dropped, so don’t reintroduce it.

Signature pieces

These live in index.html and can’t stand alone on a second page, so they are described here and drawn under Layouts. DESIGN.md has each one in full.

• The Soft Lift RuleSurfaces are flat at rest unless they are a photograph, a pinned card, or a floating layer. Everything else gains elevation only as feedback. Lifts are neutral and soft, never colored glows.
• The Earned Light RuleThe beacon’s light is reserved for the moment someone reaches out. Don’t reuse it as page decoration, a loading spinner, or a hover effect, or it stops meaning “you’ve been heard”.
• Not an insurer’s interfaceNo dashboards, hero-metric stat tiles, countdown or scarcity urgency, or aggressive conversion chrome. The design earns trust by being calm, legible, and honest.

Form elements

There is exactly one authored form on this site, #intake-form in index.html. The dialog clones it, and Netlify detects it at build time. Author a second one and you break both.

The states

Live controls, not screenshots, so tab through them. These are demonstration fields and go nowhere.

Anatomy

Every control is one .field block: a label, the control, an optional hint, and an error slot that starts hidden.

• Don’t build a second formAdd fields to #intake-form instead. It is the only form Netlify knows about, the only one that works without JavaScript, and the one the dialog clones.
• Give every field an id prefixThe inline form uses in- and the dialog clone cf-; modal.js re-keys them so both copies can share a document. A validated field X needs an error element X-err. That is the whole contract.
• Label with for, help with aria-describedbyPlaceholders are not labels, and a hint the control doesn’t point at is invisible to a screen reader.
• Set autocompletename, email, tel: this is the difference between a one-tap form and a chore on a phone.
• Mark errors three waysaria-invalid="true" on the control, the error id joined onto its aria-describedby, and the message in X-err. On a failed submit the summary takes focus, which is how it gets announced; there is no role="alert".
• Keep error text in InkThe Coral border and the ▲ carry the signal. Coral body text at caption size would not clear AA.
• Never ask for health detailsThe form collects a name, a way to reply, and a short description. The note above the fields says so, and it rides along into the dialog clone.
• Leave the spam layers aloneThe honeypot company field, the two-second time-trap, and the Turnstile check are load-bearing; contact-form.js drops anything that trips the first two, and holds a send until the third has a token.

Overlays and dialogs

Three overlays. Each one takes the keyboard when it opens and gives it back exactly where it took it.

Try it

These buttons open the real contact dialog. This page has no form of its own, so modal.js fetches index.html and borrows it, exactly as any secondary page does. The gear in the bar above opens Site preferences.

Why the contact dialog isn’t showModal()

A dialog opened with showModal() goes into the browser’s top layer. When the form used reCAPTCHA, the dialog’s ::backdrop painted over the challenge overlay that reCAPTCHA appended to <body>, and the visitor got an invisible puzzle. The form now uses Cloudflare Turnstile, whose challenge stays inside the widget, so that constraint is gone; the hand-built dialog stays because it works and is tested. It opens with dialog.show(), and everything the top layer would have given for free is built by hand: a real #contact-backdrop element that also handles a click outside, inert on the rest of <body>, Escape, a focus trap, a scroll lock, and focus returned to the button that opened it. Site preferences has no such history and uses the native modal.

Hooks

Parts

• Load the module<script type="module" src="assets/js/modal.js">. On a page with no #intake-form it fetches the homepage and borrows the form, the success panel, the dialog, and the backdrop. The page’s CSP <meta> must allow Turnstile and Calendly, or the borrowed dialog’s bot check is silently blocked.
• Point the trigger somewhere real firstSecondary pages link to /index.html#intake and add data-open-contact on top. If the fetch fails or JavaScript never runs, the link still works.
• Pick the variant by the weight of the askThe drawer is for a call to action in the flow of a page. The lightbox is for the hero’s primary action, where the page should feel paused.
• Don’t style the dialog per pageBoth variants are already in src/input.css; a page-local override will drift from the other one.
• Let the animation finishClosing is .is-closing, then close() on animationend. Calling close() directly cuts the drawer off mid-slide.
• Check it with Animations offReduced motion swaps the slide for a fade; everything else must still work.

Motion

Gentle and continuous. Things rise in, draw on, or march slowly; each plays once as it comes into view, and then stays put.

ease-calm      cubic-bezier(0.22, 1, 0.36, 1)    buttons, the Get started tab
--reveal-ease  cubic-bezier(0.16, 1, 0.3, 1)     everything that comes into the light

Write a plain prefers-reduced-motion query. A PostCSS step (scripts/postcss/motion-pref.js) makes every such block also answer the Animations off switch in Site preferences (:root[data-motion="off"]). JavaScript that animates checks prefersReducedMotion in main.js, which covers both.

Sound

Pressing any button plays one soft, synthesised click: a short wooden tick over a falling sine, a few percent different each time, at low volume. It is the only sound on the site. It never plays on hover, scroll, or page load, and it is silent with reduced motion, with Animations off, or when localStorage.sound is off. There is no audio file; sound.js builds it with Web Audio.

• The Calm Motion RuleMotion moves one way and never demands attention: things rise in, draw on, or march slowly, and loops pause when off screen. Nothing flashes, bounces, or blocks reading, and reduced motion keeps only color and opacity changes.
• Nothing waits on an animationContent is fully visible without JavaScript, and a failed script hides nothing. Start states begin at an opacity of 0.01, not 0, so the browser still counts the hero as painted.
• Only the theme switch starts a view transitionIts two rules in src/input.css name ::view-transition-*(root) and carry no class, because a page has one root transition at a time. A second feature that called startViewTransition would inherit the theme’s 280ms cross-fade, so give that one its own view-transition-name rather than retiming these.

CSS tokens

Semantic custom properties on :root in src/input.css, swapped by data-theme or the visitor’s device setting. This is what the theme buttons actually switch.

The ledger below is the working set, and scripts/build-docs.js writes its values in from the source, exactly as authored: a value that reads var(--sky) points at the palette. The CSS reference lists all 73 custom properties.

Set from script

A few attributes and properties carry a visitor’s choice or a measurement, never a design decision.

Code reference

The source comments are the documentation. Every build regenerates the reference pages from them, so they always match what ships.

After changing a token, a theme value, or this page, run the builder and commit what it writes. To change what a reference page says, edit the source comments. In src/input.css, a /* ==== */ banner opens a section, /* --- Title: text --- */ opens a sub-section, and the comment directly above a rule becomes its note.

npm run build:docs    # writes site/docs/js and site/docs/css, and updates this page
npm run check:docs    # writes nothing; exits 1 if this page is out of date
npm run build         # the full build; Netlify runs this

• The Three Layers RuleContent lives in the HTML, presentation in the CSS, and behavior in the JavaScript. Every word a visitor can reach is written once, in the page, and structured data marks up those words instead of repeating them. Script shows, hides, and moves what’s already there. It never writes copy or markup, and never sets a style except to hand CSS a number only it can measure.
• State is an attributeScript sets open, hidden, aria-expanded, or a data-* value, and CSS decides what each state looks like. Where the words change with the state, write both versions and show one, as the booking band’s data-calendly-after copy does.
• Native before scriptedUse the element that already does the job before writing script that imitates it. The FAQ rows are <details> elements with microdata on each question, and no script at all.