AI Agent Guide

This guide is for AI agents (Claude, Cursor, Copilot, Codex, ...) building interfaces with GNexus UI Kit — in Vue projects, plain HTML pages, or inside this repository.

It answers the two most common failure modes:

1. The agent invents its own component instead of using one from the kit → see Component selection.
2. The agent builds a custom component that drifts from the styleguide → see Building a custom component in the GNexus style.

The one rule

Before writing ANY markup, check the component selection table (or docs/catalog.json). If a component exists for the need, use it. Do not hand-roll buttons, modals, tabs, toasts, forms, badges or tables.

Raw markup is acceptable only for layout wrappers and content with no adapter component yet.

Required setup (once per app)

import "gnexus-ui-kit/dist/css/kit.css";
import "gnexus-ui-kit/dist/assets/fonts/phosphor-icons/src/css/icons.css";

Vue: use the adapter (gnexus-ui-kit/vue) — see docs/vue/ai-usage-guide.md for the full Vue contract. Vanilla JS: the bundle publishes GNexusUIKit.* on window — see docs/javascript.md.

Component selection

Every mapping below is generated from docs/catalog.json — the single source of truth. If your need is not in this table, search docs/catalog.json before inventing markup.

Rules that prevent drift

• Variants: only primary, secondary, accent, success, warning, danger, error, info. Never invent a variant name (danger and error render the same in most components).
• Icons: Phosphor only, always with the base ph class. Vue props: icon="ph-house" (prefix required). Raw HTML: <i class="ph ph-house"></i>.
• Colors: use design tokens, never raw hex values. In SCSS: $surface-panel-muted, $color-text-light, $color-primary, $color-secondary, $color-success/warning/error/info. In plain CSS (no build step): the tokens are exposed as custom properties in kit.css — var(--gn-color-secondary), var(--gn-surface-panel-muted), var(--gn-border-width-accent), var(--gn-space-4), var(--gn-motion-base), ... — plus the kit's component and utility classes (p-*, m-*, g-*, row, d-flex, text-*) instead of restyling.
• Spacing: $space-1 … $space-12 scale, never arbitrary pixel values.
• Focus: every interactive element shows a visible focus ring (@include focus_ring in SCSS).
• Hover: wrap hover styling in @include hover_touch so touch devices fall back to :active.
• Motion: $motion-fast (0.15s) / $motion-base (0.2s) / $motion-slow (0.28s) with ease. No decorative animation.

Building a custom component in the GNexus style

If — and only if — the catalog has no component for the need, build one, but it must look native. Checklist:

1. Surface: @include hard_panel — $surface-panel-muted background, 2px solid border ($border-width-base), light border-radius ($border-radius-md, 6px).
2. Accent: important panels get a thick left accent — @include hard_panel($border-color-muted, $border-width-accent) (6px left border).
3. Title: small, bold, uppercase ($font-size-sm, $font-weight-bold, text-transform: uppercase). No hero-size headings inside panels.
4. Text: $color-text-light for primary text, $color-text-medium for secondary/meta. Meta text uses $font-size-xs/$font-size-sm.
5. Typeface: IBM Plex Mono is already the base font — do not override font-family.
6. Interactive states: @include focus_ring on :focus-visible, @include hover_touch for hover affordances, transitions on $motion-fast/$motion-base.
7. Icons: <i class="ph ph-name"></i>, sizes from $icon-size-xs … $icon-size-xl.
8. State colors: $color-success, $color-warning, $color-error, $color-info — the same four the kit's badges/alerts/status cards use.

Do (matches the kit's own panels):

.my-widget {
  @include hard_panel($border-color-muted, $border-width-accent);
  padding: $space-4;
  transition-duration: $motion-base;
  transition-property: border-color;
  transition-timing-function: $motion-ease;

  @include hover_touch {
    border-color: $color-secondary;
  }

  &:focus-visible {
    @include focus_ring;
  }
}

.my-widget-title {
  font-size: $font-size-sm;
  font-weight: $font-weight-bold;
  text-transform: uppercase;
}

Don't (the classic drift):

// WRONG: invented palette, oversized rounding, random spacing, no focus ring
.my-widget {
  background: #1a1b26;
  border: 1px solid #333;
  border-radius: 14px;
  padding: 13px;
  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.4);
}

Full token reference: docs/style-guide.md. In plain CSS (no SCSS build) the same tokens are available as var(--gn-*) custom properties — see CSS custom properties below; the mapping is 1:1 ($color-secondary → --gn-color-secondary, $space-4 → --gn-space-4).

Paste this into the consuming project

Add this block to the consuming project's CLAUDE.md / AGENTS.md (whichever your agent reads), so the agent knows the kit exists:

## GNexus UI Kit

This project uses GNexus UI Kit (npm: `gnexus-ui-kit`). Rules:

- Before writing ANY UI markup, check the component catalog in
  `node_modules/gnexus-ui-kit/docs/catalog.json` (columns: need, component,
  props, useWhen). If a component exists for the need, use it.
- In Vue: import components from `gnexus-ui-kit/vue` (GnButton, GnModal, ...).
  In vanilla HTML: use the kit's documented classes, not custom lookalikes.
- Icons: Phosphor only — `icon="ph-house"` in Vue, `<i class="ph ph-house"></i>` in HTML.
- Variants: only `primary, secondary, accent, success, warning, danger, error, info`.
- Custom components must follow the GNexus recipe:
  `node_modules/gnexus-ui-kit/docs/ai-guide.md` ("Building a custom component").
- Full agent guide: `node_modules/gnexus-ui-kit/docs/ai-guide.md`

CSS custom properties

kit.css publishes the design tokens on :root as --gn-* custom properties, so plain-CSS consumers (no SCSS build) style on-palette without hex values:

.my-widget {
  background: var(--gn-surface-panel-muted);
  border: var(--gn-border-width-base) var(--gn-border-style-base) var(--gn-border-color-muted);
  border-left-width: var(--gn-border-width-accent);
  padding: var(--gn-space-4);
  transition-duration: var(--gn-motion-base);
}

Available groups: colors (--gn-color-*, 14), surfaces (--gn-surface-*), borders (--gn-border-*), focus (--gn-focus-*), motion (--gn-motion-*), typography (--gn-font-*, --gn-line-height-*), spacing (--gn-space-0 … --gn-space-12). The SCSS tokens remain the source of truth.

For maintainers of this repository

When working inside this repo, follow CLAUDE.md — it carries the repo workflow rules (demo sync, build verification, screenshot policy) on top of everything above.