Design Compass

A visual style compass: search a library of design systems, see each one rendered rather than described, compare them side by side, pick one per project, and export the spec.

No login, no database, no network — the library is static data compiled into the bundle, so it works on a plane.

npm install
npm run dev      # http://localhost:3000

What it does

Search that understands more than substrings. Free text is matched across name, aliases, moods, use cases, signature moves, typefaces and prose, each field weighted, and a one-character typo still finds the style. A small query language sits on top:

Query	Means
calm dashboard	both words must match somewhere (AND)
"quiet luxury"	matched as a phrase
-neon	drop anything matching neon
family:retro	field-scoped: family, for, mood, era, a11y, font, name
fintech	synonyms map onto vocabulary the library actually uses

If strict AND finds nothing, the search widens to OR and says so. If a word matches no style anywhere, it names the word rather than showing an empty screen.

Filters that are honest about counts. Family, what you are building, accessibility level, mood, and a bucketed range on each of the six axes. Every facet count is computed against all filters except itself, so a checkbox never says zero for an option that would widen the results.

Typography as a scale. Every preview shows H1, H2, H3 and body together, because the interval between levels is what actually separates two typographic systems — Data Dense and Luxury Minimal can share a typeface and look nothing alike. The ratio is derived from the density axis rather than authored, and everything that reports it says so.

Visual identification. Every card renders the same miniature interface — nav bar, headline, body copy, primary and ghost buttons, stat panels, palette strip — from that style's own tokens. Fixed sample copy, on purpose: if the words changed per style you would be comparing the writing.

Comparison. Up to four styles line up in columns with the identical preview in each, then a table of era, use cases, typefaces, accent, radius, border, spacing, measured body contrast, and all six axis positions. Exportable as a Markdown table.

Exploration. The compass view plots every style on two axes you choose, each dot filled with its own accent color. Hovering a name in the legend lights up its dot. Every style also carries declared neighbors, and nearest() falls back to axis distance.

Projects. A named project holds a brief, a shortlist, one pick and notes, and lives in browser storage. Export brief produces a Markdown document: the decision, what it beat, the reasoning, and the full build spec for the chosen style.

Color combinations. A fourth view builds a complete, role-assigned palette from one brand color and a harmony scheme, then checks it against the rules that matter. It is not a swatch generator: it corrects as it goes. Any tool can rotate a hue 180 degrees; the work is knowing the complement it just produced cannot hold white text, and moving it until it can.

• OKLCH, not HSL. HSL claims yellow at 50% lightness and blue at 50% lightness are equally bright, which is why HSL ramps blow out in the yellows and go dead in the blues. Out-of-gamut colors have their chroma reduced rather than their channels clipped, so an orange ramp stays orange at the dark end instead of turning red.
• Sixteen roles, not five swatches. Page, surface, alt surface, control border, decorative divider, body text, muted text, accent, on-accent, soft accent, text-safe accent, both halves of the focus ring, and three status colors — each with a line about what it is for.
• The scheme produces a categorical set. Harmony schemes exist to generate the secondaries a system uses for chart series, category tags and illustration — so the control produces exactly that, shown on a color wheel, applied to chips and bars, and written into every export as --series-N with a readable label color for each. Secondaries are staggered in lightness as well as hue, because that is what makes a categorical set survive color-vision deficiency.
• Edit any role by hand. Click a swatch for Lightness / Intensity / Hue sliders whose tracks are painted with the colors they produce. Edits cascade — change the accent and its label, soft tint, text-safe variant and ramp all follow — and a hand-set color is left exactly where you put it, with the review reporting the cost rather than the tool quietly correcting it. Sliders are OKLCH, not HSL, for the same reason the ramps are.
• Twelve rules, all computed. Nothing is asserted: every verdict is arithmetic on the emitted colors, and each one explains why it exists. See below.
• Named shades. 98 industry-standard shades across nine hue families — sage, cinnabar, umber, chartreuse — each with what it does on a screen, what it pairs with, and a per-family guide covering what the hue signals and the specific way it goes wrong. Click any shade to rebuild the palette around it.
• Judged in a real layout. The palette is rendered into any of the 73 library styles, keeping that style's shape, spacing and typography. You see the colors in Swiss discipline and in Neo-Brutalism before committing, rather than as a row of squares.
• Seen with color deficiency. Accent, success, warning and error simulated under protanopia, deuteranopia and tritanopia. If two bands merge, those two states must never be told apart by color alone.

Exports. Four formats per style — a one-page Markdown summary, W3C-shaped token JSON, CSS custom properties, and a Tailwind v4 @theme block — all generated from the same token object the preview renders, so a downloaded file is never a prettier description of something else.

The rules, and why they are what they are

Two of them were calibrated by measurement rather than taste, and both changed as a result.

Status colors under red-green deficiency. The first threshold flagged every palette the tool produced. Measuring the shipping status pairs from Material, Tailwind, GOV.UK, Bootstrap, IBM Carbon and Ant Design put all six between 0.02 and 0.06 on the same scale — that is, no red-green pair separates by hue for a deuteranope, and a stricter threshold would only have been calling every design system in the industry wrong. So the rule was rewritten around what is actually achievable: separate the two by lightness, and treat the second channel — an icon, a word, a shape — as mandatory rather than a nicety.

The focus ring. The rule warned on every palette, because a ring drawn in the accent color has no contrast against an accent-colored button. That is not a palette defect, it is why the two-tone ring exists. The generator now emits both halves — an outer color sized against the page, an inner one sized against whatever it surrounds — and the rule checks the pattern that is actually shipped.

The rest: body and muted text contrast, button labels on the accent, a text-safe accent variant, control borders at 3:1 (dividers deliberately exempt — forcing 3:1 on a hairline makes every card look boxed in), status separation in greyscale, brand-versus- error hue collision, tinted neutrals, no pure black on pure white, and a cap on how many hues one team can actually govern.

A red brand fails the collision rule, and should. If the brand color is the error color, users cannot tell the primary action from the failure message. The generator moves the error color apart in lightness and says so; the finding stays.

Structure patterns

A separate section from style and color, because they are separate decisions: 38 navigation, layout, hero, content and footer patterns, each with a wireframe rather than a description. Every one answers the question nobody asks in time — how much does it hold before it breaks — and states what you are also signing up to build if you pick it (a hamburger means aria-expanded, focus management and Escape; a mega menu means click-to-open and a way out of eighty links).

Wireframes render in any of the 73 library styles, so a navigation choice can be judged in the visual language it will actually ship in. Choices are recorded per project and reach the exported brief with their obligations attached.

The wireframes are data, not markup, which means they are checked like data: every block must sit inside the canvas, use more than one kind, and cover enough of it to read as a layout. That check caught six patterns whose blocks ran off the right edge because a horizontal helper was used where a vertical stack was meant.

Auditing the controls

npm run audit:controls drives every interactive control in the running app and reports any that produce no change in the rendered DOM.

It exists because four controls shipped doing nothing visible: the Color tab's search box and its example chips (they filter the style library, which is not on that screen), a results bar carrying a hidden attribute that a class with display: flex silently overrode, and the Scheme dropdown, which changed zero roles and zero ramps. Every one was found by a person clicking it and asking what it did — never by a test.

It needs a running server and Playwright, so it is a pre-release check rather than a CI step. It hashes outerHTML; an earlier version compared lengths and reported four false positives, because swapping one hex fill for another leaves the length identical.

Layout

Path	What it is
lib/types.ts	Axes, families, use cases, and the token contract every style fills in
lib/styles.ts	The library — 73 styles
lib/search.ts	Query parsing, weighted scoring, synonyms, filters, similarity
lib/export.ts	The four export formats, plus comparison and project briefs
lib/typography.ts	The derived type scale
lib/patterns.ts	38 structure patterns and their wireframes
lib/color.ts	WCAG contrast, OKLCH conversion, color-vision simulation
lib/shades.ts	98 named shades and the nine hue guides
lib/palette.ts	Schemes, role assignment with contrast correction, the rules engine
app/	The page, the scoped stylesheet, and the seventeen typefaces the previews need
components/	The UI
scripts/audit-controls.mjs	Drives every control and reports the dead ones
scripts/test.ts	The checks below. Runs in npm test, which runs in prebuild — a failing invariant fails the deploy

Adding a style

Append an entry to STYLES in lib/styles.ts and run npx tsx scripts/tests/design-compass.ts. The suite will stop you if:

• an id is duplicated, or a neighbors entry names a style that does not exist;
• a palette entry or token is not a 6-digit hex, or an axis is outside 0-100;
• body text fails 4.5:1 on its own surface, muted text fails 3:1, or a button label fails 3:1 on the accent — the previews are the product's central claim, and an unreadable style in the library is a lie the tool tells its user;
• the style is thin: fewer than four moods, three aliases, two avoidWhen entries or four signature moves;
• a font stack names a --dc-* variable that app/layout.tsx never binds, which would silently render the style in a fallback serif and make it look like every other style that failed the same way.

bg is deliberately exempt from the contrast floor: it is a backdrop, not a text surface. Skeuomorphic's dark felt page under light steel panels is the case that proves it.

Adding a named shade

Append to SHADES in lib/shades.ts. Every pairs entry must name another shade in the library, the note has to say something specific enough to argue with, and every hue family needs a guide with at least three tips and a trap.

What the color tests actually run

The generator is swept across all 98 shades in both modes — 196 palettes, every role checked for contrast on every one. Two bugs were caught that way and are now regression guards:

• An achromatic brand color reports hue 0, which is 27 degrees from the error hue and not a collision at all. Reporting one shoved the error color into the success color.
• Moving the error color away from a dark red accent moved it straight into the success color, because the naive fix optimized one constraint and ignored the other.

Both were found by the sweep, not by looking at screenshots. The suite also mutation- tests cleanly: reverting either fix, or clipping instead of gamut-fitting in OKLCH, fails with a message naming the specific palette and the specific number.

Where this came from

Generated from the sources in the RoboTrig repo by scripts/extract-design-compass.sh. Edit it there and re-run the script, or adopt this copy as the origin and delete the route from that repo — but do not maintain both.