# 8i Brand and Interface System

Version 0.1 — 8 September 2026

This document is the implementation contract for designers, developers and AI agents working on 8i public websites, guides, knowledge interfaces and tools. Use it together with `assets/data/design-tokens.json`, the rendered style guide at `/guide/style/`, and the agent brief at `/guide/style/AI.md`.

## Project structure

- `assets/css/` — page and component stylesheets.
- `assets/js/` — page behaviour and canvas scenes.
- `assets/data/` — machine-readable design tokens.
- `assets/docs/` — implementation guidance for people and agents.
- `assets/icons/` — organisational intelligence icons.
- `assets/*.svg` — approved brand marks.
- Site entry pages remain at the project root. Keep `robots.txt` at the root so crawlers can discover it.

## Core idea

8i turns a higher illuminating principle into practical organisational intelligence. The interface expresses this with a vertical spatial model:

1. **Principle** — light, perspective and orientation.
2. **Intelligence** — connected views and relationships.
3. **Practice** — tools, workflows, guides and data.
4. **Illumin8d** — an organisation that is aligned, understood and purposeful.

Spatial design supports this model. It must never make practical content difficult to read or use.

## Brand

Use the supplied `assets/8i-logo.svg`. Pair the mark with the full wordmark **8i.co.za** in headers and primary brand lockups. The accent system includes `8i-logo-accent-light.svg` for light surfaces and `8i-logo-accent-dark.svg` for blue or dark surfaces.

- Preserve the SVG proportions.
- Keep clear space around the lockup equal to at least the internal aperture of the mark.
- On light surfaces, retain illumination gold (`#f6cd49`) and use the specified soft blue shadow: `0 3px 5px #0f0fed38`.
- On blue or dark surfaces, use the yellow outer form with a `blue.50` centre.
- Keep the original single-colour blue or white mark available when the accent would compete with surrounding content.
- Do not stretch, rotate, outline, add additional effects to, or independently redraw the mark.
- Ephraim.ai is the illuminating principle; 8i.co.za is the practice. When both appear, show this relationship vertically.

## Colour

**8i blue `#0f0fed`** remains the primary pigment. Every dark, mid and light interface tone is a shade or tint of this blue. **Illumination gold `#f6cd49`** is the controlled accent.

Yellow represents illumination and activation. Use it for the primary action, active navigation markers, selected controls, small status details and one meaningful phrase in a conceptual composition. Keep it below roughly 5% of the visible screen. Do not use yellow for large page surfaces, body copy, every link, or decoration without meaning.

Use semantic tokens instead of direct colour values:

- `color.semantic.background` for the page.
- `color.semantic.surface` for cards and controls.
- `color.semantic.surfaceRaised` for elevated content.
- `color.semantic.action` for the primary action.
- `color.semantic.focus` for keyboard focus and selected structure.
- `color.semantic.text` and `textMuted` for copy.
- `border` and `borderStrong` for structure.

## Light and dark modes

Both modes use the same hierarchy and component geometry.

- Dark mode uses `blue.900` for the page, `blue.850` for surfaces and `blue.50` for primary text.
- Light mode uses `blue.50` for the page, `blue.100` for surfaces and `blue.900` for primary text.
- Primary actions use `accent.500` in both modes with `blue.950` text.
- Large yellow text uses `accent.500` in dark mode and `accent.700` in light mode for readable contrast.
- Respect the visitor’s system preference on first use and remember an explicit theme choice.

System states may not rely on hue. Pair every state with an icon, label and structural treatment:

- Success: check icon + SUCCESS label + solid border.
- Attention: exclamation icon + CHECK label + dashed border.
- Error: cross icon + ERROR label + heavier border.
- Loading: animated ring + LOADING label.
- Empty: open circle + EMPTY label + quiet border.

## Typography

The brand family is **Baloo Chettan 2**.

- Display and headings: weight 600.
- Body: weight 400.
- Interface emphasis: weight 600.
- Labels: weight 700 with wide tracking.
- File paths, code, data and machine-readable values: system monospace.
- Keep body text at 16px or larger.
- Keep paragraphs between 65 and 75 characters wide.
- Use sentence case for interface labels.
- Reserve uppercase for short eyebrows, categories and states.

## Layout and depth

Use the spacing scale in `assets/data/design-tokens.json`. Avoid one-off spacing values.

- Desktop pages use a 12-column grid and a maximum content width of 1180px.
- Practical reading content stays on a stable, high-contrast plane.
- Stars, perspective lines and glows belong behind content.
- Depth should show hierarchy or connection; decoration alone is not enough.
- Maintain generous space around major brand and conceptual moments.
- Data views can be dense, but their controls, rows and status information need clear grouping.
- Hide decorative depth when reduced motion is requested or when it competes with content.

## Component priorities

Reuse components in this order:

1. Existing semantic HTML element.
2. Existing 8i component from the style guide.
3. A documented variant of an existing component.
4. A new component added to the style guide before product use.

The minimum shared component set is:

- Global header and footer
- Breadcrumbs and side navigation
- Buttons, icon buttons and text links
- Chips, tags and status labels
- Tabs
- Cards and path cards
- Numbered steps
- Copyable prompt/code blocks
- Notices and contextual help
- Inputs, search, select, radio and toggle controls
- Data toolbars, tables, pagination and folder indexes
- Success, attention, error, loading and empty states

## Guided content

Guides are task interfaces. Each guide should contain:

1. A direct outcome-focused title.
2. One short sentence describing who the guide is for.
3. A compact method summary.
4. Ordered steps.
5. Copyable content where appropriate.
6. A contextual help route.
7. Public source links.
8. Updated metadata.

Keep platform or path choices in tabs or cards. Do not duplicate the complete guide inside every choice when the underlying steps are shared.

## Data interfaces

Large knowledge indexes and indexes need:

- A visible search or filter control.
- A clear count and current range.
- Human-readable title plus exact machine path.
- Content type and status.
- Responsive table handling.
- Folder-level navigation before very large file listings.
- Empty and fetch-error states.
- Direct source URLs that can be cited by people and agents.

Do not imply that catalog “In Stock” equals live warehouse quantity. Live prices, quantities and operational claims must come from the relevant current source.

#### Content voice

Write with calm confidence. Be direct, useful and human.

- Lead with the outcome or next action.
- Prefer short sentences and concrete verbs.
- Explain technical terms when they help someone decide or act.
- Keep labels literal.
- Avoid inflated claims, unexplained jargon and decorative copy inside practical tools.
- Always write **AM.CO.ZA** in client-facing content.
- Describe Advanced Machinery as **AM.CO.ZA / Advanced Machinery (Pty) Ltd, a South African company** when formal context is needed.
- Cite public source URLs used for facts.
- Never invent prices, stock quantities, performance results or customer outcomes.

## Accessibility

Every production component must:

- Work with keyboard navigation.
- Have a visible focus state.
- Use semantic HTML and native controls where possible.
- Expose selected, expanded, loading and error states to assistive technology.
- Meet WCAG AA text contrast.
- Respect `prefers-reduced-motion`.
- Keep touch targets at least 42px high.
- Avoid meaning conveyed only by colour, position or animation.
- Provide useful alternative text for informative images and empty alt text for decorative images.

## Agent contract

Before generating or editing an 8i interface, an AI agent must:

1. Read `assets/docs/brand-system.md` and `assets/data/design-tokens.json`.
2. Inspect the closest existing page and component implementation.
3. Reuse names, markup and tokens before adding a variation.
4. Keep the interface responsive, semantic and keyboard accessible.
5. Use the approved blue scale and the controlled yellow accent tokens; keep yellow below 5% of the visible composition.
6. Preserve supplied SVG artwork and icon proportions.
7. Treat business facts and live data as sourced content.
8. Add any necessary reusable pattern to `style-guide.html`, its stylesheet and this document.
9. Record deviations and the reason in the implementation notes.

## Reference surfaces

The initial component inventory was based on these functional surfaces:

- `/guide/` — guide index and path cards.
- `/guide/amcoza/ai-connect/` — platform tabs, ordered steps, prompt copy and help notices.
- `/guide/amcoza/ai-builder/` — technical cards, file lists, constraints and code-oriented content.
- `/data/amcoza/` — large indexes, folders, tables, metadata and public source links.

These pages define functional needs. This system defines the shared 8i visual and interaction language.


## Light lockup (light surfaces / light mode)

On light backgrounds the wordmark **8i.co.za** uses 8i blue `#0f0fed` (blue-500). The mark uses the warm-gold + blue “light” SVG (`/assets/8i-logo-accent-light.svg`) with a soft blue-tinted drop shadow. Do not render the light-surface wordmark in white, gold, or grey.


## Theme default and persistence

Default view follows the OS `prefers-color-scheme` (light/dark) on every public 8i.co.za page.

A manual toggle stores `sessionStorage` key `8i-theme` (`light`|`dark`) for the **browser tab session** — shared across the whole site origin in that session, not cookies, not `localStorage`. Closing the tab/browser (e.g. next day) clears it and the default returns to the system preference.

Boot snippet + `/assets/js/theme.js` apply the same rules site-wide.

## Asset URLs

Always use absolute URLs with domain, e.g. `https://8i.co.za/assets/8i-logo-accent-dark.svg`, so saved/downloaded HTML still loads CSS/JS/images. Never page-relative `assets/...`. Prefer domain form over root-relative `/assets/...`.