Neeto maintains NeetoUI, a proprietary React component library that acts as the design system and UI foundation for an ecosystem of 15+ SaaS products.

Currently:

• All Neeto products import exclusively from NeetoUI

• Some NeetoUI components wrap Ant Design

• Other components are custom implementations

Products never import Ant Design directly.

This architecture has ensured cross-product consistency, but the rise of AI coding tools introduces new considerations.

Engineers now regularly use:

• Claude

• Cursor

• Windsurf

• GitHub Copilot

The design system should evolve to work effectively with AI-generated code while maintaining long-term maintainability and design consistency.

---

Goals

The strategy should achieve the following goals.

1. Cross-Product Design Consistency

Maintain consistent UI patterns across all Neeto products through a shared design system.

2. AI Tool Compatibility

AI-generated code should align with NeetoUI patterns, not bypass them.

3. Long-Term Maintainability

Reduce long-term dependency on Ant Design.

4. Developer Experience

New engineers should receive accurate suggestions from AI tools and easily discover the correct component usage.

---

Constraints

Several practical constraints must guide the strategy.

• 15+ production products depend on NeetoUI

• A big-bang migration is not feasible

• Migration must be incremental

• Team expertise is primarily React

• Team may not have strong Tailwind CSS expertise

• Documentation is already available via Context7 MCP for Claude

---

Architecture Options

The following architectural approaches were evaluated.

---

Option A — Keep NeetoUI As-Is (Ant Design Underneath)

Description

Continue the current architecture:

Products
   ↓
NeetoUI
   ↓
Ant Design

Advantages

• No migration cost

• Stable production environment

• Developers already familiar with the system

Disadvantages

AI models are heavily trained on:

• Radix UI

• shadcn

• Tailwind

• Headless UI

They are not trained on proprietary wrappers around Ant Design.

This leads to issues such as AI suggesting incorrect imports:

import { Button } from "antd"

instead of:

import { Button } from "@bigbinary/neeto-ui"

AI may also suggest Ant-specific props that NeetoUI does not expose.

Risk

Long-term lock-in to Ant Design architecture.

Verdict

Stable in the short term but not aligned with the AI-driven development ecosystem.

---

Option B — Publish NeetoUI as a shadcn-Style Registry

Description

Expose NeetoUI components via a component registry similar to shadcn.

Example usage:

npx neeto-ui add button

Advantages

• AI tools can understand and reference real components

• Developers can inspect component source

• Standardized component usage examples

• Improved compatibility with AI coding tools

Disadvantages

Internal architecture still depends on Ant Design.

Verdict

High value with minimal risk.

This improvement should be implemented regardless of the chosen long-term strategy.

---

Option C — Replace Ant Design Internals with Radix UI

Description

Gradually replace Ant Design internals while keeping the NeetoUI API stable.

Example transition:

Current architecture:

NeetoModal
   → Ant Modal

Future architecture:

NeetoModal
   → Radix Dialog

Advantages

• Removes long-term dependency on Ant Design

• Radix provides accessible headless primitives

• Widely supported and understood by AI tools

Disadvantages

Requires incremental rewriting of several components.

Component complexity varies.

Risk

Public API changes could break products.

This risk can be avoided by preserving the NeetoUI public API.

Verdict

Strong long-term architecture with manageable migration risk.

---

Option D — Full Rebuild on shadcn

Description

Completely rebuild NeetoUI on top of:

• Radix UI

• Tailwind CSS

• shadcn patterns

Advantages

Clean modern architecture.

Disadvantages

Very high migration cost.

Estimated effort:

12–18 months

Significant risk to the stability of 15+ production products.

Verdict

Technically attractive but too risky operationally.

---

Option E — Migrate to BaseUI (MUI Headless Library)

Description

Replace Ant Design with BaseUI, a headless component library from the MUI ecosystem.

Comparison

Verdict

Radix has stronger ecosystem adoption and documentation.

BaseUI introduces unnecessary risk.

---

Option F — Hybrid Strategy (Recommended)

This option combines the advantages of Options B and C.

Strategy

1. Publish NeetoUI as a shadcn-style registry

2. Gradually replace Ant Design internals with Radix primitives

Final architecture becomes:

Products
   ↓
NeetoUI (Stable API)
   ↓
Radix UI primitives
   ↓
DOM

Advantages

• AI compatibility improves immediately

• Migration can happen incrementally

• Public API remains stable

• Ant Design dependency can be removed gradually

Verdict

Best balance between innovation, stability, and maintainability.

---

AI Code Generation Impact

AI compatibility differs significantly across options.

Modern AI models are trained extensively on:

• Radix UI

• shadcn

• Tailwind ecosystems

Aligning with these ecosystems significantly improves AI-generated code quality.

---

Design Tokens Strategy

Introduce design tokens using CSS custom properties.

Example:

:root {
  --neeto-color-primary: #5b5bd6;
  --neeto-radius-md: 6px;
  --neeto-spacing-sm: 8px;
}

Components reference tokens instead of hardcoded values.

.button {
  background: var(--neeto-color-primary);
}

Benefits

• Consistent theming across products

• Easier design system evolution

• AI-readable design constraints

• Compatible with Tailwind if adopted later

---

LLM Documentation (llms.txt)

A public llms.txt file should be published for NeetoUI.

Example location:

neeto-ui.dev/llms.txt

Example content:

# NeetoUI LLM Guide

NeetoUI is the design system used across all Neeto SaaS products.

Rules:

1. Always import components from "@bigbinary/neeto-ui"
2. Never import components from Ant Design
3. Use NeetoUI layout primitives
4. Follow Neeto spacing tokens

Example:

import { Button, Modal } from "@bigbinary/neeto-ui"

<Button variant="primary">Save</Button>

This helps AI tools generate correct code aligned with NeetoUI standards.

---

Recommended Architecture

The long-term architecture should become:

Products (15+)
     ↓
NeetoUI API (Stable)
     ↓
Radix UI primitives
     ↓
CSS Design Tokens

AI tools interact primarily with:

• NeetoUI registry

• NeetoUI documentation

• llms.txt

---

Phased Migration Plan

This plan assumes a 10-engineer frontend team.

---

Phase 1 — AI Enablement (1–2 Months)

Objectives:

• Publish NeetoUI component registry

• Improve AI-friendly documentation

• Publish llms.txt

• Introduce design tokens

Expected Impact:

Immediate improvement in AI-generated code accuracy.

Estimated Effort:

2 engineers for approximately 6 weeks.

---

Phase 2 — Radix Infrastructure Layer (2 Months)

Introduce Radix primitives internally while preserving the NeetoUI API.

Examples:

• NeetoDialog

• NeetoPopover

• NeetoTooltip

Estimated Effort:

3 engineers for 8 weeks.

---

Phase 3 — Component Migration (6–8 Months)

Replace Ant Design implementations incrementally.

Suggested migration order:

Products continue using the same NeetoUI APIs.

Estimated Effort:

5 engineers for 6–8 months.

---

Phase 4 — Remove Ant Design (3 Months)

After all components are migrated, remove Ant Design entirely.

Benefits:

• Reduced bundle size

• Simplified dependency graph

Estimated Effort:

2 engineers for 3 months.

---

Estimated Timeline

Total estimated timeline:

Approximately 12 months

Migration occurs gradually without disrupting existing products.

---

Final Recommendation

Adopt Option F: Hybrid Strategy

1. Publish NeetoUI as a registry for AI tooling

2. Introduce design tokens

3. Gradually migrate components to Radix UI

4. Remove Ant Design dependency

This approach ensures:

• Strong AI compatibility

• Stable design system APIs

• Incremental migration

• Long-term architectural flexibility.