Documentation

• 1: Foundations
• 1.1: Colour
• 1.2: Typography
• 1.3: Space, shape, and motion
• 2: Logo
• 2.1: Lockups
• 2.2: Usage
• 2.3: Files
• 3: Interface
• 3.1: Components
• 3.2: Dark mode
• 3.3: Code
• 3.4: Icons
• 3.5: Forms
• 4: Themes
• 4.1: Hugo
• 4.2: Terminal
• 5: Portfolio presentation
• 5.1: Status treatments
• 5.2: Social previews
• 5.3: Diagrams and demos
• 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: Social and OG images
• 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, 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:

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;
  }
}

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

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

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

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

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, 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;

Use the post-Bootstrap map file only when a named semantic role is genuinely missing:

// assets/scss/_variables_project_after_bs.scss
$projectious-colors: (
  "accent-solid": #cc4528,
  "surface": #f8f9fb,
);
$theme-colors: map-merge($theme-colors, $projectious-colors);

Then put type and shape rules in _styles_project.scss. Keep colour out of this part of the file — all of it belongs in the single colour layer below, so there is one place to look when a value is wrong.

// assets/scss/_styles_project.scss
@import url("https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=Plus+Jakarta+Sans:wght@400;500;600;700;800&family=Source+Sans+3:wght@400;500;600&display=swap");

h1, h2, h3, h4, h5, h6 { letter-spacing: -0.3px; }
code, pre { font-family: "IBM Plex Mono", monospace; }
.btn {
  border-radius: 6px;
  font-family: "Plus Jakarta Sans", sans-serif;
  font-weight: 600;
}
pre, .highlight { border-radius: 9px; }

How Docsy binds to the shared layer

Docsy’s colour work happens in two places: Bootstrap’s semantic variables, which Docsy and Bootstrap components read on their own, and a small custom property layer for the surfaces Bootstrap has no variable for. Do not restate hex values in component rules — bind to the token and let the mode switch do the work.

Bootstrap’s $warning is the gold from the shared layer, not the accent. Docsy’s [data-bs-theme] attribute is the mode switch; the same token names resolve differently under it, so no component rule needs a dark-mode variant.

Complete Docsy color layer

Add this to assets/scss/_styles_project.scss, after the Bootstrap variables in assets/scss/_variables_project.scss. It is the whole surface map: the custom properties, the Bootstrap variables they drive, and the component rules that Bootstrap does not cover.

// assets/scss/_styles_project.scss

:root,
[data-bs-theme="light"] {
  --pj-canvas: #f8f9fb;
  --pj-surface: #ffffff;
  --pj-surface-hover: #e2e9f2;
  --pj-text: #142438;
  --pj-text-secondary: #5c6f82;
  --pj-heading: #1d3352;
  --pj-link: #3a5a82;
  --pj-link-hover: #c04424;
  --pj-nav-active-bg: #d3deec;
  --pj-nav-active-text: #1d3352;
  --pj-border: #cdd0d5;
  --pj-border-strong: #546a82;
  --pj-focus: #cc4528;
  --pj-info-bg: #e2e9f2;      --pj-info-border: #7490b2;
  --pj-success-bg: #d1ebe0;   --pj-success-border: #2f7d65;
  --pj-warning-bg: #f5ecd0;   --pj-warning-border: #8b6508;
  --pj-danger-bg: #f9e3e1;    --pj-danger-border: #a8261c;
  --pj-navbar: rgba(248, 249, 251, 0.85);
  --pj-footer: #f0f3f8;
}

[data-bs-theme="dark"] {
  --pj-canvas: #0e1720;
  --pj-surface: #131e2b;
  --pj-surface-hover: #1a2b3e;
  --pj-text: #c5daf0;
  --pj-text-secondary: #97a8b8;
  --pj-heading: #c5daf0;
  --pj-link: #8aacc8;
  --pj-link-hover: #ea7558;
  --pj-nav-active-bg: #20354d;
  --pj-nav-active-text: #c5daf0;
  --pj-border: #263f5a;
  --pj-border-strong: #4d7098;
  --pj-focus: #f09878;
  --pj-info-bg: #1a2b3e;      --pj-info-border: #4d7098;
  --pj-success-bg: #18382d;   --pj-success-border: #6cc090;
  --pj-warning-bg: #3d1e13;   --pj-warning-border: #e0a92a;
  --pj-danger-bg: #3a1d20;    --pj-danger-border: #f08b80;
  --pj-navbar: rgba(14, 23, 32, 0.85);
  --pj-footer: #131e2b;
}

// Mode-independent. The code surface is dark in both modes by design.
:root {
  --pj-action: #cc4528;
  --pj-action-hover: #b84228;
  --pj-action-label: #ffffff;
  --pj-code: #0e1720;
  --pj-code-text: #c5daf0;
  --pj-code-chrome: #131e2b;
}

// Hand the tokens to Bootstrap so its own components follow without extra rules.
:root, [data-bs-theme="light"], [data-bs-theme="dark"] {
  --bs-body-bg: var(--pj-canvas);
  --bs-body-color: var(--pj-text);
  --bs-secondary-color: var(--pj-text-secondary);
  --bs-secondary-bg: var(--pj-surface);
  --bs-heading-color: var(--pj-heading);
  --bs-link-color: var(--pj-link);
  --bs-link-hover-color: var(--pj-link-hover);
  --bs-border-color: var(--pj-border);
  --bs-code-color: var(--pj-link); // Bootstrap's default is a pink outside the brand
}

// Bootstrap 5.3 composes most colours through `*-rgb` triplets rather than the
// hex variables — `a { color: rgba(var(--bs-link-color-rgb), var(--bs-link-opacity)) }`.
// Setting only `--bs-link-color` leaves every link on the theme's default. The
// triplets cannot reference a var(), so they are restated per mode.
:root, [data-bs-theme="light"] {
  --bs-body-color-rgb: 20, 36, 56;
  --bs-link-color-rgb: 58, 90, 130;
  --bs-link-hover-color-rgb: 204, 69, 40;
  --bs-emphasis-color-rgb: 20, 36, 56;
}
[data-bs-theme="dark"] {
  --bs-body-color-rgb: 197, 218, 240;
  --bs-link-color-rgb: 138, 172, 200;
  --bs-link-hover-color-rgb: 234, 117, 88;
  --bs-emphasis-color-rgb: 197, 218, 240;
}

// Docsy generates a per-block link colour for the landing blocks and applies it
// at `.td-box--x p > a`, which outranks a plain `.td-box--x a`. It also dims the
// active table-of-contents entry with a (0,3,1) selector. Match the shape of
// each rather than writing a weaker selector and reaching for !important.
.td-box--light p > a, .td-box--light span > a,
.td-box--white p > a, .td-box--white span > a { color: var(--pj-link); }
.td-toc #TableOfContents a.active { color: var(--pj-nav-active-text); font-weight: 600; }

// blocks/cover carries Docsy's `td-overlay--dark` scrim, which exists to darken
// a background photograph. With no cover image it only washes the surface grey.
.td-cover-block.td-overlay::after { background-color: transparent; }

// Shell. Navbar, sidebar and TOC share the canvas; borders and space separate
// them. No panel fills — the reading column is the only thing with weight.
.td-navbar {
  background: var(--pj-navbar);
  backdrop-filter: blur(12px);
  border-bottom: 1px solid var(--pj-border);
}
.td-sidebar,
.td-toc { background: var(--pj-canvas); border-color: var(--pj-border); }
.td-footer { background: var(--pj-footer); color: #c5daf0; }
.td-footer a { color: #8aacc8; }

// Navigation: quiet at rest, tinted pill when current, and a left marker so
// the current item is not signalled by colour alone.
.td-sidebar-link,
.td-toc a { color: var(--pj-text-secondary); }
.td-sidebar-link:hover,
.td-toc a:hover { background: var(--pj-surface-hover); color: var(--pj-heading); }
.td-sidebar-link.active,
.td-toc a.active {
  background: var(--pj-nav-active-bg);
  color: var(--pj-nav-active-text);
  font-weight: 600;
  border-radius: 6px;
  box-shadow: inset 2px 0 0 var(--pj-action);
}

.card { background: var(--pj-surface); border-color: var(--pj-border); border-radius: 9px; }
.table { --bs-table-border-color: var(--pj-border); }

.form-control, .form-select, .td-search__input {
  background: var(--pj-surface);
  border-color: var(--pj-border-strong);
  color: var(--pj-text);
}

.btn-primary {
  background: var(--pj-action);
  border-color: var(--pj-action);
  color: var(--pj-action-label);
}
.btn-primary:hover,
.btn-primary:focus-visible,
.btn-primary:active {
  background: var(--pj-action-hover);
  border-color: var(--pj-action-hover);
  color: var(--pj-action-label);
}

// The ring sits outside the control, so it never lands on the accent fill.
:focus-visible { outline: 2px solid var(--pj-focus); outline-offset: 2px; }

pre, .highlight, .td-content pre {
  background: var(--pj-code);
  color: var(--pj-code-text);
  border-radius: 9px;
}
.highlight .filename,
.td-click-to-copy { background: var(--pj-code-chrome); color: #97a8b8; }

.alert { border-left-width: 3px; color: var(--pj-text); }
.alert-info    { background: var(--pj-info-bg);    border-color: var(--pj-info-border); }
.alert-success { background: var(--pj-success-bg); border-color: var(--pj-success-border); }
.alert-warning { background: var(--pj-warning-bg); border-color: var(--pj-warning-border); }
.alert-danger  { background: var(--pj-danger-bg);  border-color: var(--pj-danger-border); }

Two details are easy to miss. The alert rule sets color explicitly: without it, a Bootstrap alert keeps its own tinted foreground and the dark-mode tints are unreadable. And the code block’s filename bar needs --pj-code-chrome, because the surface underneath it is dark in light mode too — a theme that styles only pre leaves dark text on a dark bar.

Docsy exposes a light/dark menu through params.ui.showLightDarkModeMenu. Do not disable it for a branded site: add the dark values above and test them.

Brand every visible theme element

Page-part example

Use ordinary Docsy content and one primary action. This produces a direct, task-oriented block without turning documentation into a marketing page.

---
title: Deploy a provider
linkTitle: Deploy
description: Validate a provider configuration and promote it safely.
weight: 10
---

<div class="alert alert-info" role="alert"><div class="h4 alert-heading" role="heading">Before you begin</div>


Run the validation command locally before requesting promotion.
</div>


## Validate the configuration

Use `brand/tokens/tokens.json` as the input. Do not duplicate token values.

<a class="btn btn-primary" href="#deploy">Deploy configuration</a>

Review specimen

This is the Docsy review fixture: a content-led page that exercises hierarchy, link behavior, callouts, cards, code, status, and one primary action. The visual direction takes modular discovery cues from Kubeflow without copying its identity, assets, or page composition.

Ship a reliable integration

Use this specimen to inspect the actual Docsy shell, type scale, hierarchy, link behavior, callouts, cards, code treatment, and primary action in one place. The page must remain readable before any interaction is available.

Review release check

What the reader needs first

The table should remain inside a scrollable container on narrow screens. Link text remains blue, such as the token reference, while the accent-filled control remains reserved for the next action.

A card-led decision surface

Cards are scanning aids, not decoration. Their links remain links rather than becoming three competing primary actions.

Code remains a dark working surface

params:
  ui:
    navbar_theme: light
    showLightDarkModeMenu: true
  offlineSearch: true

Inline code such as brand/tokens/tokens.json must stay distinct from its paragraph without looking like a second button. The block above stays dark in both theme modes, with readable syntax and a discoverable copy control.

Status language is semantic

Release check

At 320px, check the menu, table overflow, cards, action, code block, and TOC. At 1280px, check reading measure, fixed navigation, sidebar hierarchy, and the balance between the content column and its table of contents. Repeat each check in light and dark modes with keyboard navigation and 200% zoom.

Accessibility and release gate

In addition to the shared contract, test Docsy’s menu, sidebar, search, light / dark control, code copy affordance, and Bootstrap callouts at 320px and 1280px. Do not let a project SCSS override remove focus indicators or semantic headings.

Sources and upgrade boundary

• Docsy: adding content
• Docsy: look and feel
• Hugo configuration

When updating Docsy, diff the generated output and re-check every override in assets/scss/; theme-internal SCSS is not a stable public API.

Hextra

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

Hextra is a Hugo documentation theme with a compact shell, generated side navigation, and a supported custom-CSS entry point. Use its quiet, task-focused reading model while retaining projectious.work typography, colour, assets, and interaction rules.

What conformant looks like

The reading column should stay calm: clear heading hierarchy, an unobtrusive sidebar, a useful table of contents, and one action only when the task calls for it. Avoid a copied product-marketing treatment, excessive card shadows, or a logo that competes with the page title.

Install and configure the theme

Pin the Hextra module or checked-in theme version. Keep the installation and theme upgrade separate from brand overrides. Hextra reads its site settings from hugo.yaml; its configuration guide documents navigation, sidebar, favicon, theme, search, and page settings.

module:
  imports:
    - path: github.com/imfing/hextra

enableGitInfo: true
markup:
  goldmark:
    renderer:
      unsafe: true # only for reviewed component examples
  highlight:
    noClasses: false

params:
  theme:
    default: system
    displayToggle: true
  navbar:
    displayTitle: true
    displayLogo: true
    width: wide
    logo:
      path: images/logo.svg
      dark: images/logo-dark.svg
      link: /
      width: 160
      height: 32
  page:
    width: wide
    displayPagination: true
  footer:
    width: wide
  search:
    enable: true
    type: flexsearch
    flexsearch:
      index: content
      tokenize: forward
  editURL:
    enable: true
    base: https://github.com/projectious-work/brand/edit/development/src/content

menu:
  main:
    - name: Documentation
      pageRef: /docs
      weight: 10
    - name: Search
      weight: 20
      params:
        type: search
    - name: Theme
      weight: 30
      params:
        type: theme-toggle
    - name: GitHub
      url: https://github.com/projectious-work/brand
      weight: 40
      params:
        icon: github

Hextra generates the main sidebar from the content directory. Create a folder with an _index.md to make a group, then set front-matter weights. Exclude utility pages with sidebar.exclude: true; hide a sidebar only when a page needs the additional reading width.

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 Hextra example. It is built manually with the scripts in examples/hugo-hextra/ and deployed beneath the GitHub Pages site.

Load the brand through custom CSS

Hextra automatically loads assets/css/custom.css. Use it as the single brand adapter. The Hextra customization guide documents its primary HSL variables, layout variables, and public component classes. The guidance below targets Hextra v0.10.0; pin that version, and re-check the four class names it depends on after any upgrade.

Hextra derives a ten-step --color-primary-* ramp from three HSL variables, and uses that ramp for the active sidebar item, the code-block tint, and several focus states. Two things about it decide whether a brand adapter works:

Set the primary variables under html.dark as well as :root. Hextra’s own stylesheet re-declares all three under .dark. An adapter that sets them only on :root gets brand colours in light mode and stock Hextra blue (204deg 100% 50%) in dark mode — on the current sidebar item, which is the most visible navigation state on the page.

Do not let the derived ramp reach the code block. Hextra tints code with bg-primary-700/5, which is a light wash. The brand keeps code dark in both modes, so the adapter overrides the pre inside .hextra-code-block — not the wrapper, which sits behind that tint and has no visible effect.

/* assets/css/custom.css */
@import url("https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=Plus+Jakarta+Sans:wght@400;500;600;700;800&family=Source+Sans+3:wght@400;500;600&display=swap");

/* midnight-9 #1d3352 expressed as HSL, so Hextra's derived ramp stays in the
   brand's hue rather than its default azure. */
:root {
  --primary-hue: 214deg;
  --primary-saturation: 47%;
  --primary-lightness: 22%;
  --hextra-max-page-width: 90rem;
  --hextra-max-navbar-width: 90rem;
  --hextra-max-footer-width: 90rem;
}

/* Required: Hextra re-declares these under .dark and would otherwise revert. */
html.dark {
  --primary-hue: 214deg;
  --primary-saturation: 47%;
  --primary-lightness: 62%;
}

@layer theme {
  :root {
    --hx-default-font-family: "Source Sans 3", system-ui, sans-serif;
    --hx-default-mono-font-family: "IBM Plex Mono", ui-monospace, monospace;
  }
}

The dark lightness is raised to 62% because Hextra reads primary-lightness as the mid of the ramp and derives dark-mode text roles above it. At the light value of 22% the dark sidebar’s active label resolves near-black on a dark tint.

How Hextra binds to the shared layer

Hextra marks the current sidebar entry with the hextra-sidebar-active-item class and the current TOC entry with hextra-toc-active. It does not emit aria-current, so an adapter written against a[aria-current="page"] silently styles nothing.

Complete Hextra color layer

Append this to the same assets/css/custom.css. The token block is byte-for-byte the Docsy one; only the selectors below it differ. Keep it that way — if the two adapters ever need different values, the shared layer is wrong, not the theme.

/* assets/css/custom.css — continued */

:root {
  --pj-canvas: #f8f9fb;
  --pj-surface: #ffffff;
  --pj-surface-hover: #e2e9f2;
  --pj-text: #142438;
  --pj-text-secondary: #5c6f82;
  --pj-heading: #1d3352;
  --pj-link: #3a5a82;
  --pj-link-hover: #c04424;
  --pj-nav-active-bg: #d3deec;
  --pj-nav-active-text: #1d3352;
  --pj-border: #cdd0d5;
  --pj-border-strong: #546a82;
  --pj-focus: #cc4528;
  --pj-info-bg: #e2e9f2;      --pj-info-border: #7490b2;
  --pj-success-bg: #d1ebe0;   --pj-success-border: #2f7d65;
  --pj-warning-bg: #f5ecd0;   --pj-warning-border: #8b6508;
  --pj-danger-bg: #f9e3e1;    --pj-danger-border: #a8261c;
  --pj-navbar: rgba(248, 249, 251, 0.85);
  --pj-footer: #f0f3f8;

  /* Mode-independent. */
  --pj-action: #cc4528;
  --pj-action-hover: #b84228;
  --pj-action-label: #ffffff;
  --pj-code: #0e1720;
  --pj-code-text: #c5daf0;
  --pj-code-chrome: #131e2b;
}

html.dark {
  --pj-canvas: #0e1720;
  --pj-surface: #131e2b;
  --pj-surface-hover: #1a2b3e;
  --pj-text: #c5daf0;
  --pj-text-secondary: #97a8b8;
  --pj-heading: #c5daf0;
  --pj-link: #8aacc8;
  --pj-link-hover: #ea7558;
  --pj-nav-active-bg: #20354d;
  --pj-nav-active-text: #c5daf0;
  --pj-border: #263f5a;
  --pj-border-strong: #4d7098;
  --pj-focus: #f09878;
  --pj-info-bg: #1a2b3e;      --pj-info-border: #4d7098;
  --pj-success-bg: #18382d;   --pj-success-border: #6cc090;
  --pj-warning-bg: #3d1e13;   --pj-warning-border: #e0a92a;
  --pj-danger-bg: #3a1d20;    --pj-danger-border: #f08b80;
  --pj-navbar: rgba(14, 23, 32, 0.85);
  --pj-footer: #131e2b;
}

/* Shell. Navbar, sidebar and TOC all sit on the canvas; a hairline and
   whitespace do the separating. */
body { background: var(--pj-canvas); color: var(--pj-text); }
.hextra-nav-container {
  background: var(--pj-navbar);
  backdrop-filter: blur(12px);
  border-bottom: 1px solid var(--pj-border);
}
.hextra-sidebar-container,
.hextra-toc { background: var(--pj-canvas); }
.hextra-footer { background: var(--pj-footer); color: #c5daf0; }
.hextra-footer a { color: #8aacc8; }

.content h1, .content h2, .content h3, .content h4 {
  color: var(--pj-heading);
  font-family: "Plus Jakarta Sans", system-ui, sans-serif;
  letter-spacing: -0.3px;
}
.content, .content p, .content li { color: var(--pj-text); }
.content a { color: var(--pj-link); }
.content a:hover, .content a:focus-visible { color: var(--pj-link-hover); }

/* Navigation. Quiet at rest, tinted pill when current, plus a left marker so
   the current item is not signalled by colour alone. */
.hextra-sidebar-container a,
.hextra-toc a { color: var(--pj-text-secondary); }
.hextra-sidebar-container a:hover,
.hextra-toc a:hover { background: var(--pj-surface-hover); color: var(--pj-heading); }
.hextra-sidebar-active-item,
.hextra-toc a.hextra-toc-active {
  background: var(--pj-nav-active-bg) !important;
  color: var(--pj-nav-active-text) !important;
  font-weight: 600;
  border-radius: 6px;
  box-shadow: inset 2px 0 0 var(--pj-action);
}

.hextra-card, .hextra-feature-card {
  background: var(--pj-surface);
  border-color: var(--pj-border);
  border-radius: 9px;
}
.hextra-card:hover { background: var(--pj-surface-hover); }

input, textarea, select, .search-input {
  background: var(--pj-surface);
  border-color: var(--pj-border-strong);
  color: var(--pj-text);
}

.pj-primary-action {
  display: inline-flex;
  align-items: center;
  min-height: 40px;
  padding: 0 16px;
  border-radius: 6px;
  background: var(--pj-action);
  border: 1px solid var(--pj-action);
  color: var(--pj-action-label);
  font-family: "Plus Jakarta Sans", sans-serif;
  font-weight: 600;
  text-decoration: none;
}
.pj-primary-action:hover,
.pj-primary-action:focus-visible {
  background: var(--pj-action-hover);
  border-color: var(--pj-action-hover);
  color: var(--pj-action-label);
}

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

/* Code stays dark in both modes. Target the `pre`, not the wrapper: Hextra
   tints the inner element and the wrapper's background never shows. */
.hextra-code-block pre,
.content pre {
  background: var(--pj-code) !important;
  color: var(--pj-code-text);
  border-radius: 9px;
}
.hextra-code-block .hextra-code-filename {
  background: var(--pj-code-chrome) !important;
  color: #97a8b8 !important;
}

/* See the note below: Hextra's own callout cannot be rebound from CSS. */
.pj-callout {
  margin: 24px 0;
  padding: 12px 16px;
  border-left: 3px solid;
  border-radius: 0 6px 6px 0;
  color: var(--pj-text);
}
.pj-callout-title {
  margin: 0 0 4px;
  font-family: "Plus Jakarta Sans", sans-serif;
  font-weight: 700;
  font-size: 0.9375rem;
}
.pj-callout-info    { background: var(--pj-info-bg);    border-color: var(--pj-info-border); }
.pj-callout-success { background: var(--pj-success-bg); border-color: var(--pj-success-border); }
.pj-callout-warning { background: var(--pj-warning-bg); border-color: var(--pj-warning-border); }
.pj-callout-danger  { background: var(--pj-danger-bg);  border-color: var(--pj-danger-border); }

Hextra’s built-in callout shortcode styles itself entirely with Tailwind utility classes and emits no stable class hook, so its semantic tints cannot be rebound from custom.css — a .hextra-callout-* rule matches nothing. The brand callout is therefore a small project shortcode in layouts/_shortcodes/pj-callout.html that emits the class names above; see examples/hugo-hextra/ for the implementation. Give each type a text label as well as a colour, so the state never depends on colour alone.

Two further theme behaviours have to be answered, or the result fails contrast in light mode specifically:

Pin the syntax palette to the code surface. Hextra ships separate light and dark Chroma stylesheets and selects between them by mode. The brand keeps code dark in both modes, so in light mode the theme paints its light palette — navy keywords, near-black identifiers — onto a midnight surface at roughly 1.1:1. The brand syntax theme has to be restated for both modes, and at sufficient specificity: Hextra’s rules are .highlight .chroma .xx, and its dark variant .dark .highlight .chroma .xx, so a two-class selector loses no matter what order the stylesheets load in.

Restate link colour on components that carry their own. Hextra colours every link inside .content, and .content a outranks a single component class. A primary action and any specimen containing links will otherwise have their labels repainted blue — including white-on-accent labels, which drops them to 1.5:1.

.content a.pj-primary-action,
.content a.pj-primary-action:hover { color: var(--pj-action-label); }

The !important declarations are deliberate and limited to three places where Hextra applies a Tailwind utility directly in its markup — the active navigation item, the code surface, and the filename bar. A utility class in the template always outranks a stylesheet selector, so this is the documented extension point behaving as designed, not an override of theme internals.

Brand every visible theme element

Page-part and review fixture

Use the same content states as the Docsy review specimen above so theme migrations compare like with like. Hextra expresses the callout, cards, and action through its documented shortcodes and one project CSS adapter:

---
title: Ship a reliable integration
description: A task-focused theme review fixture.
weight: 10
---

{{< callout type="info" >}}
Validate the configuration locally, then request promotion.
{{< /callout >}}

<a class="pj-primary-action" href="#release-check">Review release check</a>

## What the reader needs first

| Area | State | Owner |
|---|---|---|
| Configuration | Validated | Platform team |
| Documentation | Reviewed | Technical writer |
| Release | Waiting for approval | Release manager |

{{< cards >}}
  {{< card link="#validate" title="Validate"
      subtitle="Check tokens, configuration, and internal links" >}}
  {{< card link="#review" title="Review"
      subtitle="Confirm accessibility in light and dark modes" >}}
  {{< card link="#release-check" title="Promote"
      subtitle="Create a release from verified content" >}}
{{< /cards >}}

## Code remains a dark working surface

```yaml
params:
  theme:
    default: system
    displayToggle: true
```

## Release check {#release-check}

Check 320px and 1280px widths, keyboard focus, 200% zoom, and both modes.

Intended shell anatomy

┌─────────────────────────────────────────────────────────────────────┐
│ projectious.work      Documentation  Search  Theme                  │
├───────────────┬───────────────────────────────────────┬─────────────┤
│ Foundations   │ Platform operations                    │ On this page│
│ Themes        │ Ship a reliable integration            │ What reader │
│   Hugo        │ One concise explanation.               │ Cards       │
│               │ [Review release check]                 │ Code        │
│               │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Status      │
│               │ │ Validate │ │ Review   │ │ Promote  │ │             │
│               │ └──────────┘ └──────────┘ └──────────┘ │             │
└───────────────┴───────────────────────────────────────┴─────────────┘

This is an anatomy diagram, not a prescribed pixel layout. Keep Hextra’s native responsive behavior. At smaller widths, the sidebar and TOC become available through the theme’s controls; the reading order stays header, title, explanation, action, and content.

Hextra acceptance cues

Do not add a custom page template merely to achieve this fixture. Hextra’s content tree, documented cards and callout shortcodes, and one project CSS adapter should be sufficient. Use a layout override only when documented configuration and public component classes cannot meet an explicit product requirement; record the maintenance cost alongside the override.

Accessibility and release gate

In addition to the shared contract, test Hextra’s sidebar, TOC, search, theme toggle, cards, callouts, logo/favicons, code contrast, and custom action at 320px and 1280px. Do not let a custom CSS override remove focus indicators, semantic headings, or text selection.

Sources and upgrade boundary

• Hextra configuration
• Hextra customization
• Hugo configuration

When upgrading Hextra, compare the generated shell before and after the change. Limit overrides to documented settings and public classes; a copied theme template becomes the project’s maintenance burden.

4.2 - Terminal

This page is the source of truth for rendering the projectious.work brand in a terminal. It answers which sixteen colours the brand uses, which program owns each part of the result, and how to prove a configuration is conformant.

The terminal is where the brand’s rule that code surfaces stay dark in both modes stops being a stylistic choice and becomes the only option: a terminal has one surface, it is dark, and everything is measured against it.

Implementation contract

What owns what

A terminal’s appearance is produced by two programs that do not overlap, and almost every “my theme is wrong” report is a confusion between them.

A multiplexer cannot fix a wrong ANSI palette, and an emulator cannot style a status bar. Configure the emulator first; a multiplexer theme applied over an unbranded emulator will look wrong no matter how carefully it is written.

Inputs and ownership