| name | Axiom Docs | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| description | A precise, technical documentation system built on Fumadocs and made unmistakably Axiom. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| colors |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| typography |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| rounded |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| spacing |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| components |
|
Creative North Star: "The Precision Instrument"
Axiom Docs should feel like a well-calibrated instrument for technical work: exact without being brittle, information-dense without becoming noisy, and quiet enough that the reader's task remains dominant. Fumadocs supplies the documentation infrastructure; the visible system is Axiom's own, expressed through graphite surfaces, precise typography, compact controls, and a deliberately scarce orange signal.
The composition is centered around reading and scanning. Long-form articles use comfortable measure and strong vertical rhythm, while navigation, tables, query examples, and API controls become denser where comparison speed matters. The system is flat by default and gains depth through tonal layers, hairline borders, and clear state changes—not decorative effects.
It must never read as a stock Fumadocs theme, a generic documentation template, or a sparse marketing page. Every component should earn its space and expose its purpose immediately.
Key Characteristics:
- Precise, technical, and confident.
- Dark-first graphite surfaces with a complete light counterpart.
- Restrained Axiom Orange used as an interaction signal.
- Geist for fluent reading; Geist Mono for technical texture and control labels.
- Compact 2–4px working radii and a 4px spacing rhythm.
- Flat tonal layering, hairline borders, and shadows reserved for floating UI.
- Comfortable prose paired with dense, scan-friendly reference components.
The palette behaves like instrument markings on graphite: neutral surfaces carry the work, white establishes hierarchy, and Axiom Orange identifies the point of interaction.
- Axiom Orange: The brand and interaction accent. Use it for active tab indicators, focus emphasis, selected feedback, query highlights, and other small signals—not for large background fields.
- Information Blue: Reserved for semantic information and field focus where the implementation already uses a conventional input state. It is not the product's primary interaction color.
- Success Green, Warning Amber, and Destructive Red: Reserved for method badges, validation, notices, and true status communication.
- Graphite Canvas: The canonical dark page background and the deepest layer.
- Graphite Surface: The default dark control, code, and contained-content surface.
- Graphite Raised: The dark hover and nested-surface layer.
- Graphite Overlay: The dark popover and dialog layer.
- Signal White and Soft White: Primary and secondary dark-theme text, respectively.
- Muted Gray, Mid Gray, and Quiet Gray: Supporting text, metadata, breadcrumbs, inactive navigation, and low-priority chrome. The neutral text ramp is tuned so every rung that carries text clears WCAG AA in both themes: dark quaternary uses Mid Gray (#858585 ≥ 4.5:1), and in light the tertiary/quaternary rungs shift down one step (Graphite Copy / Quiet Gray) so the bottom rung still reads. Quiet Gray is never used for text at metadata scale on the light canvas.
- Paper White: The light-theme surface and inverse text reference.
- Graphite Copy: The primary long-form copy value in light mode, and the light-theme tertiary text rung.
Two accents need a darkened value to stay legible when they carry text on the light canvas, since the brand hues only reach ~3.6:1 there. These are theme-aware tokens (--color-accent-text, --color-warning-text) that resolve to the brand hue in dark and to the darker value in light:
- Accent Text (light #b8461d): Axiom Orange used as text or fill — search-match highlights, hovered links (5.1:1).
- Warning Text (light #92400e): Amber used as text — the API
REQUIREDmarkers (6+:1). - Method badges likewise carry theme-aware text colors: the bright dark-theme greens/blues/ambers/reds are replaced by darker values on the light tint so
GET/POST/PUT/DELETEclear AA in both themes.
The Orange Signal Rule. Orange marks an actionable or selected point and should occupy less than 10% of a typical screen. Its rarity gives it authority.
The Contrast Ladder Rule. Headings, strong text, body copy, metadata, and disabled content must remain visibly distinct. Never flatten them into one gray.
The Semantic Color Rule. Blue, green, amber, and red communicate state only. Never let them compete with Axiom Orange as brand accents.
Display Font: Geist (with system sans-serif fallbacks)
Body Font: Geist (with system sans-serif fallbacks)
Label/Mono Font: Geist Mono, with SF Mono and Menlo fallbacks; APL/MPL syntax titles may use the dedicated system-monospace query stack.
Character: Geist keeps long technical prose open and highly legible; Geist Mono adds exactness to code, labels, breadcrumbs, values, and reference controls. Weight and contrast create hierarchy before size does.
- Display (600, 44px, 48px): Landing-page statements only; reduce to 36px/40px on phones.
- Headline (600, 34px, 42px): Article titles; use the query monospace treatment for APL/MPL function and operator pages.
- Title (600, 24px, 31px): Primary article sections (h2) with balanced wrapping.
- Subsection (600, 20px/17px): Article h3 (20px) and h4 (17px), sized to stay clearly above the 16px body.
- Body (400, 16px, 1.75): Long-form reading in a 768px article column. The column is deliberately generous; body was lifted from 15px→16px to ease sustained technical reading.
- Intro (400, 18px, 29px): The first article summary; lower contrast than the title and more open than body copy.
- UI (450–600, 14px, 18px): Header nav, sidebar items, and drawer navigation. The whole nav system (header tabs, sidebar, dropdown menus) reads at 13–14px so navigation is comfortable, not cramped.
- TOC (450–550, 13px): Floating table-of-contents links.
- Label (450–600, 10–13px, 14–18px): Breadcrumbs, table headers, metadata, and compact technical chrome; uppercase only when the label is genuinely categorical. The
DOCSbrand badge is 14px mono with a 2px orange separator. - Code (400, 13px, 21px): Multiline code and API samples in the reading column; inline code scales to the surrounding prose (
.84em), except inside table cells where it inherits the 14px cell size. - Prose tables (400, 14px body / 550, 13px mono header): Content tables read at body-adjacent size, not label size.
The Reading First Rule. Long-form text lives in a fixed 768px column at 16px/1.75, and never inherits compact UI leading. Code, tables, and figures may use the full column; running prose shares the same width so the article reads as one measured block.
The Mono With Purpose Rule. Monospace means code, query syntax, identifiers, values, or technical chrome. It is never a blanket aesthetic applied to ordinary prose.
The Hierarchy Before Scale Rule. Use weight, contrast, and spacing before reaching for oversized typography.
The system is flat by default. Canvas, surface, raised, and overlay tones establish depth; a one-pixel border clarifies edges. Shadows are prohibited on ordinary cards, code blocks, tables, buttons, and navigation. They are reserved for floating menus and modal dialogs where separation from the page is structurally necessary.
- Overlay: A hairline outline plus a compact 8px/24px ambient shadow for menus and popovers.
- Dialog: A hairline outline plus a deeper 24px/48px ambient shadow for modal search and assistant surfaces.
- Focus: A two-stage ring that separates the control from the canvas and then communicates keyboard focus; orange is preferred for documentation controls, with semantic blue retained for established API form focus.
The Flat-by-Default Rule. If a surface is part of normal document flow, it gets tonal contrast and a hairline border—not a drop shadow.
The Structural Shadow Rule. A shadow is allowed only when the element floats above unrelated content and must communicate that change in layer.
- Shape: Compact rectangular controls with restrained corners (3–4px in the documentation UI).
- Primary: High-contrast inverse fill, 30px tall, with 10px horizontal padding and a 600-weight compact label.
- Hover / Focus: Shift one tonal step or reduce opacity slightly; keyboard focus uses a clearly visible two-pixel orange outline without moving layout.
- Secondary / Ghost: Hairline border or transparent fill, graphite tonal hover, and no decorative shadow.
- Style: Use only for compact status, source, or API-method metadata. Corners stay at 3px; labels are 9–11px monospace or compact sans.
- State: Color communicates the method or status and is always paired with text. Method-badge colors are theme-aware so they clear AA on both the dark and light tints. Avoid pill shapes for navigation or ordinary actions.
- Corner Style: Restrained 4px corners for search results, code, frames, tables, and API surfaces.
- Background: Canvas, surface, or raised neutral tokens according to nesting depth.
- Shadow Strategy: None in document flow; follow the Elevation rules for overlays only.
- Border: One-pixel neutral borders define grouping. Semantic notices (callouts) are the deliberate exception: a 3px semantic left rule, a subtle inert background, a soft 3px radius, and sans-serif body copy at 14px (never monospace — callouts are prose, not code).
- Internal Padding: Usually 12–16px; larger landing-page regions create separation with whitespace instead of card chrome.
- Style: Dark canvas or surface fill, one-pixel border, 4px radius, and compact 12–15px type. Search may read as a full-width prompt; API credentials remain clearly labeled fields.
- Focus: Visible border and ring with sufficient contrast. Placeholder text must remain readable and secondary to entered content.
- Error / Disabled: Use semantic color plus text or state attributes; never rely on color alone. Credential fields retain privacy annotations and session-only persistence.
- Style: The fixed 56px header, 260px desktop sidebar, and floating table of contents form one hierarchy. Header tabs and sidebar items are 14px sans; TOC links are 13px sans; sidebar group headers and breadcrumbs use monospace technical chrome. The nav system is sized for comfortable scanning, not maximum density. The sidebar sits on a recessed rail (
--bg-sidebar: true black in dark,gray-100in light) with a hairline right divider, so it reads a step below the brighter reading column — tonal contrast plus a border, never a shadow (see the Flat-by-Default Rule). - States: Hover uses a subtle tonal shift. The active section tab in the header carries a short orange underline at the header edge; active sidebar items gain stronger text weight and a clearly raised neutral background (lifted enough to read against the recessed rail). Orange stays confined to these small selected indicators.
- Mobile: Below the desktop breakpoint, top-level sections and the page hierarchy share one drawer. Never expose two competing hamburger menus.
Search and Ask AI share one modal entry point. The dialog uses a strong structural border, a 4px radius, and the dialog shadow; mode tabs, the query field, ranked results, assistant messages, sources, and composer remain visually distinct through dividers and tonal layers. Search must feel immediate, while the assistant loads only when requested and remains grounded in documentation sources.
Each article exposes a split "Copy page" control with a dropdown of page actions, styled as two-line items (bold action + muted description). Native actions come first — Copy page (Markdown for LLMs), View as Markdown, and Ask AI about this page (opens the grounded in-product assistant with the page as context) — then a divider and external hand-offs to Claude, ChatGPT, and Grok, each with its monochrome brand mark (never a generic external-link glyph) and a ?q= deep link carrying the page's Markdown URL.
Code samples use a surface background, 4px corners, high-contrast syntax themes, and copy controls that appear on hover or focus. Tabs use a compact monospace label and a short orange active indicator. Query examples and API samples share this language while retaining their specific actions and density.
Tables are bordered and scan-oriented. Prose content tables read at 14px sans body / 13px mono headers with ~9px cell padding; inline code in a cell drops its chip and inherits the cell size so identifier columns stay legible. The denser API schema tables keep their compact label-scale type. Nested API schema children are visibly indented, and locations or method metadata occupy dedicated columns or badges.
- Do make Fumadocs infrastructure disappear behind an unmistakably Axiom visual system.
- Do use Axiom Orange as a scarce interaction signal and keep status colors semantic.
- Do preserve the contrast ladder between headings, body copy, metadata, code, and disabled states in both themes.
- Do keep ordinary controls and containers at 3–4px radii with a compact 4px spacing rhythm.
- Do center the reading experience in the viewport, protect the 768px article column, and keep the landing-page TOC column reserved even when empty.
- Do use tonal layers and one-pixel borders for structure; reserve shadows for floating menus and dialogs.
- Do keep documentation, query reference, and API reference coherent while preserving their distinct controls and density.
- Do meet WCAG 2.2 AA, including keyboard access, visible focus, contrast, semantic structure, and reduced-motion behavior.
- Don't ship a stock Fumadocs theme whose framework defaults are more visible than Axiom's identity.
- Don't reproduce Mintlify's visual language or information architecture; Mintlify is migration context, not a design target.
- Don't create generic documentation templates with oversized rounded cards, pill-heavy controls, decorative shadows, or blue-as-default interaction color.
- Don't flatten the contrast hierarchy and make body copy, headings, labels, and code feel equally prominent.
- Don't use sparse marketing-page treatments that sacrifice technical density, navigation depth, or fast scanning.
- Don't add ornamental effects that compete with reading, including gratuitous gradients, glassmorphism, and animation without a functional purpose.
- Don't add a second mobile navigation trigger or detach top-level sections from the documentation hierarchy.
- Don't hide essential code actions from keyboard users even when pointer users reveal them on hover.