Jun 8, 2026

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.

Technology

design system

Artificial Intelligence

Author

Bitta SinghaUI / UX Designer - I

Geeklego: The Open-Source Design System Built to Work With AI

Book a call

Table of Contents

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.

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:

And in a component:

Here's why all three tiers are necessary. When you toggle dark mode, you update one Tier 2 semantic:

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 reads `geeklego.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.

`/figma-sync` — Sync your Tier 1–3 token definitions to Figma variable collections and text styles automatically. The skill diffs the current Figma state against `geeklego.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, missing `rel="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:

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.

Two apps open:

`localhost:5176` — the token editor: customize your Tier 1–3 tokens visually, no code required

`localhost:6006` — Storybook with all 81 components, live-connected to the token editor

Open your AI tool and start building:

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.

GitHub: https://github.com/GeekyAnts/geeklego

Website: https://geeklego.io/?utm_source=geekyants.com&utm_medium=referral&utm_campaign=geeklego_cross_promotion

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.

SHARE ON