# Neutral Design System 1.0 Instructions for coding agents implementing Neutral interfaces. Read this file in full before changing product or marketing UI. ## Published guide and distribution - Human-readable guide: `https://computeneutral.com/brand/` - This implementation contract: `https://computeneutral.com/system/brand/agent.md` - Reusable installation prompt: `https://computeneutral.com/system/brand/INSTALL_PROMPT.md` - Machine-readable tokens: `https://computeneutral.com/system/brand/tokens/tokens.json` - Machine-readable components: `https://computeneutral.com/system/brand/component-catalogue.json` - Versioned release: `https://computeneutral.com/downloads/neutral-design-system-1.0.0.zip` When this file is installed locally, follow the local version and its adjacent assets so implementation remains reproducible. Agents without a local copy must use the official public entrypoints above and install the complete versioned system before changing Neutral UI. Do not scrape design values from the guide HTML when a machine-readable source exists. ## What Neutral is Neutral is the independent reliability layer for AI compute, connecting evidence across workloads and infrastructure to isolate likely failure domains, coordinate the next action and protect productive GPU time. The approved brand promise is: **Every compute hour, accounted for.** Automatic diagnosis, approved remediation and preventative operation belong to Neutral's product direction. Describe them as current capabilities only where the implemented workflow and evidence support the claim. Follow `brand/verbal-identity.md` for all public, product and technical language. The visual character is neutral in role, not vague in appearance: sharp, legible, operational and exact. The system supports light and dark product modes with one coherent structure. ## Sources of truth Install and follow these files together: - `brand/colour-system.md` - `brand/typography.md` - `brand/layout-system.md` - `brand/logo-system.md` - `brand/iconography/README.md` - `brand/iconography/MOTION.md` - `brand/data-visualisation.md` - `brand/product-components.md` - `brand/component-catalogue.json` - `brand/verbal-identity.md` - `brand/presentations/README.md` - `brand/presentations/manifest.json` - `brand/fonts/fonts.css` - `brand/fonts/instrument-sans/` - `brand/fonts/commit-mono/` - `brand/tokens/colours.css` - `brand/tokens/typography.css` - `brand/tokens/layout.css` - `brand/tokens/iconography.css` - `brand/tokens/data-visualisation.css` - `brand/tokens/components.css` - `brand/tokens/tokens.json` - `brand/iconography/manifest/icons.json` - `brand/iconography/manifest/motion.json` - `brand/iconography/generated/` - `brand/iconography/runtime/motion-controller.mjs` - Approved production files from `brand/logo-pack/` When a prose example conflicts with a token or explicit approved decision, stop and report the conflict. Do not silently invent a third value. ## Thirteen non-negotiable rules 1. Light canvases are Paper and dark canvases are Carbon. Linen is a secondary light surface, never the page canvas. 2. Use only the approved palette. Cobalt is the action and selection accent. Success, Warning and Error describe data state rather than brand personality. 3. Use Instrument Sans for interface and explanatory text. Use Commit Mono for metrics, evidence, identifiers, timestamps, logs and commands. Use Commit Mono 600 for glanceable operational text. 4. Poppins Black belongs only to the supplied logo artwork. Never typeset, redraw, recolour, crop or rearrange the logo. Use the Carbon square as the default favicon and app tile; Cobalt is an exceptional fallback only when monochrome cannot be used. 5. Use the four-pixel spacing foundation and group related content more tightly than unrelated content. 6. Geometry communicates role: `0px` structure, `2px` tags, `4px` controls and `8px` detached overlays. Capsules are functional exceptions. 7. Use one-pixel structural rules. Do not use decorative shadows, gradients, glass, glow or blur. 8. Use the canonical Neutral icons at `16`, `20` or `24px`. Preserve their geometry on hover and use motion only while the represented process is active. 9. Every interactive element has a visible `2px` Cobalt focus ring with a `2px` offset. Pointer targets are at least `32px`; touch targets are at least `44px`. 10. Do not fade text to manufacture hierarchy. Body text uses the primary role; metadata uses the explicit metadata role at full opacity. 11. Charts show quantities, units and operational thresholds and provide equivalent pointer, keyboard and touch inspection. They never animate on initial load or loop decoratively. 12. Respect light mode, dark mode and reduced motion. State and meaning never depend on colour, animation or hover alone. 13. Follow the approved verbal hierarchy and claim ladder. Put conclusions before evidence and actions; never promote an inferred failure domain into a definitive root cause or an ambition into a present-tense guarantee. ## Product versus communications The product uses Instrument Sans throughout interface copy and Commit Mono for technical information. Marketing may use the larger approved Instrument Sans display scale. Neither surface uses a replacement display face, and Poppins remains confined to the logo artwork. All surfaces use the same verbal identity. Product copy is shortest and follows the observed → inferred → impact → next action → owner sequence. Marketing may explain the commercial consequence, but it may not broaden the underlying claim. ## Creating branded presentations For PowerPoint or Google Slides, begin with `brand/presentations/README.md` and its machine-readable `manifest.json`. Reuse the supplied `.potx` template or copy the native Google Slides template; use the editable example charts and tables rather than recreating their styling. Public entrypoint: `https://computeneutral.com/system/brand/presentations/README.md`. Install the bundled desktop fonts for PowerPoint. Google uses the approved Consolas technical fallback. Copy and relink the Google Sheets chart source when a new deck needs independent data. Respect existing Google access permissions. All example numbers are illustrative and must be replaced before presenting. The presentation inventory records verification limits and provisional chart-grid styling. Its availability does not resolve the Ash/Stone source conflict or authorize a brand-token change. Update local distributed assets and inventory together, then publish the mirror; native Google files require their own update and verification. ## Redesigning an existing Neutral product Do not treat this system as permission to replace working product behaviour. Before editing: 1. Identify the framework, styling method, chart library and icon pipeline. 2. Capture representative routes in light and dark modes at wide, middle and narrow widths. 3. Inventory fonts, colours, opacity-based text, radii, shadows, gradients, spacing, focus, density, icons and motion. 4. Inventory behaviour for charts, time ranges, filters, URL state, caching, loading, inspection, tables, virtualization, permissions and responsive disclosure. 5. Produce a mapping table with: existing primitive, file locations, current behaviour, Neutral target, token mapping, risk and migration layer. 6. Preserve data queries, range values, aggregation, timezone, routes, permissions and state management unless a separate requirement changes them. 7. Migrate foundations, shared primitives, data primitives and route compositions in separate reviewable layers. 8. Record justified exceptions instead of creating an untracked second visual language. If the user has asked only for an audit, stop after the mapping and migration plan. If the user has asked for implementation, continue through the migration without asking for approval at every ordinary step. ## Installation approach - Keep a canonical copy of `tokens.json` and the relevant CSS tokens inside the product repository. - Integrate the tokens into the product's native theme layer. Do not introduce a parallel runtime styling system solely to preserve the reference class names. - Load the approved self-hosted fonts before colour, typography and layout tokens, then load component, icon and chart styles. - Self-host licensed production fonts when the app does not already provide them. - Copy only approved logo assets and required icon sizes. Do not redraw either system. - Add a short pointer to this file in the coding agent's instruction file so future interface work reloads the contract. Agent instruction locations may include: - Codex and compatible agents: `AGENTS.md` - Claude Code: `CLAUDE.md` - Cursor: `.cursor/rules/neutral-design-system.mdc` - GitHub Copilot: `.github/copilot-instructions.md` - Gemini CLI: `GEMINI.md` - Windsurf: `.windsurfrules` - Aider: `CONVENTIONS.md` Do not overwrite an existing instruction file. Append a clearly labelled Neutral Design System section and preserve all compatible repository rules. ## CSS load order When the reference CSS is used directly, load it in this order: 1. `fonts/fonts.css` 2. `colours.css` 3. `typography.css` 4. `layout.css` 5. `iconography.css` 6. `data-visualisation.css` 7. `components.css` Application-specific styles load after the Neutral files and may adapt composition, not fixed identity rules. A component-library or utility-framework adapter should preserve the same dependency order in its theme configuration. ## Charts and existing time ranges - Retain the current chart library if it can meet the contract accessibly. - Map current series, grids, thresholds, labels and tooltips to the data visualisation tokens. - Keep each feature's supported ranges and range order. Normalise only the visible compact label where semantics are identical. - Preserve a selected range through refetch and existing URL or navigation behaviour. - Keep valid data visible during background refresh. - Do not animate initial appearance. Animate a range or query transition for `200–300ms` only when the visible data changes. - An interrupted transition continues from visible geometry. - Pointer hover previews inspection; click or tap pins it; keyboard users receive the same values. - Use exact values and units. Never infer a zero from missing data. ## Components Map existing components to the contracts in `product-components.md`. Use `component-catalogue.json` as the complete machine-readable index and copy-ready reference markup. The classes in `tokens/components.css` are a reference output, not a requirement to discard established React, Vue, native or utility APIs. When a required component is not covered: 1. Start from the nearest component anatomy. 2. Use existing colour, type, spacing, radius and motion tokens. 3. Prefix new reference classes and tokens with `neutral-`. 4. Document the new component, its states, accessibility and responsive behaviour. 5. Report the addition so it can be considered for the canonical system. ## Verification before completion - Compare representative before and after routes without changing product semantics. - Verify light and dark modes. - Verify keyboard focus and reading order. - Verify reduced motion. - Verify pointer and touch targets. - Verify charts at narrow, middle and wide widths with real labels and extreme values. - Verify time range selection, URL state, refetch, loading, empty, stale, partial and error states. - Verify tooltip and pinned inspection with pointer, keyboard and touch. - Verify tables retain sorting, filtering, pagination or virtualization. - Search for unapproved colours, light font weights, text opacity, arbitrary radii, shadows, gradients and noncanonical icons. - Run the repository's tests, type checks and visual regression suite. At handoff, report what was mapped, what changed, what behaviour was preserved, any exceptions and the verification performed.