Business card

The digital-first vCard, shared by QR code or link.

The primary format is digital — a vCard shared via QR code or direct link, not a printed card.

Paper stock#

The same card on white. This is the form to hand a printer when a physical card is required, and the one to reach for when the card will sit on a light surface it does not control — a conference badge holder, a scanned page, a slide.

Three things change, and nothing else does:

The wash does not survive the change of surface. At 12% on midnight it reads as a soft light source; at 12% on white it reads as a printing fault — an uneven patch of ink that a press will faithfully reproduce. So the accent moves to a rule down the leading edge, which is one line, prints cleanly at any size, and is the same device the signature uses.

The name, role, and contact rows keep their type sizes and weights exactly. Only their colours change, to the light-mode text steps: midnight-9 for the name, slate-9 for the role at 5.58:1, and slate-11 for the mono rows at 5.18:1.

Layout#

• Midnight surface, mark top-left, name in Plus Jakarta Sans 700.
• Role in Source Sans 3 400, in slate-dark-11.
• Contact rows in IBM Plex Mono at 11px — addresses and handles are data, and monospace makes them scannable and unambiguous.
• projectious.work always present.
• Accent used once, on the QR frame or the primary contact method.

Print fallback#

If a printed card is required:

• 85×55mm, matte stock.
• Single-colour midnight on uncoated white, or reversed white on midnight.
• Use the monochrome mark — no accent on press unless a spot colour is budgeted.
• Reserve clear space equal to half the mark’s height on every side; do not bleed the mark to the trim edge.

Handing colour to a printer#

The brand is defined in sRGB hex. Press is not sRGB, so a printed card needs the values converted — and the conversion is the vendor’s job, not a lookup table’s.

Give the printer the Lab values. They are device-independent: they describe the colour itself rather than one recipe for making it, so the vendor can hit them on whatever stock and profile the job actually runs on.

Do not guess a Pantone equivalent. If the job budgets a spot colour, give the vendor the Lab value and let them specify the closest ink; a Pantone number picked from a screen swatch is a different colour with an authoritative name on it.

Colour

Three 12-step scales in two modes, their step roles, and the contrast rules that govern them.

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.

The light app background is midnight-1 (#f8f9fb), not white. White is the raised surface. Links use midnight-11, never the accent. Colour carries meaning: do not introduce bluish-purple gradients, rainbow categorisation, or decorative colour families.

• 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 dark terminal is the default and every colour in it is measured against midnight-dark-1. An optional light companion is available for explicitly light code and terminal panels; it is a separate measured palette, never an automatic colour-mode substitution. A terminal 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 each terminal palette is a companion to the three interface scales rather than another scale: sixteen fixed ANSI slots plus chrome, derived from the ramps and measured against its own background.

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 identity accent is never body text. Light-mode accent text uses orange-11 (#c04424); dark-mode accent text uses orange-dark-10 (accent-light, #ea7558). A solid control with a white label always uses accent-solid.

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.

Components

The component set as live specimens — buttons, inputs, cards, tables, navigation, feedback, overlays, and data display.

Every specimen on this page is live markup styled by the brand tokens, ported from the supplied kitchen-sink mockup. 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.

Hover is structural across components: primary surfaces move to opacity:.88 and card borders move to midnight-7. Pressed controls remain at their hover state and never scale down. Do not lighten or darken a brand colour to create an interaction state.

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 16px 24px, 1px slate-5 border, flat at rest. shadow-1 is reserved for hover; nested controls step down one radius.

Transparency is restricted. Use backdrop blur only for dark-on-dark modal scrims and dark-panel inner cards, where the inner surface is rgba(255,255,255,.04). Do not put frosted glass on a light surface. Tags and badges use solid pale tints, never alpha overlays.

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 dark by default. Use the complete light companion only for an explicitly light panel; never switch it automatically with interface mode. See Code.

Hugo

The projectious.work implementation contract and theme guidance for selected Hugo theme frameworks: [Docsy](https://www.docsy.dev/) and [Hextra](https://imfing.github.io/hextra/).

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 src/data/brand.yaml. 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.

Docsy#

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

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("/scss/main.css"); /* includes the self-hosted brand font faces */

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="callout callout--info">
  <span class="ico ico--sm" aria-hidden="true"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="9"></circle><path d="M12 8h.01"></path><path d="M11 12h1v4h1"></path></svg></span>
  <div class="callout__body">
    <div class="callout__title">Before you begin</div>
    <p>Run the validation command locally before requesting promotion.</p>

  </div>
</div>

## Validate the configuration

Use `src/data/brand.yaml` 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 src/data/brand.yaml 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#

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/main/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

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("/scss/main.css"); /* includes the self-hosted brand font faces */

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

Licensing

A split licence — brand assets are proprietary, code and tokens are MIT.

The repository carries two categories of intellectual property under different terms. The full text is in LICENSE.md; this page summarises it.

Brand assets — proprietary, source-available#

Everything representing the visual identity: logos, brand imagery, and the supplied design-system documents.

Document templates fall under these same terms: they embed brand identity (colours, fonts, tagline). You may use them as structural reference for your own templates, but not redistribute them with projectious.work branding intact.

Code, scripts, and tokens — MIT#

Source code, automation scripts, and configuration files (.py, .js, .sh, .json, .yaml) are MIT-licensed: use, copy, modify, merge, publish, distribute, sublicense, and sell, provided the copyright and permission notice travel with the software.

The design tokens — documented under Tokens — are in this category. The values are free to use; the marks are not.

What this means in practice#

For commercial inquiries or brand consent: info@projectious.work

Lockups

Four approved lockups, rendered live, and where each one belongs.

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 16px. Below that the inner rings collapse; use a wordmark or a purpose-built favicon instead. Any lockup with a wordmark must be at least 24px high.

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.

Status treatments

Text-first maturity labels for truthful portfolio presentation.

Required pattern#

Every project presentation must show a status as text. Color, icons, position, and motion may reinforce the label but must never replace it.

Do not substitute broad claims such as “platform”, “production-ready”, or “enterprise” unless the owning repository publishes evidence for that claim. Prefer narrow artifact categories: CLI, process layer, applied research, prototype, library, or supporting asset.

Accessibility#

• Keep the full status label visible at all viewport sizes.
• Pair every color with the status-specific shape in the table.
• Use normal text contrast of at least 4.5:1 and large-text/UI contrast of at least 3:1.
• Test light and dark variants independently.
• Do not encode a status change with animation alone.

The source templates use high-contrast neutral text and reserve accent color for a supporting rule. Maintainers must rerun local validation after changing colors.

Project examples#

Examples are prompts for maintainers, not permanent factual claims. Confirm each status and limitation with the owning repository before publishing.

Composed patterns

How the components combine into whole screens — the page shell, the KPI row, and the primary/secondary split.

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.

On a light marketing or documentation shell, the header uses sentence-case navigation, the lowercase brand lockup, and one accent action on the right. The footer places the brand mark left and page metadata right in the caption style. Headers may stick; decorative elements and other page furniture may not.

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#

The supplied dashboard mockup is 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.

The supplied mobile mockup is its narrow counterpart: 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.

Audio and video

Sonic identity and video production rules.

Audio identity#

Four defined cues. All are short, tonal, and mid-register — the audio equivalent of “slides into place, doesn’t bounce”.

Error is a single low note, not a buzz or a descending pair — it marks the event without scolding.

Video rules#

• Demos run at real time. No fast-forward, no speed ramps. If a step is slow, that is information the viewer needs.
• Transitions are a cut or a 200ms fade. No swoops, wipes, or 3D moves.
• All video uses midnight surfaces.
• Video never autoplays. Playback begins with a deliberate user action.
• Subtitles are always available.
• Export at 1080p minimum, 4K when possible.

Dark mode

Both modes are equally supported. The implementation rules that keep them in step.

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 dark by default, regardless of interface mode. An explicitly selected light code panel uses the complete light companion palette; it never switches automatically. 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
}

Email signature

A signature that survives every mail client, carries the details business mail is required to carry, and stays quiet on a white message.

Email is not the web. Every value below is a literal, every layout is a table, and nothing depends on a stylesheet the client is free to discard.

Two forms are supplied:

The signature#

Both specimens are rendered on white, because that is where a signature actually lives. The surrounding page has a colour mode; a mail message generally does not.

One rule, and it is vertical#

A signature accumulates dividers as it accumulates fields — one under the name, another above the legal block, another before the disclaimer — and each reads as a section break in a message that is not sectioned. On a white background the result is a small form stapled to the bottom of a letter.

So there are no horizontal rules at all. One vertical accent rule runs down the left of the whole block: it marks the signature as a unit, ties it to the brand, and costs one line instead of four. Everything else is separated by space and by type size.

Fields#

Replace every [PLACEHOLDER]. Delete any row that does not apply — the block is built so that removing a row leaves no gap behind it.

What the law asks for#

A starting point, not legal advice — confirm against your own jurisdiction before shipping a signature.

Construction#

Declaring white three times is not belt-and-braces#

It is the difference between a signature that survives dark mode and one that does not, and it is the most common way this block breaks.

<table … bgcolor="#ffffff" style="…background:#ffffff;background-color:#ffffff;…">
  <tr bgcolor="#ffffff" style="background-color:#ffffff">
    <td bgcolor="#ffffff" style="background:#ffffff;background-color:#ffffff;…">

A client that repaints a message for dark mode works element by element: it looks at each one, decides whether it has a background it should keep, and inverts the rest. Declare white only on the <td> and the <table> around it has no background to keep — so the cell stays white while its own container is repainted dark. The result is a white island with a dark halo, or worse, the dark text inverted to light and then drawn on the white cell that was kept.

Every enclosing element that has a painted area needs the declaration, and each one needs it in both forms: the bgcolor attribute, which Outlook’s renderer prefers, and background-color, because several clients strip the background shorthand while keeping longhands.

Colours#

Three families, which is what a signature should have.

Before shipping a change#

• Send to Outlook (Windows), Gmail web, Apple Mail, and one mobile client.
• Reply to that message twice and check how the signature looks quoted inside a thread.
• Turn on the client’s dark mode and confirm the hierarchy still reads.
• Forward it, to confirm nothing depends on the original message’s styles.

Social previews

Repository artwork that states category and maturity plainly.

Content model#

Every 1280×640 preview contains only:

1. projectious.work organisation mark and name.
2. Project name.
3. One narrow artifact category.
4. One complete maturity label from the status vocabulary.
5. An optional short limitation, never a marketing claim.

Keep the status label intact and save a project-specific SVG beside its source. Examples demonstrate the content structure; they are not evidence of current maturity.

Export and validation#

Run:

bash scripts/validate-portfolio-assets.sh
bash scripts/export-portfolio-assets.sh

The export script uses resvg when available and otherwise leaves the SVG source as the canonical reusable asset. Commit generated PNGs only when a repository needs them.

Source and generated exports use this repository’s split license. The projectious.work name and marks remain subject to the trademark terms. Record any third-party typeface, icon, logo, or screenshot in the provenance inventory before use. The supplied templates contain no third-party logos or screenshots.

Terminal

The default dark and optional light projectious.work terminal palettes, plus configuration for tmux, WezTerm, Kitty, Ghostty, iTerm2, and Zellij.

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.

Real terminal and code chrome stays dark by default. The design system also defines an optional light companion for deliberately light specimens. It is a separate explicit choice—not a colour-mode response—and every value is measured against its own surface.

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#