Style guide

Palette

Three pinned colors and one amber. Every other color is a lightness step inside one of the three families, computed to hit a contrast target, not picked by eye.

The palette is entirely cool on purpose. Anchor Light is the only warm thing on the page, which is what gives it its force. A new color means a new step in an existing family, or a new pin, and a new pin is a decision for the client.

Field

Structure

Water

Light

The one amber

What each color is for

Translucent steps are written from the channel tokens, for example rgb(var(--tint-rgb) / 0.72). Instrument White runs from 0.12 (borders) to 0.95 (halos); Midnight Hull from 0.72 to 0.96 for overlays. Functional labels never drop below 0.72.

• The Three Pins RuleThe palette derives from #061e45, #eef3ff and #eef3ff, plus Anchor Light. Reference colors through the tokens, never as raw hex.
• The One Amber RuleAmber marks the single most important action in a view, the Charter Smarter booking link. Never decoration, text or tags, and never two competing in one viewport: the floating bar hides itself while the closing section's amber button is on screen.

Two worlds and contrast

Every section is either ink with Instrument White ink, or Deep Water with ink and charcoal ink. There is no white section and no gray one.

The site has one color scheme and does not change with the device's light or dark setting (color-scheme: light). The two worlds do the work a theme would: ink for atmosphere (stats, destinations, the sailing school, booking), panel for detail and decisions (gallery, layout, CAPTAIN360, rates, availability).

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 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.

Pairs that are never used

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

• The Two Worlds RuleEvery section is ink or light. Deep Water is the one approved light surface; Instrument White stays available as a panel fill that reads as a panel.
• The Photographic Field RuleA light section that carries a photograph (CAPTAIN360, rates) is still a Deep Water section. It is washed with rgb(var(--ink-page-rgb) / α), and α is solved so Instrument White clears 4.5:1 over the photograph's darkest pixel: 0.74 on CAPTAIN360, 0.64 on rates. the tint at 0.78, the tint at 0.66 and the tint at 0.66 never sit on the wash; they get a Deep Water 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 a theme with the switch in the footer of every page, and the choice stays in their browser. A color theme is one block of token values, [data-theme="ensign"], and nothing else: no rule asks which theme is on. On the root element the attribute themes the page. On any other element it themes what is inside it, which is how the plate below is drawn in Ensign on a Night Watch page. The values and ratios in it are filled from Ensign's block by tools/build-docs.py, the way the rest of the guide is filled from :root.

Ensign is a second theme of the same world, not a light build. The darkest of its five colors is the page field, so every section is still one of three dark steps, and every wash that was solved for light type on a dark field keeps its shape. A third theme, Reader, has no colors to show here: it takes the design off and hands the page to the browser's own stylesheet, on the system canvas.

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. The layout drawing keeps the ink it was repainted in, and Anchor Light stays in reserve.

Whatever was solved against the field is solved again. In Ensign the wash over a photograph, --ink-page-rgb, is 9 16 27 and not the page field as channels: with Ensign Navy in the wash, the US Virgin Islands headline fell to 2.76:1 on a phone, where the type crosses the brightest sky. The layout drawing's wash, --wash-drawing, comes down from 0.45 to 0.32, because its lines composite brighter on a lighter field. The token table lists every value Ensign pins beside Night Watch's.

• 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 the way a new photograph is, every line of type against the worst pixel behind it, before it ships.
• The One Action Rule, in any themeThe rule is about there being one filled action in a view, not about its hue. It is Depth Cyan in Night Watch and Signal Red in Ensign, and in both it is the only thing that takes the fill.

Type system

A classical, high-contrast serif for voice, and one geometric sans in two voices: used light for everything you read or count, and tracked out in capitals like the lettering on an instrument panel.

That is everything the font request carries, and CSS may ask for nothing else: a weight the request does not carry is silently drawn at the nearest one, so the source would describe a page that does not exist. The families are reached through --font-display, --font-body and --font-label (both sans tokens are Barlow; they stay separate so either voice can change face alone), whose stacks lead with a metric-matched stand-in (Georgia at 88.4% for Playfair, Arial at 92.8% for Barlow) so the swap to the webfont moves no line break.

• The Logbook Voice RuleSerif for things you would say; tracked uppercase Barlow for things you would annotate or press; light Barlow, in sentence case, for everything you would read or count. Never a label in Playfair, never a paragraph in tracked capitals, never a headline in Barlow. Facts follow the reading voice: an inclusion, a discount, “per person, for the week” are light Barlow, even inside a card whose name is serif.
• The One Weight Per Voice RuleThe serif is 400, the label voice is Barlow 400 and body is Barlow 300, on every page. The inner pages set body to Barlow 300, so their labels and serif fragments are named in two grouped rules beside .lede in pages.css; the label group is also where a label takes --font-label. A new class joins the matching group.
• The Light Hand RuleBold is not part of the system. 500 is the ceiling, and only for short uppercase labels that must hold up over photography.
• The Heading Carries the Section RuleNo uppercase eyebrow sits above a heading. Uppercase strings are written in sentence case in the source and transformed by CSS, so assistive technology reads words, not letters.

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 (20px), which is what sits level with 17px 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 without a second pair of values. The lead is written with :where() and only matches a heading that follows a sibling, because a heading that opens a container already has the container's padding over it. A definition list is a heading and its paragraph too, and so cannot be laid out on a grid gap: a gap falls between every child, 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 ink reads smaller and thinner than the same text on Deep Water. Body copy there steps up to Body on ink (18px), and running text of 14px or smaller is never lighter than 400, which is why the footer sets 400 where the page sets 300. The 46px stats numerals keep 300: at that size the hairline is the point. 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 over light grounds, and Instrument White on ink, with its water kept 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's lettered on the hulls: MOON cut out of a moon disc, then STRUCK beside it in light Jost capitals. The two O's are a pair of wayfarer sunglasses seen straight on: a brow that rises to the end piece at each side, two lenses that narrow toward the bottom, and a keyhole bridge between them. The cut-out letters and the sunglasses 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; the sea is Moonstruck Navy itself. On ink the same file becomes a mask over a fill that is Instrument White down to the gap above the water, the tint at its text-soft step from there, and --mark-sea for the sea, so there is one file to maintain and every ink is a token. The sea is a token of its own because the field decides it: Night Watch is too dark to show the hull's navy (1.20:1), so there it is Depth Cyan Muted, the sea on the app icon, and Ensign takes Moonstruck Navy. The first stop is at 75% of the height and holds while the img keeps the file's proportions (a set height, width auto); the second, at 86.2%, falls inside the water, which the mask draws solid. It is not tinted with a CSS filter chain: a chain lands on its color only in browsers that clamp after every step, and iOS Safari does not (it 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 on a rounded field of Moonstruck Navy, the same --chart-navy that the pages' theme-color and the web manifest carry. Every other icon is that same drawing, rasterized by tools/build-icons.py: a 32px PNG for browsers that will not read an SVG, a 180px touch icon and the manifest's 192 and 512, all square to the edge because the platform cuts its own corners and composites what is outside them onto black, 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 amber 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 deliberately 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 (four stats, 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, ink blocks are charts, gray blocks are type, outlined blocks are Deep Water panels. Below 1152px these go fluid, and at 768px every one of them 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: each action leaves for a phone 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 from pages.css; the homepage draws the same buttons with inline styles.

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

On ink: the closing section's actions. .btn-sky, .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 every filled button swaps to a Instrument White fill with Midnight Hull ink over 0.25s; the ghost firms its outline and takes a 10% fill. 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) are in the same vocabulary; both are live on the inset under Components. The first three specimens above are restated from the homepage's inline styles in assets/style-guide.css.

• 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 thing, 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 and frames; 14 to 16px on contained panels such as the CAPTAIN360 cards; fully round for icon-only controls and portraits.

The polaroid mat, carrying a chart inset

The boat section's panel 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 the same mat carries a chart inset, which can be swapped for a photograph without changing the page. This one is lifted from usvi.html and is fully 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 amber, never a pill.

Navigation

Uppercase Barlow at 13px with 2px tracking. 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 panel, Depth Cyan on ink. In a log they stand alone at 24px, each named by its title and an accessible label; only the legend gives them visible names. They are the only icon set on the site besides the stroke glyphs in the buttons.

• 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 six 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: it is computed, never entered, and draws exactly as unavailable. Pointing at an open window above the grid inks its days.

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 the divider rests and how high the knob rides are chosen by hand per chart to clear its pins and labels, the same license a label's side has.

• 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: in the <style> block of 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 builder and commit what it writes:

python3 tools/build-docs.py            # writes docs/ and updates this page
python3 tools/build-docs.py --check    # writes nothing; exits 1 if anything is out of date