Style guide

Palette

Three ink steps carry the page, two creams carry the type, one tint carries everything quiet, and two accents divide the work between acting and measuring.

Every value was measured against the field it sits on, not picked by eye. A new step inside a family is a design decision; a new hue is one to take to the client.

Field

Type

Accents

What each color is for

Translucent steps are written from the channel tokens, as in rgb(var(--tint-rgb) / 0.72). No type is set below the text floor.

• The One Field RuleEvery section is one of the three ink steps, told from its neighbor by how far it sits above or below the page. There are no light, white or gray surfaces. A panel that wants to stand out steps up to Night Watch; one that wants to recede drops to Midnight Hull.
• The One Action RuleDepth Cyan fills the single most important action in a view, the Charter Smarter booking link, and nothing else. The floating bar hides itself while the closing section's button is on screen, so two never share a viewport. The rule is about there being one action, not about its hue: the fill is --action.
• The Cyan Is Data RuleBeside that button, Depth Cyan is reserved for what carries a measurement: chart pins and routes, key numerals, gauge fills, an open day. Never a heading, a border or a flourish.
• The Lit and Unlit RuleA state that is off is drawn, not dimmed. A booked day sits on its own Night Watch panel and a turnaround day drops into a Midnight Hull well, each still numbered at the text floor.

Fields and contrast

One dark world in three steps. Depth comes from how far a surface sits above or below the page, never from a change of temperature.

There is no light section, and the site does not follow the device's light or dark setting (color-scheme: dark).

Measured contrast

Computed from the shipped token values by tools/build-docs.py, with a translucent ink composited over its field first and rounded down to one decimal, so 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.

Pairs that are never used

Recorded so that nobody reaches for them. Each has cost a bug before.

• The Photographic Field RuleA section that carries a photograph is washed with rgb(var(--ink-page-rgb) / α) so the image settles back into the night field: 0.88 on CAPTAIN360, 0.86 on rates. α is solved so cream type clears 4.5:1 over the photograph's brightest pixel. The tint's soft and mute steps never sit on the wash; they get a Night Watch panel. Re-measure when a photograph changes.
• The Calendar Legibility RuleEvery calendar day state clears 4.5:1, and state is never carried by color alone: each day has hidden text, and on-hold days keep their stripe.

Themes

Everything else in this guide is Night Watch, the theme a visitor arrives in. Ensign is the second: the same tokens, pinned again on red, white and two blues over navy.

A visitor chooses with the switch in the footer of every page, and the choice stays in their browser. A theme is one block of token values, [data-theme="ensign"], and nothing else: no rule asks which theme is on. On the root element it themes the page; on any other it themes what is inside it, as the plate below does. Ensign is still one dark world: its darkest color is the page field, so every section is one of three dark steps and every wash solved for light type keeps its shape. Values and ratios are filled from that block by tools/build-docs.py.

What a theme leaves alone, and what it solves again

Whatever is bound to an asset stays: Moonstruck Navy and the sea plate are matched to 26 satellite plates, so in Ensign a chart sits a step below the page where in Night Watch it sits above it, and Anchor Light stays in reserve. Whatever was solved against the field is solved again: in Ensign the photographic wash, --ink-page-rgb, is 9 16 27 rather than the page field, because with Ensign Navy in the wash the US Virgin Islands headline fell to 2.76:1 on a phone; and --wash-drawing comes down from 0.45 to 0.32, because the layout drawing's lines composite brighter on a lighter field. The token table lists every value Ensign pins.

• The Theme Is Tokens RuleA color theme is one block of token values, mirrored in both stylesheets, and nothing else. Whatever has to differ between themes becomes a token first: --action and --action-ink exist so that the booking action can take a color the data does not share. A new theme is measured like a new photograph, every line of type against the worst pixel behind it, before it ships.
• The One Action Rule, in any themeThe fill is Depth Cyan in Night Watch and Signal Red in Ensign, and in both it is the only thing that takes it.

Type system

Three faces, three jobs: an italic serif for what is said, a roman sans for what is read, and tracked monospace capitals for what is annotated or pressed.

Six files carry all of it, served from this site (assets/fonts/, each family's license beside it); CSS may ask for nothing else, because a weight with no file is drawn at the nearest one. The families are reached through --font-display, --font-body and --font-label, whose stacks lead with a metric-matched stand-in (Georgia at 85.2% for Playfair, Arial at 94.4% for Barlow, Courier New for Plex Mono), so the swap to the webfont moves no line break.

• The Three Voices RulePlayfair is italic, Barlow is roman, and IBM Plex Mono is small capitals. A roman Playfair heading, an italic Barlow paragraph or a lowercase mono label all read as mistakes. No uppercase eyebrow sits above a heading: the heading carries the section. Uppercase strings are written in sentence case in the source and transformed by CSS, so assistive technology reads words, not letters.
• The Figures Are Readings RuleAny number a guest acts on (a rate, a length, a year, a day count) is set in Playfair italic 900 with lining tabular figures. Numbers inside running prose stay in Barlow.

Type scale

Roles are tokens, named for the job and not the value. Every size below is set live from its token.

• The Optical Size RulePlayfair's x-height is 0.386em to Barlow's 0.460em, so the serif reads about a sixth smaller at the same pixel size. Serif running text is never set below Serif text (1.25rem), which is what sits level with 1.0625rem Barlow: Side by side: Barlow 17 · Playfair 20 · and Playfair 17, which is lost
• The Heading Leads RuleA heading takes its space from above, not below, so it binds to the block it introduces instead of floating between two. --head-lead (1.25em) sits over a heading that follows content in the same flow; --head-trail (0.4em) sits under every heading. Both are em, so a subhead leads by more than a title. The lead only matches a heading that follows a sibling, because one that opens a container already has the container's padding over it. A definition list is a heading and its paragraph too, so it cannot sit on a grid gap, which would put a term as far from its own explanation as from the next entry. The rule Clearing in The term hugs its own explanation and keeps its distance from the entry above. On a grid gap Clearing in One gap between every child, so the term floats and reads as the tail of what came before.
• The Dark Field RuleLight text on a dark field reads thinner than the same text on a light one. Body copy on the deepest fields steps up to Body on navy (1.125rem), and running text of 14px or smaller never drops below the tint's 0.66 step. Every body paragraph takes --leading-body; a list of one-line items may open to 1.8, where the leading is the space between items.
• The Plain Figures RuleFigures here are data. Playfair's default old-style 1 and 0 read as letters, so body sets lining-nums site-wide and anything columnar adds tabular-nums beside it. The property is not additive: a rule that sets tabular-nums alone turns the old-style figures back on. $4,100 lining$4,100 old-style, never

The mark

One mark, in two inks: its own colors on a light ground, and Instrument White on the site's dark fields, with its water in two bands: a light blue grey over the sea, which is Depth Cyan Muted in Night Watch and the hull's Moonstruck Navy in Ensign.

The file is assets/Moonstruck-Logo.svg. It follows the name as it is lettered on the hulls: MOON cut out of a moon disc, then STRUCK beside it in light Jost capitals, with the two O's drawn as a pair of wayfarer sunglasses seen straight on. The cut-out letters and the lenses are real holes, which is what lets the file work as a mask. The water under the disc is two bands, as on the hull: a light blue grey, then Moonstruck Navy. The disc's navy (#1f2b5b) and the band's blue grey (#9db2cc) belong to the asset and sit outside the token set.

On a dark field the same file becomes a mask over a fill: Instrument White down to the gap above the water, the tint at its text-soft step from there, and --mark-sea for the sea. There is one file to maintain, and every ink is a token. The sea has a token of its own because the field decides it: the hull's navy is too dark to show on Night Watch (1.20:1), so there it is Depth Cyan Muted, the sea on the app icon, and Ensign takes Moonstruck Navy. The first stop sits at 75% of the height, inside the gap; the second, at 86.2%, falls inside the water, which the mask draws solid. It is not a CSS filter chain: iOS Safari does not clamp after every step, and drew the mark cyan.

background: linear-gradient(var(--cream-bright) 75%, var(--text-soft) 75% 86.2%, var(--mark-sea) 86.2%);   /* the water is below 75%, the sea below 86.2% */
mask: url("Moonstruck-Logo.svg") center / contain no-repeat;   /* with the -webkit- twin */
object-position: -999px 0;   /* the img's own pixels, out of the box */

Beside it

The favicon (assets/icon.svg) sets the mark in Lamp Cream on a rounded field of Deep Water, the --ink-page that the pages' theme-color and the web manifest carry. tools/build-icons.py rasterizes that drawing into the rest: a 32px PNG, a 180px touch icon, the manifest's 192 and 512, a maskable 512 drawn smaller to sit inside Android's safe circle, and a flat black mask-icon.svg for a pinned Safari tab. Paradise Yacht Management's mark sits beside Moonstruck's in the footer at the same 46px; the Charter Smarter mark appears once, on the homepage's booking card, where it says where the booking button leads.

Grid and measure

A nine-column page grid: 1040px at most, a 32px gutter, and everything else derived from those two numbers.

Nine is chosen for the editorial 3 + 6 and 4 + 5 splits it allows; it is not a twelve-column utility grid. The grid governs page-level placement only: components subdivide freely inside their span, because the page's natural groupings (two destinations, seven days) do not divide by nine.

One column is 87px. The widths above are worked out from the tokens by tools/build-docs.py.

Margins and rhythm

Vertical rhythm goes lower on a phone, not higher.

Breakpoints

• The Column Span RuleA new container takes a span token, never a hand-picked pixel width. If a block needs a width the scale does not offer, the scale is wrong: fix the tokens, not the block.
• The One Margin RuleThe horizontal page margin comes from --section-x and nothing else. A full-bleed escape is written calc(-1 * var(--section-x)), so it tracks the margin.
• The Shrinkable Track RuleA single-column grid is written minmax(0, 1fr), never a bare 1fr, which cannot shrink below its content. With a pannable chart inside, a bare track once ran a 390px phone page to 734px. When checking a phone layout, confirm that innerWidth equals the width you asked for.

Layouts

The compositions the pages are built from, drawn on the nine columns. Every split sums to nine, so edges land on the same column lines from section to section.

Blue blocks are photographs, navy blocks are charts, dark blocks are type, outlined blocks are panels. Below 1152px these go fluid, and at 768px each is a single column in source order, which is also the order a screen reader gets.

Buttons and controls

Square, tracked and quiet. Small, widely tracked uppercase labels with generous padding and a color swap on hover.

Every button is a link: the site has no form, so each action leaves for a call, an email or the Charter Smarter booking form, and an external one says so in its accessible name (“Book with Charter Smarter (opens in a new tab)”). These are the real .btn classes; the homepage draws the same buttons with inline styles.

On Deep Water: .btn-primary, .btn-dark, and the focus ring in Depth Cyan

On Moonstruck Navy: the closing section's actions. .btn-primary, .btn-ghost, and the ring in Instrument White

The floating action bar, over photography. Dark is 92% so it holds on any frame

On hover the primary keeps its color and lights a 2px Lamp Cream bezel; Dark swaps to an Instrument White fill over 0.25s; the ghost firms its outline and takes a 10% wash. In the closing section the three actions share a 236px minimum width, so none reads as the runt.

Icon controls

Round is reserved for controls that are only an icon. Anything on imagery carries the Control shadow.

Carousel arrow 52px · lightbox arrow 56px · close 48px · counter chip · chart pin 24px · a 24px mark inside its 44px hit area

The divider knob (40px) and the map opener (34px) share the vocabulary; both are live on the inset under Components.

• The Hit Area RuleA small target keeps its drawn size and grows an invisible 44px hit area from an ::after with a negative inset: the destination cards' text links, the footer's 24px social marks and its email address. Chart pins stay at their drawn size, because each has a full-height row in the key that does the same job, and padded pins on a crowded chart would steal each other's taps.
• Promise only what worksNo role="button" with a guarded handler, and no “Tap” hint under a mouse. The plate zoom is available at every width, never enlarges past the source's own pixels, and words its hint for the pointer in use.

Components

Sections sit flat. Only what floats over content gets a shadow, and only contained cards get a radius.

Corners: none on buttons and section edges; 2px on mats, frames and the CAPTAIN360 cards; 14 to 16px on the destination and booking cards; fully round for icon-only controls and portraits.

The polaroid mat, carrying a chart inset

The boat section's mat: Night Watch wrapping the plate on three sides and deepening into a lip that carries the caption, so the caption belongs to the picture. Photographs sit square, never tilted. On the destination pages it carries a chart inset, which a photograph can replace without changing the page. This one is lifted from usvi.html and is live: drag the divider, or focus it and use the arrow keys.

5

1 nm

Badge

A short Standout label on a square Midnight Hull plate: one vocabulary for the hero's line, the “Most popular” tag and the photo band's caption. Never a pill.

Navigation

Uppercase IBM Plex Mono at 13px, tracked. The link for where you are carries a 1px hairline 8px below the label, drawn as a pseudo-element so that it stops at the last letter; text-decoration would run on under the trailing tracking. On the homepage it follows a reading line two fifths of the way down the viewport and draws in over 0.35s; inner pages mark Destinations, their parent.

Planning pictograms

The thirteen pictograms that printed charter itineraries use, lifted as vector paths into assets/icons/tags.svg. They fill with currentColor: the tint at 0.66 on a panel, Depth Cyan on a chart field. In a log they stand alone at 24px, named by their title and an accessible label; only the legend shows names. They are the only icon set on the site besides the button glyphs.

• Beach chairs
• Beach time
• Dive / SCUBA
• Dock available
• Hiking
• Island tour
• Jumping
• Lobster specialty
• Notable bar
• Paddleboarding
• Secluded
• Snorkeling
• Swimming

Gauges

“How the week leans”: relative emphasis from a charter's planning sheet, on a scale ruled in quarters. These are the seven-night passage's. Each fill runs once, from the left, when the block enters view.

• Snorkeling
• Beach time
• Sailing time

Calendar days

The availability grid's seven states, with the fills and inks the homepage's stylesheet gives data-cal-day. An open day that touches a booking or a hold is a turnaround day: computed, never entered, and drawn exactly as unavailable. A day a charter can start on (five nights open from it) is a button, and every other day is a plain cell. Pointing at or focusing one previews its stay of up to seven nights; choosing it lights the stay and fills the readout under the grid with the dates, the nights and one action, an email with the dates in its subject. No price is shown there: what a week costs is the rate table's to say.

The months drawn run only as far as the blocks are maintained. A date with no block reads as open, so an unmaintained month would advertise weeks nobody has checked.

Charts

The inner pages draw real nautical charts; they do not decorate with them. One asset carries the geography, and every chart on the site is a viewBox crop of that one drawing.

This is the seven-night plan chart and the first two entries of its log, lifted from itineraries.html. Point at an entry, or tab to a pin, and its leg lights while the others fall to 28%. The satellite view is the same window, in register; the passage stays plotted on both.

1Norman Island2The Baths3North Sound4Anegada5Cane Garden Bay6Jost Van Dyke7Cruz Bay8Charlotte Amalie

Numbered by legNot for navigation

Drag the chart to pan

1. 1Day 1
   Saturday

   Charlotte Amalie to Norman Island

   1 h under sail

   Welcome to the Virgin Islands. After everyone is aboard, we hold a short safety briefing and set sail for Norman Island: snorkeling at the Caves, then an evening at the Willy T, the floating bar in the Bight.
2. 2Day 2
   Sunday

   Norman Island to The Baths, Virgin Gorda

   3 h under sail

   We head for the Baths for light swimming and a hike through the granite boulders, then on to Spanish Town for dinner ashore at CocoMaya.

Anatomy

x = (lon + 65.12) × 1000        y = (18.80 − lat) × 1054.35        1 nautical mile = 17.57 units

The divider

A role="slider" whose value text names the share of satellite. Only the knob and the line take a drag, never the whole plate, because on a phone the chart already pans sideways and the page has to scroll past it. Where it rests and how high the knob rides are chosen by hand per chart, to clear its pins and labels.

• The Chart Truth RuleChart geometry is data, never drawn by eye: coastlines come from the asset, positions from coordinates, the scale bar from the projection. A pin is where the boat lies (the mooring field, not the beach or the town), and the generator's check_afloat() names any pin or track that touches land. A satellite plate is emitted only at the chart's exact viewBox, so imagery is never shown out of register.

Overlays and dialogs

Four overlays, one behavior. Each is a real dialog, and each gives the keyboard back exactly where it took it.

All four share this contract: role="dialog" and aria-modal; the element that had focus is remembered; the page stops scrolling behind; Tab wraps inside; Escape closes; focus returns to where it came from. A closed overlay is visibility: hidden as well as transparent, because pointer-events: none alone leaves its links in the tab order.

The implementations are openOverlay(), closeOverlay() and onOverlayKeys() on the homepage, and toggleMenu(), onMenuKeys(), openMap() and mapKeys() in pages.js; see the JavaScript reference.

Motion

Slow and calm. Things arrive once, over most of a second, on one soft curve, and then stay put.

--ease-reveal: cubic-bezier(0.22, 0.61, 0.36, 1)

Every animation has its counterpart in the prefers-reduced-motion block at the foot of each stylesheet, and a new one needs a line there. Adding ?static to an inner page's URL resolves every entrance at once, for screenshots and print.

CSS tokens

Every custom property on :root, with its value read from the source.

The set is written twice: at the top of assets/home.css, which tools/minify.py inlines into index.html, and at the top of assets/pages.css. The two must agree, and tools/build-docs.py reports any that do not. Descriptions come from the @token tags in pages.css.

Component properties

A few custom properties are scoped to a component. They carry a measurement from the generator or from script, never a design decision.

Code reference

The source comments are the documentation. The reference pages are generated from them.

After changing a doc comment, a token or this page, run the build and commit what it writes. tools/build-docs.py alone rewrites just docs/ and this page.

python3 tools/build.py            # the whole build, in the order that works
python3 tools/build.py --check    # writes nothing; exits 1 if anything is out of date