Geeklego: The Open-Source Design System Built to Work With AI
Build AI-generated UIs without design drift. Explore Geeklego’s open-source design system, token editor, and AI-powered workflow layer.
Fork it. Define your 3-tier design system. Let Claude Code, Codex, Gemini CLI — or any AI coding tool — generate a consistent, accessible UI that can never break your design rules.
Originally published on the GeekyAnts Blog.
The Problem With Design Systems in the Age of AI
Design systems are supposed to bring consistency. But in practice, they are a document that developers mean to follow, a Notion page that's three months out of date, and a set of tokens that might or might not match what's actually in the code.
Now add AI coding tools to the picture. Claude Code, Codex, Gemini CLI, and Cursor — these tools generate components fast. Impressively fast. But fast without constraints is how you end up with hardcoded hex values, skipped token tiers, and five different ways to truncate text across a codebase that was supposed to be consistent.
The problem is structural: design systems are defined separately from the rules that enforce them. AI tools have no way to know that --color-brand-500 should never appear directly in a component, or that every spacing value must come from a semantic token, or that dark mode only works if you respect the semantic tier. No one told the AI. So it guesses — and it guesses consistently wrong in different ways.
Geeklego is our answer to this problem. And it's open source.
What Is Geeklego?
Geeklego is an open-source, AI-native design system built on Tailwind CSS v4. It ships three things:
A 3-tier design system — a single CSS file (
geeklego.css) that defines every visual value across three strict tiers: raw primitives, purpose-driven semantics, and component-specific tokens. It is the authoritative, machine-readable source of truth for the entire project.A skill layer — six AI skills (for Claude Code, Codex, Gemini CLI, or any agent-capable tool) that generate components, sync with Figma, audit for accessibility and security, and add internationalization — all while enforcing the 3-tier architecture automatically.
81 production-ready components — atoms, molecules, and organisms that are expressions of the design system, each generated by the skill layer and proven to follow the rules.
Geeklego is not a component library you install and override. It's a design system you own and extend — with an AI layer that makes extension fast, consistent, and safe.
The philosophy is simple: define the system first. Let AI build from it, not around it.
The Vision: A Design System That Teaches Itself to AI
Every AI coding tool — Claude Code, Codex, Gemini CLI, Cursor — is only as good as the context it has. Give it no context, and it invents conventions. Give it a good context, and it follows yours.
Geeklego's vision is to make the design system itself that context. Not a README that someone has to remember to reference. Not a Storybook that AI can't read. The actual architecture — the 3-tier token chain, the 5-file component structure, the 45 explicit rules — is encoded in a machine-readable spec (CLAUDE.md) that any AI coding tool can consume before it writes a single line.
AI that is constrained by your design system, not set loose on your codebase.
When any AI tool generates a component in Geeklego, it can't hardcode #6366f1. It can't use h-[40px]. It can't reference a Tier 1 primitive directly from a component. The architecture makes inconsistency structurally impossible — not a guideline someone has to remember, not a lint rule someone can suppress.
The long-term vision: you define the system once. Every AI that ever touches your codebase — today's tools, next year's tools, tools that don't exist yet — generates components that follow it perfectly. Hundreds of components, zero design drift. That's what Geeklego is building toward.
Design-System-First: The 3-Tier Architecture That Changes Everything
In every component library you've used, the design system emerges from component code. You build a Button, extract its colors into variables, build a Card, extract its spacing, and over time something resembling a design system appears.
Geeklego inverts this completely.
Before a single component is written, the design system is defined and published across three distinct tiers. Components are built as expressions of the system, constrained to use only what the system provides — and only in the order the system prescribes.
The 3-Tier Token Chain
This is the central idea in Geeklego. Everything else flows from it.
Tier 1 — Primitives are raw values: --color-brand-500: #6366f1, --spacing-4: 1rem. They are the foundation of the entire system. No component ever references a primitive directly. That's the rule.
Tier 2 — Semantics give purpose to primitives: --color-action-primary: var(--color-brand-500). This is where theming happens. When you switch to dark mode, semantic tokens update. Primitives stay unchanged. The semantic tier is the single mechanism that makes theme switching work correctly across every component in the library simultaneously.
Tier 3 — Component tokens bind individual components to semantics: --button-bg: var(--color-action-primary). A component token must always reference a Tier 2 semantic. Referencing a primitive directly — skipping Tier 2 — is forbidden. This is non-negotiable, encoded in the architecture, and enforced by the Claude Code skill before it writes a single line of component code.
Here's the full chain for a Button's background color:
/* Tier 1 — Primitives*/
/--color-brand-500: #6366f1;
/* Tier 2 — Semantics*/
/--color-action-primary: var(--color-brand-500);
/ Tier 3 — Component tokens*/
/--button-bg: var(--color-action-primary);
And in a component:
<button className="bg-[var(--button-bg)] ...">Submit</button>
Here's why all three tiers are necessary. When you toggle dark mode, you update one Tier 2 semantic:
[data-theme="dark"] { --color-action-primary: var(--color-brand-400);}
That is the only change. Every component that reads --button-bg Picks up the new value through the chain — automatically, correctly, everywhere. No per-component dark mode overrides. No !important patches. No missing cases discovered in production.
If a component token had skipped Tier 2 and referenced a Tier 1 primitive directly, that component would be invisible to theme switches. It would render the same color in light and dark mode, and you'd never know why until a designer filed a bug report.
The 3-tier chain is not a bureaucracy. It's the mechanism that makes the entire system coherent.
No Arbitrary Values. Ever.
The 3-tier chain only works if it's airtight. So Geeklego forbids Tailwind arbitrary values like bg-[#6366f1] or h-[40px]. Every value — every color, every size, every spacing unit — must flow through all three tiers and arrive as a Tier 3 component token.
The only permitted syntax is bg-[var(--button-bg)], wrapping a Tier 3 CSS variable in Tailwind v4's arbitrary value syntax.
This constraint has a profound side effect: AI can only generate valid, chain-compliant code. When Claude Code generates a component, there's nowhere to put a hardcoded value. The language doesn't permit it. Design integrity is enforced by architecture, not code review.
What Ships With Geeklego Today
81 Production-Ready Components
Geeklego currently ships three levels of the component hierarchy:
L1 Atoms (38 components) — the building blocks: Avatar, Badge, Button, Checkbox, Input, Select, Spinner, Switch, Tooltip, and 29 more. Atoms import nothing — they're pure expressions of the design system.
L2 Molecules (27 components) — combinations of atoms: AlertBanner, Breadcrumb, ButtonGroup, Calendar, Card, Combobox, DateInput, DropdownMenu, Fieldset, FormField, InputGroup, Navbar, NumberInput, Pagination, Popover, RadioGroup, SearchBar, StatCard, Stepper, Toast, Tooltip, TreeView, and more.
L3 Organisms (16 components) — full UI sections: Accordion, AreaChart, BarChart, Carousel, Chat, ColorPicker, DataTable, Datepicker, Drawer, Footer, Form, Header, Modal, PieChart, Sidebar, Tabs, and more in active development.
L4 Templates and L5 Pages are in active development. DashboardLayout, AuthLayout, and LandingLayout are coming next.
Every component in the fork ships with:
Full TypeScript types and JSDoc-annotated props
Light and dark mode support out of the box, via the 3-tier token chain
WCAG 2.2 Level AA accessibility (keyboard nav, ARIA, focus management)
Responsive design via Tailwind responsive prefixes
8 Storybook stories per component (used as automated tests via Vitest)
Optional Schema.org markup for SEO
Optional i18n string support
A Visual Token Editor
npm run dev opens a full React app at localhost:5176 for editing the design system without touching code.
A three-panel layout: a left NavRail organizes tokens into three tiers (Foundations with 8 sub-categories like color, spacing, typography, and shadow; Semantic with purpose-driven alias groups; Components listed by level) with drill-down sub-categories, a center pane shows the selected category or component, and a right Inspector panel displays token details with value editing and alias chain visualization. Export is available from the header bar. Changes preview instantly across Storybook via WebSocket. Full undo/redo history. Automatic backup. Token validation. Export as CSS or JSON.
This means designers can edit the design system directly. Not in a Notion doc that may or may not reflect the code. In the actual source of truth, with live preview.
Storybook as Living Tests
Geeklego treats Storybook stories as executable tests. Each .stories.tsx file becomes a Vitest test running headless in Chromium via Playwright. No separate test infrastructure. Stories serve double duty as documentation and automated regression tests.
Every component requires eight stories: default, variant A, variant B, size/scale, disabled state, loading state, dark mode, and an accessibility story tagged for WCAG audit.
The Skill Layer: AI That Knows the Rules
This is the part of Geeklego that has no equivalent in any other design system.
Geeklego ships with six skills — self-contained, machine-readable workflow definitions that any capable AI coding tool can execute. They work today with Claude Code, and are designed to be portable to Codex, Gemini CLI, or any agent-capable environment that can read a prompt file and call tools.
Each skill is not a prompt template. It's a disciplined workflow that reads the design system state first, validates the 3-tier chain, applies the change, then runs a verification pass. The AI doesn't guess. It follows a documented process.
The Six Skills
/component-builder— The flagship skill. Invoke it with any component description and the AI readsgeeklego.css, verifies no token block already exists, writes Tier 3 component tokens (each correctly referencing a Tier 2 semantic), generates all five required files, then runs four sequential audits: accessibility, performance, SEO, and security. A component that takes a human two to three hours ships in two to three minutes — and is structurally guaranteed to follow the token chain./component-builder build a Tooltip atom/component-builder build a StatCard molecule/component-builder build a DataTable organism with sorting and pagination/figma-sync— Sync your Tier 1–3 token definitions to Figma variable collections and text styles automatically. The skill diffs the current Figma state againstgeeklego.css, reports what's out of sync, then creates or updates variables to match. Design and code never drift apart./i18n— Add internationalization to any component without committing to a specific i18n library. Library-agnostic, prop-first architecture with RTL support via logical CSS properties. Reads the string inventory to know which system strings already have i18n coverage./state-handling— Audit and generate visual state patterns. Every interactive component needs correct loading, disabled, error, and selected states with proper ARIA attributes. This skill reads the state-handling reference, validates what exists, and generates what's missing./security-review— Audit components for XSS vulnerabilities, unsafe href handling, missingrel="noopener"on external links, and unsanitized user input. Runs against the full component tree./screenshot-workflow— Generate component screenshots automatically for documentation, changelogs, or CI/CD visual regression pipelines.
On-Demand Audit Commands
Beyond the skills, natural-language audit commands run across the entire codebase:
do a refactor check # Memoization, hooks compliance, performance utility usagedo a reuse audit # Find inlined markup that should use existing atomsdo an SEO audit # Schema.org coverage, semantic HTML, heading hierarchy
The Machine-Readable Spec
The skills work because the design system's rules are encoded in a machine-readable spec — CLAUDE.md — that any AI coding tool reads before starting any task. It contains 45 explicit "never do" rules, 49 "always do" rules, naming conventions, the token chain hierarchy, component level definitions, and reference documents for worked examples, semantic HTML, ARIA patterns, and Schema.org mappings.
This is not a README for humans. It's a contract for AI. Every tool that reads it gets the same constraints. Design integrity is preserved not by hoping the AI guesses right, but by telling it exactly what right means — before it generates a single token.
How Geeklego Differs From Other Design Systems
Most design systems are collections of decisions: here are the colors, here are the spacing values, here is a Figma file. Implementation is left to the team. Consistency depends on culture, code review, and people remembering the rules.
Geeklego is a design system that enforces its own rules. Not through linting, not through code review, not through policy — through architecture. The 3-tier chain makes it structurally impossible to introduce a hardcoded value or skip a token tier, because the skill that generates components checks the chain before writing anything. And the machine-readable spec means any AI tool you bring to the project inherits those constraints immediately.
| Feature | Typical design system | Geeklego |
|---|---|---|
| Token architecture | Ad hoc or flat | Strict 3-tier chain: primitives → semantics → component tokens |
| Dark mode | Per-component overrides | Automatic — update Tier 2 semantics, all components cascade |
| AI compatibility | Unstructured — AI must guess conventions | Machine-readable spec — AI reads the rules before generating anything |
| Component generation | Manual | Skill-driven with full 3-tier validation and audit pipeline |
| Figma integration | Manual, periodic sync | Automated sync skill, diff-aware |
| Token editor | External tools or none | Built-in visual editor with live preview |
| Accessibility | Depends on the team | WCAG 2.2 AA baked into the component-builder skill |
| i18n | Separate effort | Library-agnostic pattern, built into the skill layer |
| Multi-brand support | Fork and diverge | Fork and share component logic; only tokens differ |
The shift is from "design system as document" to "design system as enforced architecture." One you reference. The other you can't break.
Real-World Use Cases
Rapid prototyping. Edit the design system in the token editor. Use /component-builder to generate components that match. Preview in Storybook. Sync tokens to Figma for designer feedback. When the design is locked, your production components are ready. Two days instead of two weeks.
Design system governance at scale. Define your tokens. Every team generates components via /component-builder — they can't deviate because the architecture prevents it. Run audits on PRs. The design system becomes enforceable by architecture, not by policy. Code reviews drop from 30 minutes to 5 minutes.
Multi-brand products. Fork Geeklego twice. Each fork has its own geeklego.css with its own colors, fonts, and spacing. Both forks share identical component logic. Update the logic once, both brands benefit. Maintain one codebase, support multiple brands.
Accessible component libraries. Accessibility is built into the component-builder skill — not bolted on after. Every generated component includes the right ARIA attributes, keyboard navigation patterns, touch targets, and semantic HTML. WCAG 2.2 AA by default, not by accident.
Getting Started: Fork and Make It Yours
Geeklego is designed to be forked, not installed. Forking gives you the full 3-tier design system, the visual token editor, all 81 components, and every AI skill — everything you need to customize the system and build from it.
1. Fork the repo on GitHub, then clone your fork
git clone https://github.com/YOUR-USERNAME/geeklego.git cd geeklego
2. Install dependenciesnpm install
3. Start both the token editor and Storybooknpm run dev:all
Two apps open:
localhost:5176— the token editor: customize your Tier 1–3 tokens visually, no code requiredlocalhost:6006— Storybook with all 81 components, live-connected to the token editor
Open your AI tool and start building:
# With Claude Code
/help # see all available skills
/component-builder build a [ComponentName] # generate a new component end-to-end
# With Gemini CLI or Codex
# Point your agent at CLAUDE.md as system context,
# then trigger the same skill workflows from the .claude/skills/ directory
The machine-readable spec in CLAUDE.md is read automatically by Claude Code before every task. For Codex, Gemini CLI, or other agent-capable tools, pass CLAUDE.md as your system context — it's plain markdown and works with any tool that accepts instruction files.
Customize your design system:
Open the token editor at localhost:5176. Edit Tier 1 primitives (your brand colors, spacing scale, type sizes), Tier 2 semantics (what each primitive means in context), and watch every component in Storybook update in real time. When you're ready, export as CSS or JSON.
That's it. The design system is yours. The components follow it automatically. The AI skill layer keeps new components consistent with it, forever.
How to Contribute
Geeklego is open source and actively welcoming contributors. The remaining work on the roadmap includes HeroSection (L3), DashboardLayout, AuthLayout, and LandingLayout (L4 Templates).
Every contribution follows the same pattern — 5 files, the 3-tier token chain, 8 Storybook stories. The machine-readable spec and the skill layer make it straightforward to use your AI tool of choice to generate a contribution that meets the bar from the first commit. You don't need to memorize the rules — the spec teaches the AI, and the AI generates compliant code.
Website: https://geeklego.io
Issues & discussions: open a thread on GitHub
Give it a star, open an issue, or fork it — use /component-builder to generate your contribution and it'll follow the rules from the first commit. We'd love to see what you build.
Geeklego is open source under the MIT license. Built with React 19, Tailwind CSS v4, Vite 6, Storybook 10, and Vitest.
Originally published at geekyants.com/blog.
