AI & Developer Experience

The urbicon CLI

One dev-dependency, @urbicon-ui/design, gives your agent the full design surface: component discovery, recipes, patterns, principles and the token reference — all pinned to the library version you installed. The same package closes the loop: generated markup is linted by urbicon validate (as an edit-time hook and a CI gate), judged against a scoring rubric, and design intent survives sessions in a design.manifest.md in your repo.

# One dev-dependency wires your agent into the design system
# (already there if you set the project up with `sv add @urbicon-ui`):
bun add -d @urbicon-ui/design

# Insert the agent context block (AGENTS.md), scaffold design.manifest.md,
# and optionally wire the edit-time hook + CI gate:
bunx urbicon init --hook --ci

# Done — the next agent session reads AGENTS.md and takes over.

Two commands, then hands-off. The context block tells your agent which commands exist and when to run them — so the commands below are what the agent executes, not a workflow you learn. Your touchpoints afterwards are reviews, not operations: the decisions the agent records in design.manifest.md show up in your git diff, and a red design gate shows up in CI.

# Knowledge — version-matched to the library you installed:

urbicon find "date input"          # fuzzy catalog search
urbicon get-component date-picker  # real API: props, variants, examples
urbicon recipe login               # production-ready Svelte 5 recipes
urbicon icons calendar             # icon discovery
urbicon pattern dashboard          # composition patterns per page archetype
urbicon principles --topic theming # design heuristics + paradigm profiles
urbicon css-reference intents      # the token truth: naming, dark mode, overrides

# The closed design loop — generate → validate → judge:

urbicon validate src/              # lint tokens, dark:/focus:, z-index; 0–100 scores
urbicon principles --rubric        # 8-criterion rubric to judge a generated UI
urbicon context                    # read the project's design memory
urbicon record-decision --title …  # write a decision the next session will see

llms.txt

Every component has its own llm.txt file with structured documentation. Agents can fetch it from the docs site, and urbicon get-component --section serves the same sections locally to minimize token usage.

# llms.txt (quick reference)
# llms-full.txt (complete API for every component)

# Per-component docs with 5 sections:
#   overview | examples | variants | api | slots
# e.g. /primitives/button/llm.txt

.cursorrules

IDE-specific guidance for AI code generation. Ensures generated code follows project conventions: barrel imports, semantic tokens, Svelte 5 runes, focus-visible, and more.

# .cursorrules — AI-specific guidance

# Imports: ALWAYS barrel imports
import { Button, Input } from '@urbicon-ui/blocks';

# Styling: ALWAYS semantic tokens
class="bg-surface-base text-text-primary"

# Focus: ALWAYS focus-visible (not focus)
class="focus-visible:ring-2 focus-visible:ring-primary"

# Svelte 5: ALWAYS runes
let { variant, intent } = $props();

How It Works

JSDoc annotations in component source files are the single source of truth. One edit automatically updates the documentation site, llms.txt files, and the version-pinned knowledge bundle the CLI reads.