https://github.com/oscarabcorona/hex-core
AI-native component library for LLMs and humans.
https://github.com/oscarabcorona/hex-core
ai-components ai-native component-library mcp radix-ui react shadcn-alternative tailwindcss
Last synced: 3 months ago
JSON representation
AI-native component library for LLMs and humans.
- Host: GitHub
- URL: https://github.com/oscarabcorona/hex-core
- Owner: oscarabcorona
- License: mit
- Created: 2026-04-16T16:44:28.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-05-05T15:34:43.000Z (3 months ago)
- Last Synced: 2026-05-05T17:30:57.023Z (3 months ago)
- Topics: ai-components, ai-native, component-library, mcp, radix-ui, react, shadcn-alternative, tailwindcss
- Language: TypeScript
- Homepage: https://hex-core.dev
- Size: 8.27 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# Hex Core
[](https://github.com/oscarabcorona/hex-core/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@hex-core/components)
[](https://www.npmjs.com/package/@hex-core/components)
[](LICENSE)
[](https://github.com/sponsors/oscarabcorona)
**The component layer for spec-driven UI development.**
Hex Core turns a brief (or a `spec.md` / `plan.md` section) into a ranked component checklist over MCP. No server, no runtime — just static JSON and 12 MCP tools over a catalog of 83 components.
## Why Hex Core?
shadcn/ui is built for humans browsing docs. Hex Core is built for **AI agents** that need:
- **Machine-readable component specs** — Zod schemas with props, variants, slots, and constraints
- **AI hints** — `whenToUse`, `whenNotToUse`, `commonMistakes`, `accessibilityNotes` per component
- **Recipes** — six spec-driven blueprints (auth form, settings page, pricing table, data table, confirm-destructive, command palette) with ordered install steps and post-install checklists
- **MCP server** — 12 tools for component discovery, installation, theming, scaffolding, spec resolution, and emitting paste-into-LLM app context
- **Token budgets** — each component declares its token cost for efficient LLM context usage
> [!WARNING]
> **Use the scoped package names.** The npm packages are `@hex-core/cli` and `@hex-core/mcp`. An unrelated `hex-core` package is published on npm by a different author — `npx hex-core …` will fail with `npm error could not determine executable to run`. Always include the `@hex-core/` scope in install commands.
## Quick Start
### For AI (MCP)
Add to your Claude Code settings (`.claude/settings.json`):
```json
{
"mcpServers": {
"hex-core": {
"command": "npx",
"args": ["@hex-core/mcp"]
}
}
}
```
Then ask Claude: *"Search hex-core for a button component and add it to my project"*
### For Humans (CLI)
```bash
npx @hex-core/cli init # detects Tailwind v3 vs v4, scaffolds globals.css, auto-installs peer deps
npx @hex-core/cli add button input label # writes components, auto-installs Radix peers, rewrites imports to your @/ alias
npx @hex-core/cli doctor # diagnose what's missing if anything breaks
```
## Packages
| Package | Description |
|---------|-------------|
| `@hex-core/registry` | Zod schemas and types for the component registry |
| `@hex-core/tokens` | Design token engine with 3 themes |
| `@hex-core/components` | Component source code (React + Tailwind) |
| `@hex-core/motion` | UI animation primitives + deterministic timeline composer (zero-dep WAAPI core, optional `motion@^11` adapter) |
| `@hex-core/mcp` | MCP server for AI-native distribution |
| `@hex-core/cli` | CLI for human developers |
## MCP Tools
| Tool | Purpose |
|------|---------|
| `search_components` | Discover components by query, category, or tags |
| `get_component` | Get full source code + metadata for installation |
| `get_component_schema` | Get props/variants/AI hints (token-efficient) |
| `get_theme` | Get theme in CSS, JSON, or Tailwind format |
| `list_themes` | List available themes |
| `scaffold_project` | Generate complete project setup |
| `customize_component` | Apply CSS overrides to components |
| `list_recipes` | Catalog of spec-driven blueprints |
| `get_recipe` | Ordered install steps + post-install checklist |
| `resolve_spec` | Deterministic brief → ranked component + recipe shortlist |
| `verify_checklist` | Cross-check installed components against the internal-dep graph |
| `emit_app_context` | Synthesize a paste-into-LLM markdown payload of theme + installed components |
See **[hex-core.dev/docs/spec-driven](https://hex-core.dev/docs/spec-driven)** for the full spec-driven workflow.
## Spec-driven example
```bash
# 1. Discover recipes
npx @hex-core/cli recipe list
# 2. Install every component in a recipe + print its checklist
npx @hex-core/cli recipe add settings-page
```
Or from an MCP client: ask *"Resolve this spec into hex-core components: build a settings page with notifications toggle"* — `resolve_spec` returns the `settings-page` recipe and a ranked component shortlist.
## Skills (for Claude Code)
Hex Core ships nine prose context packs in `SKILL.md` format — overview, MCP tools decision tree, recipes workflow, theming, CLI, a11y, anti-patterns, registry authoring, motion. Install in one command:
```bash
npx @hex-core/cli skills install
```
This copies the skills into `.claude/skills/` so any agent working in your repo loads them via trigger keywords on demand. See **[hex-core.dev/docs/skills](https://hex-core.dev/docs/skills)**.
## Themes
- **Default** — Refined, neutral. Professional and versatile.
- **Midnight** — Dark-first with deep blues. Built for developer tools.
- **Ember** — Warm terracotta and amber. For creative applications.
## Components
**117 registry items** across primitives (Button, Input, Checkbox, Switch, Slider, …), compounds (Combobox, DataTable, Command, Calendar, Date Picker, …), AI-native (Composer, Message, Reasoning, ToolCall, Terminal, Canvas, Diagram, AudioPlayer, AudioWaveform, SpeechRecognition, …), 23 artifact diagrams (sankey, mindmap, gantt, …), and 11 motion primitives (Motion factory, Presence, Timeline composer, useAnimate, useScroll, …). Every item ships with a machine-readable `.schema.ts` containing props, variants, AI hints (`whenToUse`, `whenNotToUse`, `commonMistakes`, `accessibilityNotes`), and a token budget.
Full catalog + live demos: **[hex-core.dev/docs](https://hex-core.dev/docs)**
## Development
```bash
pnpm install
pnpm build
pnpm run build:registry
```
## Architecture
```
hex-core/
├── packages/
│ ├── registry/ # Zod schemas + types
│ ├── tokens/ # Design token engine
│ ├── components/ # React component source
│ ├── mcp-server/ # MCP server
│ └── cli/ # CLI tool
├── registry/ # Built registry JSON
└── scripts/ # Build scripts
```
Each component has two files:
- `{name}.tsx` — React component (Radix UI + Tailwind + CVA)
- `{name}.schema.ts` — Machine-readable spec with props, variants, AI hints
## Releases
Feature branch → PR → `main` → `/release` skill. CI on `main` runs `Lint` / `Build` / `Test` (~2 min). Slow regression checks (a11y axe-scan + Playwright visual diffs) run locally via `pnpm regression` as a pre-release gate; see [CONTRIBUTING.md](CONTRIBUTING.md#releasing).
## Sponsor
If hex-core saves you time, consider [sponsoring development on GitHub](https://github.com/sponsors/oscarabcorona).
## License
[MIT](LICENSE)