AI-ready Neon

Neon ist AI-ready, wenn Entscheidungen, Semantik und Grenzen so explizit sind, dass Agenten sie anwenden können, statt zu raten. Diese Seite beschreibt den Stack, den Readiness-Check und die Cursor-Einrichtung.

Drei Schichten Kontext

Schicht	Quelle	Zweck
Regeln	AGENTS.md in addxion-neon und addxion-com	Harte Grenzen (Repo, Prefix, Brand)
Strukturiert	packages/mcp/dist/catalog.json, tokens.json	Maschinenlesbare Components und Tokens
Abfragbar	MCP-Server @addxion/mcp	Tools zur Laufzeit in Cursor

addxion-neon/
  packages/components/src/*.meta.ts   # Usage, Anti-Patterns, Props
  packages/mcp/                       # stdio MCP + build-catalog
  packages/core/src/tokens/           # CSS SSOT + tokens.meta.ts

Docs und Demos leben in addxion-docs unter addxion.com/docs/neon/. Der Code bleibt in addxion-neon.

Readiness-Check

Bevor du Neon-UI per Agent erzeugst, solltest du diese Fragen mit „ja“ beantworten können:

1. Tokens: Kennt der Agent semantische Tokens (primary, text-muted) statt Hex-Werte?
2. Prefix: Wird überall tw: (Doppelpunkt) genutzt, nie tw-?
3. Components: Sind Props und Variants dokumentiert (Docs + *.meta.ts)?
4. Brand: Markenwerte nur in brand.css beim Consumer, nicht in addxion-neon?
5. Sections: Werden versionierte Sections (hero-v1) nicht in-place überschrieben?
6. Verifikation: Läuft bun run check in addxion-neon nach Änderungen grün?

MCP-Server einrichten

Der MCP-Server @addxion/mcp läuft lokal über stdio und wird von Cursor gestartet.

Voraussetzungen

Geschwister-Repos:

GitHub/
  addxion-neon/
  addxion-com/

In addxion-neon einmal installieren:

cd addxion-neon
bun install
bun run check

Cursor-Konfiguration

In addxion-com liegt .cursor/mcp.json:

{
  "mcpServers": {
    "addxion-neon": {
      "command": "bun",
      "args": ["run", "mcp"],
      "cwd": "../addxion-neon"
    }
  }
}

Cursor neu starten. Unter MCP-Einstellungen sollte addxion-neon mit grünem Status erscheinen.

MCP-Tools

Tool	Beschreibung
list_tokens	Semantic/Primitive Tokens mit Usage
find_component	Suche nach Name oder Use-Case
get_component	Volles Meta inkl. Anti-Patterns
get_pattern	Versionierte Sections (z. B. hero-v1)
list_rules	Harte Agent-Regeln

Resources

URI	Inhalt
neon://tokens	tokens.json
neon://catalog	catalog.json

Manuell testen

cd addxion-neon
bun run mcp

Der Prozess bleibt offen (stdio). Cursor startet ihn automatisch im Hintergrund.

Workflow mit Agenten

1. Briefing: Repo nennen, „Neon, kein Brand in addxion-neon, tw: Prefix“.
2. Kontext holen: list_rules, dann get_component oder find_component.
3. Implementieren: Existierende Patterns kopieren (z. B. Button, Hero v1).
4. Neue Komponente: .astro + *.variants.ts + *.meta.ts in addxion-neon, Docs in addxion-docs.
5. Prüfen: bun run check in addxion-neon; bun run build in addxion-docs (Docs) oder addxion-com (Consumer-Seiten)
6. Index: Bei neuen Docs-Seiten addxion-docs llms.txt; bei Marketing-Seiten addxion-com llms.txt.

Component Contracts (*.meta.ts)

Jede Primitive und Section hat eine Meta-Datei neben dem Quellcode:

packages/components/src/button.meta.ts

export const buttonMeta = {
  name: "Button",
  whenToUse: ["Primäre CTAs mit variant=\"primary\""],
  whenNotToUse: ["Status-Anzeigen (dafür Badge)"],
  antiPatterns: ["Keine Hex-Farben", "Prefix tw:, nie tw-"],
  // props, variants, related …
};

bun run export:catalog (Teil von check) generiert packages/mcp/dist/catalog.json.

Checkliste: neue Komponente oder Section

1. .astro + ggf. *.variants.ts in addxion-neon/packages/components/src/
2. *.meta.ts mit Usage, Anti-Patterns, Props
3. Export in meta/index.ts und package.json (Subpath)
4. Starlight-Doc unter src/content/docs/neon/ in addxion-docs
5. bun run check in addxion-neon
6. bun run build in addxion-docs
7. llms.txt im passenden Repo aktualisieren
8. MCP testen: get_component oder get_pattern

addxion.ai (später)

addxion.ai nutzt aktuell UUI, nicht Neon. Migration ist Phase ai-1 im Masterplan: Token-Mapping dokumentieren, neue Screens optional mit Neon. Kein Big-Bang. Siehe AI Architecture.

Anti-Patterns (Kurz)

• Gedankenstrich-Spam und KI-Floskeln in Copy vermeiden (siehe Documentation as Code)
• Keine erfundenen Token-Namen oder Component-Variants
• Keine Marken-Tokens in addxion-neon
• Keine Sections ohne Versions-Suffix (hero-v1, nicht hero)
• Keine Hex-Literale statt semantischer Tokens

Verwandte Docs

• Principles — SSOT, Brand Flexibility
• Architecture — Verweis auf MASTERPLAN.md
• Tokens — Semantic Referenz
• Repo Boundaries — addxion-neon ↔ addxion-com

Truths

ID	Wahrheit
T-PKG-NEON	Consumer-Einstieg: @addxion/neon, nicht @addxion/core
T-PLATFORM-SSOT	Plattform-Wahrheit nur in addxion-docs
T-DOCS-SYNC	Docs im gleichen PR-Zyklus wie Ökosystem-Code

Für Agents

Scope: Checkliste — Neon-Änderungen agent- und build-sicher machen.

• Vor Merge: bun run check in addxion-neon, bun run build in Consumern/Docs
• Manifest und Tokens konsistent halten
• Brand-Werte nicht in addxion-neon