@the-efficacious/brand

The Efficacious brand system as code — design tokens, theme CSS, a shared UnoCSS preset, and the logo artwork. One source, published once, consumed by every surface across CommandSuite, TurnDB, and Efficacious itself.

pnpm add @the-efficacious/brand

import '@the-efficacious/brand/fonts.css';
import '@the-efficacious/brand/tokens.css';

.panel {
  background: var(--ef-surface-raised);
  border: 1px solid var(--ef-border);
  border-radius: var(--ef-radius-cap-tl);
  color: var(--ef-text);
}

Why this package exists

The theme started as one stylesheet and ended up copied into four checkouts. Each copy drifted. None of the drift was noticed, because every copy still worked — a fork of a stylesheet doesn't throw. By the time it was measured:

• theme.css existed in four places, at two different lengths
• one copy had been hand-patched on two lines to force a dark surface, because the file hard-coded hexes that a token override couldn't reach
• three tokens (--bg-alt, --link, --line) were referenced at 14 call sites and defined nowhere — border-left: 2px solid var(--line) was a dropped declaration in production
• two hosts compiled the same components against different breakpoint scales, putting a nav in-flow and translated offscreen between 768–899px
• a shared component returned utility class names that only one host's build config could emit, so sender colours silently vanished in the other

Every one of those is the same failure: design decisions living in places that can be copied. This package makes there be one place.

The two-layer model

primitives          semantic              product
──────────          ────────              ───────
--ef-n800     ←──   --ef-surface-raised ←──  .panel
--ef-gold-base ←──  --ef-assert         ←──  .meter--assert

Primitives are named for what a value is (--ef-n800, --ef-gold-base). They are the raw palette. Product code must never reference them.

Semantic tokens are named for the role they play (--ef-surface-raised, --ef-lamp-alarm, --ef-assert). This is the only layer you use.

A theme is a different resolution of the same role set. Components that touch only roles survive a reskin untouched — that is the entire contract, and it is what makes a rebrand a change to one file instead of 54 components.

The indirection is preserved in the emitted CSS, so you can read which primitive a role points at:

:root, :root[data-ef-theme="helm"] {
  --ef-surface-raised: var(--ef-n800);
  --ef-assert: var(--ef-gold-base);
}

Why the neutral ramp spans black to warm white

--ef-n1000 through --ef-n0 is one continuous warm-neutral scale covering both ends, not a "dark palette". A dark-only ramp would bake the current theme's polarity into the primitives and make a light surface a second, forked palette later. The brand guide already calls for both — a dark Brand Surface for heroes and release moments, a light Work Surface for prose — so the ramp has to carry both from the start.

Themes

helm — the CommandSuite product theme

A console for long watches. The virtues of a starship bridge — every system stated, colour that means status, controls sized for certainty, language that stays composed under alarm — with none of the chrome, glow, or theatrics. The room is dark because the work is calm.

Ships on :root and on [data-ef-theme="helm"]. Both selectors are emitted so a consumer that sets no attribute still gets a complete, correct surface.

Additional themes attach to [data-ef-theme="<name>"]. Only helm ships today because only helm has been calibrated against a mock — a light theme would mean inventing values, and inventing values is what this package exists to prevent.

The rules the system enforces

These aren't style preferences. They come out of the brand guide and the Helm spike, and pnpm check mechanically enforces the ones that can be checked.

Gold is a reserve, not a palette entry

| Tier | Token | Where | |---|---|---| | 0 | --ef-mark | Logo artwork only. Never interface chrome. | | 1 | --ef-assert | Verified results, published proofs, the single highest CTA on a page. | | 2 | (ink) | Ordinary interface work — default buttons, active states. Hover darkens or inverts; it never becomes gold. | | 3 | (greys) | Borders, rules, secondary text. Everything that organises without asserting. |

The budget is one gold assertion per view. A composite treatment counts once — a verified card may carry a gold border, value, and badge together. Two competing assertions mean one of them has not earned it.

Five lamps, five meanings, no exceptions

| Token | Meaning | Motion | |---|---|---| | --ef-lamp-nominal | System healthy | static | | --ef-lamp-working | In progress | pulse 1.6s | | --ef-lamp-caution | Attention warranted, work continues | static | | --ef-lamp-alarm | Work stopped or degraded | pulse 0.9s | | --ef-lamp-stood-down | Deliberately off | static |

These colours mean only these states and appear nowhere else. Grey is a state too: stood down is not an error.

There is no red in this system. Alarm is deep ember. The palette carries --ef-red500 from the brand guide so a light theme has it available, but no Helm role maps to it. The pulse rates are the severity signal, so both are tokens rather than literals — and both respect prefers-reduced-motion, since a lamp that cannot pulse still states its colour.

The chamfer rotates

12px is not a corner radius. It is a single chamfered corner, rotated between neighbouring panels so a grid doesn't read uniform:

--ef-radius-cap-tl: 12px 3px 3px 3px;   /* 29 uses in the mock */
--ef-radius-cap-tr: 3px 12px 3px 3px;   /* 18 */
--ef-radius-cap-br: 3px 3px 12px 3px;   /* 6  */
--ef-radius-cap-bl: 3px 3px 3px 12px;   /* 2  */

Flattening this to a scalar --radius-lg deletes the device entirely. It is the clearest example of why the vocabulary was derived from the target rather than mapped onto the incumbent theme's --r-xs/sm/md.

Control grammar

Parchment commits · outline proposes · bare text defers · ember stops. Hover brightens; nothing ever glows.

Links hover into gold

Body links are warm white on a muted underline (3px offset). On hover, text and underline take gold — the same transient-under-attention category as the scrollbar's drag-gold, spending no per-view budget. --ef-link / --ef-link-underline / --ef-link-hover.

Focus is a border, not a ring

FOCUS — BORDER → #F4F1E9 · NO GLOW. Change border-color to --ef-field-border-focus; do not add an outline or a shadow. Glow is on the refused list, and a focus treatment is the easiest place to smuggle one in.

Identity: shape carries class

A person's tile is lighter than an agent's. The glyph is two initials in Rajdhani 700 at 40% of the tile, in --ef-identity-glyph — never gold, and never a hue hashed per username, because "the moment colour is decoration, an amber dot stops meaning amber."

Presence reuses the lamp grammar rather than adding a second colour system: working → working, on watch → nominal, idle → stood down, fault → alarm. Only off-watch has its own treatment — a hollow ring, because a blank corner is indistinguishable from a component that failed to render.

Note a deliberate departure: the mock renders agent names in gold. That is not carried here. It was a styling artefact rather than brand intent, and an unbounded gold would break the Tier 1 budget on any transcript with more than one agent in it. Agent names take primary text.

Iconography: Lucide, following the text

Lucide is the brand's icon system — sourced from the mock itself, whose inline icons are Lucide paths (send, check-check) at the library's native 24-unit viewBox. The library is not bundled, by the same policy as typefaces: the brand names the system and the spec; consumers install the binding for their framework (lucide-preact, lucide-react, @lucide/astro, lucide-static) and keep majors aligned.

The spec, exported as iconography and as tokens: stroke 2 (2.4 below ~12px render size), currentColor always — an icon never picks its own colour, it follows its container's text role, which keeps icons inside the lamp grammar and the gold budget automatically. Sizes: --ef-icon-inline (15px), --ef-icon-badge (11px).

The scrollbar is a readout

Always visible when content overflows — position is status, and status is never hidden. 12px rail, 6px hair, 44px minimum thumb so it is always catchable. The thumb takes --ef-scroll-thumb-drag — the one gold — only while being dragged. That is the single transient use of Tier 1 in the system, and it spends no per-view budget because it exists only under the hand.

A panel owes the watch one of four answers

Here is the data · it is coming and here is how far along · there is nothing and here is why · it broke and here is what broke. Waiting is measured, emptiness is explained, failure keeps your work, and every dead end offers one exit. Nothing waits in silence.

Type

Rajdhani (display, controls, logotype) · Outfit (body) · JetBrains Mono (labels, data, code, and every uppercase setting).

Rajdhani is always mixed case — logotype, headline, and label alike. Uppercase collapses EFFI into four vertical stems and flattens Rajdhani's C/O/U into matching rectangles; mixed case also preserves the internal capital that makes CommandSuite and TurnDB compound names rather than shouted ones. Caps are the monospace's job.

Below 15px the lowercase apertures close — use the mark alone.

Tracked strings are not centred. Letter-spacing is applied after every character including the last, so a centred tracked string carries a phantom trailing space and lands half the tracking left of its axis. Cancel it with a negative right margin — every --ef-track-* has a matching --ef-track-fix-*:

letter-spacing: var(--ef-track-tag);
margin-right: var(--ef-track-fix-tag);

Refused

Glow · scanlines · chrome bevels · decorative colour · invented numerals.

The exact page — the reference of record

bench/exact/helm.html is the canonical mock itself: its fully-rendered DOM (3,591 elements, captured from the live page — every binding expanded) with every literal style value mechanically substituted for a token. No reconstruction, no interpretation, no shortcuts — exactly what is there, expressed through @the-efficacious/brand.

It is generated by pnpm build from reference/capture/ and it is not allowlisted in the guardrails: pnpm check scans it like any product file. That makes it the completeness proof — a passing check means every value the mock paints is expressible in the token vocabulary. Substitution currently maps all values with zero left over.

It is static (interactive demos don't respond) and it is not a component library — its DOM is the mock's inline-styled markup. For fidelity questions ("is this exactly the design?"), this page is the answer. Recapture after a mock update: pnpm bench, open the reference page, paste scripts/capture-exact.browser.js in the console, pnpm build.

The bench — the componentization layer

bench/ reproduces all fifteen plates from reference/Efficacious UI Helm.dc.html using only tokens — no colour literals, no raw font stacks.

pnpm build                   # emits dist/ AND stitches bench/index.html
pnpm bench                   # → http://localhost:4400 (stitches per request)
pnpm fidelity                # coverage against the mock
pnpm fidelity --missing      # every gap, by plate

Each plate is authored as its own file under bench/plates/, and the build stitches them (plus the token data) into a static bench/index.html — no runtime fetch, so after pnpm build the page opens straight from a double-click, no server needed. The dev server stitches on every request, so while editing a plate a browser refresh is enough.

Two things are deliberate and worth knowing:

• bench/index.html is generated (and gitignored, like dist/). Edit bench/shell.html or a plate file, never the stitched output.
• Each plates/*.html is a standalone document — double-click one and it renders styled on its own (after pnpm build, which the stylesheet links point into). The stitcher takes only each plate's body content, so the same file works alone and inlined.

That gives both shapes: one scrolling document to diff against the mock, and one file per plate to review or edit without scrolling four thousand lines.

bench/plates/01-command.html    06-messages     11-guidance
             02-systems         07-rails        12-bearings
             03-readouts        08-ledger       13-flow
             04-telemetry       09-selectors    14-identity
             05-console         10-states       15-signals

Coverage is measured, not judged

fidelity — bench vs reference/Efficacious UI Helm.dc.html
  17 plate file(s) · 111/111 sections · 100%

scripts/fidelity.mjs enumerates the mock's own structure — plates, sub-plates, and every section label — and reports which of them the bench carries. CI fails below 100%, so a converted plate cannot quietly regress.

This exists because judgement failed twice. A first pass covered four plates of fifteen and read as finished. A second covered roughly half the sections and also read as finished. A partial conversion renders exactly like a complete one — there is no visual tell, so the only way to know is to enumerate the original and diff.

The cost of not knowing was real: the missing plates held nine colours the primitives lacked, and specified three things that had been recorded as open design questions or invented outright (sender colours, lamp grounds, the focus treatment). The SPEC tables in particular are where the system states its own rules — tooltip delays, toast dwell, badge caps, GOLD — NEVER, SIGNALS ARE NOT ASSERTIONS — and those were the last things to be converted and the easiest to have skipped.

What the bench proves

If a plate can't be built without reaching for a literal, the token layer is wrong — not the bench. It covers 77 of 79 semantic roles; --ef-mark is deliberately absent from every interface surface, because Tier 0 is artwork only and its appearing in chrome would be the bug, not its absence.

The palette and role tables are rendered from dist/tokens.json rather than hand-listed, so the bench cannot drift from the tokens it is proving.

Guardrails

pnpm check                        # this repo
node scripts/check-tokens.mjs ../commandsuite    # a consumer

| Rule | Catches | |---|---| | no-colour-literal | hex / rgb / hsl outside src/tokens/ | | no-raw-font-stack | font-family not going through a token | | unknown-token | var(--ef-*) the build never emitted | | duplicate-tokens | a second file defining primitives — i.e. a fork | | breakpoint-drift | a media query off the shared scale |

Every consuming repo should run this in CI. The failure mode this system is recovering from was invisible for months precisely because it never threw.

Consuming it

CSS

import '@the-efficacious/brand/fonts.css';
import '@the-efficacious/brand/tokens.css';

UnoCSS

import presetWind4 from '@unocss/preset-wind4';
import { efficacious } from '@the-efficacious/brand/uno';

export default defineConfig({
  presets: [presetWind4(), efficacious()],
});

Gives you bg-ef-surface-raised, text-ef-lamp-alarm, border-ef-assert, font-display|body|mono, r-cap-tl|tr|br|bl, and one breakpoint scale (700 / 900 / 1100 / 1280). Colours resolve to var(--ef-*) rather than literals, so a utility and an inline style agree under a theme swap.

Every consumer must use this preset. Breakpoints and brand colours are design decisions; leaving them in per-repo build config is what broke them before.

JavaScript

import { brands, echelon, helm, gold } from '@the-efficacious/brand';

brands.commandsuite.name        // 'CommandSuite'
brands.commandsuite.mark        // the Echelon — geometry, not a file
brands.commandsuite.minSymbolPx // 24
helm.color.assert               // '#cfb055'

Mark geometry ships as data so a nav lockup can inline the SVG without a network fetch. Fills name gold primitives rather than hexes, so a mono knockout is an override rather than a second copy of the artwork.

Raw token data

@the-efficacious/brand/tokens.json — the same values for anything that isn't CSS or JS (design tooling, docs generation, review).

Layout

src/tokens/primitives.ts   raw palette          ← the only place colour is authored
src/tokens/semantic.ts     roles + themes       ← the layer you use
src/tokens/scale.ts        type, radii, space, motion
src/index.ts               brand metadata + mark geometry
src/uno.ts                 shared UnoCSS preset
scripts/emit.mjs           → dist/{tokens,fonts}.css, dist/tokens.json
scripts/check-tokens.mjs   the guardrails
bench/                     the Helm acceptance test
logo-pack/                 SVG + PNG artwork, all three brands
reference/                 the source mocks — brand guide, logo system, Helm

dist/ is generated. Run pnpm build after touching anything in src/.

Provenance

Values are traced to their source in the token files, because the two source documents disagree in places and the disagreements matter:

• GUIDE — reference/Efficacious Brand Guide.dc.html (v1.0, July 2026)
• HELM — reference/Efficacious UI Helm.dc.html (Spike 04, calibrated)
• PACK — logo-pack/README.txt

Known conflicts, and how they were resolved:

| Conflict | Resolution | |---|---| | GUIDE names #CFB055 "Gold Primary"; PACK names #B8962E "gold primary" | GUIDE wins — it is v1.0 and the document HELM was built against. PACK's README wants correcting. | | GUIDE's white is #F8F7F5; HELM's is #F4F1E9 | Both kept. HELM's reads on the console, GUIDE's on a light ground. | | GUIDE's semantic colours are brighter than HELM's lamps | Both kept as primitives; the theme picks. | | GUIDE specifies a 4px spacing grid; HELM's own padding runs on 2px | GUIDE's named scale is canonical and is what to design against. Recorded honestly in scale.ts. |

Anything the mocks do not specify is marked [NEW] at its definition with the reasoning. Today that count is zero — every value traces to a source. The last three apparent gaps (focus treatment, lamp grounds, link colour) each turned out to be specified somewhere that had not been read yet; the link rule fell to a diff against the canonical Claude Design project (Efficacious branding system), which also confirmed the local reference/ export is byte-identical to the canonical file for as much of it as the design API returns, and that support.js is the mock viewer's generic runtime with no design content in it.

Releasing

npm version minor        # or patch / major
git push --follow-tags   # tag fires .github/workflows/release.yml

The workflow builds, runs the guardrails and the fidelity floor, then publishes with OIDC trusted publishing and provenance — no npm token exists anywhere. Publishing is idempotent: a tag whose version is already on the registry skips cleanly. 0.1.0 was bootstrapped with a local npm publish because npm only allows Trusted Publisher configuration on packages that already exist.

Licence

Apache-2.0 for the code, tokens, and stylesheets — the OSS core depends on this package and must be able to redistribute it.

The marks, logotypes, and the name Efficacious are trademarks and are not covered by that grant. See TRADEMARKS.md.