Architecture

How Gremorie is organised at the repo level, and how distribution works for an AI-native system.

Repository structure

Gremorie is an Nx monorepo at usegremorie/gremorie (transferred from kalvner/shadng in Phase 0 of the migration). It hosts the Angular edition today; the registry, MCP server, and React edition land in later phases.

gremorie/
├── apps/
│   ├── docs/               # this site (Fumadocs)
│   ├── tokens/             # visual token editor (Phase 5: depends on @gremorie/react)
│   └── mcp/                # MCP server (Phase 4)
├── packages/
│   ├── ng-core/            # @gremorie/ng-core (Angular cross-category utilities)
│   ├── ng-ai/              # @gremorie/ng-ai (PromptInput, Attachments)
│   ├── ng-containers/      # @gremorie/ng-containers (ScrollArea, ...)
│   ├── ng-data/            # @gremorie/ng-data (Charts on D3)
│   ├── rx-core/            # @gremorie/rx-core (React cross-category utilities)
│   ├── rx-ai/              # @gremorie/rx-ai (React AI primitives, starting with PromptInput)
│   ├── cli/                # @gremorie/cli (the `gremorie` CLI)
│   ├── docs/               # Analog docs host (becomes docs-ng — Angular preview iframe)
│   ├── iap/                # IAP harness package
│   ├── playground/         # internal playground
│   ├── token-engine/       # @gremorie/token-engine — token graph / CSS parsing
│   ├── registry/           # @gremorie/registry (Phase 3)
│   ├── eslint-config/      # @gremorie/eslint-config
│   └── tsconfig/           # @gremorie/tsconfig
└── tools/                  # Nx generators and scripts

Token architecture (3 layers)

Three layers, each with a distinct responsibility:

Layer	Lives in	Naming	Changes
1. Primitive	`@theme {}` blocks	`--color-<palette>-<stop>`	Almost never (follows Tailwind)
2. Semantic	`:root` / `[data-theme]` selectors	`--<role>` (no prefix)	Per theme switch
3. Chart	`@theme inline {}` blocks	`--color-chart-<group>-<n>`	Per chart-data context

Editing a primitive cascades through every theme that references it. Switching data-theme="X" updates every semantic token in-place — components stay ignorant of which theme is active.

Categories (functional groups)

Components are organised by what they do, not what they look like. The canonical categories are:

Containers · Typography · Forms · Display · Data
Feedback · Navigation · Overlays · AI

AI is one category alongside the others — not a special case. The Angular edition starts with the AI category (PromptInput, Conversation, Message); the broader categories ship as the registry grows.

Distribution

Gremorie does not publish a versioned npm package as the primary delivery channel. Instead, components are installed as source via a registry: you copy the code into your project, edit it, and it becomes yours.

npx gremorie add ng-ai

The gremorie CLI reads the registry, fetches the requested item, and writes it into the consumer's project. An MCP server (Phase 4) reads the same registry and exposes tools like list_components, get_component, get_guidelines to language models — so an AI agent can generate code that uses the system correctly.

Build & deploy

This site deploys to gremorie.com via Vercel (domain to register). The Nx workspace uses nx run-many for cross-package builds; CI runs lint + typecheck + build per package on every push.