Documentation

• 1: Foundations
• 1.1: Colour
• 1.2: Typography
• 1.3: Space, shape, and motion
• 1.4: Responsive
• 2: Logo
• 2.1: Lockups
• 2.2: Usage
• 2.3: Files
• 3: Interface
• 3.1: Components
• 3.2: Composed patterns
• 3.3: Dark mode
• 3.4: Code
• 3.5: Icons
• 3.6: Forms
• 3.7: States
• 3.8: Accessibility
• 4: Themes
• 4.1: Hugo
• 4.2: Terminal
• 5: Portfolio presentation
• 5.1: Status treatments
• 5.2: Social previews
• 5.3: Diagrams and demos
• 5.4: Documents
• 6: Media
• 6.1: Audio and video
• 6.2: Photography and illustration
• 6.3: Presentations
• 7: Collateral
• 7.1: Business card
• 7.2: Email signature
• 7.3: Email
• 7.4: Social and OG images
• 7.5: Service one-pager
• 8: Governance
• 8.1: Licensing
• 8.2: Trademark
• 8.3: Legal assessment
• 8.4: Asset provenance
• 9: Tokens

1 - Foundations

Foundations are the values the rest of the system is built from. They are deliberately small in number and fixed: a component may choose which token to use, but it does not invent new ones.

1.1 - Colour

The palette is three scales — midnight, orange, and slate — each expressed as a 12-step ramp in a light and a dark variant. The step numbering follows the Radix convention, which assigns every step a role. Using a step outside its role is the single most common way to break the system.

Core colours

These are the named aliases most projects reach for first. They are shortcuts into the scales, not a separate palette.

• Primary

  #1d3352

  Text, headings, primary surfaces
• Primary Light

  #2b4d78

  Hover states, dark-mode primary
• Primary Dark

  #132440

  Dark backgrounds, navbar, code blocks
• Accent

  #E05232

  CTAs, highlights, active states
• Accent Light

  #ea7558

  Accent hover on dark, syntax strings
• Accent Dark

  #b84228

  Accent pressed state
• Accent Solid

  #cc4528

  Fill for solid controls with white text (4.72:1)
• Secondary

  #546a82

  Supporting text, borders

Step roles

Every scale uses the same twelve roles in the same order:

Midnight

Midnight is the primary. It carries structure, text, and the calm end of the system. Step 9 (#1d3352) is the brand primary and is identical in both modes.

Orange

Orange is the accent. It marks the primary action, the active state, and little else. Step 9 (#E05232) is constant across modes.

Slate

Slate is the secondary — supporting text, borders, and neutral surfaces. Step 9 (#546a82) is the brand secondary and is constant across modes.

Terminal

The three scales cover every surface that has a light mode. A terminal does not: it has one surface, it is dark, and every colour in it is measured against that one background. It also needs six hues where the interface needs three, because programs have been writing to sixteen ANSI slots since long before this system existed.

So the terminal palette is a fourth member of the system rather than a fifth scale — a fixed sixteen-slot palette plus its chrome, derived from the ramps and measured against midnight-dark-1.

Read the provenance column carefully. The bright ramp is the brand: where a hue already exists in the system, the bright slot takes that step verbatim. The normal ramp has no brand equivalent — the scales define one value per semantic role, not a dim and a bright — so each normal slot is its bright counterpart darkened until it reads a step back while still clearing the floor.

Magenta and cyan exist in neither half of the brand. They are here because a terminal requires them, and nowhere else.

Terminal chrome

The accent gets no ANSI slot, because it is not semantic — it marks where you are. That, and the surfaces around the sixteen, live here.

Every non-background value clears 4.5:1 against the surface; the measured floor is 4.95:1. ANSI 0 bright is the one deliberate exception — programs use it for box drawing and rules, not for text.

Configuration for tmux, WezTerm, Kitty, Ghostty, iTerm2, and Zellij is on the Terminal theming page.

Contrast rules

• Never use pure #000 or #fff as text. Use step 12 of the relevant scale: #142438 on light, #c5daf0 on dark.
• Step 9 is constant across modes. The solid accent does not shift when the theme changes.
• Body text targets 4.5:1, large text (≥24px, or ≥18.66px bold) targets 3:1.
• Verify against the actual surface. A step that passes on the app background may fail on an elevated panel.

Where an identity colour cannot carry text

Being the brand colour does not make a value a legible background. White on orange-9 (#E05232) measures 3.87:1 — fine as a mark or a border, but below the floor for button labels. Rather than dilute the accent, the system adds a separate fill for that job:

The same principle produced the code-comment token: when no existing step can do the job accessibly, name a new one rather than misuse a step.

Semantic colours are mode-specific

The callout hues are tuned for dark text on tinted light backgrounds. Used as foregrounds on the dark app surface they fall below AA, so dark mode has its own set:

Data visualisation

A chart palette introduces no new colours. It is a set of rules for which existing steps may sit beside each other in a plot, and — more usefully — for when colour stops being the right tool.

Categorical: three series

One step-9 solid per family, in that order. All three clear the 3:1 non-text contrast floor against a white plot area, so a bar or a line is visible without a border.

Assign them in order and keep the assignment stable across every chart in a deck or a dashboard: if midnight is “cloud” on slide four, it is “cloud” on slide nine. A series that changes colour between charts costs the reader more than a fourth series would have gained them.

There is no fourth series

The palette stops at three, and extending it is the wrong fix. The step-6 tier is not an option: midnight-6 and slate-6 measure 1.03:1 against each other — the same colour, for practical purposes — and all three step-6 values sit at 1.8–2.0:1 against white, below the 3:1 floor for a mark you have to see.

When a chart has more than three categories, one of these is the answer:

• Group the tail. Rank the categories and collapse everything past the third into “Other”. If the fourth is genuinely interesting, it is the subject of its own chart.
• Small multiples. One chart per category, same axes, same scale. Reading eight small charts is faster than decoding an eight-colour legend.
• Direct labelling with one highlight. Draw every series in slate-7, draw the one being discussed in orange-9, and label it in place. This is the house style for a line chart in a deck — one idea per slide holds for charts too.
• Stop using colour. A ranked bar chart in a single colour, sorted by value, answers “which is biggest” better than any palette does.

Sequential and ordinal scales

A magnitude scale uses one family, steps 3 through 8:

--midnight-3 → --midnight-4 → --midnight-5 → --midnight-6 → --midnight-7 → --midnight-8

Six levels, stepping evenly in luminance (each 1.06–1.40× its neighbour) — which is what makes the ramp readable as an ordered scale rather than as six colours.

Step 9 is not the top of that ramp. It is 3.87× darker than step 8, which is a jump the eye reads as a category boundary rather than one more level. Use it deliberately for exactly that: a four-bucket choropleth of 3 · 5 · 7 · 9, where the top bucket is meant to separate itself. Do not append it to a six-level heatmap.

Steps 3–7 are all below 3:1 against a white plot area, so a sequential fill needs an edge: give the plot a 1px slate-4 cell grid, or the reader loses the boundary between a light cell and the page.

For a diverging scale — where the middle is neutral and both ends are extreme — run midnight-8 → midnight-3 → orange-3 → orange-8, with --midnight-1 at the midpoint. Never build a diverging scale from success and danger: those hues carry a judgement, and “below average” is not “wrong”.

Chart furniture

Numbers are set in IBM Plex Mono, right-aligned, for the same reason table numerics are: digits have to line up to be compared.

Dark mode

Both modes are equally supported. See Dark mode for the implementation rules — theme switching, persistence, image treatment, and the always-dark code surface.

1.2 - Typography

The system uses three typefaces, each with one job. All three are licensed under the SIL Open Font License 1.1 and served from Google Fonts, so there are no bundled font binaries to license or redistribute.

The three families

Loading them:

<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:wght@400;500;600;700;800&family=Source+Sans+3:wght@400;500;600&family=IBM+Plex+Mono:wght@400;500&display=swap">

The ramp

Every row below is set in the family, size, weight, and line-height it documents — this is the live specimen, not a picture of one.

Rules

• Letter-spacing tightens to −0.3px above 20px. Large type set at default tracking reads loose and unresolved.
• Overline is a label, not a heading. 11px, 600, uppercase, 0.08em tracking. Use it above a heading, never as one.
• Body copy is 16px / 1.65. This is the reading size for documentation and long-form prose. Do not set body text below 14px.
• Never set body copy in Plus Jakarta Sans, and never set headings in Source Sans 3. The split is what makes the voice recognisable.

1.3 - Space, shape, and motion

Spacing

A 4px base with a nine-step scale. Every margin, padding, and gap resolves to one of these values.

Content sits inside a 1100px measure. Wider viewports gain margin, not line length.

Radius

Radius is a signal of scale: the larger the surface, the larger the radius. Mixing radii on nested surfaces reads as a mistake — a 6px control inside a 9px card is correct; a 13px control inside a 6px card is not.

Elevation

Four levels. Shadows are soft and low-contrast; the system leans on borders and surface tint before it reaches for shadow.

In dark mode, elevation is expressed by lightening the surface rather than deepening the shadow — a shadow on a near-black background is invisible.

Motion

Things slide into place. They do not bounce.

Durations

Easing

Motion rules

• All animation wraps in @media (prefers-reduced-motion: no-preference), or is disabled under prefers-reduced-motion: reduce.
• CSS-only for HTML. For React, use Framer Motion with these same timing values.
• Never animate text character-by-character.
• Page transitions cap at 400ms.

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

1.4 - Responsive

The rest of the foundations describe values that do not change with viewport width. This page describes the four points at which the layout does.

Breakpoints

Four breakpoints, declared in brand/tokens/variables.css and normative here:

Below sm is not a breakpoint; it is the base. Write the narrow layout first and add width with min-width queries, so an unstyled or unsupported viewport gets the single-column layout rather than a clipped desktop one.

/* Base — single column, 360px and up. */
.panel-row { display: grid; gap: var(--space-4); }

@media (min-width: 768px) {
  .panel-row { grid-template-columns: repeat(2, 1fr); }
}
@media (min-width: 1024px) {
  .panel-row { grid-template-columns: 1.5fr 1fr; }
}

How the grid collapses

The grid is 12 columns inside the 1100px measure. It does not stay twelve columns all the way down — it resolves to four column counts:

Below md, every multi-column region becomes one column. There is no two-column layout on a phone: two 160px columns are two unreadable columns. Regions stack in source order, so the DOM must already be in reading order — do not rely on order or grid-area to fix a sequence that is wrong in the markup, because that breaks the focus and reading order.

Spacing steps down one rung when the grid collapses: a --space-6 (32px) section gap on desktop becomes --space-5 (24px) below md. Radius, type scale, and border weights do not change — a card is a 9px card at every width.

Touch targets

44×44px minimum for anything tappable, at every viewport — the floor is a finger, not a breakpoint.

The default control heights are 32 / 40 / 48px, so the sm and md sizes are below the floor on their own. Two ways to resolve it, in order of preference:

1. Grow the hit area, not the control. Keep the 40px visual button and give it a transparent 2px vertical extension, or wrap it in a 44px-tall row. The measurement stays normative; the target clears the floor.
2. Use lg (48px) on touch-primary surfaces. Correct for the primary action on a phone, where a 40px button next to a 48px one reads as demoted.

Never shrink to sm (32px) for a touch target. Spacing between adjacent targets is at least --space-2 (8px), so a mis-tap does not fire the neighbour.

/* Preferred: 40px control, 44px target. */
.pj-btn--md {
  min-height: 40px;
  position: relative;
}
.pj-btn--md::after {
  content: "";
  position: absolute;
  inset: -2px 0;   /* 40 + 2 + 2 = 44 */
}

Mobile navigation

Use a bottom tab bar for application surfaces. Use a top drawer for documentation and marketing surfaces. The choice follows the shape of the navigation, not the shape of the device:

• An application has a small, flat set of destinations — the dashboard example has five. Five or fewer flat destinations fit a tab bar, which keeps the current location permanently visible, sits in the thumb arc, and costs no taps to reach. That is worth the 56px of permanent screen it occupies.
• Documentation has a deep, nested tree. A tab bar cannot express it, and flattening the tree to fit one is worse than a drawer. A drawer behind a labelled disclosure control costs one tap and can show the whole hierarchy.

The failure mode is a tab bar with six or more items, or one that hides the primary destination behind “More”. If the destinations do not fit, the surface is a drawer surface.

Both patterns carry the same obligations: the current destination is marked with an accent underline or fill plus the label, never colour alone; the drawer traps focus while open, closes on Esc, and returns focus to its trigger — the same contract as a modal.

Tables, code, and diagrams

Three content types cannot reflow, and each has one answer:

• Tables scroll horizontally inside their own container with the first column pinned — never the page. See wide tables.
• Code blocks scroll horizontally. Do not soft-wrap code: a wrapped line changes what the code appears to say.
• Diagrams get a scrollable container or a re-drawn narrow variant. Do not scale a diagram down until its labels are unreadable — an 8px label is not a responsive diagram, it is a broken one.

Worked example

Mobile onboarding — three screens in a device frame: an onboarding panel on midnight, an engagement list of stacked cards, and a finding-review screen with two side-by-side actions. It is the dashboard below md: same tokens, same components, one column, tab bar instead of sidebar.

2 - Logo

The mark is a stencil peony bud — concentric petal cuts resolving to an accent centre. It reads as a single form at 16px and holds its internal structure at poster scale.

2.1 - Lockups

Four lockups are approved. Each has a defined context; using one outside its context is what makes a layout feel off-brand even when the colours are right.

All four are built with HTML and CSS rather than flattened artwork, so spacing comes from natural text flow and never needs re-kerning.

The four lockups

On light and dark

Every lockup has a light-surface and a dark-surface rendering. The mark’s inner cuts pick up the surface colour, so it never needs a plate or a knockout box.

The mark alone

The mark may stand alone only where the wordmark is already established nearby — an app icon on a page that names the product, an avatar in a signed-in context, a favicon.

Minimum for the standalone mark is 24px. The 16px rendering exists for favicons only, where the browser supplies the name.

Product line

Product names extend the wordmark with the same dot construction and flow.

Wordmark construction

The separator between “projectious” and “work” is a dot in the mark’s own geometry, not a typed period. It takes slate on light surfaces and midnight-11 on dark. Spacing is handled by flex layout so the wordmark reflows naturally — do not hand-kern it or convert it to a static image.

2.2 - Usage

Clear space

Minimum clear space is 1× the icon height on all sides. Nothing — text, rules, image edges, other logos — enters that exclusion zone.

At a 40px mark, that is 40px of clear space in every direction. The zone scales with the mark, so it never needs recalculating per context.

Minimum sizes

Below these sizes the petal cuts collapse into a smudge. If the space is smaller than the minimum, use a smaller variant rather than scaling one down.

Monochrome

Four monochrome treatments are approved, for print, fax, embossing, and any single-colour reproduction:

The white-reversed variant uses slate for its inner lines rather than the background colour, so the petal structure stays visible. All petal structure must remain legible in every monochrome variant — a solid silhouette is not an approved treatment.

On colour

The slate-5 threshold is the decision rule: measure the background, pick the side it falls on. On the accent, neither variant has enough separation on its own, which is why the ring exists.

On photography

Never place the mark directly on an unmodified photograph. Apply a semi-transparent midnight backing — a shape, a scrim, or a gradient — so the mark sits on a controlled surface. The backing is part of the logo treatment, not an optional enhancement.

Watermark

For background use, the mark may run as a watermark at 8–15% opacity. It renders as a uniform wash: no accent colour in watermark mode, since a single coloured element at low opacity reads as a printing error.

Favicons

Icon-only, on a midnight tile, with 12% padding. Corner radius scales with size:

2.3 - Files

Formats

SVG is the source. Raster exports exist for contexts that cannot take vector — prefer SVG wherever the medium allows it.

Variants

Each raster size ships in five variants:

• icon-light — for light surfaces
• icon-dark — for dark surfaces
• icon-mono-black — single-colour black
• icon-mono-white — single-colour white, reversed
• icon-mono-gray — single-colour grey

Downloads

The logo files are served from this site and are also in the repository under brand/logo/.

3 - Interface

Interface guidance applies the foundations to working software. Where a component appears here, its measurements are normative — a 40px input is 40px, not “about 40px”.

3.1 - Components

Every specimen on this page is live markup styled by the brand tokens, ported from brand/html/projectious-kitchen-sink.html. They follow your colour mode — switch the theme and they change with the documentation.

Measurements listed here are normative: a 40px input is 40px.

Buttons

Five variants, three sizes. Plus Jakarta Sans 600, 6px radius, 200ms transitions.

Inputs

Default height 40px (sm 32, lg 48). Source Sans 3 at 13px, slate-7 border, and a 2px focus ring at midnight 15% alpha.

Full rules — labels, validation, focus — are on Forms.

Cards

Radius 9px, padding 24px, 1px slate-4 border, shadow-1 at rest. Nested controls step down one radius.

Tables

Header cells use the overline style. Striping uses the subtle background step, never a border-only rule. Wide tables scroll inside their own container.

Table with search and filters

A toolbar above the table carries the search field and filter chips. Active filters are shown as removable chips so the current view is always legible — never leave a filter applied with no visible indication.

Multi-level headers

Grouped columns use a two-row header. The group row is centred over its span and separated by a vertical rule — the only place the system uses one.

Grouped rows and totals

Row groups act as sub-headings inside the table. A totals row is separated by a 2px rule — heavier than the body rules, so it reads as a summary rather than another record.

Wide tables

A wide table scrolls inside its own container, never the page, and pins its first column so the row identity stays visible while scrolling.

Navigation

The navbar follows the colour mode: midnight-1 at 88% alpha in light, midnight-dark-1 at 88% in dark, both over a 12px backdrop blur so content scrolling underneath stays legible. It is separated by a 1px border, not a fill — the header is chrome, and a solid midnight band at the top of every page spends the brand’s darkest surface on navigation.

The active link carries a 2px accent-solid underline plus the high-emphasis text step. The underline is accent-solid rather than orange-9 because it sits directly against 13px text and is read as part of it.

This specimen mirrors .td-navbar — the header at the top of this page. Switch the theme and both change together.

Alerts and feedback

Four semantic colours as a 4px left border on a tinted background. The hues are mode-specific — see Colour.

Modals and overlays

Modal radius 13px with shadow-3; scrim is midnight at 40% alpha. Focus is trapped while open and restored to the trigger on close; Esc always closes.

Data display

Code and terminal

The code surface is always dark — see Code.

3.2 - Composed patterns

Components answers “what does a card look like”. This page answers the question after it: what does a whole screen look like when it is made only of those parts.

Nothing here is a new component. Every element below already exists on the components page; what is normative here is the arrangement — which regions a screen has, in what order, at what widths.

The page shell

Three regions, always in this order in the DOM:

The sidebar is the only large midnight fill on the screen. It is the application’s frame, so it stays constant while the content region changes; a sidebar that re-renders per route reads as a page reload.

The header carries exactly one accent button. That is the whole quota for the screen — one accent per view — which is why the pattern places it here rather than leaving it to the content region to spend.

Below lg (1024px) the sidebar leaves and becomes the mobile navigation pattern; see Responsive.

The KPI row

Directly under the header: four stat cards in a repeat(4, 1fr) grid, --space-4 gap.

Four, not three and not six. Three leaves a hole in a 12-column grid; six turns the row into a wall of numbers nobody reads. If there are five things worth measuring, the fifth one is not a KPI.

Each card is a pj-stat — the number first in Plus Jakarta Sans 800, its label under it in the overline style, then a delta line. The pj-stat carries its own border and radius, so it is not nested inside a pj-card; that would draw the box twice.

A delta states its direction in text or an arrow, not in colour. The default __delta is the success hue; a delta that is not good news takes an explicit colour, and a delta that is merely neutral takes the muted foreground rather than borrowing a semantic one.

Primary content and secondary panel

Under the KPI row, a 1.5fr / 1fr split: the thing the page is about on the left, the thing that gives it context on the right.

• Primary is the record set — a table in a pj-table-shell, with its toolbar, filter chips, and pagination footer.
• Secondary is a pj-card holding a feed: a pj-timeline or pj-list of recent events, each with a status dot and a text label.

align-items: start, so the two panels are independent — the feed does not stretch to match a long table, and the table does not gain whitespace to match a short feed.

The split is 1.5fr / 1fr because the primary panel holds tabular data with four or more columns and the secondary holds one column of prose. An even 1fr / 1fr starves the table and pads the feed.

At md the ratio flattens to 1fr / 1fr; below md the secondary panel moves below the primary, in source order.

Reading the whole thing at once

Dashboard mockup — a client engagement dashboard built entirely from the parts above: page shell, KPI row, engagement table, agent-activity feed. Open it beside the components page and every element in it should be findable there.

Its narrow counterpart is Mobile onboarding — the same system with the sidebar replaced by a tab bar and every region in one column.

Density

One pattern, two densities. The measurements on the components page are the comfortable density and are the default. A compact density exists for screens whose job is scanning many rows at once — an audit log, a run history:

Density changes padding and control height. It does not change type size, radius, or border weight — a compact table is the same table with less air, not a smaller one. Compact is never used on touch-primary surfaces, where the 44px floor applies regardless.

3.3 - Dark mode

Dark mode is not a variant of the brand — it is half of it. Both modes are designed, tested, and shipped together.

Implementation rules

• Default follows prefers-color-scheme, with a manual override toggle persisted to localStorage.
• CSS custom properties swap per theme. Components read tokens; they do not branch on the mode themselves.
• Step 9 (solid accent) stays constant across modes. #E05232 is #E05232 everywhere.
• No pure #000 or #fff as text. Use step 12 — #c5daf0 on dark, #142438 on light.
• Images get a subtle overlay (black at low alpha) in dark mode, so a bright photograph does not punch a hole in a dark page.
• Code blocks are always dark, regardless of mode. See Code.

Surfaces

Elevation in dark mode is expressed by lightening the surface, not by deepening the shadow — a shadow against a near-black background is invisible.

Restating text on dark surfaces

The default heading colour is midnight-9, chosen so headings read correctly on light pages. That same value on a midnight surface is invisible — #1d3352 on #1d3352 is a contrast ratio of 1.00:1.

Any component that paints its own dark background must therefore restate its text colours. This applies to covers, dark boxes, footers, and overlays:

.surface--dark {
  --bs-body-color: #c5daf0;    // midnight-dark-12
  --bs-heading-color: #c5daf0;
  --bs-secondary-color: #97a8b8; // slate-dark-11, still AA
}

3.4 - Code

Code blocks are always dark

Code blocks stay dark regardless of colour mode. A code surface that flips with the theme forces the syntax palette to be designed twice and makes screenshots inconsistent between users. The surface is midnight-2 from the dark scale (#131e2b) in both light and dark mode.

The block you are reading is rendered by that rule:

// Agent pipeline definition
const pipeline = createPipeline({
  name: "validate-deploy",
  policy: "strict",
  agents: ["auditor", "deployer"],
});

Syntax theme

Because the surface is always dark, every syntax value is read from the dark scale. Contrast is measured against #131e2b.

Ten roles, not twenty-two tokens

Editors do not describe code with six token types. The Language Server Protocol defines 22 semantic token types and 10 modifiers, and TextMate grammars — the model behind VS Code, Sublime Text, and most highlighters — define 11 root scopes with a deep sub-scope tree under each.

A theme should not answer that with twenty-two colours. Past roughly nine, hue stops being a signal: everything is coloured, so nothing is marked. The two scope vocabularies are therefore grouped into ten roles, and the modifiers are carried by weight and slant rather than by more hue.

Every role is an existing brand or terminal value. The expansion introduced no new colour — the terminal palette had already added the two hues, cyan and magenta, that a syntax theme needs and the three interface scales do not have.

Modifiers are not colours

LSP modifiers combine with any token type: ten modifiers against ten roles is a hundred states. Hue cannot carry that, so it does not try.

Why comments have a dedicated token

Comments are the one syntax role with no scale step available to it. Steps 8–10 are border and solid-surface roles and are not held to text thresholds; step 11 is already spoken for by operators.

So code-comment (#72889d, 4.59:1) exists as a dedicated syntax token — the dimmest value that clears AA while staying visibly below operators. It is not a scale step and should not be treated as one.

Worked examples

Each block below is a real, compilable-shaped fragment chosen to exercise as many of the ten roles as its language has. The coverage table after them records which roles each language actually reaches — several cannot reach all ten, and that is a property of the language, not a gap in the theme.

C

/* Ring buffer — fixed capacity, no allocation after init. */
#include <stdint.h>
#define RING_CAP 256          // macro: a decorator-role token

typedef enum { RING_OK = 0, RING_FULL = 1 } ring_status_t;

typedef struct {
    uint8_t  data[RING_CAP];
    size_t   head, tail;
    _Bool    wrapped;
} ring_t;

static inline size_t ring_len(const ring_t *r) {
    return (r->head - r->tail) & (RING_CAP - 1);
}

static const char *RING_TAG = "ring\n";   // string literal

ring_status_t ring_push(ring_t *restrict r, uint8_t byte) {
    // Reject when one slot short of capacity, so head never meets tail.
    if (ring_len(r) == RING_CAP - 1) return RING_FULL;
    r->data[r->head++ & (RING_CAP - 1)] = byte;
    return RING_OK;
}

C++

// Policy-based cache. Types, templates, and a lambda.
#include <string>
#include <unordered_map>

namespace projectious::cache {

template <typename Key, typename Value>
class LruCache final {
public:
    explicit LruCache(std::size_t capacity) noexcept : capacity_{capacity} {}

    [[nodiscard]] auto get(const Key& key) const -> const Value* {
        const auto it = entries_.find(key);
        return it == entries_.end() ? nullptr : &it->second;
    }

    void put(Key key, Value value) {
        static constexpr auto kTag = "lru";  // string literal
        // Evict before insert so size never exceeds the capacity.
        if (entries_.size() >= capacity_) evict();
        entries_.emplace(std::move(key), std::move(value));
    }

private:
    void evict() noexcept { /* … */ }

    std::size_t capacity_{0};
    std::unordered_map<Key, Value> entries_{};
};

}  // namespace projectious::cache

Python

"""Pipeline stages and their policy gates."""

from __future__ import annotations

import functools
from dataclasses import dataclass, field
from typing import Final, Iterable

# Retry budget is a policy decision, not a tuning knob.
MAX_RETRIES: Final[int] = 3
DEFAULT_POLICY = "strict"


@dataclass(frozen=True, slots=True)
class Stage:
    """A single stage. Immutable once constructed."""

    name: str
    policy: str = DEFAULT_POLICY
    retries: int = 0
    tags: list[str] = field(default_factory=list)

    @property
    def is_strict(self) -> bool:
        return self.policy == "strict"

    @staticmethod
    def parse(raw: str) -> "Stage":
        name, _, policy = raw.partition(":")
        return Stage(name=name.strip(), policy=policy or DEFAULT_POLICY)


@functools.lru_cache(maxsize=None)
def validate(stages: Iterable[Stage]) -> bool:
    for stage in stages:
        if stage.retries > MAX_RETRIES:
            raise ValueError(f"{stage.name!r} exceeds {MAX_RETRIES} retries")
    return True

Rust

//! Policy evaluation for pipeline stages.

use std::collections::HashMap;
use std::fmt::{self, Display};

const MAX_RETRIES: u32 = 3;

/// How strictly a stage is evaluated.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Policy {
    Strict,
    Advisory,
}

#[derive(Debug, Default)]
pub struct Stage<'a> {
    pub name: &'a str,
    pub policy: Option<Policy>,
    pub retries: u32,
}

impl<'a> Stage<'a> {
    // Strict by default: a gate that is not configured should fail closed.
    pub fn new(name: &'a str) -> Self {
        Self { name, policy: Some(Policy::Strict), retries: 0 }
    }

    pub fn validate(&self) -> Result<(), String> {
        if self.retries > MAX_RETRIES {
            return Err(format!("{} exceeds {MAX_RETRIES} retries", self.name));
        }
        Ok(())
    }
}

impl Display for Policy {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", match self { Policy::Strict => "strict", _ => "advisory" })
    }
}

Go

// Package pipeline evaluates stages against their policy gates.
package pipeline

import (
	"errors"
	"fmt"
)

const MaxRetries = 3

// Policy is how strictly a stage is evaluated.
type Policy int

const (
	Strict Policy = iota
	Advisory
)

var ErrTooManyRetries = errors.New("stage exceeds retry budget")

type Stage struct {
	Name    string `json:"name"`
	Policy  Policy `json:"policy"`
	Retries int    `json:"retries,omitempty"`
}

func (s *Stage) Validate() error {
	if s.Retries > MaxRetries {
		return fmt.Errorf("%q: %w", s.Name, ErrTooManyRetries)
	}
	return nil
}

func ValidateAll(stages []Stage) (ok bool, err error) {
	for i := range stages {
		if err = stages[i].Validate(); err != nil {
			return false, err
		}
	}
	return true, nil
}

Java

package work.projectious.pipeline;

import java.util.List;
import java.util.Objects;

/** A single pipeline stage and its policy gate. */
public final class Stage implements Comparable<Stage> {

    public static final int MAX_RETRIES = 3;
    public static final long TIMEOUT_MS = 30_000L;
    public static final int MASK = 0xFF;

    private final String name;
    private final Policy policy;
    private int retries = 0;
    private double budget = 12.60;

    public Stage(String name, Policy policy) {
        this.name = Objects.requireNonNull(name, "name");
        this.policy = policy;
    }

    @Override
    public int compareTo(Stage other) {
        return this.name.compareTo(other.name);
    }

    @Deprecated(since = "2.0", forRemoval = true)
    public boolean isStrict() {
        return policy == Policy.STRICT;
    }

    public void validate(List<String> errors) throws IllegalStateException {
        if (retries > MAX_RETRIES) {
            throw new IllegalStateException("%s exceeds %d retries".formatted(name, MAX_RETRIES));
        }
    }

    public enum Policy { STRICT, ADVISORY }
}

Assembly (NASM)

; Sum a byte array. rdi = pointer, rsi = length, returns in rax.
        section .data
msg:    db  "sum: ", 0
LEN     equ 5

        section .text
        global  sum_bytes

sum_bytes:
        xor     rax, rax            ; accumulator
        test    rsi, rsi
        jz      .done               ; empty input

.loop:
        movzx   rdx, byte [rdi]
        add     rax, rdx
        inc     rdi
        dec     rsi
        jnz     .loop

.done:
        ret

Bash

#!/usr/bin/env bash
# Validate a pipeline definition and promote it when the gates pass.
set -euo pipefail

readonly MAX_RETRIES=3
readonly POLICY="${PIPELINE_POLICY:-strict}"
declare -A GATE_STATUS=()

log() { printf '%s  %s\n' "$(date -u +%FT%TZ)" "$*" >&2; }

validate_stage() {
    local -r name="$1" retries="${2:-0}"
    if (( retries > MAX_RETRIES )); then
        log "ERROR ${name} exceeds ${MAX_RETRIES} retries"
        return 1
    fi
    GATE_STATUS["$name"]="ok"
}

main() {
    local -a stages=("validate" "deploy")
    for stage in "${stages[@]}"; do
        validate_stage "$stage" 0 || exit 1
    done
    log "policy=${POLICY} stages=${#stages[@]}"
}

main "$@"

LaTeX

\documentclass[11pt,a4paper]{article}
\usepackage[utf8]{inputenc}
\usepackage{amsmath}

% Pipeline notation used throughout the paper.
\newcommand{\stage}[2]{\ensuremath{#1 \xrightarrow{#2}}}

\title{Policy Gates in Composable Pipelines}
\author{Jane Doe}

\begin{document}
\maketitle

\section{Definitions}
A stage $s_i$ passes when its retry count $r_i \leq 3$:
\begin{equation}
    \forall s_i \in S : r_i \leq R_{\max}, \quad R_{\max} = 3
\end{equation}

\begin{itemize}
    \item \textbf{Strict} — the gate fails closed.
    \item \emph{Advisory} — the gate records and continues.
\end{itemize}

\end{document}

Markdown

---
title: Stage reference
weight: 10
---

# Stage reference

A stage passes when its retry count stays at or below **three**. See the
[policy guide](../policy/) for the full rules.

## Fields

| Field | Type | Default |
|---|---|---|
| `name` | string | — |
| `policy` | enum | `strict` |

> Advisory gates record a failure and continue. Strict gates fail closed.

1. Validate the configuration
2. Request promotion
3. Deploy

```sh
pipeline validate --policy strict
```

<!-- Deprecated: `--legacy-gate` is removed in 2.0. -->

JSON

{
  "$schema": "https://projectious.work/schema/pipeline-2.json",
  "name": "validate-deploy",
  "policy": "strict",
  "retries": 3,
  "enabled": true,
  "owner": null,
  "budget": 12.6,
  "stages": [
    { "name": "validate", "gate": "strict", "timeoutSeconds": 120 },
    { "name": "deploy", "gate": "advisory", "timeoutSeconds": 600 }
  ],
  "tags": ["platform", "eu-central"]
}

YAML

# Pipeline definition — one policy gate per stage.
apiVersion: projectious.work/v2
kind: Pipeline
metadata:
  name: validate-deploy
  labels: { team: platform, region: eu-central }

defaults: &defaults
  policy: strict
  retries: 3
  enabled: true

spec:
  <<: *defaults
  budget: 12.60
  owner: ~
  stages:
    - name: validate
      timeoutSeconds: 120
    - name: deploy
      policy: advisory
      timeoutSeconds: 600
  owner: "platform@projectious.work"
  schema: 'https://projectious.work/schema/pipeline-2.json'
  notes: |
    Advisory gates record and continue.
    Strict gates fail closed.

TOML

# Pipeline definition — one policy gate per stage.
schema = "https://projectious.work/schema/pipeline-2.json"

[pipeline]
name    = "validate-deploy"
policy  = "strict"
retries = 3
enabled = true
budget  = 12.60
created = 2026-08-02T09:00:00Z
tags    = ["platform", "eu-central"]

[[pipeline.stage]]
name           = "validate"
gate           = "strict"
timeoutSeconds = 120

[[pipeline.stage]]
name           = "deploy"
gate           = "advisory"
timeoutSeconds = 600

What each language reaches

The table is measured from the rendered page, not asserted: every block above is parsed and its emitted token classes are mapped back to the roles. ● means the role appears in that example.

Nine roles rather than ten, because invalid only appears when a grammar actually fails to parse — a correct example cannot demonstrate it.

Where a language falls short, the reason is the language or the lexer:

• Bash — no type system, and Chroma’s shell lexer does not mark function definitions.
• Go — Go has no macro or annotation construct; its struct tags are strings.
• Java — Chroma’s Java lexer emits a plain name for every numeric literal, so numbers cannot be separated. A lexer limitation, not a palette one.
• LaTeX — No type, callable or operator concept in the grammar — commands are keywords.
• Markdown — Prose, not code: there is nothing to name, call, or annotate.
• JSON — By design: no comments, no identifiers, no callables. Keys take the keyword role.
• YAML — Anchors and merge keys take the macro role; there are no callables or types.
• TOML — Table headers take the plain role; there are no callables or types.

Inline code

Inline code does not take the dark block treatment — it follows the surrounding surface. On light surfaces it sits on midnight-2 (light scale) with orange-11 text; in dark mode both values shift to their dark-scale counterparts. It uses IBM Plex Mono at 13px with a 3px radius.

Terminal output

Terminal blocks use the same dark surface. Prompts take the comment colour, output takes the operator colour, so a transcript stays readable without becoming a second syntax theme.

$ hugo --gc --minify
Start building sites …
Total in 842 ms

3.5 - Icons

Library

The system uses Lucide — an actively maintained fork of Feather with over 1,400 icons.

ISC is one of the most permissive open-source licences available, which is why it was chosen over icon sets with attribution or share-alike terms. See the legal assessment for the clearance detail.

Getting the actual icon

Every icon in this system is a verbatim Lucide path. The specimens on this page are lucide/shield, copied from the library rather than approximated — including the 1 1 0 0 1 arc segments that give Lucide its corner radius, which is exactly the character a redrawn path loses.

Take the file, do not trace it:

curl -O https://unpkg.com/lucide-static@0.544.0/icons/shield.svg

Pin the version. lucide-static@latest resolves to whatever shipped this morning, which lets an upstream release silently change a committed document. The copies used by the worked examples are vendored at brand/examples/lucide/ at a pinned version, with the upstream ISC notice beside them.

Inline the <path> and set width, height, and stroke at the use site; keep viewBox="0 0 24 24", fill="none", stroke-width="2", and both stroke-linecap and stroke-linejoin at round. Changing any of those five is what makes an icon stop looking like the rest of the set.

Usage

• Stroke width 2, matching Lucide’s default. Do not thin or thicken strokes to “match” a layout.
• Size on the 4px grid: 16, 20, 24, 32px. 20px is the default for inline UI.
• Colour follows text. An icon beside a label takes the label’s colour. Standalone icons carrying meaning take --color-secondary; an icon marking the primary action takes the accent.
• Icons are not decoration. Every icon must carry meaning the label does not already carry, or be marked aria-hidden="true".

3.6 - Forms

Sizing

All inputs are set in Source Sans 3 at 13px.

States

Labels

Labels use the overline style and sit above the field. Floating labels are not used anywhere in the system — they hide the label at exactly the moment the user is filling the field, and they break at long label lengths.

.field__label {
  font-size: 11px;
  font-weight: 600;
  line-height: 1.3;
  text-transform: uppercase;
  letter-spacing: 0.08em;
  color: var(--color-secondary);
}

Validation

• Error text sits below the field, in orange-11 on light surfaces.
• Never rely on border colour alone to signal an error — pair it with text.
• Validate on blur, not on every keystroke; re-validate on submit.

3.7 - States

A component set shows every part working. A product spends a lot of its life in the three states where nothing is working yet: there is no data, the data has not arrived, and the data will not arrive. Those three screens are where a design system is actually tested, so they are specified here rather than left to whoever hits them first.

Every state on this page follows the same shape:

What is true → why → the one thing to do about it.

If a state cannot name the one thing to do, it is an error state with an optimistic title.

Empty states

Three kinds, and they are not interchangeable:

The first-run empty state is the only one that gets an accent button — it is the only one where creating something is what the user came to do. “Filtered to nothing” gets a ghost button, because the fix is to undo, not to create.

An empty state is body text, not an illustration. The system’s answer to a blank screen is a diagram or nothing, never a mascot or a spot illustration of a person holding a magnifying glass.

Loading states

Two mechanisms, chosen by what you know about the shape of what is coming:

Prefer the skeleton. A spinner in the middle of a region that is about to become a table tells the user nothing and then reflows the page underneath them.

A skeleton is midnight-2 blocks at the real dimensions of the content, with the real gaps and the real number of rows where that is known. It carries a 100ms shimmer at --duration-standard, and it does not shimmer at all under prefers-reduced-motion: reduce — it simply sits there as static blocks.

Timing rules, so the loading state does not become its own flicker:

• Under 200ms — show nothing. A skeleton that appears and vanishes is worse than a brief pause.
• 200ms to 10s — skeleton or spinner.
• Over 10s — a determinate pj-progress bar with a count (“3 of 12 checks”), or the state moves to a background job with its own row in the list.

Every loading region carries role="status" and an accessible label, or a screen-reader user gets silence where a sighted user gets motion. Never animate a skeleton in a way that hides that the operation has stalled — a shimmer that runs for two minutes says “working” when the truth is “stuck”.

Error pages

Full-page errors — 404 and 500 — are the brand’s worst-case first impression, so they use the same page shell and the same voice as everything else. No apology paragraph, no cartoon, no error code as a headline.

The code (404, 500) appears as an overline above the headline, in the muted foreground — findable when someone is reporting the problem, never the loudest thing on the page.

A 500 says what did not happen. “Nothing was deployed” is the sentence the reader needs; “an unexpected error occurred” is the sentence they cannot act on. If the outcome is genuinely unknown, say that instead — it is a different fact and it changes what they do next.

Inline errors

Not every failure takes the page. A failure scoped to one region stays in that region, so the rest of the screen remains usable:

• A field fails with pj-input--error and a message below it — never a tooltip, never colour on the border alone.
• A panel fails with a pj-alert--danger inside the panel and a retry control, while the surrounding page keeps working.
• A background job fails into a row in the activity feed with a pj-status --err dot and the word “Failed”.

3.8 - Accessibility

Accessibility appears throughout this system as measurements — contrast ratios on Colour, the 44px touch floor on Responsive, the focus trap on modals. This page covers what those cannot: order, announcement, and focus — the properties that only exist once components are composed into a screen.

The target is WCAG 2.2 Level AA.

Reading and focus order

There is one order, and the DOM defines it. Keyboard order, screen-reader order, and visual order must agree.

That makes source order a layout constraint, not a detail: write regions in the order they should be read, and let CSS place them. The page shell is therefore authored as skip link → header → sidebar → main → complementary, and Grid puts the sidebar on the left.

Never use order, row-reverse, or grid-area to change the sequence a reader encounters. It moves the pixels and leaves the keyboard behind, which is exactly the bug that a stacked mobile layout exposes: if the DOM is already in reading order, the collapse to one column is free.

Never set a positive tabindex. tabindex="0" puts an element in the natural order and tabindex="-1" makes it programmatically focusable; anything above zero creates a second, competing order.

Skip links

Every page begins with a skip link — the first focusable element in the DOM, visually hidden until focused, then rendered as a normal control against the midnight header.

One skip link per major landmark the keyboard would otherwise have to traverse. For the page shell that is two: Skip to content and Skip to navigation. A sidebar of thirty items in front of the content is thirty tab stops on every single page.

<a class="pj-skip" href="#main">Skip to content</a>
<a class="pj-skip" href="#nav">Skip to navigation</a>

.pj-skip {
  position: absolute;
  left: var(--space-4);
  top: calc(-1 * var(--space-9));      /* off-screen, still focusable */
  z-index: 100;
  padding: var(--space-2) var(--space-4);
  min-height: 44px;
  background: var(--color-primary);
  color: #fff;
  border-radius: var(--radius-md);
  transition: top var(--duration-standard) var(--ease-out);
}
.pj-skip:focus { top: var(--space-4); }

The target must be able to receive focus: <main id="main" tabindex="-1">. Without it, some browsers move the viewport but leave focus at the top of the document, and the next Tab lands back in the navigation.

Landmarks

The page shell maps onto landmarks one-to-one. Use the elements, not role attributes on divs:

Two nav elements on a page need two different aria-labels. An unlabelled pair is announced as “navigation, navigation”.

Headings are a real hierarchy, not a type ramp: one <h1> per page, no skipped levels. If a heading is the wrong size, restyle it — do not renumber it.

Focus visibility

Focus is always visible. The system never sets outline: none without replacing it with something at least as loud.

The focus ring is a 2px orange-10 (#cc4528) outline at 2px offset, drawn with :focus-visible so a mouse click on a button does not leave a ring behind while keyboard focus still does.

:focus-visible {
  outline: 2px solid var(--color-accent-solid);
  outline-offset: 2px;
}

The offset matters: at 0 the ring sits on the control’s own border and disappears against an outline button, whose border is already the accent.

Moving focus

Focus moves only in response to something the user did, and it always ends somewhere they can see.

Modals and drawers trap focus while open and close on Esc. Everything else must not trap: a Tab inside a table, a card, or a tab strip leaves it again.

Deleting a row without moving focus leaves it on a detached node, which drops the keyboard user back at the top of the document — a silent, common, and entirely avoidable regression.

ARIA for the composed patterns

The components page shows tabs, navigation, status, and overlays as markup. This is what each owes assistive technology once it is real.

Tabs

pj-tabs is a tab strip, so it needs the full pattern: role="tablist" on the container, role="tab" with aria-selected on each tab, role="tabpanel" with aria-labelledby on each panel. Arrow keys move between tabs; Tab leaves the strip entirely — only the selected tab is in the tab order.

If arrow-key navigation is not implemented, do not use the tab roles. A tablist that does not respond to arrow keys is worse than a list of links, because it has promised behaviour it does not have.

Navigation

The current page in a pj-sidebar or pj-navbar is marked aria-current="page". The 600-weight and the accent underline are the visual half of that statement; aria-current is the other half, and neither substitutes for the other.

Status and semantic colour

Every pj-status dot is paired with its text label. That rule appears on the components page as a visual-design rule; it is also the accessibility rule, and it is why the system has no bare-dot variant to reach for.

Live regions announce changes that happen without a user action:

Reserve assertive for things that interrupt correctly. An assertive region that fires on every keystroke makes the page unusable with a screen reader.

Icons

An icon that repeats its label is aria-hidden="true". An icon that is the control carries the accessible name: <button aria-label="Security settings">. See Icons.

Tables

A pj-table uses <th scope="col">, and scope="row" on the identifying column. Sortable headers carry aria-sort="ascending" | "descending" | "none", updated when the sort changes — the arrow glyph alone is not announced. Multi-level headers need scope="colgroup" on the group row.

Motion and preference

The motion rules are an accessibility requirement, not a stylistic one. Everything animated is wrapped in prefers-reduced-motion: no-preference, or neutralised under reduce.

Skeletons stop shimmering under reduce but stay visible — the loading state is information, and removing it would remove the information along with the motion.

What to check before shipping a screen

1. Tab from the address bar to the end. Focus is visible at every stop and the order matches the visual order.
2. The skip link is the first stop, and using it lands focus in <main>.
3. Nothing is reachable only by mouse; nothing is reachable only by keyboard.
4. Every image, icon button, and form control has an accessible name.
5. Zoom to 200% and to 400%. Nothing is clipped; nothing scrolls in two directions at once.
6. Turn colour off — greyscale the screen. Every state is still distinguishable.
7. Contrast every new pairing against its actual surface, not against white.

4 - Themes

This section contains guidance for configuring selected theming frameworks to use the projectious.work brand.

The Hugo guide combines the implementation contract, theme-specific guidance, and review fixtures in one page. It currently contains configurations for Docsy and Hextra.

The Terminal guide covers the sixteen-colour ANSI palette and the configuration that applies it to tmux, WezTerm, Kitty, Ghostty, iTerm2, and Zellij.

4.1 - Hugo

This page is the source of truth for rendering the projectious.work brand with Hugo. It answers which files supply the brand, where a theme may be changed, and how to prove the result is conformant.

Choose the Docsy or Hextra subsection after reading the shared contract. The examples use named values such as midnight-9 and accent-solid; resolve those names from the canonical token source when building a production theme.

Implementation Contract

This contract applies before choosing Docsy or Hextra. It gives a human implementer and an AI agent one unambiguous answer to the theme’s source of truth, customization boundary, and release evidence.

Inputs and ownership

A value copied from a code example is an illustration, not a replacement for the source of truth.

File boundary

Keep the theme dependency and the branded site separate. This lets a theme upgrade remain a small, reviewable dependency change.

site/
├── hugo.yaml
├── assets/
│   ├── css/custom.css                    # Hextra adapter
│   └── scss/
│       ├── _variables_project.scss       # Docsy Bootstrap variables
│       ├── _variables_project_after_bs.scss
│       └── _styles_project.scss          # Docsy component overrides
├── layouts/_shortcodes/                  # Hextra: pj-callout only
├── static/
│   ├── images/                           # supplied logo variants only
│   └── favicons/                         # supplied favicon variants only
├── content/docs/                         # navigation and page content
└── themes/ or go.mod                     # pinned theme dependency

Do not place project branding under a vendored theme directory. Use only the documented extension point first; document any deliberate exception in the theme’s upgrade notes.

Non-negotiable visual rules

1. Use Plus Jakarta Sans for headings, Source Sans 3 for reading copy, and IBM Plex Mono for code.
2. Use accent-solid (#cc4528) for a single primary action per view. Its white label meets the normal-text contrast floor; identity orange does not automatically do so.
3. Keep ordinary links blue. Accent colour is emphasis, not the default link colour.
4. Keep code surfaces dark in both light and dark modes. Syntax tokens must be tested against that dark surface.
5. Use quiet surfaces, token borders, and modest radii: 3px small, 6px normal, 9px large. Do not introduce gradients or oversized shadows.
6. Support a user-controlled light/dark mode when the selected theme supports it. Test both modes independently; never make a dark mode by inverting a light screenshot.
7. Make focus visible without depending on colour alone. The current-page marker, active navigation item, and alerts need a non-colour cue too.

The shared semantic layer

Both themes bind to one token set. A theme adapter may only map these names onto its own selectors; it may not redefine what a name means, and it may not introduce a colour that is not in this table. This is what makes a Docsy site and a Hextra site recognisably the same product, and it is the only reason the two dark modes can be reviewed against each other.

Every value below is a step from the canonical scales in brand/tokens/tokens.json. The ratio column is the measured contrast against the surface that role actually sits on.

Four rules follow from the table and are not negotiable per theme:

Surfaces come off the ramp in step order, in both modes. The step roles are not decorative: step 1 is the app background, step 2 the subtle section band, steps 3–5 element fills, hover and active. Light mode used pure white as its canvas for a while, which reads fine on its own but leaves a card with nothing to lift off — a white panel on a white page separates by border alone, and the elevation scale has no room to work. Taking the canvas to step 1 puts white back where it is useful, as the raised surface.

The accent has a text step and a solid step, and they are different. Step 10 is “solid hover” — a surface role. Accent used as text, which in practice means a link hover, takes step 11, the scale’s low-emphasis text step. Solid accent fills keep step 10 with a white label. Using step 10 as text is the most common way this system gets bent: it passes on white at 4.72:1 and then fails the moment the surface underneath is anything but pure white.

There are two text tiers, not three. --pj-text and --pj-text-secondary are the only text colours. The scales define steps 11 and 12 as the text roles; a third “muted” tier has to come from step 9 or below, and no step below 11 clears 4.5:1 against the dark surfaces. If copy is not important enough for --pj-text-secondary, it is not important enough to ship.

The primary action is one colour in every mode and both themes. Fill --pj-action, hover --pj-action-hover, label always white. It does not lighten in dark mode and the label never changes colour, because every alternative either drops white below 4.5:1 or forces the label to invert on hover. Signal the dark-mode hover with the focus ring and elevation instead.

The warning border is gold, not the accent. #e05232 is the identity colour; using it as the warning edge makes every warning read as a brand flourish and makes the accent read as an error. Gold #8b6508 and #e0a92a carry the warning role in the two modes.

The header may be the one neutral surface. The default is a navbar that takes the canvas colour, so the reading surface runs unbroken from the top of the window. A site whose dark mode needs more separation may instead give the header the slate ramp — #20262c, 1.18:1 against the navy canvas — which leaves navy as the only saturated surface and lets the content read as the page rather than as another bar. The documentation site does this. Pick one and apply it in both themes; what is not allowed is a header in a third colour that is neither the canvas nor a documented surface step.

Dividers are quiet, and they are never the accent. A brand-coloured divider is a recurring request and the answer is no: the accent marks the one action a view is asking for, and a page whose every rule is orange has spent it. Orange is also poor as a line — 3.87:1 on white and 4.67:1 on midnight, loud enough to read as content and muddy at 1px. Where a divider needs more presence, raise its contrast and leave its weight at 1px; a 1px rule at 1.55:1 reads crisper than a 2px rule at 1.2:1 and stays out of the reading path. The accent may take one structural job per page — the documentation site uses a 40px accent lead-in on the section rule under each H2 — but never the rule itself.

--pj-border is a divider that groups content; it sits below 3:1 and that is correct, because the content it separates carries its own contrast. --pj-border-strong is for an input or control whose edge is the only thing announcing that it is interactive, and it clears 3:1 in both modes.

Required page states

Review these states with real content before approving the theme. A theme that only renders the home page is not complete.

Release evidence

Attach or record the following for a theme change:

• the pinned theme version and the official API/configuration pages consulted;
• screenshots at 320px and 1280px in light and dark mode;
• keyboard evidence for the navbar, sidebar, search, theme toggle, and a primary action;
• automated build output and a manual check at 200% zoom;
• a list of project override files, confirming that no vendored theme source was edited.

The Docsy and Hextra review fixtures below use comparable content states so visual regressions during a theme migration are easy to see.

Docsy

Open the Docsy example to inspect the documented patterns in a working site.

Docsy is Hugo’s Bootstrap-and-SCSS documentation theme. Its documented project SCSS files are the supported customization seam; this is where the brand belongs. Do not edit themes/docsy/.

What conformant looks like

Use a confident but quiet technical shell: a light navigation bar, a clear page title, white reading surfaces, and cards or callouts only where they help scanning. Reserve dark surfaces for code, the footer, and dark mode.

Heading hierarchy example

The page title Hugo contains H2 sections, such as Docsy, and each H2 can contain H3 subsections. H4 headings provide one further detail level. Hugo’s table of contents is configured to include headings through H4.

Install and configure the theme

Use the current Docsy installation method selected by the site (Hugo module, submodule, or checked-in theme). Keep the version pinned and upgrade it in its own pull request. The Docsy content guide documents the docs content type and its generated nested side navigation.

For a site rooted at src/, this is the relevant shape of hugo.yaml:

theme: [docsy]
enableGitInfo: true

markup:
  goldmark:
    renderer:
      unsafe: true # only when reviewed Hugo/HTML examples require it
  highlight:
    noClasses: false

params:
  ui:
    navbar_logo: true
    navbar_theme: light
    showLightDarkModeMenu: true
    sidebar_menu_compact: true
    sidebar_menu_foldable: true
    sidebar_search_disable: false
  copyright:
    authors: "Projectious"
    from_year: 2026

menu:
  main:
    - name: Documentation
      url: /docs/
      weight: 10

Keep pages under content/docs/. A section _index.md creates a sidebar group; descendant page weight values create a deliberate order. The following is enough to make a new group and pages appear as a nested Docsy sidebar menu:

content/docs/
└── platform/
    ├── _index.md       # title: Platform; weight: 40
    ├── deployment.md   # title: Deployment; weight: 10
    └── operations.md   # title: Operations; weight: 20

For a complete local kitchen-sink implementation, see the Docsy example. It is built manually with the scripts in examples/hugo-docsy/ and deployed beneath the GitHub Pages site.

Use title, linkTitle, description, and weight in front matter. A description also feeds document summaries and search metadata. Internal links use relref, so a changed base URL cannot silently break them.

Map the brand into Bootstrap and Docsy

Docsy reads project styles from assets/scss/ before theme styles. Place the following files in the site, not in the theme:

src/assets/scss/
├── _variables_project.scss
├── _variables_project_after_bs.scss
└── _styles_project.scss

Start with Bootstrap’s semantic roles, rather than assigning a brand colour to every individual selector.

// assets/scss/_variables_project.scss
$primary: #1d3352;   // midnight-9: headings, stable navigation
$secondary: #546a82; // slate-9: secondary UI
$success: #2f7d65;
$info: #3a5a82;
$warning: #8b6508;
$danger: #a8261c;

// slate-7 is a hairline, not a control edge: it measures 2.13:1 on white and
// leaves an input with no perceivable boundary. Use the strong border step.
$input-border-color: #546a82;

$font-family-sans-serif: "Source Sans 3", system-ui, sans-serif;
$font-family-monospace: "IBM Plex Mono", ui-monospace, monospace;
$headings-font-family: "Plus Jakarta Sans", system-ui, sans-serif;
$headings-font-weight: 700;
$body-line-height: 1.65;
$border-radius-sm: 3px;
$border-radius: 6px;
$border-radius-lg: 9px;
$enable-gradients: false;