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

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.

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 an open-source, AI-native design system built on Tailwind CSS v4. It ships three things:

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.

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.

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

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.

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.

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:

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.

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

`/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

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.

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.

The shift is from "design system as document" to "design system as enforced architecture." One you reference. The other you can't break.

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.

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:6006` — Storybook with all 81 components, live-connected to the token editor

Open your AI tool and start building:

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.

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/?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.